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 Keith Packard not be used in
  11  * advertising or publicity pertaining to distribution of the software without
  12  * specific, written prior permission.  Keith Packard makes 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, returning FcFalse if that call fails.
  63 @@
  64
  65 @RET@           FcConfig *
  66 @FUNC@          FcConfigGetCurrent
  67 @TYPE1@         void
  68 @PURPOSE@       Return current configuration
  69 @DESC@
  70 Returns the current default configuration.
  71 @@
  72
  73 @RET@           FcBool
  74 @FUNC@          FcConfigUptoDate
  75 @TYPE1@         FcConfig *                      @ARG1@          config
  76 @PURPOSE@       Check timestamps on config files
  77 @DESC@
  78 Checks all of the files related to <parameter>config</parameter> and returns
  79 whether any of them has been modified since the configuration was created.
  80 If <parameter>config</parameter> is NULL, the current configuration is used.
  81 @@
  82
  83 @RET@           FcChar8 *
  84 @FUNC@          FcConfigHome
  85 @TYPE1@         void
  86 @PURPOSE@       return the current home directory.
  87 @DESC@
  88 Return the current user's home directory, if it is available, and if using it
  89 is enabled, and NULL otherwise.
  90 See also <function>FcConfigEnableHome</function>).
  91 @@
  92
  93 @RET@           FcBol
  94 @FUNC@          FcConfigEnableHome
  95 @TYPE1@         FcBool%                         @ARG1@          enable
  96 @PURPOSE@       controls use of the home directory.
  97 @DESC@
  98 If <parameter>enable</parameter> is FcTrue, then Fontconfig will use various
  99 files which are specified relative to the user's home directory (using the ~
 100 notation in the configuration). When <parameter>enable</parameter> is
 101 FcFalse, then all use of the home directory in these contexts will be
 102 disabled. The previous setting of the value is returned.
 103 @@
 104
 105 @RET@           FcBool
 106 @FUNC@          FcConfigBuildFonts
 107 @TYPE1@         FcConfig *                      @ARG1@          config
 108 @PURPOSE@       Build font database
 109 @DESC@
 110 Builds the set of available fonts for the given configuration.  Note that
 111 any changes to the configuration after this call have indeterminate effects.
 112 Returns FcFalse if this operation runs out of memory.
 113 If <parameter>config</parameter> is NULL, the current configuration is used.
 114 @@
 115
 116 @RET@           FcStrList *
 117 @FUNC@          FcConfigGetConfigDirs
 118 @TYPE1@         FcConfig *                      @ARG1@          config
 119 @PURPOSE@       Get config directories
 120 @DESC@
 121 Returns the list of font directories specified in the configuration files
 122 for <parameter>config</parameter>.  Does not include any subdirectories.
 123 If <parameter>config</parameter> is NULL, the current configuration is used.
 124 @@
 125
 126 @RET@           FcStrList *
 127 @FUNC@          FcConfigGetFontDirs
 128 @TYPE1@         FcConfig *                      @ARG1@          config
 129 @PURPOSE@       Get font directories
 130 @DESC@
 131 Returns the list of font directories in <parameter>config</parameter>. This includes the
 132 configured font directories along with any directories below those in the
 133 filesystem.
 134 If <parameter>config</parameter> is NULL, the current configuration is used.
 135 @@
 136
 137 @RET@           FcStrList *
 138 @FUNC@          FcConfigGetConfigFiles
 139 @TYPE1@         FcConfig *                      @ARG1@          config
 140 @PURPOSE@       Get config files
 141 @DESC@
 142 Returns the list of known configuration files used to generate <parameter>config</parameter>.
 143 If <parameter>config</parameter> is NULL, the current configuration is used.
 144 @@
 145
 146 @RET@           FcChar8 *
 147 @FUNC@          FcConfigGetCache
 148 @TYPE1@         FcConfig *                      @ARG1@          config
 149 @PURPOSE@       DEPRECATED used to return per-user cache filename
 150 @DESC@
 151 With fontconfig no longer using per-user cache files, this function now
 152 simply returns NULL to indicate that no per-user file exists.
 153 @@
 154
 155 @RET@           FcStrList *
 156 @FUNC@          FcConfigGetCacheDirs
 157 @TYPE1@         FcConfig *                      @ARG1@          config
 158 @PURPOSE@       return the list of directories searched for cache files
 159 @DESC@
 160 <function>FcConfigGetCacheDirs</function> returns a string list containing
 161 all of the directories that fontconfig will search when attempting to load a
 162 cache file for a font directory.
 163 If <parameter>config</parameter> is NULL, the current configuration is used.
 164 @@
 165
 166 @RET@           FcFontSet *
 167 @FUNC@          FcConfigGetFonts
 168 @TYPE1@         FcConfig *                      @ARG1@          config
 169 @TYPE2@         FcSetName%                      @ARG2@          set
 170 @PURPOSE@       Get config font set
 171 @DESC@
 172 Returns one of the two sets of fonts from the configuration as specified
 173 by <parameter>set</parameter>. This font set is owned by the library and must
 174 not be modified or freed.
 175 If <parameter>config</parameter> is NULL, the current configuration is used.
 176 @@
 177
 178 @RET@           FcBlanks *
 179 @FUNC@          FcConfigGetBlanks
 180 @TYPE1@         FcConfig *                      @ARG1@          config
 181 @PURPOSE@       Get config blanks
 182 @DESC@
 183 Returns the FcBlanks object associated with the given configuration, if no
 184 blanks were present in the configuration, this function will return 0.
 185 The returned FcBlanks object if not NULL, is valid as long as the owning
 186 FcConfig is alive.
 187 If <parameter>config</parameter> is NULL, the current configuration is used.
 188 @@
 189
 190 @RET@           int
 191 @FUNC@          FcConfigGetRescanInterval
 192 @TYPE1@         FcConfig *                      @ARG1@          config
 193 @PURPOSE@       Get config rescan interval
 194 @DESC@
 195 Returns the interval between automatic checks of the configuration (in
 196 seconds) specified in <parameter>config</parameter>.  The configuration is checked during
 197 a call to FcFontList when this interval has passed since the last check.
 198 An interval setting of zero disables automatic checks.
 199 If <parameter>config</parameter> is NULL, the current configuration is used.
 200 @@
 201
 202 @RET@           FcBool
 203 @FUNC@          FcConfigSetRescanInterval
 204 @TYPE1@         FcConfig *                      @ARG1@          config
 205 @TYPE2@         int%                            @ARG2@          rescanInterval
 206 @PURPOSE@       Set config rescan interval
 207 @DESC@
 208 Sets the rescan interval. Returns FcFalse if the interval cannot be set (due
 209 to allocation failure). Otherwise returns FcTrue.
 210 An interval setting of zero disables automatic checks.
 211 If <parameter>config</parameter> is NULL, the current configuration is used.
 212 @@
 213
 214 @RET@           FcBool
 215 @FUNC@          FcConfigAppFontAddFile
 216 @TYPE1@         FcConfig *                      @ARG1@          config
 217 @TYPE2@         const FcChar8 *                 @ARG2@          file
 218 @PURPOSE@       Add font file to font database
 219 @DESC@
 220 Adds an application-specific font to the configuration. Returns FcFalse
 221 if the fonts cannot be added (due to allocation failure). Otherwise returns FcTrue.
 222 If <parameter>config</parameter> is NULL, the current configuration is used.
 223 @@
 224
 225 @RET@           FcBool
 226 @FUNC@          FcConfigAppFontAddDir
 227 @TYPE1@         FcConfig *                      @ARG1@          config
 228 @TYPE2@         const FcChar8 *                 @ARG2@          dir
 229 @PURPOSE@       Add fonts from directory to font database
 230 @DESC@
 231 Scans the specified directory for fonts, adding each one found to the
 232 application-specific set of fonts. Returns FcFalse
 233 if the fonts cannot be added (due to allocation failure). Otherwise returns FcTrue.
 234 If <parameter>config</parameter> is NULL, 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 caling 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 FC_CONFIG_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 FC_CONFIG_DIR 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 @@