doc/fcconfig.fncs

   1 /*
   2  * $Id$
   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  * KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
  17  * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
  18  * EVENT SHALL KEITH PACKARD 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@           void
  33 @FUNC@          FcConfigDestroy
  34 @TYPE1@         FcConfig *                      @ARG1@          config
  35 @PURPOSE@       Destroy a configuration
  36 @DESC@
  37 Destroys a configuration and any data associated with it.  Note that calling
  38 this function with the return from FcConfigGetCurrent will place the library
  39 in an indeterminate state.
  40 @@
  41
  42 @RET@           FcBool
  43 @FUNC@          FcConfigSetCurrent
  44 @TYPE1@         FcConfig *                      @ARG1@          config
  45 @PURPOSE@       Set configuration as default
  46 @DESC@
  47 Sets the current default configuration to <parameter>config</parameter>.  Implicitly calls
  48 FcConfigBuildFonts if necessary, returning FcFalse if that call fails.
  49 @@
  50
  51 @RET@           FcConfig *
  52 @FUNC@          FcConfigGetCurrent
  53 @TYPE1@         void
  54 @PURPOSE@       Return current configuration
  55 @DESC@
  56 Returns the current default configuration.
  57 @@
  58
  59 @RET@           FcBool
  60 @FUNC@          FcConfigUptoDate
  61 @TYPE1@         FcConfig *                      @ARG1@          config
  62 @PURPOSE@       Check timestamps on config files
  63 @DESC@
  64 Checks all of the files related to <parameter>config</parameter> and returns
  65 whether any of them has been modified since the configuration was created.
  66 @@
  67
  68 @RET@           FcBool
  69 @FUNC@          FcConfigBuildFonts
  70 @TYPE1@         FcConfig *                      @ARG1@          config
  71 @PURPOSE@       Build font database
  72 @DESC@
  73 Builds the set of available fonts for the given configuration.  Note that
  74 any changes to the configuration after this call have indeterminate effects.
  75 Returns FcFalse if this operation runs out of memory.
  76 @@
  77
  78 @RET@           FcStrList *
  79 @FUNC@          FcConfigGetConfigDirs
  80 @TYPE1@         FcConfig *                      @ARG1@          config
  81 @PURPOSE@       Get config directories
  82 @DESC@
  83 Returns the list of font directories specified in the configuration files
  84 for <parameter>config</parameter>.  Does not include any subdirectories.
  85 @@
  86
  87 @RET@           FcStrList *
  88 @FUNC@          FcConfigGetFontDirs
  89 @TYPE1@         FcConfig *                      @ARG1@          config
  90 @PURPOSE@       Get font directories
  91 @DESC@
  92 Returns the list of font directories in <parameter>config</parameter>. This includes the
  93 configured font directories along with any directories below those in the
  94 filesystem.
  95 @@
  96
  97 @RET@           FcStrList *
  98 @FUNC@          FcConfigGetConfigFiles
  99 @TYPE1@         FcConfig *                      @ARG1@          config
 100 @PURPOSE@       Get config files
 101 @DESC@
 102 Returns the list of known configuration files used to generate <parameter>config</parameter>.
 103 Note that this will not include any configuration done with FcConfigParse.
 104 @@
 105
 106 @RET@           char *
 107 @FUNC@          FcConfigGetCache
 108 @TYPE1@         FcConfig *                      @ARG1@          config
 109 @PURPOSE@       Get cache filename
 110 @DESC@
 111 Returns the name of the file used to store per-user font information.
 112 @@
 113
 114 @RET@           FcFontSet *
 115 @FUNC@          FcConfigGetFonts
 116 @TYPE1@         FcConfig *                      @ARG1@          config
 117 @TYPE2@         FcSetName%                      @ARG2@          set
 118 @PURPOSE@       Get config font set
 119 @DESC@
 120 Returns one of the two sets of fonts from the configuration as specified
 121 by <parameter>set</parameter>.
 122 @@
 123
 124 @RET@           FcBlanks *
 125 @FUNC@          FcConfigGetBlanks
 126 @TYPE1@         FcConfig *                      @ARG1@          config
 127 @PURPOSE@       Get config blanks
 128 @DESC@
 129 Returns the FcBlanks object associated with the given configuration, if no
 130 blanks were present in the configuration, this function will return 0.
 131 @@
 132
 133 @RET@           int
 134 @FUNC@          FcConfigGetRescanInterval
 135 @TYPE1@         FcConfig *                      @ARG1@          config
 136 @PURPOSE@       Get config rescan interval
 137 @DESC@
 138 Returns the interval between automatic checks of the configuration (in
 139 seconds) specified in <parameter>config</parameter>.  The configuration is checked during
 140 a call to FcFontList when this interval has passed since the last check.
 141 @@
 142
 143 @RET@           FcBool
 144 @FUNC@          FcConfigSetRescanInterval
 145 @TYPE1@         FcConfig *                      @ARG1@          config
 146 @TYPE2@         int%                            @ARG2@          rescanInterval
 147 @PURPOSE@       Set config rescan interval
 148 @DESC@
 149 Sets the rescan interval; returns FcFalse if an error occurred.
 150 @@
 151
 152 @RET@           FcBool
 153 @FUNC@          FcConfigAppFontAddFile
 154 @TYPE1@         FcConfig *                      @ARG1@          config
 155 @TYPE2@         const char *                    @ARG2@          file
 156 @PURPOSE@       Add font file to font database
 157 @DESC@
 158 Adds an application-specific font to the configuration.
 159 @@
 160
 161 @RET@           FcBool
 162 @FUNC@          FcConfigAppFontAddDir
 163 @TYPE1@         FcConfig *                      @ARG1@          config
 164 @TYPE2@         const char *                    @ARG1@          dir
 165 @PURPOSE@       Add fonts from directory to font database
 166 @DESC@
 167 Scans the specified directory for fonts, adding each one found to the
 168 application-specific set of fonts.
 169 @@
 170
 171 @RET@           void
 172 @FUNC@          FcConfigAppFontClear
 173 @TYPE1@         FcConfig *                      @ARG1@          config
 174 @PURPOSE@       Remove all app fonts from font database
 175 @DESC@
 176 Clears the set of application-specific fonts.
 177 @@
 178
 179 @RET@           FcBool
 180 @FUNC@          FcConfigSubstituteWithPat
 181 @TYPE1@         FcConfig *                      @ARG1@          config
 182 @TYPE2@         FcPattern *                     @ARG2@          p
 183 @TYPE3@         FcPattern *                     @ARG3@          p_pat
 184 @TYPE4@         FcMatchKind%                     @ARG4@          kind
 185 @PURPOSE@       Execute substitutions
 186 @DESC@
 187 Performs the sequence of pattern modification operations, if <parameter>kind</parameter> is
 188 FcMatchPattern, then those tagged as pattern operations are applied, else
 189 if <parameter>kind</parameter> is FcMatchFont, those tagged as font operations are applied and
 190 p_pat is used for &lt;test&gt; elements with target=pattern.
 191 @@
 192
 193 @RET@           FcBool
 194 @FUNC@          FcConfigSubstitute
 195 @TYPE1@         FcConfig *                      @ARG1@          config
 196 @TYPE2@         FcPattern *                     @ARG2@          p
 197 @TYPE3@         FcMatchKind%                    @ARG3@          kind
 198 @PURPOSE@       Execute substitutions
 199 @DESC@
 200 Calls FcConfigSubstituteWithPat setting p_pat to NULL.
 201 @@
 202
 203 @RET@           FcPattern *
 204 @FUNC@          FcFontMatch
 205 @TYPE1@         FcConfig *                      @ARG1@          config
 206 @TYPE2@         FcPattern *                     @ARG2@          p
 207 @TYPE3@         FcResult *                      @ARG3@          result
 208 @PURPOSE@       Return best font
 209 @DESC@
 210 Returns the font in <parameter>config</parameter> most close matching <parameter>p</parameter>.  This function
 211 should be called only after FcConfigSubstitute and FcDefaultSubstitute have
 212 been called for <parameter>p</parameter>; otherwise the results will not be correct.
 213 @@
 214
 215 @RET@           FcFontSet *
 216 @FUNC@          FcFontSort
 217 @TYPE1@         FcConfig *                      @ARG1@          config
 218 @TYPE2@         FcPattern *                     @ARG2@          p
 219 @TYPE3@         FcBool%                         @ARG3@          trim
 220 @TYPE4@         FcCharSet **                    @ARG4@          csp
 221 @TYPE5@         FcResult *                      @ARG5@          result
 222 @PURPOSE@       Return list of matching fonts
 223 @DESC@
 224 Returns the list of fonts sorted by closeness to <parameter>p</parameter>.  If <parameter>trim</parameter> is FcTrue,
 225 elements in the list which don't include Unicode coverage not provided by
 226 earlier elements in the list are elided.  The union of Unicode coverage of
 227 all of the fonts is returned in <parameter>csp</parameter>, if <parameter>csp</parameter> is not NULL.  This function
 228 should be called only after FcConfigSubstitute and FcDefaultSubstitute have
 229 been called for <parameter>p</parameter>; otherwise the results will not be correct.
 230     </para><para>
 231 The returned FcFontSet references FcPattern structures which may be shared
 232 by the return value from multiple FcFontSort calls, applications must not
 233 modify these patterns.  Instead, they should be passed, along with <parameter>p</parameter> to
 234 FcFontRenderPrepare which combines them into a complete pattern.
 235     </para><para>
 236 The FcFontSet returned by FcFontSort is destroyed by caling FcFontSetDestroy.
 237 @@
 238
 239 @RET@           FcPattern *
 240 @FUNC@          FcFontRenderPrepare
 241 @TYPE1@         FcConfig *                      @ARG1@          config
 242 @TYPE2@         FcPattern *                     @ARG2@          pat
 243 @TYPE3@         FcPattern *                     @ARG3@          font
 244 @PURPOSE@       Prepare pattern for loading font file
 245 @DESC@
 246 Creates a new pattern consisting of elements of <parameter>font</parameter> not appearing
 247 in <parameter>pat</parameter>, elements of <parameter>pat</parameter> not appearing in <parameter>font</parameter> and the best matching
 248 value from <parameter>pat</parameter> for elements appearing in both.  The result is passed to
 249 FcConfigSubstitute with <parameter>kind</parameter> FcMatchFont and then returned.
 250 @@
 251
 252 @RET@           FcFontSet *
 253 @FUNC@          FcFontList
 254 @TYPE1@         FcConfig *                      @ARG1@          config
 255 @TYPE2@         FcPattern *                     @ARG2@          p
 256 @TYPE3@         FcObjectSet *                   @ARG3@          os
 257 @PURPOSE@       List fonts
 258 @DESC@
 259 Selects fonts matching <parameter>p</parameter>, creates patterns from those fonts containing
 260 only the objects in <parameter>os</parameter> and returns the set of unique such patterns.
 261 @@
 262
 263 @RET@           char *
 264 @FUNC@          FcConfigFilename
 265 @TYPE1@         const char *                    @ARG1@          name
 266 @PURPOSE@       Find a config file
 267 @DESC@
 268 Given the specified external entity name, return the associated filename.
 269 This provides applications a way to convert various configuration file
 270 references into filename form.
 271     </para><para>
 272 A null or empty <parameter>name</parameter> indicates that the default configuration file should
 273 be used; which file this references can be overridden with the
 274 FC_CONFIG_FILE environment variable.  Next, if the name starts with <parameter>~</parameter>, it
 275 refers to a file in the current users home directory.  Otherwise if the name
 276 doesn't start with '/', it refers to a file in the default configuration
 277 directory; the built-in default directory can be overridden with the
 278 FC_CONFIG_DIR environment variable.
 279 @@
 280
 281 @RET@           FcBool
 282 @FUNC@          FcConfigParseAndLoad
 283 @TYPE1@         FcConfig *                      @ARG1@          config
 284 @TYPE2@         const FcChar8 *                 @ARG2@          file
 285 @TYPE3@         FcBool%                         @ARG3@          complain
 286 @PURPOSE@       load a configuration file
 287 @DESC@
 288 Walks the configuration in 'file' and constructs the internal representation
 289 in 'config'.  Any include files referenced from within 'file' will be loaded
 290 with FcConfigLoad and also parsed.  If 'complain' is FcFalse, no warning
 291 will be displayed if 'file' does not exist.
 292 @@