| <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN"> |
| <!-- |
| $Id$ |
| |
| Copyright © 2002 Keith Packard |
| |
| Permission to use, copy, modify, distribute, and sell this software and its |
| documentation for any purpose is hereby granted without fee, provided that |
| the above copyright notice appear in all copies and that both that |
| copyright notice and this permission notice appear in supporting |
| documentation, and that the name of Keith Packard not be used in |
| advertising or publicity pertaining to distribution of the software without |
| specific, written prior permission. Keith Packard makes no |
| representations about the suitability of this software for any purpose. It |
| is provided "as is" without express or implied warranty. |
| |
| KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, |
| INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO |
| EVENT SHALL KEITH PACKARD BE LIABLE FOR ANY SPECIAL, INDIRECT OR |
| CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, |
| DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER |
| TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR |
| PERFORMANCE OF THIS SOFTWARE. |
| --> |
| <article> |
| <artheader> |
| <title>Fontconfig Developers Guide</title> |
| <titleabbrev>Fontconfig</titleabbrev> |
| <author><firstname>Keith</><surname>Packard</></author> |
| <authorinitials>krp</authorinitials> |
| </artheader> |
| <sect1><title>NAME</title> |
| <para> |
| fontconfig - Font configuration and customization library |
| </para> |
| </sect1> |
| <sect1><title>SYNOPSIS</title> |
| <programlisting> |
| #include <fontconfig/fontconfig.h> |
| #include <fontconfig/fcfreetype.h> |
| </programlisting> |
| </sect1> |
| <sect1><title>DESCRIPTION</title> |
| <para> |
| Fontconfig is a library designed to provide system-wide font configuration, |
| customization and application access. |
| </para> |
| </sect1> |
| <sect1><title>FUNCTIONAL OVERVIEW</title> |
| <para> |
| Fontconfig contains two essential modules, the configuration module which |
| builds an internal configuration from XML files and the matching module |
| which accepts font patterns and returns the nearest matching font. |
| </para> |
| <sect2><title>FONT CONFIGURATION</title> |
| <para> |
| The configuration module consists of the FcConfig datatype, libexpat and |
| FcConfigParse which walks over an XML tree and ammends a configuration with |
| data found within. From an external perspective, configuration of the |
| library consists of generating a valid XML tree and feeding that to |
| FcConfigParse. The only other mechanism provided to applications for |
| changing the running configuration is to add fonts and directories to the |
| list of application-provided font files. |
| </para><para> |
| The intent is to make font configurations relatively static, and shared by |
| as many applications as possible. It is hoped that this will lead to more |
| stable font selection when passing names from one application to another. |
| XML was chosen as a configuration file format because it provides a format |
| which is easy for external agents to edit while retaining the correct |
| structure and syntax. |
| </para><para> |
| Font configuration is separate from font matching; applications needing to |
| do their own matching can access the available fonts from the library and |
| perform private matching. The intent is to permit applications to pick and |
| choose appropriate functionality from the library instead of forcing them to |
| choose between this library and a private configuration mechanism. The hope |
| is that this will ensure that configuration of fonts for all applications |
| can be centralized in one place. Centralizing font configuration will |
| simplify and regularize font installation and customization. |
| </para> |
| </sect2> |
| <sect2> |
| <title>FONT PROPERTIES</title> |
| <para> |
| While font patterns may contain essentially any properties, there are some |
| well known properties with associated types. Fontconfig uses some of these |
| properties for font matching and font completion. Others are provided as a |
| convenience for the applications rendering mechanism. |
| </para> |
| <table> |
| <title>Property Definitions</title> |
| <tgroup cols=4 align=left colsep=1 rowsep=1> |
| <colspec colname=Property> |
| <colspec colname=CPP> |
| <colspec colname=Type> |
| <colspec colname=Description> |
| <thead> |
| <row> |
| <entry>Property</entry> |
| <entry>CPP Symbol</entry> |
| <entry>Type</entry> |
| <entry>Description</entry> |
| </row> |
| </thead> |
| <tbody> |
| <row><entry>family</entry><entry>FC_FAMILY</entry><entry>String</entry><entry>Font family name</entry></row> |
| <row><entry>style</entry><entry>FC_STYLE</entry><entry>String</entry><entry>Font style. Overrides weight and slant</entry></row> |
| <row><entry>slant</entry><entry>FC_SLANT</entry><entry>Int</entry><entry>Italic, oblique or roman</entry></row> |
| <row><entry>weight</entry><entry>FC_WEIGHT</entry><entry>Int</entry><entry>Light, medium, demibold, bold or black</entry></row> |
| <row><entry>size</entry><entry>FC_SIZE</entry><entry>Double</entry><entry>Point size</entry></row> |
| <row><entry>aspect</entry><entry>FC_ASPECT</entry><entry>Double</entry><entry>Stretches glyphs horizontally before hinting</entry></row> |
| <row><entry>pixelsize</entry><entry>FC_PIXEL_SIZE</entry><entry>Double</entry><entry>Pixel size</entry></row> |
| <row><entry>spacing</entry><entry>FC_SPACING</entry><entry>Int</entry><entry>Proportional, monospace or charcell</entry></row> |
| <row><entry>foundry</entry><entry>FC_FOUNDRY</entry><entry>String</entry><entry>Font foundry name</entry></row> |
| <row><entry>antialias</entry><entry>FC_ANTIALIAS</entry><entry>Bool</entry><entry>Whether glyphs can be antialiased</entry></row> |
| <row><entry>hinting</entry><entry>FC_HINTING</entry><entry>Bool</entry><entry>Whether the rasterizer should use hinting</entry></row> |
| <row><entry>verticallayout</entry><entry>FC_VERTICAL_LAYOUT</entry><entry>Bool</entry><entry>Use vertical layout</entry></row> |
| <row><entry>autohint</entry><entry>FC_AUTOHINT</entry><entry>Bool</entry><entry>Use autohinter instead of normal hinter</entry></row> |
| <row><entry>globaladvance</entry><entry>FC_GLOBAL_ADVANCE</entry><entry>Bool</entry><entry>Use font global advance data</entry></row> |
| <row><entry>file</entry><entry>FC_FILE</entry><entry>String</entry><entry>The filename holding the font</entry></row> |
| <row><entry>index</entry><entry>FC_INDEX</entry><entry>Int</entry><entry>The index of the font within the file</entry></row> |
| <row><entry>ftface</entry><entry>FC_FT_FACE</entry><entry>FT_Face</entry><entry>Use the specified FreeType face object</entry></row> |
| <row><entry>rasterizer</entry><entry>FC_RASTERIZER</entry><entry>String</entry><entry>Which rasterizer is in use</entry></row> |
| <row><entry>outline</entry><entry>FC_OUTLINE</entry><entry>Bool</entry><entry>Whether the glyphs are outlines</entry></row> |
| <row><entry>scalable</entry><entry>FC_SCALABLE</entry><entry>Bool</entry><entry>Whether glyphs can be scaled</entry></row> |
| <row><entry>scale</entry><entry>FC_SCALE</entry><entry>Double</entry><entry>Scale factor for point->pixel conversions</entry></row> |
| <row><entry>dpi</entry><entry>FC_DPI</entry><entry>Double</entry><entry>Target dots per inch</entry></row> |
| <row><entry>rgba</entry><entry>FC_RGBA</entry><entry>Int</entry><entry>unknown, rgb, bgr, vrgb, vbgr, none - subpixel geometry</entry></row> |
| <row><entry>minspace</entry><entry>FC_MINSPACE</entry><entry>Bool</entry><entry>Eliminate leading from line spacing</entry></row> |
| <row><entry>charset</entry><entry>FC_CHARSET</entry><entry>CharSet</entry><entry>Unicode chars encoded by the font</entry></row> |
| <row><entry>lang</entry><entry>FC_LANG</entry><entry>String</entry><entry>List of RFC-3066-style languages this font supports</entry></row> |
| </tbody> |
| </tgroup> |
| </table> |
| </sect2> |
| </sect1> |
| <sect1><title>DATATYPES</title> |
| <para> |
| Fontconfig uses abstract datatypes to hide internal implementation details |
| for most data structures. A few structures are exposed where appropriate. |
| </para> |
| <sect2><title>FcChar8, FcChar16, FcChar32, FcBool</title> |
| <para> |
| These are primitive datatypes; the FcChar* types hold precisely the number |
| of bits stated (if supported by the C implementation). FcBool holds |
| one of two CPP symbols: FcFalse or FcTrue. |
| </para> |
| </sect2> |
| <sect2><title>FcMatrix</title> |
| <para> |
| An FcMatrix holds an affine transformation, usually used to reshape glyphs. |
| A small set of matrix operations are provided to manipulate these. |
| <programlisting> |
| typedef struct _FcMatrix { |
| double xx, xy, yx, yy; |
| } FcMatrix; |
| </programlisting> |
| </para> |
| </sect2> |
| <sect2> |
| <title>FcCharSet</title> |
| <para> |
| An FcCharSet is an abstract type that holds the set of encoded unicode chars |
| in a font. Operations to build and compare these sets are provided. |
| </para> |
| </sect2> |
| <sect2> |
| <title>FcType</title> |
| <para> |
| Tags the kind of data stored in an FcValue. |
| </para> |
| </sect2> |
| <sect2> |
| <title>FcValue</title> |
| <para> |
| An FcValue object holds a single value with one of a number of different |
| types. The 'type' tag indicates which member is valid. |
| <programlisting> |
| typedef struct _FcValue { |
| FcType type; |
| union { |
| const FcChar8 *s; |
| int i; |
| FcBool b; |
| double d; |
| const FcMatrix *m; |
| const FcCharSet *c; |
| } u; |
| } FcValue; |
| </programlisting> |
| <table colsep=0 rowsep=0> |
| <title>FcValue Members</title> |
| <tgroup cols=3 align=left colsep=0 rowsep=0> |
| <thead><row> |
| <entry>Type</entry> |
| <entry>Union member</entry> |
| <entry>Datatype</entry> |
| </row></thead> |
| <tbody> |
| <row><entry>FcTypeVoid</entry><entry>(none)</entry><entry>(none)</entry></row> |
| <row><entry>FcTypeInteger</entry><entry>i</entry><entry>int</entry></row> |
| <row><entry>FcTypeDouble</entry><entry>d</entry><entry>double</entry></row> |
| <row><entry>FcTypeString</entry><entry>s</entry><entry>char *</entry></row> |
| <row><entry>FcTypeBool</entry><entry>b</entry><entry>b</entry></row> |
| <row><entry>FcTypeMatrix</entry><entry>m</entry><entry>FcMatrix *</entry></row> |
| <row><entry>FcTypeCharSet</entry><entry>c</entry><entry>FcCharSet *</entry></row> |
| </tbody> |
| </tgroup> |
| </table> |
| </para> |
| </sect2> |
| <sect2> |
| <title>FcPattern</title> |
| <para> |
| holds a set of names with associated value lists; each name refers to a |
| property of a font. FcPatterns are used as inputs to the matching code as |
| well as holding information about specific fonts. Each property can hold |
| one or more values; conventionally all of the same type, although the |
| interface doesn't demand that. |
| </para> |
| </sect2> |
| <sect2> |
| <title>FcFontSet</title> |
| <para> |
| <programlisting> |
| typedef struct _FcFontSet { |
| int nfont; |
| int sfont; |
| FcPattern **fonts; |
| } FcFontSet; |
| </programlisting> |
| An FcFontSet contains a list of FcPatterns. Internally fontconfig uses this |
| data structure to hold sets of fonts. Externally, fontconfig returns the |
| results of listing fonts in this format. 'nfont' holds the number of |
| patterns in the 'fonts' array; 'sfont' is used to indicate the size of that |
| array. |
| </para> |
| </sect2> |
| <sect2> |
| <title>FcStrSet, FcStrList</title> |
| <para> |
| FcStrSet holds a list of strings that can be appended to and enumerated. |
| Its unique characteristic is that the enumeration works even while strings |
| are appended during enumeration. FcStrList is used during enumeration to |
| safely and correctly walk the list of strings even while that list is edited |
| in the middle of enumeration. |
| </para> |
| </sect2> |
| <sect2> |
| <title>FcObjectSet</title> |
| <para> |
| <programlisting> |
| typedef struct _FcObjectSet { |
| int nobject; |
| int sobject; |
| const char **objects; |
| } FcObjectSet; |
| </programlisting> |
| holds a set of names and is used to specify which fields from fonts are |
| placed in the the list of returned patterns when listing fonts. |
| </para> |
| </sect2> |
| <sect2> |
| <title>FcObjectType</title> |
| <para> |
| <programlisting> |
| typedef struct _FcObjectType { |
| const char *object; |
| FcType type; |
| } FcObjectType; |
| </programlisting> |
| marks the type of a pattern element generated when parsing font names. |
| Applications can add new object types so that font names may contain the new |
| elements. |
| </para> |
| </sect2> |
| <sect2> |
| <title>FcConstant</title> |
| <para> |
| <programlisting> |
| typedef struct _FcConstant { |
| const FcChar8 *name; |
| const char *object; |
| int value; |
| } FcConstant; |
| </programlisting> |
| Provides for symbolic constants for new pattern elements. When 'name' is |
| seen in a font name, an 'object' element is created with value 'value'. |
| </para> |
| </sect2> |
| <sect2> |
| <title>FcBlanks</title> |
| <para> |
| holds a list of Unicode chars which are expected to be blank; unexpectedly |
| blank chars are assumed to be invalid and are elided from the charset |
| associated with the font. |
| </para> |
| </sect2> |
| <sect2> |
| <title>FcFileCache</title> |
| <para> |
| holds the per-user cache information for use while loading the font |
| database. This is built automatically for the current configuration when |
| that is loaded. Applications must always pass '0' when one is requested. |
| </para> |
| </sect2> |
| <sect2> |
| <title>FcConfig</title> |
| <para> |
| holds a complete configuration of the library; there is one default |
| configuration, other can be constructed from XML data structures. All |
| public entry points that need global data can take an optional FcConfig* |
| argument; passing 0 uses the default configuration. FcConfig objects hold two |
| sets of fonts, the first contains those specified by the configuration, the |
| second set holds those added by the application at run-time. Interfaces |
| that need to reference a particulat set use one of the FcSetName enumerated |
| values. |
| </para> |
| </sect2> |
| <sect2> |
| <title>FcSetName</title> |
| <para> |
| Specifies one of the two sets of fonts available in a configuration; |
| FcSetSystem for those fonts specified in the configuration and |
| FcSetApplication which holds fonts provided by the application. |
| </para> |
| </sect2> |
| <sect2> |
| <title>FcResult</title> |
| <para> |
| Used as a return type for functions manipulating FcPattern objects. |
| <table colsep=0 rowsep=0> |
| <title>FcResult Values</title> |
| <tgroup cols=2 align=left colsep=0 rowsep=0> |
| <thead><row> |
| <entry>Result Code</entry> |
| <entry>Meaning</entry> |
| </row></thead> |
| <tbody> |
| <row><entry>FcResultMatch</entry><entry>Object exists with the specified ID</entry></row> |
| <row><entry>FcResultNoMatch</entry><entry>Object doesn't exist at all</entry></row> |
| <row><entry>FcResultTypeMismatch</entry><entry>Object exists, but the type doesn't match</entry></row> |
| <row><entry>FcResultNoId</entry><entry>Object exists, but has fewer values than specified</entry></row> |
| </tbody> |
| </tgroup> |
| </table> |
| </para> |
| </sect2> |
| <sect2> |
| <title>FcAtomic</title> |
| <para> |
| Used for locking access to config files. Provides a safe way to update |
| configuration files. |
| </para> |
| </sect2> |
| </sect1> |
| <sect1><title>FUNCTIONS</title> |
| <para> |
| Functions are grouped by the main datatype involved |
| </para> |
| <sect2><title>FcMatrix</title> |
| <para> |
| FcMatrix structures hold an affine transformation in matrix form. |
| </para> |
| <sect3><title>FcMatrixInit</title><programlisting> |
| #define FcMatrixInit(m) ((m)->xx = (m)->yy = 1, (m)->xy = (m)->yx = 0) |
| </programlisting><para> |
| Initializes a matrix to the identify transformation. |
| </para></sect3> |
| <sect3><title>FcMatrixCopy</title><programlisting> |
| FcMatrix *FcMatrixCopy (const FcMatrix *mat) |
| </programlisting><para> |
| Allocates a new FcMatrix and copies 'mat' into it. |
| </para></sect3> |
| <sect3><title>FcMatrixEqual</title><programlisting> |
| FcBool FcMatrixEqual (const FcMatrix *mat1, const FcMatrix *mat2) |
| </programlisting><para> |
| Returns FcTrue if 'mat1' and 'mat2' are equal, else FcFalse. |
| </para></sect3> |
| <sect3><title>FcMatrixMultiply</title><programlisting> |
| void FcMatrixMultiply (FcMatrix *result, const FcMatrix *a, const FcMatrix *b) |
| </programlisting><para> |
| Multiplies 'a' and 'b' together, placing the result in 'result'. 'result' |
| may refer to the sam matrix as either 'a' or 'b'. |
| </para></sect3> |
| <sect3><title>FcMatrixRotate</title><programlisting> |
| void FcMatrixRotate (FcMatrix *m, double c, double s) |
| </programlisting><para> |
| If 'c' is cos(angle) and 's' is sin(angle), FcMatrixRotate rotates the |
| matrix by 'angle'. |
| </para></sect3> |
| <sect3><title>FcMatrixScale</title><programlisting> |
| void FcMatrixScale (FcMatrix *m, double sx, double sy) |
| </programlisting><para> |
| Scales 'm' by 'sx' in the horizontal dimension and 'sy' in the |
| vertical dimension. |
| </para></sect3> |
| <sect3><title>FcMatrixShear</title><programlisting> |
| void FcMatrixShear (FcMatrix *m, double sh, double sv) |
| </programlisting><para> |
| Shears 'm' by 'sh' in the horizontal direction and 'sv' in the |
| vertical direction. |
| </para></sect3> |
| </sect2> |
| <sect2><title>FcCharSet</title> |
| <para> |
| An FcCharSet is a boolean array indicating a set of unicode chars. Those |
| associated with a font are marked constant and cannot be edited. |
| FcCharSets may be reference counted internally to reduce memory consumption; |
| this may be visible to applications as the result of FcCharSetCopy may |
| return it's argument, and that CharSet may remain unmodifiable. |
| </para> |
| <sect3><title>FcCharSetCreate</title><programlisting> |
| FcCharSet *FcCharSetCreate (void) |
| </programlisting><para> |
| Creates an empty FcCharSet object. |
| </para></sect3> |
| <sect3><title>FcCharSetDestroy</title><programlisting> |
| void FcCharSetDestroy (FcCharSet *fcs) |
| </programlisting><para> |
| Frees an FcCharSet object. |
| </para></sect3> |
| <sect3><title>FcCharSetAddChar</title><programlisting> |
| FcBool FcCharSetAddChar (FcCharSet *fcs, FcChar32 ucs4) |
| </programlisting><para> |
| Adds a single unicode char to the set, returning FcFalse on |
| failure, either as a result of a constant set or from running out of memory. |
| </para></sect3> |
| <sect3><title>FcCharSetCopy</title><programlisting> |
| FcCharSet *FcCharSetCopy (FcCharSet *src) |
| </programlisting><para> |
| Makes a copy of 'src'; note that this may not actually do anything more than |
| increment the reference count on 'src'. |
| </para></sect3> |
| <sect3><title>FcCharSetEqual</title><programlisting> |
| FcBool FcCharSetEqual (const FcCharSet *a, const FcCharSet *b) |
| </programlisting><para> |
| Returns whether 'a' and 'b' contain the same set of unicode chars. |
| </para></sect3> |
| <sect3><title>FcCharSetIntersect</title><programlisting> |
| FcCharSet *FcCharSetIntersect (const FcCharSet *a, const FcCharSet *b) |
| </programlisting><para> |
| Returns a set including only those chars found in both 'a' and 'b'. |
| </para></sect3> |
| <sect3><title>FcCharSetUnion</title><programlisting> |
| FcCharSet *FcCharSetUnion (const FcCharSet *a, const FcCharSet *b); |
| </programlisting><para> |
| Returns a set including only those chars found in either 'a' or 'b'. |
| </para></sect3> |
| <sect3><title>FcCharSetSubtract</title><programlisting> |
| FcCharSet *FcCharSetSubtract (const FcCharSet *a, const FcCharSet *b) |
| </programlisting><para> |
| Returns a set including only those chars found in 'a' but not 'b'. |
| </para></sect3> |
| <sect3><title>FcCharSetHasChar</title><programlisting> |
| FcBool FcCharSetHasChar (const FcCharSet *fcs, FcChar32 ucs4) |
| </programlisting><para> |
| Returns whether 'fcs' contains the char 'ucs4'. |
| </para></sect3> |
| <sect3><title>FcCharSetCount</title><programlisting> |
| FcChar32 FcCharSetCount (const FcCharSet *a) |
| </programlisting><para> |
| Returns the total number of unicode chars in 'a'. |
| </para></sect3> |
| <sect3><title>FcCharSetIntersectCount</title><programlisting> |
| FcChar32 FcCharSetIntersectCount (const FcCharSet *a, const FcCharSet *b) |
| </programlisting><para> |
| Returns the number of chars that are in both 'a' and 'b'. |
| </para></sect3> |
| <sect3><title>FcCharSetSubtractCount</title><programlisting> |
| FcChar32 FcCharSetSubtractCount (const FcCharSet *a, const FcCharSet *b) |
| </programlisting><para> |
| Returns the number of chars that are in 'a' but not in 'b'. |
| </para></sect3> |
| <sect3><title>FcCharSetIsSubset</title><programlisting> |
| FcBool FcCharSetIsSubset (const FcCharSet *a, const FcCharSet *b) |
| </programlisting><para> |
| Returns whether 'a' is a subset of 'b'. |
| </para></sect3> |
| <sect3><title>FcCharSetFirstPage</title><programlisting> |
| FcChar32 FcCharSetFirstPage (const FcCharSet *a, FcChar32 [FC_CHARSET_MAP_SIZE], FcChar32 *next) |
| </programlisting><para> |
| Builds an array of bits marking the first page of Unicode coverage of 'a'. |
| Returns the base of the array. 'next' contains the next page in the font. |
| </para></sect3> |
| <sect3><title>FcCharSetNextPage</title><programlisting> |
| FcChar32 FcCharSetNextPage (const FcCharSet *a, FcChar32 [FC_CHARSET_MAP_SIZE], FcChar32 *next) |
| </programlisting><para> |
| Builds an array of bits marking the Unicode coverage of 'a' for page '*next'. |
| Returns the base of the array. 'next' contains the next page in the font. |
| </para></sect3> |
| </sect2> |
| <sect2><title>FcValue</title> |
| <para> |
| FcValue is a structure containing a type tag and a union of all possible |
| datatypes. The tag is an enum of type |
| <emphasis>FcType</emphasis> |
| and is intended to provide a measure of run-time |
| typechecking, although that depends on careful programming. |
| </para> |
| <sect3><title>FcValueDestroy</title><programlisting> |
| void FcValueDestroy (FcValue v) |
| </programlisting><para> |
| Frees any memory referenced by `v'. Values of type FcTypeString, |
| FcTypeMatrix and FcTypeCharSet reference memory, the other types do not. |
| </para></sect3> |
| <sect3><title>FcValueSave</title><programlisting> |
| FcValue FcValueSave (FcValue v) |
| </programlisting><para> |
| Returns a copy of `v' duplicating any object referenced by it so that `v' |
| may be safely destroyed without harming the new value. |
| </para></sect3> |
| </sect2> |
| <sect2><title>FcPattern</title> |
| <para> |
| An FcPattern is an opaque type that holds both patterns to match against the |
| available fonts, as well as the information about each font. |
| </para> |
| <sect3><title>FcPatternCreate</title><programlisting> |
| FcPattern *FcPatternCreate (void) |
| </programlisting><para> |
| Creates a pattern with no properties; used to build patterns from scratch. |
| </para></sect3> |
| <sect3><title>FcPatternDestroy</title><programlisting> |
| void FcPatternDestroy (FcPattern *p) |
| </programlisting><para> |
| Destroys a pattern, in the process destroying all related values. |
| </para></sect3> |
| <sect3><title>FcPatternEqual</title><programlisting> |
| FcBool FcPatternEqual (const FcPattern *pa, const FcPattern *pb); |
| </programlisting><para> |
| Returns whether 'pa' and 'pb' are exactly alike. |
| </para></sect3> |
| <sect3><title>FcPatternEqualSubset</title><programlisting> |
| FcBool FcPatternEqualSubset (const FcPattern *pa, const FcPattern *pb, const FcObjectSet *os) |
| </programlisting><para> |
| Returns whether 'pa' and 'pb' have exactly the same values for all of the |
| objects in 'os'. |
| </para></sect3> |
| <sect3><title>FcPatternHash</title><programlisting> |
| FcChar32 FcPatternHash (const FcPattern *p) |
| </programlisting><para> |
| Returns a 32-bit number which is the same for any two patterns which are |
| exactly alike. |
| </para></sect3> |
| <sect3><title>FcPatternAdd</title><programlisting> |
| FcBool FcPatternAdd (FcPattern *p, const char *object, FcValue value, FcBool append) |
| </programlisting><para> |
| Adds a single value to the list of values associated with the property named |
| `object'. If `append' is FcTrue, the value is added at the end of any |
| existing list, otherwise it is inserted at the begining. `value' is saved |
| (with FcValueSave) when inserted into the pattern so that the library |
| retains no reference to any application-supplied data structure. |
| </para></sect3> |
| <sect3><title>FcPatternAddWeak</title><programlisting> |
| FcBool FcPatternAddWeak (FcPattern *p, const char *object, FcValue value, FcBool append) |
| </programlisting><para> |
| FcPatternAddWeak is essentially the same as FcPatternAdd except that any |
| values added to the list have binding 'weak' instead of 'strong'. |
| </para></sect3> |
| <sect3><title>FcPatternAdd <emphasis>Type</emphasis></title><programlisting> |
| FcBool FcPatternAddInteger (FcPattern *p, const char *object, int i) |
| FcBool FcPatternAddDouble (FcPattern *p, const char *object, double d) |
| FcBool FcPatternAddString (FcPattern *p, const char *object, const char *s) |
| FcBool FcPatternAddMatrix (FcPattern *p, const char *object, const FcMatrix *s) |
| FcBool FcPatternAddCharSet (FcPattern *p, const char *object, const FcCharSet *c) |
| FcBool FcPatternAddBool (FcPattern *p, const char *object, FcBool b) |
| </programlisting><para> |
| These are all convenience functions that insert objects of the specified |
| type into the pattern. Use these in preference to FcPatternAdd as they |
| will provide compile-time typechecking. These all append values to |
| any existing list of values. |
| </para></sect3> |
| <sect3><title>FcPatternGet</title><programlisting> |
| FcResult FcPatternGet (FcPattern *p, const char *object, int id, FcValue *v) |
| </programlisting><para> |
| Returns in `v' the `id'th value associated with the property `object'. |
| The value returned is not a copy, but rather refers to the data stored |
| within the pattern directly. Applications must not free this value. |
| </para></sect3> |
| <sect3><title>FcPatternGet <emphasis>Type</emphasis></title><programlisting> |
| FcResult FcPatternGetInteger (FcPattern *p, const char *object, int n, int *i); |
| FcResult FcPatternGetDouble (FcPattern *p, const char *object, int n, double *d); |
| FcResult FcPatternGetString (FcPattern *p, const char *object, int n, char **const s); |
| FcResult FcPatternGetMatrix (FcPattern *p, const char *object, int n, FcMatrix **s); |
| FcResult FcPatternGetCharSet (FcPattern *p, const char *object, int n, FcCharSet **c); |
| FcResult FcPatternGetBool (FcPattern *p, const char *object, int n, FcBool *b); |
| </programlisting><para> |
| These are convenience functions that call FcPatternGet and verify that the |
| returned data is of the expected type. They return FcResultTypeMismatch if |
| this is not the case. Note that these (like FcPatternGet) do not make a |
| copy of any data structure referenced by the return value. Use these |
| in preference to FcPatternGet to provide compile-time typechecking. |
| </para></sect3> |
| <sect3><title>FcPatternBuild, FcPatternVaBuild</title><programlisting> |
| FcPattern *FcPatternBuild (FcPattern *orig, ...); |
| FcPattern *FcPatternVaBuild (FcPattern *orig, va_list va) |
| </programlisting><para> |
| Builds a pattern using a list of objects, types and values. Each |
| value to be entered in the pattern is specified with three arguments: |
| </para> |
| <orderedlist> |
| <listitem><para> |
| Object name, a string describing the property to be added. |
| </para></listitem><listitem><para> |
| Object type, one of the FcType enumerated values |
| </para></listitem><listitem><para> |
| Value, not an FcValue, but the raw type as passed to any of the |
| FcPatternAdd<type> functions. Must match the type of the second |
| argument. |
| </para></listitem> |
| </orderedlist> |
| <para> |
| The argument list is terminated by a null object name, no object type nor |
| value need be passed for this. The values are added to `pattern', if |
| `pattern' is null, a new pattern is created. In either case, the pattern is |
| returned. Example |
| </para> |
| <programlisting> |
| pattern = FcPatternBuild (0, FC_FAMILY, FtTypeString, "Times", (char *) 0); |
| </programlisting> |
| <para> |
| FcPatternVaBuild is used when the arguments are already in the form of a |
| varargs value. |
| </para></sect3> |
| <sect3><title>FcPatternDel</title><programlisting> |
| FcBool FcPatternDel (FcPattern *p, const char *object) |
| </programlisting><para> |
| Deletes all values associated with the property `object', returning |
| whether the property existed or not. |
| </para></sect3> |
| <sect3><title>FcPatternPrint</title><programlisting> |
| void FcPatternPrint (const FcPattern *p) |
| </programlisting><para> |
| Prints an easily readable version of the pattern to stdout. There is |
| no provision for reparsing data in this format, it's just for diagnostics |
| and debugging. |
| </para></sect3> |
| <sect3><title>FcDefaultSubstitute</title><programlisting> |
| void FcDefaultSubstitute (FcPattern *pattern) |
| </programlisting><para> |
| Supplies default values for underspecified font patterns: |
| <itemizedlist> |
| <listitem><para> |
| Patterns without a specified style or weight are set to Medium |
| </para></listitem> |
| <listitem><para> |
| Patterns without a specified style or slant are set to Roman |
| </para></listitem> |
| <listitem><para> |
| Patterns without a specified pixel size are given one computed from any |
| specified point size (default 12), dpi (default 75) and scale (default 1). |
| </para></listitem> |
| </itemizedlist> |
| </para></sect3> |
| <sect3><title>FcNameParse</title><programlisting> |
| FcPattern *FcNameParse (const char *name) |
| </programlisting><para> |
| Converts 'name' from the standard text format described above into a pattern. |
| </para></sect3> |
| <sect3><title>FcNameUnparse</title><programlisting> |
| FcChar8 *FcNameUnparse (FcPattern *pat) |
| </programlisting><para> |
| Converts the given pattern into the standard text format described above. |
| The return value is not static, but instead refers to newly allocated memory |
| which should be freed by the caller. |
| </para></sect3> |
| </sect2> |
| <sect2><title>FcFontSet</title> |
| <para> |
| An FcFontSet simply holds a list of patterns; these are used to return the |
| results of listing available fonts. |
| </para> |
| <sect3><title>FcFontSetCreate</title><programlisting> |
| FcFontSet *FcFontSetCreate (void) |
| </programlisting><para> |
| Creates an empty font set. |
| </para></sect3> |
| <sect3><title>FcFontSetDestroy</title><programlisting> |
| void FcFontSetDestroy (FcFontSet *s); |
| </programlisting><para> |
| Destroys a font set. Note that this destroys any referenced patterns as |
| well. |
| </para></sect3> |
| <sect3><title>FcFontSetAdd</title><programlisting> |
| FcBool FcFontSetAdd (FcFontSet *s, FcPattern *font) |
| </programlisting><para> |
| Adds a pattern to a font set. Note that the pattern is not copied before |
| being inserted into the set. |
| </para></sect3> |
| </sect2> |
| <sect2><title>FcObjectSet</title> |
| <para> |
| An FcObjectSet holds a list of pattern property names; it is used to |
| indiciate which properties are to be returned in the patterns from |
| FcFontList. |
| </para> |
| <sect3><title>FcObjectSetCreate</title><programlisting> |
| FcObjectSet *FcObjectSetCreate (void) |
| </programlisting><para> |
| Creates an empty set. |
| </para></sect3> |
| <sect3><title>FcObjectSetAdd</title><programlisting> |
| FcBool FcObjectSetAdd (FcObjectSet *os, const char *object) |
| </programlisting><para> |
| Adds a proprety name to the set. |
| </para></sect3> |
| <sect3><title>FcObjectSetDestroy</title><programlisting> |
| void FcObjectSetDestroy (FcObjectSet *os) |
| </programlisting><para> |
| Destroys an object set. |
| </para></sect3> |
| <sect3><title>FcObjectSetBuild, FcObjectSetVaBuild</title><programlisting> |
| FcObjectSet *FcObjectSetBuild (const char *first, ...) |
| FcObjectSet *FcObjectSetVaBuild (const char *first, va_list va) |
| </programlisting><para> |
| These build an object set from a null-terminated list of property names. |
| </para></sect3> |
| </sect2> |
| <sect2><title>FcObjectType</title> |
| <para> |
| Provides for applcation-specified font name object types so that new |
| pattern elements can be generated from font names. |
| </para> |
| <sect3><title>FcNameRegisterObjectTypes</title><programlisting> |
| FcBool FcNameRegisterObjectTypes (const FcObjectType *types, int ntype) |
| </programlisting><para> |
| Register 'ntype' new object types. |
| </para></sect3> |
| <sect3><title>FcNameUnregisterObjectTypes</title><programlisting> |
| FcBool FcNameUnregisterObjectTypes (const FcObjectType *types, int ntype) |
| </programlisting><para> |
| Unregister 'ntype' object types. |
| </para></sect3> |
| <sect3><title>FcNameGetObjectType</title><programlisting> |
| const FcObjectType *FcNameGetObjectType (const char *object) |
| </programlisting><para> |
| Return the object type for the pattern element named 'object'. |
| </para></sect3> |
| </sect2> |
| <sect2><title>FcConstant</title> |
| <para> |
| Provides for application-specified symbolic constants for font names. |
| </para> |
| <sect3><title>FcNameRegisterConstants</title><programlisting> |
| FcBool FcNameRegisterConstants (const FcConstant *consts, int nconsts) |
| </programlisting><para> |
| Register 'nconsts' new symbolic constants. |
| </para></sect3> |
| <sect3><title>FcNameUnregisterConstants</title><programlisting> |
| FcBool FcNameUnregisterConstants (const FcConstant *consts, int nconsts) |
| </programlisting><para> |
| Unregister 'nconsts' symbolic constants. |
| </para></sect3> |
| <sect3><title>FcNameGetConstant</title><programlisting> |
| const FcConstant *FcNameGetConstant (FcChar8 *string) |
| </programlisting><para> |
| Return the FcConstant structure related to symbolic constant 'string'. |
| </para></sect3> |
| <sect3><title>FcNameConstant</title><programlisting> |
| FcBool FcNameConstant (FcChar8 *string, int *result); |
| </programlisting><para> |
| Returns whether a symbolic constant with name 'string' is registered, |
| placing the value of the constant in 'result' if present. |
| </para></sect3> |
| </sect2> |
| <sect2><title>FcBlanks</title> |
| <para> |
| An FcBlanks object holds a list of Unicode chars which are expected to |
| be blank when drawn. When scanning new fonts, any glyphs which are |
| empty and not in this list will be assumed to be broken and not placed in |
| the FcCharSet associated with the font. This provides a significantly more |
| accurate CharSet for applications. |
| </para> |
| <sect3><title>FcBlanksCreate</title><programlisting> |
| FcBlanks *FcBlanksCreate (void) |
| </programlisting><para> |
| Creates an empty FcBlanks object. |
| </para></sect3> |
| <sect3><title>FcBlanksDestroy</title><programlisting> |
| void FcBlanksDestroy (FcBlanks *b) |
| </programlisting><para> |
| Destroys an FcBlanks object, freeing any associated memory. |
| </para></sect3> |
| <sect3><title>FcBlanksAdd</title><programlisting> |
| FcBool FcBlanksAdd (FcBlanks *b, FcChar32 ucs4) |
| </programlisting><para> |
| Adds a single character to an FcBlanks object, returning FcFalse |
| if this process ran out of memory. |
| </para></sect3> |
| <sect3><title>FcBlanksIsMember</title><programlisting> |
| FcBool FcBlanksIsMember (FcBlanks *b, FcChar32 ucs4) |
| </programlisting><para> |
| Returns whether the specified FcBlanks object contains the indicated Unicode |
| value. |
| </para></sect3> |
| </sect2> |
| <sect2><title>FcConfig</title> |
| <para> |
| An FcConfig object holds the internal representation of a configuration. |
| There is a default configuration which applications may use by passing 0 to |
| any function using the data within an FcConfig. |
| </para> |
| <sect3><title>FcConfigCreate</title><programlisting> |
| FcConfig *FcConfigCreate (void) |
| </programlisting><para> |
| Creates an empty configuration. |
| </para></sect3> |
| <sect3><title>FcConfigDestroy</title><programlisting> |
| void FcConfigDestroy (FcConfig *config) |
| </programlisting><para> |
| Destroys a configuration and any data associated with it. Note that calling |
| this function with the return from FcConfigGetCurrent will place the library |
| in an indeterminate state. |
| </para></sect3> |
| <sect3><title>FcConfigSetCurrent</title><programlisting> |
| FcBool FcConfigSetCurrent (FcConfig *config) |
| </programlisting><para> |
| Sets the current default configuration to 'config'. Implicitly calls |
| FcConfigBuildFonts if necessary, returning FcFalse if that call fails. |
| </para></sect3> |
| <sect3><title>FcConfigGetCurrent</title><programlisting> |
| FcConfig *FcConfigGetCurrent (void) |
| </programlisting><para> |
| Returns the current default configuration. |
| </para></sect3> |
| <sect3><title>FcConfigUptoDate</title><programlisting> |
| FcBool FcConfigUptoDate (FcConfig *config) |
| </programlisting><para> |
| Checks all of the files related to 'config' and returns whether the |
| in-memory version is in sync with the disk version. |
| </para></sect3> |
| <sect3><title>FcConfigBuildFonts</title><programlisting> |
| FcBool FcConfigBuildFonts (FcConfig *config) |
| </programlisting><para> |
| Builds the set of available fonts for the given configuration. Note that |
| any changes to the configuration after this call have indeterminate effects. |
| Returns FcFalse if this operation runs out of memory. |
| </para></sect3> |
| <sect3><title>FcConfigGetConfigDirs</title><programlisting> |
| FcStrList *FcConfigGetConfigDirs (FcConfig *config) |
| </programlisting><para> |
| Returns the list of font directories specified in the configuration files |
| for 'config'. Does not include any subdirectories. |
| </para></sect3> |
| <sect3><title>FcConfigGetFontDirs</title><programlisting> |
| FcStrList *FcConfigGetFontDirs (FcConfig *config) |
| </programlisting><para> |
| Returns the list of font directories in 'config'. This includes the |
| configured font directories along with any directories below those in the |
| filesystem. |
| </para></sect3> |
| <sect3><title>FcConfigGetConfigFiles</title><programlisting> |
| FcStrList *FcConfigGetConfigFiles (FcConfig *config) |
| </programlisting><para> |
| Returns the list of known configuration files used to generate 'config'. |
| Note that this will not include any configuration done with FcConfigParse. |
| </para></sect3> |
| <sect3><title>FcConfigGetCache</title><programlisting> |
| char *FcConfigGetCache (FcConfig *config) |
| </programlisting><para> |
| Returns the name of the file used to store per-user font information. |
| </para></sect3> |
| <sect3><title>FcConfigGetFonts</title><programlisting> |
| FcFontSet *FcConfigGetFonts (FcConfig *config, FcSetName set) |
| </programlisting><para> |
| Returns one of the two sets of fonts from the configuration as specified |
| by 'set'. |
| </para></sect3> |
| <sect3><title>FcConfigGetBlanks</title><programlisting> |
| FcBlanks *FcConfigGetBlanks (FcConfig *config) |
| </programlisting><para> |
| Returns the FcBlanks object associated with the given configuration, if no |
| blanks were present in the configuration, this function will return 0. |
| </para></sect3> |
| <sect3><title>FcConfigGetRescanInverval</title><programlisting> |
| int FcConfigGetRescanInverval (FcConfig *config) |
| </programlisting><para> |
| Returns the interval between automatic checks of the configuration (in |
| seconds) specified in 'config'. The configuration is checked during |
| a call to FcFontList when this interval has passed since the last check. |
| </para></sect3> |
| <sect3><title>FcConfigSetRescanInverval</title><programlisting> |
| FcBool FcConfigSetRescanInverval (FcConfig *config, int rescanInterval) |
| </programlisting><para> |
| Sets the rescan interval; returns FcFalse if an error occurred. |
| </para></sect3> |
| <sect3><title>FcConfigAppFontAddFile</title><programlisting> |
| FcBool FcConfigAppFontAddFile (FcConfig *config, const char *file) |
| </programlisting><para> |
| Adds an application-specific font to the configuration. |
| </para></sect3> |
| <sect3><title>FcConfigAppFontAddDir</title><programlisting> |
| FcBool FcConfigAppFontAddDir (FcConfig *config, const char *dir) |
| </programlisting><para> |
| Scans the specified directory for fonts, adding each one found to the |
| application-specific set of fonts. |
| </para></sect3> |
| <sect3><title>FcConfigAppFontClear</title><programlisting> |
| void FcConfigAppFontClear (FcConfig *config) |
| </programlisting><para> |
| Clears the set of application-specific fonts. |
| </para></sect3> |
| <sect3><title>FcConfigSubstituteWithPat</title><programlisting> |
| FcBool FcConfigSubstituteWithPat (FcConfig *config, FcPattern *p, FcPattern *p_pat FcMatchKind kind) |
| </programlisting><para> |
| Performs the sequence of pattern modification operations, if 'kind' is |
| FcMatchPattern, then those tagged as pattern operations are applied, else |
| if 'kind' is FcMatchFont, those tagged as font operations are applied and |
| p_pat is used for <test> elements with target=pattern. |
| </para></sect3> |
| <sect3><title>FcConfigSubstitute</title><programlisting> |
| FcBool FcConfigSubstitute (FcConfig *config, FcPattern *p, FcMatchKind kind) |
| </programlisting><para> |
| Calls FcConfigSubstituteWithPat setting p_pat to NULL. |
| </para></sect3> |
| <sect3><title>FcFontMatch</title><programlisting> |
| FcPattern *FcFontMatch (FcConfig *config, FcPattern *p, FcResult *result) |
| </programlisting><para> |
| Returns the font in 'config' most close matching 'p'. This function |
| should be called only after FcConfigSubstitute and FcDefaultSubstitute have |
| been called for 'p'; otherwise the results will not be correct. |
| </para></sect3> |
| <sect3><title>FcFontSort</title><programlisting> |
| FcFontSet *FcFontSort (FcConfig *config, FcPattern *p, FcBool trim, FcCharSet **csp, FcResult *result) |
| </programlisting><para> |
| Returns the list of fonts sorted by closeness to 'p'. If 'trim' is FcTrue, |
| elements in the list which don't include Unicode coverage not provided by |
| earlier elements in the list are elided. The union of Unicode coverage of |
| all of the fonts is returned in 'csp', if 'csp' is not NULL. This function |
| should be called only after FcConfigSubstitute and FcDefaultSubstitute have |
| been called for 'p'; otherwise the results will not be correct. |
| </para><para> |
| The returned FcFontSet references FcPattern structures which may be shared |
| by the return value from multiple FcFontSort calls, applications must not |
| modify these patterns. Instead, they should be passed, along with 'p' to |
| FcFontRenderPrepare which combines them into a complete pattern. |
| </para><para> |
| The FcFontSet returned by FcFontSort is destroyed by caling FcFontSetDestroy. |
| </para></sect3> |
| <sect3><title>FcFontRenderPrepare</title><programlisting> |
| FcPattern *FcFontRenderPrepare (FcConfig *config, FcPattern *pat, FcPattern *font) |
| </programlisting><para> |
| Creates a new pattern consisting of elements of 'font' not appearing |
| in 'pat', elements of 'pat' not appearing in 'font' and the best matching |
| value from 'pat' for elements appearing in both. The result is passed to |
| FcConfigSubstitute with 'kind' FcMatchFont and then returned. |
| </para></sect3> |
| <sect3><title>FcFontList</title><programlisting> |
| FcFontSet *FcFontList (FcConfig *config, FcPattern *p, FcObjectSet *os) |
| </programlisting><para> |
| Selects fonts matching 'p', creates patterns from those fonts containing |
| only the objects in 'os' and returns the set of unique such patterns. |
| </para></sect3> |
| <sect3><title>FcConfigFilename</title><programlisting> |
| char *FcConfigFilename (const char *name) |
| </programlisting><para> |
| Given the specified external entity name, return the associated filename. |
| This provides applications a way to convert various configuration file |
| references into filename form. |
| </para><para> |
| A null or empty 'name' indicates that the default configuration file should |
| be used; which file this references can be overridden with the |
| FC_CONFIG_FILE environment variable. Next, if the name starts with '~', it |
| refers to a file in the current users home directory. Otherwise if the name |
| doesn't start with '/', it refers to a file in the default configuration |
| directory; the built-in default directory can be overridden with the |
| FC_CONFIG_DIR environment variable. |
| </para></sect3> |
| </sect2> |
| <sect2><title>Initialization</title> |
| <para> |
| These functions provide some control over how the library is initialized. |
| </para> |
| <sect3><title>FcInitLoadConfig</title><programlisting> |
| FcConfig *FcInitLoadConfig (void) |
| </programlisting><para> |
| Loads the default configuration file and returns the resulting configuration. |
| Does not load any font information. |
| </para></sect3> |
| <sect3><title>FcInitLoadConfigAndFonts</title><programlisting> |
| FcConfig *FcInitLoadConfigAndFonts (void) |
| </programlisting><para> |
| Loads the default configuration file and builds information about the |
| available fonts. Returns the resulting configuration. |
| </para></sect3> |
| <sect3><title>FcInit</title><programlisting> |
| FcBool FcInit (void) |
| </programlisting><para> |
| Loads the default configuration file and the fonts referenced therein and |
| sets the default configuration to that result. Returns whether this |
| process succeeded or not. If the default configuration has already |
| been loaded, this routine does nothing and returns FcTrue. |
| </para></sect3> |
| <sect3><title>FcGetVersion</title><programlisting> |
| int FcGetVersion (void) |
| </programlisting><para> |
| Returns the version number of the library. |
| </para></sect3> |
| <sect3><title>FcInitReinitialize</title><programlisting> |
| FcBool FcInitReinitialize (void) |
| </programlisting><para> |
| Forces the default configuration file to be reloaded and resets the default |
| configuration. |
| </para></sect3> |
| <sect3><title>FcInitBringUptoDate</title><programlisting> |
| FcBool FcInitBringUptoDate (void) |
| </programlisting><para> |
| Checks the rescan interval in the default configuration, checking the |
| configuration if the interval has passed and reloading the configuration if |
| when any changes are detected. |
| </para></sect3> |
| </sect2> |
| <sect2><title>FcAtomic</title> |
| <para> |
| These functions provide a safe way to update config files, allowing ongoing |
| reading of the old config file while locked for writing and ensuring that a |
| consistent and complete version of the config file is always available. |
| </para> |
| <sect3><title>FcAtomicCreate</title><programlisting> |
| FcAtomic * FcAtomicCreate (const FcChar8 *file) |
| </programlisting><para> |
| Creates a data structure containing data needed to control access to 'file'. |
| Writing is done to a separate file. Once that file is complete, the original |
| configuration file is atomically replaced so that reading process always see |
| a consistent and complete file without the need to lock for reading. |
| </para></sect3> |
| <sect3><title>FcAtomicLock</title><programlisting> |
| FcBool FcAtomicLock (FcAtomic *atomic) |
| </programlisting><para> |
| Attempts to lock the file referenced by 'atomic'. Returns FcFalse if the |
| file is locked by another process, else returns FcTrue and leaves the file |
| locked. |
| </para></sect3> |
| <sect3><title>FcAtomicNewFile</title><programlisting> |
| FcChar8 *FcAtomicNewFile (FcAtomic *atomic) |
| </programlisting><para> |
| Returns the filename for writing a new version of the file referenced |
| by 'atomic'. |
| </para></sect3> |
| <sect3><title>FcAtomicOrigFile</title><programlisting> |
| FcChar8 *FcAtomicOrigFile (FcAtomic *atomic) |
| </programlisting><para> |
| Returns the file refernced by 'atomic'. |
| </para></sect3> |
| <sect3><title>FcAtomicReplaceOrig</title><programlisting> |
| FcBool FcAtomicReplaceOrig (FcAtomic *atomic) |
| </programlisting><para> |
| Replaces the original file referenced by 'atomic' with the new file. |
| </para></sect3> |
| <sect3><title>FcAtomicDeleteNew</title><programlisting> |
| void FcAtomicDeleteNew (FcAtomic *atomic) |
| </programlisting><para> |
| Deletes the new file. |
| </para></sect3> |
| <sect3><title>FcAtomicUnlock</title><programlisting> |
| void FcAtomicUnlock (FcAtomic *atomic) |
| </programlisting><para> |
| Unlocks the file. |
| </para></sect3> |
| <sect3><title>FcAtomicDestroy</title><programlisting> |
| void FcAtomicDestroy (FcAtomic *atomic) |
| </programlisting><para> |
| Destroys 'atomic'. |
| </para></sect3> |
| </sect2> |
| <sect2><title>FreeType specific functions</title> |
| <para> |
| <programlisting> |
| #include <fontconfig/fcfreetype.h> |
| </programlisting> |
| While the fontconfig library doesn't insist that FreeType be used as the |
| rasterization mechanism for fonts, it does provide some convenience |
| functions. |
| </para> |
| <sect3><title>FcFreeTypeCharIndex</title><programlisting> |
| FT_UInt FcFreeTypeCharIndex (FT_Face face, FcChar32 ucs4) |
| </programlisting><para> |
| Maps a Unicode char to a glyph index. This function uses information from |
| several possible underlying encoding tables to work around broken fonts. |
| As a result, this function isn't designed to be used in performance |
| sensitive areas; results from this function are intended to be cached by |
| higher level functions. |
| </para></sect3> |
| <sect3><title>FcFreeTypeCharSet</title><programlisting> |
| FcCharSet *FcFreeTypeCharSet (FT_Face face, FcBlanks *blanks) Scans a |
| </programlisting><para> |
| FreeType face and returns the set of encoded Unicode chars. This scans |
| several encoding tables to build as complete a list as possible. |
| If 'blanks' is not 0, the glyphs in the font are examined and any blank glyphs |
| not in 'blanks' are not placed in the returned FcCharSet. |
| </para></sect3> |
| <sect3><title>FcFreeTypeQuery</title><programlisting> |
| FcPattern *FcFreeTypeQuery (const char *file, int id, FcBlanks *blanks, int *count) |
| </programlisting><para> |
| Constructs a pattern representing the 'id'th font in 'file'. The number |
| of fonts in 'file' is returned in 'count'. |
| </para></sect3> |
| </sect2> |
| <sect2><title>XML specific functions</title> |
| <sect3><title>FcConfigParseAndLoad</title><programlisting> |
| FcBool FcConfigParseAndLoad (FcConfig *config, const FcChar8 *file, FcBool complain) |
| </programlisting><para> |
| Walks the configuration in 'file' and constructs the internal representation |
| in 'config'. Any include files referenced from within 'file' will be loaded |
| with FcConfigLoad and also parsed. If 'complain' is FcFalse, no warning |
| will be displayed if 'file' does not exist. |
| </para></sect3> |
| </sect2> |
| <sect2><title>File and Directory routines</title> |
| <sect3><title>FcFileScan</title><programlisting> |
| FcBool FcFileScan (FcFontSet *set, FcStrSet *dirs, FcFileCache *cache, FcBlanks *blanks, const char *file, FcBool force) |
| </programlisting><para> |
| Scans a single file and adds all fonts found to 'set'. If 'force' is FcTrue, |
| then the file is scanned even if associated information is found in 'cache'. |
| If 'file' is a directory, it is added to 'dirs'. |
| </para></sect3> |
| <sect3><title>FcDirScan</title><programlisting> |
| FcBool FcDirScan (FcFontSet *set, FcStrSet *dirs, FcFileCache *cache, FcBlanks *blanks, const char *dir, FcBool force) |
| </programlisting><para> |
| Scans an entire directory and adds all fonts found to 'set'. If 'force' is |
| FcTrue, then the directory and all files within it are scanned even if |
| information is present in the per-directory cache file or 'cache'. Any |
| subdirectories found are added to 'dirs'. |
| </para></sect3> |
| <sect3><title>FcDirSave</title><programlisting> |
| FcBool FcDirSave (FcFontSet *set, FcStrSet *dirs, const char *dir) |
| </programlisting><para> |
| Creates the per-directory cache file for 'dir' and populates it with the |
| fonts in 'set' and subdirectories in 'dirs'. |
| </para></sect3> |
| <sect3><title>FcDirCacheValid</title><programlisting> |
| FcBool FcDirCacheValid (const FcChar8 *cache_file) |
| </programlisting><para> |
| Returns FcTrue if 'cache_file' is no older than the directory containing it, |
| else FcFalse. |
| </para></sect3> |
| </sect2> |
| <sect2><title>FcStrSet and FcStrList</title> |
| <para> |
| A data structure for enumerating strings, used to list directories while |
| scanning the configuration as directories are added while scanning. |
| </para> |
| <sect3><title>FcStrSetCreate</title><programlisting> |
| FcStrSet *FcStrSetCreate (void) |
| </programlisting><para> |
| Create an empty set. |
| </para></sect3> |
| <sect3><title>FcStrSetMember</title><programlisting> |
| FcBool FcStrSetMember (FcStrSet *set, const FcChar8 *s) |
| </programlisting><para> |
| Returns whether 's' is a member of 'set'. |
| </para></sect3> |
| <sect3><title>FcStrSetAdd</title><programlisting> |
| FcBool FcStrSetAdd (FcStrSet *set, const FcChar8 *s) |
| </programlisting><para> |
| Adds a copy of 's' to 'set'. |
| </para></sect3> |
| <sect3><title>FcStrSetAddFilename</title><programlisting> |
| FcBool FcStrSetAddFilename (FcStrSet *set, const FcChar8 *s) |
| </programlisting><para> |
| Adds a copy 's' to 'set', The copy is created with FcStrCopyFilename |
| so that leading '~' values are replaced with the value of the HOME |
| environment variable. |
| </para></sect3> |
| <sect3><title>FcStrSetDel</title><programlisting> |
| FcBool FcStrSetDel (FcStrSet *set, const FcChar8 *s) |
| </programlisting><para> |
| Removes 's' from 'set', returning FcTrue if 's' was a member else FcFalse. |
| </para></sect3> |
| <sect3><title>FcStrSetDestroy</title><programlisting> |
| void FcStrSetDestroy (FcStrSet *set) |
| </programlisting><para> |
| Destroys 'set'. |
| </para></sect3> |
| <sect3><title>FcStrListCreate</title><programlisting> |
| FcStrList *FcStrListCreate (FcStrSet *set) |
| </programlisting><para> |
| Creates an enumerator to list the strings in 'set'. |
| </para></sect3> |
| <sect3><title>FcStrListNext</title><programlisting> |
| FcChar8 *FcStrListNext (FcStrList *list) |
| </programlisting><para> |
| Returns the next string in 'set'. |
| </para></sect3> |
| <sect3><title>FcStrListDone</title><programlisting> |
| void FcStrListDone (FcStrList *list) |
| </programlisting><para> |
| Destroys the enumerator 'list'. |
| </para></sect3> |
| </sect2> |
| <sect2><title>String utilities</title> |
| <sect3><title>FcUtf8ToUcs4</title> |
| <programlisting> |
| int FcUtf8ToUcs4 (FcChar8 *src, FcChar32 *dst, int len) |
| </programlisting> |
| <para> |
| Converts the next Unicode char from 'src' into 'dst' and returns the number |
| of bytes containing the char. 'src' nust be at least 'len' bytes long. |
| </para></sect3> |
| <sect3><title>FcUcs4ToUtf8</title><programlisting> |
| int FcUcs4ToUtf8 (FcChar32 src, FcChar8 dst[FC_UTF8_MAX_LEN]) |
| </programlisting><para> |
| Converts the Unicode char from 'src' into 'dst' and returns the |
| number of bytes needed to encode the char. |
| </para></sect3> |
| <sect3><title>FcUtf8Len</title><programlisting> |
| FcBool FcUtf8Len (FcChar8 *src, int len, int *nchar, int *wchar) |
| </programlisting><para> |
| Counts the number of Unicode chars in 'len' bytes of 'src'. Places that |
| count in 'nchar'. 'wchar' contains 1, 2 or 4 depending on the number of |
| bytes needed to hold the largest unicode char counted. The return value |
| indicates whether 'src' is a well-formed UTF8 string. |
| </para></sect3> |
| <sect3><title>FcUtf16ToUcs4</title><programlisting> |
| int FcUtf16ToUcs4 (FcChar8 *src, FcEndian endian, FcChar32 *dst, int len) |
| </programlisting><para> |
| Converts the next Unicode char from 'src' into 'dst' and returns the |
| number of bytes containing the char. 'src' must be at least 'len' bytes |
| long. Bytes of 'src' are combined into 16-bit units according to 'endian'. |
| </para></sect3> |
| <sect3><title>FcUtf16Len</title><programlisting> |
| FcBool FcUtf16Len (FcChar8 *src, FcEndian endian, int len, int *nchar, int *wchar) |
| </programlisting><para> |
| Counts the number of Unicode chars in 'len' bytes of 'src'. Bytes of 'src' |
| are combined into 16-bit units according to 'endian'. Places that |
| count in 'nchar'. 'wchar' contains 1, 2 or 4 depending on the number of |
| bytes needed to hold the largest unicode char counted. The return value |
| indicates whether 'string' is a well-formed UTF16 string. |
| </para></sect3> |
| <sect3><title>FcStrCopy</title><programlisting> |
| FcChar8 *FcStrCopy (const FcChar8 *s) |
| </programlisting><para> |
| Allocates memory, copies 's' and returns the resulting buffer. Yes, this |
| is 'strdup', but that function isn't available on every platform. |
| </para></sect3> |
| <sect3><title>FcStrCopyFilename</title><programlisting> |
| FcChar8 *FcStrCopyFilename (const FcChar8 *s) |
| </programlisting><para> |
| Just like FcStrCopy except that it converts any leading '~' characters |
| in 's' to the value of the HOME environment variable. |
| </para></sect3> |
| <sect3><title>FcStrCmpIgnoreCase</title><programlisting> |
| int FcStrCmpIgnoreCase (const char *s1, const char *s2) |
| </programlisting><para> |
| Returns the usual <0, 0, >0 result of comparing 's1' and 's2'. This test |
| is case-insensitive in the ASCII range and will operate properly with UTF8 |
| encoded strings, although it does not check for well formed strings. |
| </para></sect3> |
| <sect3><title>FcStrDirname</title><programlisting> |
| FcChar8 *FcStrDirname (const FcChar8 *file) |
| </programlisting><para> |
| Returns the directory containing 'file'. |
| </para></sect3> |
| <sect3><title>FcStrBasename</title><programlisting> |
| FcChar8 *FcStrBasename (const FcChar8 *file) |
| </programlisting><para> |
| Returns the filename of 'file' stripped of any leading directory names. |
| </para></sect3> |
| </sect2> |
| </sect1> |
| </article> |