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