doc/fcconfig.fncs

   1 /*
   2  * fontconfig/doc/fcconfig.fncs
   3  *
   4  * Copyright © 2003 Keith Packard
   5  *
   6  * Permission to use, copy, modify, distribute, and sell this software and its
   7  * documentation for any purpose is hereby granted without fee, provided that
   8  * the above copyright notice appear in all copies and that both that
   9  * copyright notice and this permission notice appear in supporting
  10  * documentation, and that the name of the author(s) not be used in
  11  * advertising or publicity pertaining to distribution of the software without
  12  * specific, written prior permission.  The authors make no
  13  * representations about the suitability of this software for any purpose.  It
  14  * is provided "as is" without express or implied warranty.
  15  *
  16  * THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
  17  * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
  18  * EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY SPECIAL, INDIRECT OR
  19  * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
  20  * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
  21  * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  22  * PERFORMANCE OF THIS SOFTWARE.
  23  */
  24 @RET@           FcConfig *
  25 @FUNC@          FcConfigCreate
  26 @TYPE1@         void
  27 @PURPOSE@       Create a configuration
  28 @DESC@
  29 Creates an empty configuration.
  30 @@
  31
  32 @RET@           FcConfig *
  33 @FUNC@          FcConfigReference
  34 @TYPE1@         FcConfig *                      @ARG1@          config
  35 @PURPOSE@       Increment config reference count
  36 @DESC@
  37 Add another reference to <parameter>config</parameter>. Configs are freed only
  38 when the reference count reaches zero.
  39 If <parameter>config</parameter> is NULL, the current configuration is used.
  40 In that case this function will be similar to FcConfigGetCurrent() except that
  41 it increments the reference count before returning and the user is responsible
  42 for destroying the configuration when not needed anymore.
  43 @@
  44
  45 @RET@           void
  46 @FUNC@          FcConfigDestroy
  47 @TYPE1@         FcConfig *                      @ARG1@          config
  48 @PURPOSE@       Destroy a configuration
  49 @DESC@
  50 Decrements the config reference count. If all references are gone, destroys
  51 the configuration and any data associated with it.
  52 Note that calling this function with the return from FcConfigGetCurrent will
  53 cause a new configuration to be created for use as current configuration.
  54 @@
  55
  56 @RET@           FcBool
  57 @FUNC@          FcConfigSetCurrent
  58 @TYPE1@         FcConfig *                      @ARG1@          config
  59 @PURPOSE@       Set configuration as default
  60 @DESC@
  61 Sets the current default configuration to <parameter>config</parameter>.  Implicitly calls
  62 FcConfigBuildFonts if necessary, and FcConfigReference() to inrease the reference count
  63 in <parameter>config</parameter> since 2.12.0, returning FcFalse if that call fails.
  64 @@
  65
  66 @RET@           FcConfig *
  67 @FUNC@          FcConfigGetCurrent
  68 @TYPE1@         void
  69 @PURPOSE@       Return current configuration
  70 @DESC@
  71 Returns the current default configuration.
  72 @@
  73
  74 @RET@           FcBool
  75 @FUNC@          FcConfigUptoDate
  76 @TYPE1@         FcConfig *                      @ARG1@          config
  77 @PURPOSE@       Check timestamps on config files
  78 @DESC@
  79 Checks all of the files related to <parameter>config</parameter> and returns
  80 whether any of them has been modified since the configuration was created.
  81 If <parameter>config</parameter> is NULL, the current configuration is used.
  82 @@
  83
  84 @RET@           FcChar8 *
  85 @FUNC@          FcConfigHome
  86 @TYPE1@         void
  87 @PURPOSE@       return the current home directory.
  88 @DESC@
  89 Return the current user's home directory, if it is available, and if using it
  90 is enabled, and NULL otherwise.
  91 See also <function>FcConfigEnableHome</function>).
  92 @@
  93
  94 @RET@           FcBool
  95 @FUNC@          FcConfigEnableHome
  96 @TYPE1@         FcBool%                         @ARG1@          enable
  97 @PURPOSE@       controls use of the home directory.
  98 @DESC@
  99 If <parameter>enable</parameter> is FcTrue, then Fontconfig will use various
 100 files which are specified relative to the user's home directory (using the ~
 101 notation in the configuration). When <parameter>enable</parameter> is
 102 FcFalse, then all use of the home directory in these contexts will be
 103 disabled. The previous setting of the value is returned.
 104 @@
 105
 106 @RET@           FcBool
 107 @FUNC@          FcConfigBuildFonts
 108 @TYPE1@         FcConfig *                      @ARG1@          config
 109 @PURPOSE@       Build font database
 110 @DESC@
 111 Builds the set of available fonts for the given configuration.  Note that
 112 any changes to the configuration after this call have indeterminate effects.
 113 Returns FcFalse if this operation runs out of memory.
 114 If <parameter>config</parameter> is NULL, the current configuration is used.
 115 @@
 116
 117 @RET@           FcStrList *
 118 @FUNC@          FcConfigGetConfigDirs
 119 @TYPE1@         FcConfig *                      @ARG1@          config
 120 @PURPOSE@       Get config directories
 121 @DESC@
 122 Returns the list of font directories specified in the configuration files
 123 for <parameter>config</parameter>.  Does not include any subdirectories.
 124 If <parameter>config</parameter> is NULL, the current configuration is used.
 125 @@
 126
 127 @RET@           FcStrList *
 128 @FUNC@          FcConfigGetFontDirs
 129 @TYPE1@         FcConfig *                      @ARG1@          config
 130 @PURPOSE@       Get font directories
 131 @DESC@
 132 Returns the list of font directories in <parameter>config</parameter>. This includes the
 133 configured font directories along with any directories below those in the
 134 filesystem.
 135 If <parameter>config</parameter> is NULL, the current configuration is used.
 136 @@
 137
 138 @RET@           FcStrList *
 139 @FUNC@          FcConfigGetConfigFiles
 140 @TYPE1@         FcConfig *                      @ARG1@          config
 141 @PURPOSE@       Get config files
 142 @DESC@
 143 Returns the list of known configuration files used to generate <parameter>config</parameter>.
 144 If <parameter>config</parameter> is NULL, the current configuration is used.
 145 @@
 146
 147 @RET@           FcChar8 *
 148 @FUNC@          FcConfigGetCache
 149 @TYPE1@         FcConfig *                      @ARG1@          config
 150 @PURPOSE@       DEPRECATED used to return per-user cache filename
 151 @DESC@
 152 With fontconfig no longer using per-user cache files, this function now
 153 simply returns NULL to indicate that no per-user file exists.
 154 @@
 155
 156 @RET@           FcStrList *
 157 @FUNC@          FcConfigGetCacheDirs
 158 @TYPE1@         const FcConfig *                @ARG1@          config
 159 @PURPOSE@       return the list of directories searched for cache files
 160 @DESC@
 161 <function>FcConfigGetCacheDirs</function> returns a string list containing
 162 all of the directories that fontconfig will search when attempting to load a
 163 cache file for a font directory.
 164 If <parameter>config</parameter> is NULL, the current configuration is used.
 165 @@
 166
 167 @RET@           FcFontSet *
 168 @FUNC@          FcConfigGetFonts
 169 @TYPE1@         FcConfig *                      @ARG1@          config
 170 @TYPE2@         FcSetName%                      @ARG2@          set
 171 @PURPOSE@       Get config font set
 172 @DESC@
 173 Returns one of the two sets of fonts from the configuration as specified
 174 by <parameter>set</parameter>. This font set is owned by the library and must
 175 not be modified or freed.
 176 If <parameter>config</parameter> is NULL, the current configuration is used.
 177 @@
 178
 179 @RET@           FcBlanks *
 180 @FUNC@          FcConfigGetBlanks
 181 @TYPE1@         FcConfig *                      @ARG1@          config
 182 @PURPOSE@       Get config blanks
 183 @DESC@
 184 Returns the FcBlanks object associated with the given configuration, if no
 185 blanks were present in the configuration, this function will return 0.
 186 The returned FcBlanks object if not NULL, is valid as long as the owning
 187 FcConfig is alive.
 188 If <parameter>config</parameter> is NULL, the current configuration is used.
 189 @@
 190
 191 @RET@           int
 192 @FUNC@          FcConfigGetRescanInterval
 193 @TYPE1@         FcConfig *                      @ARG1@          config
 194 @PURPOSE@       Get config rescan interval
 195 @DESC@
 196 Returns the interval between automatic checks of the configuration (in
 197 seconds) specified in <parameter>config</parameter>.  The configuration is checked during
 198 a call to FcFontList when this interval has passed since the last check.
 199 An interval setting of zero disables automatic checks.
 200 If <parameter>config</parameter> is NULL, the current configuration is used.
 201 @@
 202
 203 @RET@           FcBool
 204 @FUNC@          FcConfigSetRescanInterval
 205 @TYPE1@         FcConfig *                      @ARG1@          config
 206 @TYPE2@         int%                            @ARG2@          rescanInterval
 207 @PURPOSE@       Set config rescan interval
 208 @DESC@
 209 Sets the rescan interval. Returns FcFalse if the interval cannot be set (due
 210 to allocation failure). Otherwise returns FcTrue.
 211 An interval setting of zero disables automatic checks.
 212 If <parameter>config</parameter> is NULL, the current configuration is used.
 213 @@
 214
 215 @RET@           FcBool
 216 @FUNC@          FcConfigAppFontAddFile
 217 @TYPE1@         FcConfig *                      @ARG1@          config
 218 @TYPE2@         const FcChar8 *                 @ARG2@          file
 219 @PURPOSE@       Add font file to font database
 220 @DESC@
 221 Adds an application-specific font to the configuration. Returns FcFalse
 222 if the fonts cannot be added (due to allocation failure or no fonts found).
 223 Otherwise returns FcTrue. If <parameter>config</parameter> is NULL,
 224 the current configuration is used.
 225 @@
 226
 227 @RET@           FcBool
 228 @FUNC@          FcConfigAppFontAddDir
 229 @TYPE1@         FcConfig *                      @ARG1@          config
 230 @TYPE2@         const FcChar8 *                 @ARG2@          dir
 231 @PURPOSE@       Add fonts from directory to font database
 232 @DESC@
 233 Scans the specified directory for fonts, adding each one found to the
 234 application-specific set of fonts. Returns FcFalse
 235 if the fonts cannot be added (due to allocation failure).
 236 Otherwise returns FcTrue. If <parameter>config</parameter> is NULL,
 237 the current configuration is used.
 238 @@
 239
 240 @RET@           void
 241 @FUNC@          FcConfigAppFontClear
 242 @TYPE1@         FcConfig *                      @ARG1@          config
 243 @PURPOSE@       Remove all app fonts from font database
 244 @DESC@
 245 Clears the set of application-specific fonts.
 246 If <parameter>config</parameter> is NULL, the current configuration is used.
 247 @@
 248
 249 @RET@           FcBool
 250 @FUNC@          FcConfigSubstituteWithPat
 251 @TYPE1@         FcConfig *                      @ARG1@          config
 252 @TYPE2@         FcPattern *                     @ARG2@          p
 253 @TYPE3@         FcPattern *                     @ARG3@          p_pat
 254 @TYPE4@         FcMatchKind%                     @ARG4@          kind
 255 @PURPOSE@       Execute substitutions
 256 @DESC@
 257 Performs the sequence of pattern modification operations, if <parameter>kind</parameter> is
 258 FcMatchPattern, then those tagged as pattern operations are applied, else
 259 if <parameter>kind</parameter> is FcMatchFont, those tagged as font operations are applied and
 260 p_pat is used for &lt;test&gt; elements with target=pattern. Returns FcFalse
 261 if the substitution cannot be performed (due to allocation failure). Otherwise returns FcTrue.
 262 If <parameter>config</parameter> is NULL, the current configuration is used.
 263 @@
 264
 265 @RET@           FcBool
 266 @FUNC@          FcConfigSubstitute
 267 @TYPE1@         FcConfig *                      @ARG1@          config
 268 @TYPE2@         FcPattern *                     @ARG2@          p
 269 @TYPE3@         FcMatchKind%                    @ARG3@          kind
 270 @PURPOSE@       Execute substitutions
 271 @DESC@
 272 Calls FcConfigSubstituteWithPat setting p_pat to NULL. Returns FcFalse
 273 if the substitution cannot be performed (due to allocation failure). Otherwise returns FcTrue.
 274 If <parameter>config</parameter> is NULL, the current configuration is used.
 275 @@
 276
 277 @RET@           FcPattern *
 278 @FUNC@          FcFontMatch
 279 @TYPE1@         FcConfig *                      @ARG1@          config
 280 @TYPE2@         FcPattern *                     @ARG2@          p
 281 @TYPE3@         FcResult *                      @ARG3@          result
 282 @PURPOSE@       Return best font
 283 @DESC@
 284 Finds the font in <parameter>sets</parameter> most closely matching
 285 <parameter>pattern</parameter> and returns the result of
 286 <function>FcFontRenderPrepare</function> for that font and the provided
 287 pattern. This function should be called only after
 288 <function>FcConfigSubstitute</function> and
 289 <function>FcDefaultSubstitute</function> have been called for
 290 <parameter>p</parameter>; otherwise the results will not be correct.
 291 If <parameter>config</parameter> is NULL, the current configuration is used.
 292 @@
 293
 294 @RET@           FcFontSet *
 295 @FUNC@          FcFontSort
 296 @TYPE1@         FcConfig *                      @ARG1@          config
 297 @TYPE2@         FcPattern *                     @ARG2@          p
 298 @TYPE3@         FcBool%                         @ARG3@          trim
 299 @TYPE4@         FcCharSet **                    @ARG4@          csp
 300 @TYPE5@         FcResult *                      @ARG5@          result
 301 @PURPOSE@       Return list of matching fonts
 302 @DESC@
 303 Returns the list of fonts sorted by closeness to <parameter>p</parameter>.  If <parameter>trim</parameter> is FcTrue,
 304 elements in the list which don't include Unicode coverage not provided by
 305 earlier elements in the list are elided.  The union of Unicode coverage of
 306 all of the fonts is returned in <parameter>csp</parameter>, if <parameter>csp</parameter> is not NULL.  This function
 307 should be called only after FcConfigSubstitute and FcDefaultSubstitute have
 308 been called for <parameter>p</parameter>; otherwise the results will not be correct.
 309     </para><para>
 310 The returned FcFontSet references FcPattern structures which may be shared
 311 by the return value from multiple FcFontSort calls, applications must not
 312 modify these patterns.  Instead, they should be passed, along with <parameter>p</parameter> to
 313 <function>FcFontRenderPrepare</function> which combines them into a complete pattern.
 314     </para><para>
 315 The FcFontSet returned by FcFontSort is destroyed by calling FcFontSetDestroy.
 316 If <parameter>config</parameter> is NULL, the current configuration is used.
 317 @@
 318
 319 @RET@           FcPattern *
 320 @FUNC@          FcFontRenderPrepare
 321 @TYPE1@         FcConfig *                      @ARG1@          config
 322 @TYPE2@         FcPattern *                     @ARG2@          pat
 323 @TYPE3@         FcPattern *                     @ARG3@          font
 324 @PURPOSE@       Prepare pattern for loading font file
 325 @DESC@
 326 Creates a new pattern consisting of elements of <parameter>font</parameter> not appearing
 327 in <parameter>pat</parameter>, elements of <parameter>pat</parameter> not appearing in <parameter>font</parameter> and the best matching
 328 value from <parameter>pat</parameter> for elements appearing in both.  The result is passed to
 329 FcConfigSubstituteWithPat with <parameter>kind</parameter> FcMatchFont and then returned.
 330 @@
 331
 332 @RET@           FcFontSet *
 333 @FUNC@          FcFontList
 334 @TYPE1@         FcConfig *                      @ARG1@          config
 335 @TYPE2@         FcPattern *                     @ARG2@          p
 336 @TYPE3@         FcObjectSet *                   @ARG3@          os
 337 @PURPOSE@       List fonts
 338 @DESC@
 339 Selects fonts matching <parameter>p</parameter>, creates patterns from those fonts containing
 340 only the objects in <parameter>os</parameter> and returns the set of unique such patterns.
 341 If <parameter>config</parameter> is NULL, the default configuration is checked
 342 to be up to date, and used.
 343 @@
 344
 345 @RET@           FcChar8 *
 346 @FUNC@          FcConfigFilename
 347 @TYPE1@         const FcChar8 *                 @ARG1@          name
 348 @PURPOSE@       Find a config file
 349 @DESC@
 350 Given the specified external entity name, return the associated filename.
 351 This provides applications a way to convert various configuration file
 352 references into filename form.
 353     </para><para>
 354 A null or empty <parameter>name</parameter> indicates that the default configuration file should
 355 be used; which file this references can be overridden with the
 356 FONTCONFIG_FILE environment variable.  Next, if the name starts with <parameter>~</parameter>, it
 357 refers to a file in the current users home directory.  Otherwise if the name
 358 doesn't start with '/', it refers to a file in the default configuration
 359 directory; the built-in default directory can be overridden with the
 360 FONTCONFIG_PATH environment variable.
 361 @@
 362
 363 @RET@           FcBool
 364 @FUNC@          FcConfigParseAndLoad
 365 @TYPE1@         FcConfig *                      @ARG1@          config
 366 @TYPE2@         const FcChar8 *                 @ARG2@          file
 367 @TYPE3@         FcBool%                         @ARG3@          complain
 368 @PURPOSE@       load a configuration file
 369 @DESC@
 370 Walks the configuration in 'file' and constructs the internal representation
 371 in 'config'.  Any include files referenced from within 'file' will be loaded
 372 and parsed.  If 'complain' is FcFalse, no warning will be displayed if
 373 'file' does not exist. Error and warning messages will be output to stderr.
 374 Returns FcFalse if some error occurred while loading the file, either a
 375 parse error, semantic error or allocation failure. Otherwise returns FcTrue.
 376 @@
 377
 378 @RET@           const FcChar8 *
 379 @FUNC@          FcConfigGetSysRoot
 380 @TYPE1@         const FcConfig *                @ARG1@          config
 381 @PURPOSE@       Obtain the system root directory
 382 @DESC@
 383 Obtrains the system root directory in 'config' if available.
 384 @SINCE@         2.10.92
 385 @@
 386
 387 @RET@           void
 388 @FUNC@          FcConfigSetSysRoot
 389 @TYPE1@         FcConfig *                      @ARG1@          config
 390 @TYPE2@         const FcChar8 *                 @ARG2@          sysroot
 391 @PURPOSE@       Set the system root directory
 392 @DESC@
 393 Set 'sysroot' as the system root directory. fontconfig prepend 'sysroot'
 394 to the cache directories in order to allow people to generate caches at
 395 the build time. Note that this causes changing current config. i.e.
 396 this function calls FcConfigSetCurrent() internally.
 397 @SINCE@         2.10.92
 398 @@
 399