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     </para><para>
 178 This function isn't MT-safe. <function>FcConfigReference</function> must be called
 179 before using this and then <function>FcConfigDestroy</function> when
 180 the return value is no longer referenced.
 181 @@
 182
 183 @RET@           FcBlanks *
 184 @FUNC@          FcConfigGetBlanks
 185 @TYPE1@         FcConfig *                      @ARG1@          config
 186 @PURPOSE@       Get config blanks
 187 @DESC@
 188 FcBlanks is deprecated.
 189 This function always returns NULL.
 190 @@
 191
 192 @RET@           int
 193 @FUNC@          FcConfigGetRescanInterval
 194 @TYPE1@         FcConfig *                      @ARG1@          config
 195 @PURPOSE@       Get config rescan interval
 196 @DESC@
 197 Returns the interval between automatic checks of the configuration (in
 198 seconds) specified in <parameter>config</parameter>.  The configuration is checked during
 199 a call to FcFontList when this interval has passed since the last check.
 200 An interval setting of zero disables automatic checks.
 201 If <parameter>config</parameter> is NULL, the current configuration is used.
 202 @@
 203
 204 @RET@           FcBool
 205 @FUNC@          FcConfigSetRescanInterval
 206 @TYPE1@         FcConfig *                      @ARG1@          config
 207 @TYPE2@         int%                            @ARG2@          rescanInterval
 208 @PURPOSE@       Set config rescan interval
 209 @DESC@
 210 Sets the rescan interval. Returns FcFalse if the interval cannot be set (due
 211 to allocation failure). Otherwise returns FcTrue.
 212 An interval setting of zero disables automatic checks.
 213 If <parameter>config</parameter> is NULL, the current configuration is used.
 214 @@
 215
 216 @RET@           FcBool
 217 @FUNC@          FcConfigAppFontAddFile
 218 @TYPE1@         FcConfig *                      @ARG1@          config
 219 @TYPE2@         const FcChar8 *                 @ARG2@          file
 220 @PURPOSE@       Add font file to font database
 221 @DESC@
 222 Adds an application-specific font to the configuration. Returns FcFalse
 223 if the fonts cannot be added (due to allocation failure or no fonts found).
 224 Otherwise returns FcTrue. If <parameter>config</parameter> is NULL,
 225 the current configuration is used.
 226 @@
 227
 228 @RET@           FcBool
 229 @FUNC@          FcConfigAppFontAddDir
 230 @TYPE1@         FcConfig *                      @ARG1@          config
 231 @TYPE2@         const FcChar8 *                 @ARG2@          dir
 232 @PURPOSE@       Add fonts from directory to font database
 233 @DESC@
 234 Scans the specified directory for fonts, adding each one found to the
 235 application-specific set of fonts. Returns FcFalse
 236 if the fonts cannot be added (due to allocation failure).
 237 Otherwise returns FcTrue. If <parameter>config</parameter> is NULL,
 238 the current configuration is used.
 239 @@
 240
 241 @RET@           void
 242 @FUNC@          FcConfigAppFontClear
 243 @TYPE1@         FcConfig *                      @ARG1@          config
 244 @PURPOSE@       Remove all app fonts from font database
 245 @DESC@
 246 Clears the set of application-specific fonts.
 247 If <parameter>config</parameter> is NULL, the current configuration is used.
 248 @@
 249
 250 @RET@           FcBool
 251 @FUNC@          FcConfigSubstituteWithPat
 252 @TYPE1@         FcConfig *                      @ARG1@          config
 253 @TYPE2@         FcPattern *                     @ARG2@          p
 254 @TYPE3@         FcPattern *                     @ARG3@          p_pat
 255 @TYPE4@         FcMatchKind%                     @ARG4@          kind
 256 @PURPOSE@       Execute substitutions
 257 @DESC@
 258 Performs the sequence of pattern modification operations, if <parameter>kind</parameter> is
 259 FcMatchPattern, then those tagged as pattern operations are applied, else
 260 if <parameter>kind</parameter> is FcMatchFont, those tagged as font operations are applied and
 261 p_pat is used for &lt;test&gt; elements with target=pattern. Returns FcFalse
 262 if the substitution cannot be performed (due to allocation failure). Otherwise returns FcTrue.
 263 If <parameter>config</parameter> is NULL, the current configuration is used.
 264 @@
 265
 266 @RET@           FcBool
 267 @FUNC@          FcConfigSubstitute
 268 @TYPE1@         FcConfig *                      @ARG1@          config
 269 @TYPE2@         FcPattern *                     @ARG2@          p
 270 @TYPE3@         FcMatchKind%                    @ARG3@          kind
 271 @PURPOSE@       Execute substitutions
 272 @DESC@
 273 Calls FcConfigSubstituteWithPat setting p_pat to NULL. Returns FcFalse
 274 if the substitution cannot be performed (due to allocation failure). Otherwise returns FcTrue.
 275 If <parameter>config</parameter> is NULL, the current configuration is used.
 276 @@
 277
 278 @RET@           FcPattern *
 279 @FUNC@          FcFontMatch
 280 @TYPE1@         FcConfig *                      @ARG1@          config
 281 @TYPE2@         FcPattern *                     @ARG2@          p
 282 @TYPE3@         FcResult *                      @ARG3@          result
 283 @PURPOSE@       Return best font
 284 @DESC@
 285 Finds the font in <parameter>sets</parameter> most closely matching
 286 <parameter>pattern</parameter> and returns the result of
 287 <function>FcFontRenderPrepare</function> for that font and the provided
 288 pattern. This function should be called only after
 289 <function>FcConfigSubstitute</function> and
 290 <function>FcDefaultSubstitute</function> have been called for
 291 <parameter>p</parameter>; otherwise the results will not be correct.
 292 If <parameter>config</parameter> is NULL, the current configuration is used.
 293 @@
 294
 295 @RET@           FcFontSet *
 296 @FUNC@          FcFontSort
 297 @TYPE1@         FcConfig *                      @ARG1@          config
 298 @TYPE2@         FcPattern *                     @ARG2@          p
 299 @TYPE3@         FcBool%                         @ARG3@          trim
 300 @TYPE4@         FcCharSet **                    @ARG4@          csp
 301 @TYPE5@         FcResult *                      @ARG5@          result
 302 @PURPOSE@       Return list of matching fonts
 303 @DESC@
 304 Returns the list of fonts sorted by closeness to <parameter>p</parameter>.  If <parameter>trim</parameter> is FcTrue,
 305 elements in the list which don't include Unicode coverage not provided by
 306 earlier elements in the list are elided.  The union of Unicode coverage of
 307 all of the fonts is returned in <parameter>csp</parameter>, if <parameter>csp</parameter> is not NULL.  This function
 308 should be called only after FcConfigSubstitute and FcDefaultSubstitute have
 309 been called for <parameter>p</parameter>; otherwise the results will not be correct.
 310     </para><para>
 311 The returned FcFontSet references FcPattern structures which may be shared
 312 by the return value from multiple FcFontSort calls, applications must not
 313 modify these patterns.  Instead, they should be passed, along with <parameter>p</parameter> to
 314 <function>FcFontRenderPrepare</function> which combines them into a complete pattern.
 315     </para><para>
 316 The FcFontSet returned by FcFontSort is destroyed by calling FcFontSetDestroy.
 317 If <parameter>config</parameter> is NULL, the current configuration is used.
 318 @@
 319
 320 @RET@           FcPattern *
 321 @FUNC@          FcFontRenderPrepare
 322 @TYPE1@         FcConfig *                      @ARG1@          config
 323 @TYPE2@         FcPattern *                     @ARG2@          pat
 324 @TYPE3@         FcPattern *                     @ARG3@          font
 325 @PURPOSE@       Prepare pattern for loading font file
 326 @DESC@
 327 Creates a new pattern consisting of elements of <parameter>font</parameter> not appearing
 328 in <parameter>pat</parameter>, elements of <parameter>pat</parameter> not appearing in <parameter>font</parameter> and the best matching
 329 value from <parameter>pat</parameter> for elements appearing in both.  The result is passed to
 330 FcConfigSubstituteWithPat with <parameter>kind</parameter> FcMatchFont and then returned.
 331 @@
 332
 333 @RET@           FcFontSet *
 334 @FUNC@          FcFontList
 335 @TYPE1@         FcConfig *                      @ARG1@          config
 336 @TYPE2@         FcPattern *                     @ARG2@          p
 337 @TYPE3@         FcObjectSet *                   @ARG3@          os
 338 @PURPOSE@       List fonts
 339 @DESC@
 340 Selects fonts matching <parameter>p</parameter>, creates patterns from those fonts containing
 341 only the objects in <parameter>os</parameter> and returns the set of unique such patterns.
 342 If <parameter>config</parameter> is NULL, the default configuration is checked
 343 to be up to date, and used.
 344 @@
 345
 346 @RET@           FcChar8 *
 347 @FUNC@          FcConfigFilename
 348 @TYPE1@         const FcChar8 *                 @ARG1@          name
 349 @PURPOSE@       Find a config file
 350 @DESC@
 351 This function is deprecated and is replaced by <function>FcConfigGetFilename</function>.
 352 @@
 353
 354 @RET@           FcChar8 *
 355 @FUNC@          FcConfigGetFilename
 356 @TYPE1@         FcConfig *                      @ARG1@          config
 357 @TYPE2@         const FcChar8 *                 @ARG2@          name
 358 @PURPOSE@       Find a config file
 359 @DESC@
 360 Given the specified external entity name, return the associated filename.
 361 This provides applications a way to convert various configuration file
 362 references into filename form.
 363     </para><para>
 364 A null or empty <parameter>name</parameter> indicates that the default configuration file should
 365 be used; which file this references can be overridden with the
 366 FONTCONFIG_FILE environment variable.  Next, if the name starts with <parameter>~</parameter>, it
 367 refers to a file in the current users home directory.  Otherwise if the name
 368 doesn't start with '/', it refers to a file in the default configuration
 369 directory; the built-in default directory can be overridden with the
 370 FONTCONFIG_PATH environment variable.
 371     </para><para>
 372 The result of this function is affected by the FONTCONFIG_SYSROOT environment variable or equivalent functionality.
 373 @@
 374
 375 @RET@           FcBool
 376 @FUNC@          FcConfigParseAndLoad
 377 @TYPE1@         FcConfig *                      @ARG1@          config
 378 @TYPE2@         const FcChar8 *                 @ARG2@          file
 379 @TYPE3@         FcBool%                         @ARG3@          complain
 380 @PURPOSE@       load a configuration file
 381 @DESC@
 382 Walks the configuration in 'file' and constructs the internal representation
 383 in 'config'.  Any include files referenced from within 'file' will be loaded
 384 and parsed.  If 'complain' is FcFalse, no warning will be displayed if
 385 'file' does not exist. Error and warning messages will be output to stderr.
 386 Returns FcFalse if some error occurred while loading the file, either a
 387 parse error, semantic error or allocation failure. Otherwise returns FcTrue.
 388 @@
 389
 390 @RET@           FcBool
 391 @FUNC@          FcConfigParseAndLoadFromMemory
 392 @TYPE1@         FcConfig *                      @ARG1@          config
 393 @TYPE2@         const FcChar8 *                 @ARG2@          buffer
 394 @TYPE3@         FcBool%                         @ARG3@          complain
 395 @PURPOSE@       load a configuration from memory
 396 @DESC@
 397 Walks the configuration in 'memory' and constructs the internal representation
 398 in 'config'.  Any includes files referenced from within 'memory' will be loaded
 399 and dparsed.  If 'complain' is FcFalse, no warning will be displayed if
 400 'file' does not exist. Error and warning messages will be output to stderr.
 401 Returns FcFalse if fsome error occurred while loading the file, either a
 402 parse error, semantic error or allocation failure. Otherwise returns FcTrue.
 403 @SINCE@         2.12.5
 404 @@
 405
 406 @RET@           const FcChar8 *
 407 @FUNC@          FcConfigGetSysRoot
 408 @TYPE1@         const FcConfig *                @ARG1@          config
 409 @PURPOSE@       Obtain the system root directory
 410 @DESC@
 411 Obtains the system root directory in 'config' if available. All files
 412 (including file properties in patterns) obtained from this 'config' are
 413 relative to this system root directory.
 414     </para><para>
 415 This function isn't MT-safe. <function>FcConfigReference</function> must be called
 416 before using this and then <function>FcConfigDestroy</function> when
 417 the return value is no longer referenced.
 418 @SINCE@         2.10.92
 419 @@
 420
 421 @RET@           void
 422 @FUNC@          FcConfigSetSysRoot
 423 @TYPE1@         FcConfig *                      @ARG1@          config
 424 @TYPE2@         const FcChar8 *                 @ARG2@          sysroot
 425 @PURPOSE@       Set the system root directory
 426 @DESC@
 427 Set 'sysroot' as the system root directory. All file paths used or created with
 428 this 'config' (including file properties in patterns) will be considered or
 429 made relative to this 'sysroot'. This allows a host to generate caches for
 430 targets at build time. This also allows a cache to be re-targeted to a
 431 different base directory if 'FcConfigGetSysRoot' is used to resolve file paths.
 432 When setting this on the current config this causes changing current config
 433 (calls FcConfigSetCurrent()).
 434 @SINCE@         2.10.92
 435 @@
 436
 437 @RET@           void
 438 @FUNC@          FcConfigFileInfoIterInit
 439 @TYPE1@         FcConfig *                      @ARG1@          config
 440 @TYPE2@         FcConfigFileInfoIter *          @ARG2@          iter
 441 @PURPOSE@       Initialize the iterator
 442 @DESC@
 443 Initialize 'iter' with the first iterator in the config file information list.
 444     </para><para>
 445 The config file information list is stored in numerical order for filenames
 446 i.e. how fontconfig actually read them.
 447     </para><para>
 448 This function isn't MT-safe. <function>FcConfigReference</function> must be called
 449 before using this and then <function>FcConfigDestroy</function> when the relevant
 450 values are no longer referenced.
 451 @SINCE@         2.12.91
 452 @@
 453
 454 @RET@           FcBool
 455 @FUNC@          FcConfigFileInfoIterNext
 456 @TYPE1@         FcConfig *                      @ARG1@          config
 457 @TYPE2@         FcConfigFileInfoIter *          @ARG2@          iter
 458 @PURPOSE@       Set the iterator to point to the next list
 459 @DESC@
 460 Set 'iter' to point to the next node in the config file information list.
 461 If there is no next node, FcFalse is returned.
 462     </para><para>
 463 This function isn't MT-safe. <function>FcConfigReference</function> must be called
 464 before using <function>FcConfigFileInfoIterInit</function> and then
 465 <function>FcConfigDestroy</function> when the relevant values are no longer referenced.
 466 @SINCE@         2.12.91
 467 @@
 468
 469 @RET@           FcBool
 470 @FUNC@          FcConfigFileInfoIterGet
 471 @TYPE1@         FcConfig *                      @ARG1@          config
 472 @TYPE2@         FcConfigFileInfoIter *          @ARG2@          iter
 473 @TYPE3@         FcChar8 **                      @ARG3@          name
 474 @TYPE4@         FcChar8 **                      @ARG4@          description
 475 @TYPE5@         FcBool *                        @ARG5@          enabled
 476 @PURPOSE@       Obtain the configuration file information
 477 @DESC@
 478 Obtain the filename, the description and the flag whether it is enabled or not
 479 for 'iter' where points to current configuration file information.
 480 If the iterator is invalid, FcFalse is returned.
 481     </para><para>
 482 This function isn't MT-safe. <function>FcConfigReference</function> must be called
 483 before using <function>FcConfigFileInfoIterInit</function> and then
 484 <function>FcConfigDestroy</function> when the relevant values are no longer referenced.
 485 @SINCE@         2.12.91
 486 @@