doc/fontconfig-devel.sgml

   1 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
   2 <!--
   3     $Id$
   4
   5     Copyright © 2002 Keith Packard
   6
   7     Permission to use, copy, modify, distribute, and sell this software and its
   8     documentation for any purpose is hereby granted without fee, provided that
   9     the above copyright notice appear in all copies and that both that
  10     copyright notice and this permission notice appear in supporting
  11     documentation, and that the name of Keith Packard not be used in
  12     advertising or publicity pertaining to distribution of the software without
  13     specific, written prior permission.  Keith Packard makes no
  14     representations about the suitability of this software for any purpose.  It
  15     is provided "as is" without express or implied warranty.
  16
  17     KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
  18     INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
  19     EVENT SHALL KEITH PACKARD BE LIABLE FOR ANY SPECIAL, INDIRECT OR
  20     CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
  21     DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
  22     TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  23     PERFORMANCE OF THIS SOFTWARE.
  24 -->
  25 <article>
  26 <artheader>
  27   <title>Fontconfig Developers Guide</title>
  28   <titleabbrev>Fontconfig</titleabbrev>
  29   <author><firstname>Keith</><surname>Packard</></author>
  30   <authorinitials>krp</authorinitials>
  31 </artheader>
  32 <sect1><title>NAME</title>
  33   <para>
  34   fontconfig - Font configuration and customization library
  35   </para>
  36 </sect1>
  37 <sect1><title>SYNOPSIS</title>
  38   <programlisting>
  39   #include &lt;fontconfig/fontconfig.h&gt;
  40   #include &lt;fontconfig/fcfreetype.h&gt;
  41   </programlisting>
  42 </sect1>
  43 <sect1><title>DESCRIPTION</title>
  44   <para>
  45 Fontconfig is a library designed to provide system-wide font configuration,
  46 customization and application access.
  47   </para>
  48 </sect1>
  49 <sect1><title>FUNCTIONAL OVERVIEW</title>
  50   <para>
  51 Fontconfig contains two essential modules, the configuration module which
  52 builds an internal configuration from XML files and the matching module
  53 which accepts font patterns and returns the nearest matching font.
  54   </para>
  55   <sect2><title>FONT CONFIGURATION</title>
  56     <para>
  57 The configuration module consists of the FcConfig datatype, libexpat and
  58 FcConfigParse which walks over an XML tree and ammends a configuration with
  59 data found within.  From an external perspective, configuration of the
  60 library consists of generating a valid XML tree and feeding that to
  61 FcConfigParse.  The only other mechanism provided to applications for
  62 changing the running configuration is to add fonts and directories to the
  63 list of application-provided font files.
  64     </para><para>
  65 The intent is to make font configurations relatively static, and shared by
  66 as many applications as possible.  It is hoped that this will lead to more
  67 stable font selection when passing names from one application to another.
  68 XML was chosen as a configuration file format because it provides a format
  69 which is easy for external agents to edit while retaining the correct
  70 structure and syntax.
  71     </para><para>
  72 Font configuration is separate from font matching; applications needing to
  73 do their own matching can access the available fonts from the library and
  74 perform private matching.  The intent is to permit applications to pick and
  75 choose appropriate functionality from the library instead of forcing them to
  76 choose between this library and a private configuration mechanism.  The hope
  77 is that this will ensure that configuration of fonts for all applications
  78 can be centralized in one place.  Centralizing font configuration will
  79 simplify and regularize font installation and customization.
  80     </para>
  81   </sect2>
  82   <sect2>
  83     <title>FONT PROPERTIES</title>
  84     <para>
  85 While font patterns may contain essentially any properties, there are some
  86 well known properties with associated types.  Fontconfig uses some of these
  87 properties for font matching and font completion.  Others are provided as a
  88 convenience for the applications rendering mechanism.
  89     </para>
  90     <table>
  91       <title>Property Definitions</title>
  92         <tgroup cols=4 align=left colsep=1 rowsep=1>
  93         <colspec colname=Property>
  94         <colspec colname=CPP>
  95         <colspec colname=Type>
  96         <colspec colname=Description>
  97         <thead>
  98           <row>
  99             <entry>Property</entry>
 100             <entry>CPP Symbol</entry>
 101             <entry>Type</entry>
 102             <entry>Description</entry>
 103           </row>
 104         </thead>
 105         <tbody>
 106 <row><entry>family</entry><entry>FC_FAMILY</entry><entry>String</entry><entry>Font family name</entry></row>
 107 <row><entry>style</entry><entry>FC_STYLE</entry><entry>String</entry><entry>Font style. Overrides weight and slant</entry></row>
 108 <row><entry>slant</entry><entry>FC_SLANT</entry><entry>Int</entry><entry>Italic, oblique or roman</entry></row>
 109 <row><entry>weight</entry><entry>FC_WEIGHT</entry><entry>Int</entry><entry>Light, medium, demibold, bold or black</entry></row>
 110 <row><entry>size</entry><entry>FC_SIZE</entry><entry>Double</entry><entry>Point size</entry></row>
 111 <row><entry>aspect</entry><entry>FC_ASPECT</entry><entry>Double</entry><entry>Stretches glyphs horizontally before hinting</entry></row>
 112 <row><entry>pixelsize</entry><entry>FC_PIXEL_SIZE</entry><entry>Double</entry><entry>Pixel size</entry></row>
 113 <row><entry>spacing</entry><entry>FC_SPACING</entry><entry>Int</entry><entry>Proportional, monospace or charcell</entry></row>
 114 <row><entry>foundry</entry><entry>FC_FOUNDRY</entry><entry>String</entry><entry>Font foundry name</entry></row>
 115 <row><entry>antialias</entry><entry>FC_ANTIALIAS</entry><entry>Bool</entry><entry>Whether glyphs can be antialiased</entry></row>
 116 <row><entry>hinting</entry><entry>FC_HINTING</entry><entry>Bool</entry><entry>Whether the rasterizer should use hinting</entry></row>
 117 <row><entry>verticallayout</entry><entry>FC_VERTICAL_LAYOUT</entry><entry>Bool</entry><entry>Use vertical layout</entry></row>
 118 <row><entry>autohint</entry><entry>FC_AUTOHINT</entry><entry>Bool</entry><entry>Use autohinter instead of normal hinter</entry></row>
 119 <row><entry>globaladvance</entry><entry>FC_GLOBAL_ADVANCE</entry><entry>Bool</entry><entry>Use font global advance data</entry></row>
 120 <row><entry>file</entry><entry>FC_FILE</entry><entry>String</entry><entry>The filename holding the font</entry></row>
 121 <row><entry>index</entry><entry>FC_INDEX</entry><entry>Int</entry><entry>The index of the font within the file</entry></row>
 122 <row><entry>ftface</entry><entry>FC_FT_FACE</entry><entry>FT_Face</entry><entry>Use the specified FreeType face object</entry></row>
 123 <row><entry>rasterizer</entry><entry>FC_RASTERIZER</entry><entry>String</entry><entry>Which rasterizer is in use</entry></row>
 124 <row><entry>outline</entry><entry>FC_OUTLINE</entry><entry>Bool</entry><entry>Whether the glyphs are outlines</entry></row>
 125 <row><entry>scalable</entry><entry>FC_SCALABLE</entry><entry>Bool</entry><entry>Whether glyphs can be scaled</entry></row>
 126 <row><entry>scale</entry><entry>FC_SCALE</entry><entry>Double</entry><entry>Scale factor for point->pixel conversions</entry></row>
 127 <row><entry>dpi</entry><entry>FC_DPI</entry><entry>Double</entry><entry>Target dots per inch</entry></row>
 128 <row><entry>rgba</entry><entry>FC_RGBA</entry><entry>Int</entry><entry>unknown, rgb, bgr, vrgb, vbgr, none - subpixel geometry</entry></row>
 129 <row><entry>minspace</entry><entry>FC_MINSPACE</entry><entry>Bool</entry><entry>Eliminate leading from line spacing</entry></row>
 130 <row><entry>charset</entry><entry>FC_CHARSET</entry><entry>CharSet</entry><entry>Unicode chars encoded by the font</entry></row>
 131 <row><entry>lang</entry><entry>FC_LANG</entry><entry>String</entry><entry>List of RFC-3066-style languages this font supports</entry></row>
 132       </tbody>
 133       </tgroup>
 134     </table>
 135   </sect2>
 136 </sect1>
 137 <sect1><title>DATATYPES</title>
 138   <para>
 139 Fontconfig uses abstract datatypes to hide internal implementation details
 140 for most data structures.  A few structures are exposed where appropriate.
 141   </para>
 142   <sect2><title>FcChar8, FcChar16, FcChar32, FcBool</title>
 143   <para>
 144 These are primitive datatypes; the FcChar* types hold precisely the number
 145 of bits stated (if supported by the C implementation).  FcBool holds
 146 one of two CPP symbols: FcFalse or FcTrue.
 147   </para>
 148   </sect2>
 149   <sect2><title>FcMatrix</title>
 150     <para>
 151 An FcMatrix holds an affine transformation, usually used to reshape glyphs.
 152 A small set of matrix operations are provided to manipulate these.
 153     <programlisting>
 154         typedef struct _FcMatrix {
 155                 double xx, xy, yx, yy;
 156         } FcMatrix;
 157     </programlisting>
 158     </para>
 159   </sect2>
 160   <sect2>
 161     <title>FcCharSet</title>
 162     <para>
 163 An FcCharSet is an abstract type that holds the set of encoded unicode chars
 164 in a font.  Operations to build and compare these sets are provided.
 165     </para>
 166   </sect2>
 167   <sect2>
 168     <title>FcType</title>
 169     <para>
 170 Tags the kind of data stored in an FcValue.
 171     </para>
 172   </sect2>
 173   <sect2>
 174     <title>FcValue</title>
 175     <para>
 176 An FcValue object holds a single value with one of a number of different
 177 types.  The 'type' tag indicates which member is valid.
 178     <programlisting>
 179         typedef struct _FcValue {
 180                 FcType type;
 181                 union {
 182                         const FcChar8 *s;
 183                         int i;
 184                         FcBool b;
 185                         double d;
 186                         const FcMatrix *m;
 187                         const FcCharSet *c;
 188                 } u;
 189         } FcValue;
 190     </programlisting>
 191     <table colsep=0 rowsep=0>
 192       <title>FcValue Members</title>
 193       <tgroup cols=3 align=left colsep=0 rowsep=0>
 194         <thead><row>
 195           <entry>Type</entry>
 196           <entry>Union member</entry>
 197           <entry>Datatype</entry>
 198         </row></thead>
 199         <tbody>
 200 <row><entry>FcTypeVoid</entry><entry>(none)</entry><entry>(none)</entry></row>
 201 <row><entry>FcTypeInteger</entry><entry>i</entry><entry>int</entry></row>
 202 <row><entry>FcTypeDouble</entry><entry>d</entry><entry>double</entry></row>
 203 <row><entry>FcTypeString</entry><entry>s</entry><entry>char *</entry></row>
 204 <row><entry>FcTypeBool</entry><entry>b</entry><entry>b</entry></row>
 205 <row><entry>FcTypeMatrix</entry><entry>m</entry><entry>FcMatrix *</entry></row>
 206 <row><entry>FcTypeCharSet</entry><entry>c</entry><entry>FcCharSet *</entry></row>
 207         </tbody>
 208       </tgroup>
 209     </table>
 210     </para>
 211   </sect2>
 212   <sect2>
 213     <title>FcPattern</title>
 214     <para>
 215 holds a set of names with associated value lists; each name refers to a
 216 property of a font.  FcPatterns are used as inputs to the matching code as
 217 well as holding information about specific fonts.  Each property can hold
 218 one or more values; conventionally all of the same type, although the
 219 interface doesn't demand that.
 220     </para>
 221   </sect2>
 222   <sect2>
 223     <title>FcFontSet</title>
 224     <para>
 225     <programlisting>
 226         typedef struct _FcFontSet {
 227                 int nfont;
 228                 int sfont;
 229                 FcPattern **fonts;
 230         } FcFontSet;
 231     </programlisting>
 232 An FcFontSet contains a list of FcPatterns.  Internally fontconfig uses this
 233 data structure to hold sets of fonts.  Externally, fontconfig returns the
 234 results of listing fonts in this format.  'nfont' holds the number of
 235 patterns in the 'fonts' array; 'sfont' is used to indicate the size of that
 236 array.
 237     </para>
 238   </sect2>
 239   <sect2>
 240     <title>FcStrSet, FcStrList</title>
 241     <para>
 242 FcStrSet holds a list of strings that can be appended to and enumerated.
 243 Its unique characteristic is that the enumeration works even while strings
 244 are appended during enumeration.  FcStrList is used during enumeration to
 245 safely and correctly walk the list of strings even while that list is edited
 246 in the middle of enumeration.
 247     </para>
 248   </sect2>
 249   <sect2>
 250     <title>FcObjectSet</title>
 251     <para>
 252       <programlisting>
 253         typedef struct _FcObjectSet {
 254                 int nobject;
 255                 int sobject;
 256                 const char **objects;
 257         } FcObjectSet;
 258       </programlisting>
 259 holds a set of names and is used to specify which fields from fonts are
 260 placed in the the list of returned patterns when listing fonts.
 261     </para>
 262   </sect2>
 263   <sect2>
 264     <title>FcObjectType</title>
 265     <para>
 266       <programlisting>
 267         typedef struct _FcObjectType {
 268                 const char *object;
 269                 FcType type;
 270         } FcObjectType;
 271       </programlisting>
 272 marks the type of a pattern element generated when parsing font names.
 273 Applications can add new object types so that font names may contain the new
 274 elements.
 275     </para>
 276   </sect2>
 277   <sect2>
 278     <title>FcConstant</title>
 279     <para>
 280       <programlisting>
 281         typedef struct _FcConstant {
 282             const FcChar8 *name;
 283             const char *object;
 284             int value;
 285         } FcConstant;
 286       </programlisting>
 287 Provides for symbolic constants for new pattern elements.  When 'name' is
 288 seen in a font name, an 'object' element is created with value 'value'.
 289     </para>
 290   </sect2>
 291   <sect2>
 292     <title>FcBlanks</title>
 293     <para>
 294 holds a list of Unicode chars which are expected to be blank; unexpectedly
 295 blank chars are assumed to be invalid and are elided from the charset
 296 associated with the font.
 297     </para>
 298   </sect2>
 299   <sect2>
 300     <title>FcFileCache</title>
 301     <para>
 302 holds the per-user cache information for use while loading the font
 303 database. This is built automatically for the current configuration when
 304 that is loaded.  Applications must always pass '0' when one is requested.
 305     </para>
 306   </sect2>
 307   <sect2>
 308     <title>FcConfig</title>
 309     <para>
 310 holds a complete configuration of the library; there is one default
 311 configuration, other can be constructed from XML data structures.  All
 312 public entry points that need global data can take an optional FcConfig*
 313 argument; passing 0 uses the default configuration.  FcConfig objects hold two
 314 sets of fonts, the first contains those specified by the configuration, the
 315 second set holds those added by the application at run-time.  Interfaces
 316 that need to reference a particulat set use one of the FcSetName enumerated
 317 values.
 318     </para>
 319   </sect2>
 320   <sect2>
 321     <title>FcSetName</title>
 322     <para>
 323 Specifies one of the two sets of fonts available in a configuration;
 324 FcSetSystem for those fonts specified in the configuration and
 325 FcSetApplication which holds fonts provided by the application.
 326     </para>
 327   </sect2>
 328   <sect2>
 329     <title>FcResult</title>
 330     <para>
 331 Used as a return type for functions manipulating FcPattern objects.
 332     <table colsep=0 rowsep=0>
 333       <title>FcResult Values</title>
 334       <tgroup cols=2 align=left colsep=0 rowsep=0>
 335         <thead><row>
 336           <entry>Result Code</entry>
 337           <entry>Meaning</entry>
 338         </row></thead>
 339         <tbody>
 340 <row><entry>FcResultMatch</entry><entry>Object exists with the specified ID</entry></row>
 341 <row><entry>FcResultNoMatch</entry><entry>Object doesn't exist at all</entry></row>
 342 <row><entry>FcResultTypeMismatch</entry><entry>Object exists, but the type doesn't match</entry></row>
 343 <row><entry>FcResultNoId</entry><entry>Object exists, but has fewer values than specified</entry></row>
 344         </tbody>
 345       </tgroup>
 346     </table>
 347     </para>
 348   </sect2>
 349   <sect2>
 350     <title>FcAtomic</title>
 351     <para>
 352 Used for locking access to config files.  Provides a safe way to update
 353 configuration files.
 354     </para>
 355   </sect2>
 356 </sect1>
 357 <sect1><title>FUNCTIONS</title>
 358   <para>
 359 Functions are grouped by the main datatype involved
 360   </para>
 361   <sect2><title>FcMatrix</title>
 362     <para>
 363 FcMatrix structures hold an affine transformation in matrix form.
 364     </para>
 365     <sect3><title>FcMatrixInit</title><programlisting>
 366 #define FcMatrixInit(m) ((m)-&gt;xx = (m)-&gt;yy = 1, (m)-&gt;xy = (m)-&gt;yx = 0)
 367     </programlisting><para>
 368 Initializes a matrix to the identify transformation.
 369     </para></sect3>
 370     <sect3><title>FcMatrixCopy</title><programlisting>
 371 FcMatrix *FcMatrixCopy (const FcMatrix *mat)
 372     </programlisting><para>
 373 Allocates a new FcMatrix and copies 'mat' into it.
 374     </para></sect3>
 375     <sect3><title>FcMatrixEqual</title><programlisting>
 376 FcBool FcMatrixEqual (const FcMatrix *mat1, const FcMatrix *mat2)
 377     </programlisting><para>
 378 Returns FcTrue if 'mat1' and 'mat2' are equal, else FcFalse.
 379     </para></sect3>
 380     <sect3><title>FcMatrixMultiply</title><programlisting>
 381 void FcMatrixMultiply (FcMatrix *result, const FcMatrix *a, const FcMatrix *b)
 382     </programlisting><para>
 383 Multiplies 'a' and 'b' together, placing the result in 'result'.  'result'
 384 may refer to the sam matrix as either 'a' or 'b'.
 385     </para></sect3>
 386     <sect3><title>FcMatrixRotate</title><programlisting>
 387 void FcMatrixRotate (FcMatrix *m, double c, double s)
 388     </programlisting><para>
 389 If 'c' is cos(angle) and 's' is sin(angle), FcMatrixRotate rotates the
 390 matrix by 'angle'.
 391     </para></sect3>
 392     <sect3><title>FcMatrixScale</title><programlisting>
 393 void FcMatrixScale (FcMatrix *m, double sx, double sy)
 394     </programlisting><para>
 395 Scales 'm' by 'sx' in the horizontal dimension and 'sy' in the
 396 vertical dimension.
 397     </para></sect3>
 398     <sect3><title>FcMatrixShear</title><programlisting>
 399 void FcMatrixShear (FcMatrix *m, double sh, double sv)
 400     </programlisting><para>
 401 Shears 'm' by 'sh' in the horizontal direction and 'sv' in the
 402 vertical direction.
 403     </para></sect3>
 404   </sect2>
 405   <sect2><title>FcCharSet</title>
 406     <para>
 407 An FcCharSet is a boolean array indicating a set of unicode chars.  Those
 408 associated with a font are marked constant and cannot be edited.
 409 FcCharSets may be reference counted internally to reduce memory consumption;
 410 this may be visible to applications as the result of FcCharSetCopy may
 411 return it's argument, and that CharSet may remain unmodifiable.
 412     </para>
 413     <sect3><title>FcCharSetCreate</title><programlisting>
 414 FcCharSet *FcCharSetCreate (void)
 415     </programlisting><para>
 416 Creates an empty FcCharSet object.
 417     </para></sect3>
 418     <sect3><title>FcCharSetDestroy</title><programlisting>
 419 void FcCharSetDestroy (FcCharSet *fcs)
 420     </programlisting><para>
 421 Frees an FcCharSet object.
 422     </para></sect3>
 423     <sect3><title>FcCharSetAddChar</title><programlisting>
 424 FcBool FcCharSetAddChar (FcCharSet *fcs, FcChar32 ucs4)
 425     </programlisting><para>
 426 Adds a single unicode char to the set, returning FcFalse on
 427 failure, either as a result of a constant set or from running out of memory.
 428     </para></sect3>
 429     <sect3><title>FcCharSetCopy</title><programlisting>
 430 FcCharSet *FcCharSetCopy (FcCharSet *src)
 431     </programlisting><para>
 432 Makes a copy of 'src'; note that this may not actually do anything more than
 433 increment the reference count on 'src'.
 434     </para></sect3>
 435     <sect3><title>FcCharSetEqual</title><programlisting>
 436 FcBool FcCharSetEqual (const FcCharSet *a, const FcCharSet *b)
 437     </programlisting><para>
 438 Returns whether 'a' and 'b' contain the same set of unicode chars.
 439     </para></sect3>
 440     <sect3><title>FcCharSetIntersect</title><programlisting>
 441 FcCharSet *FcCharSetIntersect (const FcCharSet *a, const FcCharSet *b)
 442     </programlisting><para>
 443 Returns a set including only those chars found in both 'a' and 'b'.
 444     </para></sect3>
 445     <sect3><title>FcCharSetUnion</title><programlisting>
 446 FcCharSet *FcCharSetUnion (const FcCharSet *a, const FcCharSet *b);
 447     </programlisting><para>
 448 Returns a set including only those chars found in either 'a' or 'b'.
 449     </para></sect3>
 450     <sect3><title>FcCharSetSubtract</title><programlisting>
 451 FcCharSet *FcCharSetSubtract (const FcCharSet *a, const FcCharSet *b)
 452     </programlisting><para>
 453 Returns a set including only those chars found in 'a' but not 'b'.
 454     </para></sect3>
 455     <sect3><title>FcCharSetHasChar</title><programlisting>
 456 FcBool FcCharSetHasChar (const FcCharSet *fcs, FcChar32 ucs4)
 457     </programlisting><para>
 458 Returns whether 'fcs' contains the char 'ucs4'.
 459     </para></sect3>
 460     <sect3><title>FcCharSetCount</title><programlisting>
 461 FcChar32 FcCharSetCount (const FcCharSet *a)
 462     </programlisting><para>
 463 Returns the total number of unicode chars in 'a'.
 464     </para></sect3>
 465     <sect3><title>FcCharSetIntersectCount</title><programlisting>
 466 FcChar32 FcCharSetIntersectCount (const FcCharSet *a, const FcCharSet *b)
 467     </programlisting><para>
 468 Returns the number of chars that are in both 'a' and 'b'.
 469     </para></sect3>
 470     <sect3><title>FcCharSetSubtractCount</title><programlisting>
 471 FcChar32 FcCharSetSubtractCount (const FcCharSet *a, const FcCharSet *b)
 472     </programlisting><para>
 473 Returns the number of chars that are in 'a' but not in 'b'.
 474     </para></sect3>
 475     <sect3><title>FcCharSetIsSubset</title><programlisting>
 476 FcBool FcCharSetIsSubset (const FcCharSet *a, const FcCharSet *b)
 477     </programlisting><para>
 478 Returns whether 'a' is a subset of 'b'.
 479     </para></sect3>
 480     <sect3><title>FcCharSetFirstPage</title><programlisting>
 481 FcChar32 FcCharSetFirstPage (const FcCharSet *a, FcChar32 [FC_CHARSET_MAP_SIZE], FcChar32 *next)
 482     </programlisting><para>
 483 Builds an array of bits marking the first page of Unicode coverage of 'a'.
 484 Returns the base of the array.  'next' contains the next page in the font.
 485     </para></sect3>
 486     <sect3><title>FcCharSetNextPage</title><programlisting>
 487 FcChar32 FcCharSetNextPage (const FcCharSet *a, FcChar32 [FC_CHARSET_MAP_SIZE], FcChar32 *next)
 488     </programlisting><para>
 489 Builds an array of bits marking the Unicode coverage of 'a' for page '*next'.
 490 Returns the base of the array.  'next' contains the next page in the font.
 491     </para></sect3>
 492   </sect2>
 493   <sect2><title>FcValue</title>
 494     <para>
 495 FcValue is a structure containing a type tag and a union of all possible
 496 datatypes.  The tag is an enum of type
 497 <emphasis>FcType</emphasis>
 498 and is intended to provide a measure of run-time
 499 typechecking, although that depends on careful programming.
 500     </para>
 501     <sect3><title>FcValueDestroy</title><programlisting>
 502 void FcValueDestroy (FcValue v)
 503     </programlisting><para>
 504 Frees any memory referenced by `v'.  Values of type FcTypeString,
 505 FcTypeMatrix and FcTypeCharSet reference memory, the other types do not.
 506     </para></sect3>
 507     <sect3><title>FcValueSave</title><programlisting>
 508 FcValue FcValueSave (FcValue v)
 509     </programlisting><para>
 510 Returns a copy of `v' duplicating any object referenced by it so that `v'
 511 may be safely destroyed without harming the new value.
 512     </para></sect3>
 513   </sect2>
 514   <sect2><title>FcPattern</title>
 515     <para>
 516 An FcPattern is an opaque type that holds both patterns to match against the
 517 available fonts, as well as the information about each font.
 518     </para>
 519     <sect3><title>FcPatternCreate</title><programlisting>
 520 FcPattern *FcPatternCreate (void)
 521     </programlisting><para>
 522 Creates a pattern with no properties; used to build patterns from scratch.
 523     </para></sect3>
 524     <sect3><title>FcPatternDestroy</title><programlisting>
 525 void FcPatternDestroy (FcPattern *p)
 526     </programlisting><para>
 527 Destroys a pattern, in the process destroying all related values.
 528     </para></sect3>
 529     <sect3><title>FcPatternEqual</title><programlisting>
 530 FcBool FcPatternEqual (const FcPattern *pa, const FcPattern *pb);
 531     </programlisting><para>
 532 Returns whether 'pa' and 'pb' are exactly alike.
 533     </para></sect3>
 534     <sect3><title>FcPatternEqualSubset</title><programlisting>
 535 FcBool FcPatternEqualSubset (const FcPattern *pa, const FcPattern *pb, const FcObjectSet *os)
 536     </programlisting><para>
 537 Returns whether 'pa' and 'pb' have exactly the same values for all of the
 538 objects in 'os'.
 539     </para></sect3>
 540     <sect3><title>FcPatternHash</title><programlisting>
 541 FcChar32 FcPatternHash (const FcPattern *p)
 542     </programlisting><para>
 543 Returns a 32-bit number which is the same for any two patterns which are
 544 exactly alike.
 545     </para></sect3>
 546     <sect3><title>FcPatternAdd</title><programlisting>
 547 FcBool FcPatternAdd (FcPattern *p, const char *object, FcValue value, FcBool append)
 548     </programlisting><para>
 549 Adds a single value to the list of values associated with the property named
 550 `object'.  If `append' is FcTrue, the value is added at the end of any
 551 existing list, otherwise it is inserted at the begining.  `value' is saved
 552 (with FcValueSave) when inserted into the pattern so that the library
 553 retains no reference to any application-supplied data structure.
 554     </para></sect3>
 555     <sect3><title>FcPatternAddWeak</title><programlisting>
 556 FcBool FcPatternAddWeak (FcPattern *p, const char *object, FcValue value, FcBool append)
 557     </programlisting><para>
 558 FcPatternAddWeak is essentially the same as FcPatternAdd except that any
 559 values added to the list have binding 'weak' instead of 'strong'.
 560     </para></sect3>
 561     <sect3><title>FcPatternAdd <emphasis>Type</emphasis></title><programlisting>
 562 FcBool FcPatternAddInteger (FcPattern *p, const char *object, int i)
 563 FcBool FcPatternAddDouble (FcPattern *p, const char *object, double d)
 564 FcBool FcPatternAddString (FcPattern *p, const char *object, const char *s)
 565 FcBool FcPatternAddMatrix (FcPattern *p, const char *object, const FcMatrix *s)
 566 FcBool FcPatternAddCharSet (FcPattern *p, const char *object, const FcCharSet *c)
 567 FcBool FcPatternAddBool (FcPattern *p, const char *object, FcBool b)
 568     </programlisting><para>
 569 These are all convenience functions that insert objects of the specified
 570 type into the pattern.  Use these in preference to FcPatternAdd as they
 571 will provide compile-time typechecking.  These all append values to
 572 any existing list of values.
 573     </para></sect3>
 574     <sect3><title>FcPatternGet</title><programlisting>
 575 FcResult FcPatternGet (FcPattern *p, const char *object, int id, FcValue *v)
 576     </programlisting><para>
 577 Returns in `v' the `id'th value associated with the property `object'.
 578 The value returned is not a copy, but rather refers to the data stored
 579 within the pattern directly.  Applications must not free this value.
 580     </para></sect3>
 581     <sect3><title>FcPatternGet <emphasis>Type</emphasis></title><programlisting>
 582 FcResult FcPatternGetInteger (FcPattern *p, const char *object, int n, int *i);
 583 FcResult FcPatternGetDouble (FcPattern *p, const char *object, int n, double *d);
 584 FcResult FcPatternGetString (FcPattern *p, const char *object, int n, char **const s);
 585 FcResult FcPatternGetMatrix (FcPattern *p, const char *object, int n, FcMatrix **s);
 586 FcResult FcPatternGetCharSet (FcPattern *p, const char *object, int n, FcCharSet **c);
 587 FcResult FcPatternGetBool (FcPattern *p, const char *object, int n, FcBool *b);
 588     </programlisting><para>
 589 These are convenience functions that call FcPatternGet and verify that the
 590 returned data is of the expected type. They return FcResultTypeMismatch if
 591 this is not the case.  Note that these (like FcPatternGet) do not make a
 592 copy of any data structure referenced by the return value.  Use these
 593 in preference to FcPatternGet to provide compile-time typechecking.
 594     </para></sect3>
 595     <sect3><title>FcPatternBuild, FcPatternVaBuild</title><programlisting>
 596 FcPattern *FcPatternBuild (FcPattern *orig, ...);
 597 FcPattern *FcPatternVaBuild (FcPattern *orig, va_list va)
 598     </programlisting><para>
 599 Builds a pattern using a list of objects, types and values.  Each
 600 value to be entered in the pattern is specified with three arguments:
 601     </para>
 602     <orderedlist>
 603       <listitem><para>
 604 Object name, a string describing the property to be added.
 605       </para></listitem><listitem><para>
 606 Object type, one of the FcType enumerated values
 607       </para></listitem><listitem><para>
 608 Value, not an FcValue, but the raw type as passed to any of the
 609 FcPatternAdd&lt;type&gt; functions.  Must match the type of the second
 610 argument.
 611       </para></listitem>
 612     </orderedlist>
 613     <para>
 614 The argument list is terminated by a null object name, no object type nor
 615 value need be passed for this.  The values are added to `pattern', if
 616 `pattern' is null, a new pattern is created.  In either case, the pattern is
 617 returned. Example
 618     </para>
 619     <programlisting>
 620 pattern = FcPatternBuild (0, FC_FAMILY, FtTypeString, "Times", (char *) 0);
 621     </programlisting>
 622     <para>
 623 FcPatternVaBuild is used when the arguments are already in the form of a
 624 varargs value.
 625     </para></sect3>
 626     <sect3><title>FcPatternDel</title><programlisting>
 627 FcBool FcPatternDel (FcPattern *p, const char *object)
 628     </programlisting><para>
 629 Deletes all values associated with the property `object', returning
 630 whether the property existed or not.
 631     </para></sect3>
 632     <sect3><title>FcPatternPrint</title><programlisting>
 633 void FcPatternPrint (const FcPattern *p)
 634     </programlisting><para>
 635 Prints an easily readable version of the pattern to stdout.  There is
 636 no provision for reparsing data in this format, it's just for diagnostics
 637 and debugging.
 638     </para></sect3>
 639     <sect3><title>FcDefaultSubstitute</title><programlisting>
 640 void FcDefaultSubstitute (FcPattern *pattern)
 641     </programlisting><para>
 642 Supplies default values for underspecified font patterns:
 643     <itemizedlist>
 644       <listitem><para>
 645 Patterns without a specified style or weight are set to Medium
 646       </para></listitem>
 647       <listitem><para>
 648 Patterns without a specified style or slant are set to Roman
 649       </para></listitem>
 650       <listitem><para>
 651 Patterns without a specified pixel size are given one computed from any
 652 specified point size (default 12), dpi (default 75) and scale (default 1).
 653       </para></listitem>
 654     </itemizedlist>
 655     </para></sect3>
 656     <sect3><title>FcNameParse</title><programlisting>
 657 FcPattern *FcNameParse (const char *name)
 658     </programlisting><para>
 659 Converts 'name' from the standard text format described above into a pattern.
 660     </para></sect3>
 661     <sect3><title>FcNameUnparse</title><programlisting>
 662 FcChar8 *FcNameUnparse (FcPattern *pat)
 663     </programlisting><para>
 664 Converts the given pattern into the standard text format described above.
 665 The return value is not static, but instead refers to newly allocated memory
 666 which should be freed by the caller.
 667     </para></sect3>
 668   </sect2>
 669   <sect2><title>FcFontSet</title>
 670     <para>
 671 An FcFontSet simply holds a list of patterns; these are used to return the
 672 results of listing available fonts.
 673     </para>
 674     <sect3><title>FcFontSetCreate</title><programlisting>
 675 FcFontSet *FcFontSetCreate (void)
 676     </programlisting><para>
 677 Creates an empty font set.
 678     </para></sect3>
 679     <sect3><title>FcFontSetDestroy</title><programlisting>
 680 void FcFontSetDestroy (FcFontSet *s);
 681     </programlisting><para>
 682 Destroys a font set.  Note that this destroys any referenced patterns as
 683 well.
 684     </para></sect3>
 685     <sect3><title>FcFontSetAdd</title><programlisting>
 686 FcBool FcFontSetAdd (FcFontSet *s, FcPattern *font)
 687     </programlisting><para>
 688 Adds a pattern to a font set.  Note that the pattern is not copied before
 689 being inserted into the set.
 690     </para></sect3>
 691   </sect2>
 692   <sect2><title>FcObjectSet</title>
 693     <para>
 694 An FcObjectSet holds a list of pattern property names; it is used to
 695 indiciate which properties are to be returned in the patterns from
 696 FcFontList.
 697     </para>
 698     <sect3><title>FcObjectSetCreate</title><programlisting>
 699 FcObjectSet *FcObjectSetCreate (void)
 700     </programlisting><para>
 701 Creates an empty set.
 702     </para></sect3>
 703     <sect3><title>FcObjectSetAdd</title><programlisting>
 704 FcBool FcObjectSetAdd (FcObjectSet *os, const char *object)
 705     </programlisting><para>
 706 Adds a proprety name to the set.
 707     </para></sect3>
 708     <sect3><title>FcObjectSetDestroy</title><programlisting>
 709 void FcObjectSetDestroy (FcObjectSet *os)
 710     </programlisting><para>
 711 Destroys an object set.
 712     </para></sect3>
 713     <sect3><title>FcObjectSetBuild, FcObjectSetVaBuild</title><programlisting>
 714 FcObjectSet *FcObjectSetBuild (const char *first, ...)
 715 FcObjectSet *FcObjectSetVaBuild (const char *first, va_list va)
 716     </programlisting><para>
 717 These build an object set from a null-terminated list of property names.
 718     </para></sect3>
 719   </sect2>
 720   <sect2><title>FcObjectType</title>
 721     <para>
 722 Provides for applcation-specified font name object types so that new
 723 pattern elements can be generated from font names.
 724     </para>
 725     <sect3><title>FcNameRegisterObjectTypes</title><programlisting>
 726 FcBool FcNameRegisterObjectTypes (const FcObjectType *types, int ntype)
 727     </programlisting><para>
 728 Register 'ntype' new object types.
 729     </para></sect3>
 730     <sect3><title>FcNameUnregisterObjectTypes</title><programlisting>
 731 FcBool FcNameUnregisterObjectTypes (const FcObjectType *types, int ntype)
 732     </programlisting><para>
 733 Unregister 'ntype' object types.
 734     </para></sect3>
 735     <sect3><title>FcNameGetObjectType</title><programlisting>
 736 const FcObjectType *FcNameGetObjectType (const char *object)
 737     </programlisting><para>
 738 Return the object type for the pattern element named 'object'.
 739     </para></sect3>
 740   </sect2>
 741   <sect2><title>FcConstant</title>
 742     <para>
 743 Provides for application-specified symbolic constants for font names.
 744     </para>
 745     <sect3><title>FcNameRegisterConstants</title><programlisting>
 746 FcBool FcNameRegisterConstants (const FcConstant *consts, int nconsts)
 747     </programlisting><para>
 748 Register 'nconsts' new symbolic constants.
 749     </para></sect3>
 750     <sect3><title>FcNameUnregisterConstants</title><programlisting>
 751 FcBool FcNameUnregisterConstants (const FcConstant *consts, int nconsts)
 752     </programlisting><para>
 753 Unregister 'nconsts' symbolic constants.
 754     </para></sect3>
 755     <sect3><title>FcNameGetConstant</title><programlisting>
 756 const FcConstant *FcNameGetConstant (FcChar8 *string)
 757     </programlisting><para>
 758 Return the FcConstant structure related to symbolic constant 'string'.
 759     </para></sect3>
 760     <sect3><title>FcNameConstant</title><programlisting>
 761 FcBool FcNameConstant (FcChar8 *string, int *result);
 762     </programlisting><para>
 763 Returns whether a symbolic constant with name 'string' is registered,
 764 placing the value of the constant in 'result' if present.
 765     </para></sect3>
 766   </sect2>
 767   <sect2><title>FcBlanks</title>
 768     <para>
 769 An FcBlanks object holds a list of Unicode chars which are expected to
 770 be blank when drawn.  When scanning new fonts, any glyphs which are
 771 empty and not in this list will be assumed to be broken and not placed in
 772 the FcCharSet associated with the font.  This provides a significantly more
 773 accurate CharSet for applications.
 774     </para>
 775     <sect3><title>FcBlanksCreate</title><programlisting>
 776 FcBlanks *FcBlanksCreate (void)
 777     </programlisting><para>
 778 Creates an empty FcBlanks object.
 779     </para></sect3>
 780     <sect3><title>FcBlanksDestroy</title><programlisting>
 781 void FcBlanksDestroy (FcBlanks *b)
 782     </programlisting><para>
 783 Destroys an FcBlanks object, freeing any associated memory.
 784     </para></sect3>
 785     <sect3><title>FcBlanksAdd</title><programlisting>
 786 FcBool FcBlanksAdd (FcBlanks *b, FcChar32 ucs4)
 787     </programlisting><para>
 788 Adds a single character to an FcBlanks object, returning FcFalse
 789 if this process ran out of memory.
 790     </para></sect3>
 791     <sect3><title>FcBlanksIsMember</title><programlisting>
 792 FcBool FcBlanksIsMember (FcBlanks *b, FcChar32 ucs4)
 793     </programlisting><para>
 794 Returns whether the specified FcBlanks object contains the indicated Unicode
 795 value.
 796     </para></sect3>
 797   </sect2>
 798   <sect2><title>FcConfig</title>
 799     <para>
 800 An FcConfig object holds the internal representation of a configuration.
 801 There is a default configuration which applications may use by passing 0 to
 802 any function using the data within an FcConfig.
 803     </para>
 804     <sect3><title>FcConfigCreate</title><programlisting>
 805 FcConfig *FcConfigCreate (void)
 806     </programlisting><para>
 807 Creates an empty configuration.
 808     </para></sect3>
 809     <sect3><title>FcConfigDestroy</title><programlisting>
 810 void FcConfigDestroy (FcConfig *config)
 811     </programlisting><para>
 812 Destroys a configuration and any data associated with it.  Note that calling
 813 this function with the return from FcConfigGetCurrent will place the library
 814 in an indeterminate state.
 815     </para></sect3>
 816     <sect3><title>FcConfigSetCurrent</title><programlisting>
 817 FcBool FcConfigSetCurrent (FcConfig *config)
 818     </programlisting><para>
 819 Sets the current default configuration to 'config'.  Implicitly calls
 820 FcConfigBuildFonts if necessary, returning FcFalse if that call fails.
 821     </para></sect3>
 822     <sect3><title>FcConfigGetCurrent</title><programlisting>
 823 FcConfig *FcConfigGetCurrent (void)
 824     </programlisting><para>
 825 Returns the current default configuration.
 826     </para></sect3>
 827     <sect3><title>FcConfigUptoDate</title><programlisting>
 828 FcBool FcConfigUptoDate (FcConfig *config)
 829     </programlisting><para>
 830 Checks all of the files related to 'config' and returns whether the
 831 in-memory version is in sync with the disk version.
 832     </para></sect3>
 833     <sect3><title>FcConfigBuildFonts</title><programlisting>
 834 FcBool FcConfigBuildFonts (FcConfig *config)
 835     </programlisting><para>
 836 Builds the set of available fonts for the given configuration.  Note that
 837 any changes to the configuration after this call have indeterminate effects.
 838 Returns FcFalse if this operation runs out of memory.
 839     </para></sect3>
 840     <sect3><title>FcConfigGetConfigDirs</title><programlisting>
 841 FcStrList *FcConfigGetConfigDirs (FcConfig *config)
 842     </programlisting><para>
 843 Returns the list of font directories specified in the configuration files
 844 for 'config'.  Does not include any subdirectories.
 845     </para></sect3>
 846     <sect3><title>FcConfigGetFontDirs</title><programlisting>
 847 FcStrList *FcConfigGetFontDirs (FcConfig *config)
 848     </programlisting><para>
 849 Returns the list of font directories in 'config'. This includes the
 850 configured font directories along with any directories below those in the
 851 filesystem.
 852     </para></sect3>
 853     <sect3><title>FcConfigGetConfigFiles</title><programlisting>
 854 FcStrList *FcConfigGetConfigFiles (FcConfig *config)
 855     </programlisting><para>
 856 Returns the list of known configuration files used to generate 'config'.
 857 Note that this will not include any configuration done with FcConfigParse.
 858     </para></sect3>
 859     <sect3><title>FcConfigGetCache</title><programlisting>
 860 char *FcConfigGetCache (FcConfig *config)
 861     </programlisting><para>
 862 Returns the name of the file used to store per-user font information.
 863     </para></sect3>
 864     <sect3><title>FcConfigGetFonts</title><programlisting>
 865 FcFontSet *FcConfigGetFonts (FcConfig *config, FcSetName set)
 866     </programlisting><para>
 867 Returns one of the two sets of fonts from the configuration as specified
 868 by 'set'.
 869     </para></sect3>
 870     <sect3><title>FcConfigGetBlanks</title><programlisting>
 871 FcBlanks *FcConfigGetBlanks (FcConfig *config)
 872     </programlisting><para>
 873 Returns the FcBlanks object associated with the given configuration, if no
 874 blanks were present in the configuration, this function will return 0.
 875     </para></sect3>
 876     <sect3><title>FcConfigGetRescanInverval</title><programlisting>
 877 int FcConfigGetRescanInverval (FcConfig *config)
 878     </programlisting><para>
 879 Returns the interval between automatic checks of the configuration (in
 880 seconds) specified in 'config'.  The configuration is checked during
 881 a call to FcFontList when this interval has passed since the last check.
 882     </para></sect3>
 883     <sect3><title>FcConfigSetRescanInverval</title><programlisting>
 884 FcBool FcConfigSetRescanInverval (FcConfig *config, int rescanInterval)
 885     </programlisting><para>
 886 Sets the rescan interval; returns FcFalse if an error occurred.
 887     </para></sect3>
 888     <sect3><title>FcConfigAppFontAddFile</title><programlisting>
 889 FcBool FcConfigAppFontAddFile (FcConfig *config, const char *file)
 890     </programlisting><para>
 891 Adds an application-specific font to the configuration.
 892     </para></sect3>
 893     <sect3><title>FcConfigAppFontAddDir</title><programlisting>
 894 FcBool FcConfigAppFontAddDir (FcConfig *config, const char *dir)
 895     </programlisting><para>
 896 Scans the specified directory for fonts, adding each one found to the
 897 application-specific set of fonts.
 898     </para></sect3>
 899     <sect3><title>FcConfigAppFontClear</title><programlisting>
 900 void FcConfigAppFontClear (FcConfig *config)
 901     </programlisting><para>
 902 Clears the set of application-specific fonts.
 903     </para></sect3>
 904     <sect3><title>FcConfigSubstituteWithPat</title><programlisting>
 905 FcBool FcConfigSubstituteWithPat (FcConfig *config, FcPattern *p, FcPattern *p_pat FcMatchKind kind)
 906     </programlisting><para>
 907 Performs the sequence of pattern modification operations, if 'kind' is
 908 FcMatchPattern, then those tagged as pattern operations are applied, else
 909 if 'kind' is FcMatchFont, those tagged as font operations are applied and
 910 p_pat is used for &lt;test&gt; elements with target=pattern.
 911     </para></sect3>
 912     <sect3><title>FcConfigSubstitute</title><programlisting>
 913 FcBool FcConfigSubstitute (FcConfig *config, FcPattern *p, FcMatchKind kind)
 914     </programlisting><para>
 915 Calls FcConfigSubstituteWithPat setting p_pat to NULL.
 916     </para></sect3>
 917     <sect3><title>FcFontMatch</title><programlisting>
 918 FcPattern *FcFontMatch (FcConfig *config, FcPattern *p, FcResult *result)
 919     </programlisting><para>
 920 Returns the font in 'config' most close matching 'p'.  This function
 921 should be called only after FcConfigSubstitute and FcDefaultSubstitute have
 922 been called for 'p'; otherwise the results will not be correct.
 923     </para></sect3>
 924     <sect3><title>FcFontSort</title><programlisting>
 925 FcFontSet *FcFontSort (FcConfig *config, FcPattern *p, FcBool trim, FcCharSet **csp, FcResult *result)
 926     </programlisting><para>
 927 Returns the list of fonts sorted by closeness to 'p'.  If 'trim' is FcTrue,
 928 elements in the list which don't include Unicode coverage not provided by
 929 earlier elements in the list are elided.  The union of Unicode coverage of
 930 all of the fonts is returned in 'csp', if 'csp' is not NULL.  This function
 931 should be called only after FcConfigSubstitute and FcDefaultSubstitute have
 932 been called for 'p'; otherwise the results will not be correct.
 933     </para><para>
 934 The returned FcFontSet references FcPattern structures which may be shared
 935 by the return value from multiple FcFontSort calls, applications must not
 936 modify these patterns.  Instead, they should be passed, along with 'p' to
 937 FcFontRenderPrepare which combines them into a complete pattern.
 938     </para><para>
 939 The FcFontSet returned by FcFontSort is destroyed by caling FcFontSetDestroy.
 940     </para></sect3>
 941     <sect3><title>FcFontRenderPrepare</title><programlisting>
 942 FcPattern *FcFontRenderPrepare (FcConfig *config, FcPattern *pat, FcPattern *font)
 943     </programlisting><para>
 944 Creates a new pattern consisting of elements of 'font' not appearing
 945 in 'pat', elements of 'pat' not appearing in 'font' and the best matching
 946 value from 'pat' for elements appearing in both.  The result is passed to
 947 FcConfigSubstitute with 'kind' FcMatchFont and then returned.
 948     </para></sect3>
 949     <sect3><title>FcFontList</title><programlisting>
 950 FcFontSet *FcFontList (FcConfig *config, FcPattern *p, FcObjectSet *os)
 951     </programlisting><para>
 952 Selects fonts matching 'p', creates patterns from those fonts containing
 953 only the objects in 'os' and returns the set of unique such patterns.
 954     </para></sect3>
 955     <sect3><title>FcConfigFilename</title><programlisting>
 956 char *FcConfigFilename (const char *name)
 957     </programlisting><para>
 958 Given the specified external entity name, return the associated filename.
 959 This provides applications a way to convert various configuration file
 960 references into filename form.
 961     </para><para>
 962 A null or empty 'name' indicates that the default configuration file should
 963 be used; which file this references can be overridden with the
 964 FC_CONFIG_FILE environment variable.  Next, if the name starts with '~', it
 965 refers to a file in the current users home directory.  Otherwise if the name
 966 doesn't start with '/', it refers to a file in the default configuration
 967 directory; the built-in default directory can be overridden with the
 968 FC_CONFIG_DIR environment variable.
 969     </para></sect3>
 970   </sect2>
 971   <sect2><title>Initialization</title>
 972     <para>
 973 These functions provide some control over how the library is initialized.
 974     </para>
 975     <sect3><title>FcInitLoadConfig</title><programlisting>
 976 FcConfig *FcInitLoadConfig (void)
 977     </programlisting><para>
 978 Loads the default configuration file and returns the resulting configuration.
 979 Does not load any font information.
 980     </para></sect3>
 981     <sect3><title>FcInitLoadConfigAndFonts</title><programlisting>
 982 FcConfig *FcInitLoadConfigAndFonts (void)
 983     </programlisting><para>
 984 Loads the default configuration file and builds information about the
 985 available fonts.  Returns the resulting configuration.
 986     </para></sect3>
 987     <sect3><title>FcInit</title><programlisting>
 988 FcBool FcInit (void)
 989     </programlisting><para>
 990 Loads the default configuration file and the fonts referenced therein and
 991 sets the default configuration to that result.  Returns whether this
 992 process succeeded or not.  If the default configuration has already
 993 been loaded, this routine does nothing and returns FcTrue.
 994     </para></sect3>
 995     <sect3><title>FcGetVersion</title><programlisting>
 996 int FcGetVersion (void)
 997     </programlisting><para>
 998 Returns the version number of the library.
 999     </para></sect3>
1000     <sect3><title>FcInitReinitialize</title><programlisting>
1001 FcBool FcInitReinitialize (void)
1002     </programlisting><para>
1003 Forces the default configuration file to be reloaded and resets the default
1004 configuration.
1005     </para></sect3>
1006     <sect3><title>FcInitBringUptoDate</title><programlisting>
1007 FcBool FcInitBringUptoDate (void)
1008     </programlisting><para>
1009 Checks the rescan interval in the default configuration, checking the
1010 configuration if the interval has passed and reloading the configuration if
1011 when any changes are detected.
1012     </para></sect3>
1013   </sect2>
1014   <sect2><title>FcAtomic</title>
1015     <para>
1016 These functions provide a safe way to update config files, allowing ongoing
1017 reading of the old config file while locked for writing and ensuring that a
1018 consistent and complete version of the config file is always available.
1019     </para>
1020     <sect3><title>FcAtomicCreate</title><programlisting>
1021 FcAtomic * FcAtomicCreate (const FcChar8   *file)
1022     </programlisting><para>
1023 Creates a data structure containing data needed to control access to 'file'.
1024 Writing is done to a separate file.  Once that file is complete, the original
1025 configuration file is atomically replaced so that reading process always see
1026 a consistent and complete file without the need to lock for reading.
1027     </para></sect3>
1028     <sect3><title>FcAtomicLock</title><programlisting>
1029 FcBool FcAtomicLock (FcAtomic *atomic)
1030     </programlisting><para>
1031 Attempts to lock the file referenced by 'atomic'.  Returns FcFalse if the
1032 file is locked by another process, else returns FcTrue and leaves the file
1033 locked.
1034     </para></sect3>
1035     <sect3><title>FcAtomicNewFile</title><programlisting>
1036 FcChar8 *FcAtomicNewFile (FcAtomic *atomic)
1037     </programlisting><para>
1038 Returns the filename for writing a new version of the file referenced
1039 by 'atomic'.
1040     </para></sect3>
1041     <sect3><title>FcAtomicOrigFile</title><programlisting>
1042 FcChar8 *FcAtomicOrigFile (FcAtomic *atomic)
1043     </programlisting><para>
1044 Returns the file refernced by 'atomic'.
1045     </para></sect3>
1046     <sect3><title>FcAtomicReplaceOrig</title><programlisting>
1047 FcBool FcAtomicReplaceOrig (FcAtomic *atomic)
1048     </programlisting><para>
1049 Replaces the original file referenced by 'atomic' with the new file.
1050     </para></sect3>
1051     <sect3><title>FcAtomicDeleteNew</title><programlisting>
1052 void FcAtomicDeleteNew (FcAtomic *atomic)
1053     </programlisting><para>
1054 Deletes the new file.
1055     </para></sect3>
1056     <sect3><title>FcAtomicUnlock</title><programlisting>
1057 void FcAtomicUnlock (FcAtomic *atomic)
1058     </programlisting><para>
1059 Unlocks the file.
1060     </para></sect3>
1061     <sect3><title>FcAtomicDestroy</title><programlisting>
1062 void FcAtomicDestroy (FcAtomic *atomic)
1063     </programlisting><para>
1064 Destroys 'atomic'.
1065     </para></sect3>
1066   </sect2>
1067   <sect2><title>FreeType specific functions</title>
1068     <para>
1069       <programlisting>
1070 #include &lt;fontconfig/fcfreetype.h&gt;
1071       </programlisting>
1072 While the fontconfig library doesn't insist that FreeType be used as the
1073 rasterization mechanism for fonts, it does provide some convenience
1074 functions.
1075     </para>
1076     <sect3><title>FcFreeTypeCharIndex</title><programlisting>
1077 FT_UInt FcFreeTypeCharIndex (FT_Face face, FcChar32 ucs4)
1078     </programlisting><para>
1079 Maps a Unicode char to a glyph index.  This function uses information from
1080 several possible underlying encoding tables to work around broken fonts.
1081 As a result, this function isn't designed to be used in performance
1082 sensitive areas; results from this function are intended to be cached by
1083 higher level functions.
1084     </para></sect3>
1085     <sect3><title>FcFreeTypeCharSet</title><programlisting>
1086 FcCharSet *FcFreeTypeCharSet (FT_Face face, FcBlanks *blanks) Scans a
1087     </programlisting><para>
1088 FreeType face and returns the set of encoded Unicode chars.  This scans
1089 several encoding tables to build as complete a list as possible.
1090 If 'blanks' is not 0, the glyphs in the font are examined and any blank glyphs
1091 not in 'blanks' are not placed in the returned FcCharSet.
1092     </para></sect3>
1093     <sect3><title>FcFreeTypeQuery</title><programlisting>
1094 FcPattern *FcFreeTypeQuery (const char *file, int id, FcBlanks *blanks, int *count)
1095     </programlisting><para>
1096 Constructs a pattern representing the 'id'th font in 'file'.  The number
1097 of fonts in 'file' is returned in 'count'.
1098     </para></sect3>
1099   </sect2>
1100   <sect2><title>XML specific functions</title>
1101     <sect3><title>FcConfigParseAndLoad</title><programlisting>
1102 FcBool FcConfigParseAndLoad (FcConfig *config, const FcChar8 *file, FcBool complain)
1103     </programlisting><para>
1104 Walks the configuration in 'file' and constructs the internal representation
1105 in 'config'.  Any include files referenced from within 'file' will be loaded
1106 with FcConfigLoad and also parsed.  If 'complain' is FcFalse, no warning
1107 will be displayed if 'file' does not exist.
1108     </para></sect3>
1109   </sect2>
1110   <sect2><title>File and Directory routines</title>
1111     <sect3><title>FcFileScan</title><programlisting>
1112 FcBool FcFileScan (FcFontSet *set, FcStrSet *dirs, FcFileCache *cache, FcBlanks *blanks, const char *file, FcBool force)
1113     </programlisting><para>
1114 Scans a single file and adds all fonts found to 'set'.  If 'force' is FcTrue,
1115 then the file is scanned even if associated information is found in 'cache'.
1116 If 'file' is a directory, it is added to 'dirs'.
1117     </para></sect3>
1118     <sect3><title>FcDirScan</title><programlisting>
1119 FcBool FcDirScan (FcFontSet *set, FcStrSet *dirs, FcFileCache *cache, FcBlanks *blanks, const char *dir, FcBool force)
1120     </programlisting><para>
1121 Scans an entire directory and adds all fonts found to 'set'.  If 'force' is
1122 FcTrue, then the directory and all files within it are scanned even if
1123 information is present in the per-directory cache file or 'cache'.  Any
1124 subdirectories found are added to 'dirs'.
1125     </para></sect3>
1126     <sect3><title>FcDirSave</title><programlisting>
1127 FcBool FcDirSave (FcFontSet *set, FcStrSet *dirs, const char *dir)
1128     </programlisting><para>
1129 Creates the per-directory cache file for 'dir' and populates it with the
1130 fonts in 'set' and subdirectories in 'dirs'.
1131     </para></sect3>
1132     <sect3><title>FcDirCacheValid</title><programlisting>
1133 FcBool FcDirCacheValid (const FcChar8 *cache_file)
1134     </programlisting><para>
1135 Returns FcTrue if 'cache_file' is no older than the directory containing it,
1136 else FcFalse.
1137     </para></sect3>
1138   </sect2>
1139   <sect2><title>FcStrSet and FcStrList</title>
1140     <para>
1141 A data structure for enumerating strings, used to list directories while
1142 scanning the configuration as directories are added while scanning.
1143     </para>
1144     <sect3><title>FcStrSetCreate</title><programlisting>
1145 FcStrSet *FcStrSetCreate (void)
1146     </programlisting><para>
1147 Create an empty set.
1148     </para></sect3>
1149     <sect3><title>FcStrSetMember</title><programlisting>
1150 FcBool FcStrSetMember (FcStrSet *set, const FcChar8 *s)
1151     </programlisting><para>
1152 Returns whether 's' is a member of 'set'.
1153     </para></sect3>
1154     <sect3><title>FcStrSetAdd</title><programlisting>
1155 FcBool FcStrSetAdd (FcStrSet *set, const FcChar8 *s)
1156     </programlisting><para>
1157 Adds a copy of 's' to 'set'.
1158     </para></sect3>
1159     <sect3><title>FcStrSetAddFilename</title><programlisting>
1160 FcBool FcStrSetAddFilename (FcStrSet *set, const FcChar8 *s)
1161     </programlisting><para>
1162 Adds a copy 's' to 'set', The copy is created with FcStrCopyFilename
1163 so that leading '~' values are replaced with the value of the HOME
1164 environment variable.
1165     </para></sect3>
1166     <sect3><title>FcStrSetDel</title><programlisting>
1167 FcBool FcStrSetDel (FcStrSet *set, const FcChar8 *s)
1168     </programlisting><para>
1169 Removes 's' from 'set', returning FcTrue if 's' was a member else FcFalse.
1170     </para></sect3>
1171     <sect3><title>FcStrSetDestroy</title><programlisting>
1172 void FcStrSetDestroy (FcStrSet *set)
1173     </programlisting><para>
1174 Destroys 'set'.
1175     </para></sect3>
1176     <sect3><title>FcStrListCreate</title><programlisting>
1177 FcStrList *FcStrListCreate (FcStrSet *set)
1178     </programlisting><para>
1179 Creates an enumerator to list the strings in 'set'.
1180     </para></sect3>
1181     <sect3><title>FcStrListNext</title><programlisting>
1182 FcChar8 *FcStrListNext (FcStrList *list)
1183     </programlisting><para>
1184 Returns the next string in 'set'.
1185     </para></sect3>
1186     <sect3><title>FcStrListDone</title><programlisting>
1187 void FcStrListDone (FcStrList *list)
1188     </programlisting><para>
1189 Destroys the enumerator 'list'.
1190     </para></sect3>
1191   </sect2>
1192   <sect2><title>String utilities</title>
1193     <sect3><title>FcUtf8ToUcs4</title>
1194     <programlisting>
1195 int FcUtf8ToUcs4 (FcChar8 *src, FcChar32 *dst, int len)
1196     </programlisting>
1197     <para>
1198 Converts the next Unicode char from 'src' into 'dst' and returns the number
1199 of bytes containing the char.  'src' nust be at least 'len' bytes long.
1200     </para></sect3>
1201     <sect3><title>FcUcs4ToUtf8</title><programlisting>
1202 int FcUcs4ToUtf8 (FcChar32 src, FcChar8 dst[FC_UTF8_MAX_LEN])
1203     </programlisting><para>
1204 Converts the Unicode char from 'src' into 'dst' and returns the
1205 number of bytes needed to encode the char.
1206     </para></sect3>
1207     <sect3><title>FcUtf8Len</title><programlisting>
1208 FcBool FcUtf8Len (FcChar8 *src, int len, int *nchar, int *wchar)
1209     </programlisting><para>
1210 Counts the number of Unicode chars in 'len' bytes of 'src'.  Places that
1211 count in 'nchar'.  'wchar' contains 1, 2 or 4 depending on the number of
1212 bytes needed to hold the largest unicode char counted.  The return value
1213 indicates whether 'src' is a well-formed UTF8 string.
1214     </para></sect3>
1215     <sect3><title>FcUtf16ToUcs4</title><programlisting>
1216 int FcUtf16ToUcs4 (FcChar8 *src, FcEndian endian, FcChar32 *dst, int len)
1217     </programlisting><para>
1218 Converts the next Unicode char from 'src' into 'dst' and returns the
1219 number of bytes containing the char. 'src' must be at least 'len' bytes
1220 long.  Bytes of 'src' are combined into 16-bit units according to 'endian'.
1221     </para></sect3>
1222     <sect3><title>FcUtf16Len</title><programlisting>
1223 FcBool FcUtf16Len (FcChar8 *src, FcEndian endian, int len, int *nchar, int *wchar)
1224     </programlisting><para>
1225 Counts the number of Unicode chars in 'len' bytes of 'src'.  Bytes of 'src'
1226 are combined into 16-bit units according to 'endian'.  Places that
1227 count in 'nchar'.  'wchar' contains 1, 2 or 4 depending on the number of
1228 bytes needed to hold the largest unicode char counted.  The return value
1229 indicates whether 'string' is a well-formed UTF16 string.
1230     </para></sect3>
1231     <sect3><title>FcStrCopy</title><programlisting>
1232 FcChar8 *FcStrCopy (const FcChar8 *s)
1233     </programlisting><para>
1234 Allocates memory, copies 's' and returns the resulting buffer.  Yes, this
1235 is 'strdup', but that function isn't available on every platform.
1236     </para></sect3>
1237     <sect3><title>FcStrCopyFilename</title><programlisting>
1238 FcChar8 *FcStrCopyFilename (const FcChar8 *s)
1239     </programlisting><para>
1240 Just like FcStrCopy except that it converts any leading '~' characters
1241 in 's' to the value of the HOME environment variable.
1242     </para></sect3>
1243     <sect3><title>FcStrCmpIgnoreCase</title><programlisting>
1244 int FcStrCmpIgnoreCase (const char *s1, const char *s2)
1245     </programlisting><para>
1246 Returns the usual &lt;0, 0, &gt;0 result of comparing 's1' and 's2'.  This test
1247 is case-insensitive in the ASCII range and will operate properly with UTF8
1248 encoded strings, although it does not check for well formed strings.
1249     </para></sect3>
1250     <sect3><title>FcStrDirname</title><programlisting>
1251 FcChar8 *FcStrDirname (const FcChar8 *file)
1252     </programlisting><para>
1253 Returns the directory containing 'file'.
1254     </para></sect3>
1255     <sect3><title>FcStrBasename</title><programlisting>
1256 FcChar8 *FcStrBasename (const FcChar8 *file)
1257     </programlisting><para>
1258 Returns the filename of 'file' stripped of any leading directory names.
1259     </para></sect3>
1260   </sect2>
1261 </sect1>
1262 </article>