Fontconfig Developers Reference, Version 2.2.3 Keith Packard HP Cambridge Research Lab _________________________________________________________ Table of Contents 1. DESCRIPTION 2. FUNCTIONAL OVERVIEW 2.1. FONT CONFIGURATION 2.2. FONT PROPERTIES 3. Datatypes 3.1. FcChar8, FcChar16, FcChar32, FcBool 3.2. FcMatrix 3.3. FcCharSet 3.4. FcType 3.5. FcValue 3.6. FcPattern 3.7. FcFontSet 3.8. FcStrSet, FcStrList 3.9. FcObjectSet 3.10. FcObjectType 3.11. FcConstant 3.12. FcBlanks 3.13. FcFileCache 3.14. FcConfig 3.15. FcSetName 3.16. FcResult 3.17. FcAtomic 4. FUNCTIONS 4.1. Initialization FcInitLoadConfig -- load configuration FcInitLoadConfigAndFonts -- load configuration and font data FcInit -- initialize fontconfig library FcGetVersion -- library version number FcInitReinitialize -- re-initialize library FcInitBringUptoDate -- reload configuration files if needed 4.2. FcPattern FcPatternCreate -- Create a pattern FcPatternDestroy -- Destroy a pattern FcPatternEqual -- Compare patterns FcPatternEqualSubset -- Compare portions of patterns FcPatternHash -- Compute a pattern hash value FcPatternAdd -- Add a value to a pattern FcPatternAddWeak -- Add a value to a pattern with weak binding FcPatternAdd-Type -- Add a typed value to a pattern FcPatternGet -- Return a value from a pattern FcPatternGet-Type -- Return a typed value from a pattern FcPatternBuild -- Create patterns from arguments FcPatternDel -- Delete a property from a pattern FcPatternPrint -- Print a pattern for debugging FcDefaultSubstitute -- Perform default substitutions in a pattern FcNameParse -- Parse a pattern string FcNameUnparse -- Convert a pattern back into a string that can be parsed 4.3. FcFontSet FcFontSetCreate -- Create a font set FcFontSetDestroy -- Destroy a font set FcFontSetAdd -- Add to a font set 4.4. FcObjectSet FcObjectSetCreate -- Create an object set FcObjectSetAdd -- Add to an object set FcObjectSetDestroy -- Destroy an object set FcObjectSetBuild -- Build object set from args 4.5. FreeType specific functions FcFreeTypeCharIndex -- map Unicode to glyph id FcFreeTypeCharSet -- compute unicode coverage FcFreeTypeQuery -- compute font file pattern 4.6. FcValue FcValueDestroy -- Free a value FcValueSave -- Copy a value 4.7. FcCharSet FcCharSetCreate -- Create an empty character set FcCharSetDestroy -- Destroy a character set FcCharSetAddChar -- Add a character to a charset FcCharSetCopy -- Copy a charset FcCharSetEqual -- Compare two charsets FcCharSetIntersect -- Intersect charsets FcCharSetUnion -- Add charsets FcCharSetSubtract -- Subtract charsets FcCharSetHasChar -- Check a charset for a char FcCharSetCount -- Count entries in a charset FcCharSetIntersectCount -- Intersect and count charsets FcCharSetSubtractCount -- Subtract and count charsets FcCharSetIsSubset -- Test for charset inclusion FcCharSetFirstPage -- Start enumerating charset contents FcCharSetNextPage -- Continue enumerating charset contents 4.8. FcMatrix FcMatrixInit -- initialize an FcMatrix structure FcMatrixCopy -- Copy a matrix FcMatrixEqual -- Compare two matrices FcMatrixMultiply -- Multiply matrices FcMatrixRotate -- Rotate a matrix FcMatrixScale -- Scale a matrix FcMatrixShear -- Shear a matrix 4.9. FcConfig FcConfigCreate -- Create a configuration FcConfigDestroy -- Destroy a configuration FcConfigSetCurrent -- Set configuration as default FcConfigGetCurrent -- Return current configuration FcConfigUptoDate -- Check timestamps on config files FcConfigBuildFonts -- Build font database FcConfigGetConfigDirs -- Get config directories FcConfigGetFontDirs -- Get font directories FcConfigGetConfigFiles -- Get config files FcConfigGetCache -- Get cache filename FcConfigGetFonts -- Get config font set FcConfigGetBlanks -- Get config blanks FcConfigGetRescanInverval -- Get config rescan interval FcConfigSetRescanInverval -- Set config rescan interval FcConfigAppFontAddFile -- Add font file to font database FcConfigAppFontAddDir -- Add fonts from directory to font database FcConfigAppFontClear -- Remove all app fonts from font database FcConfigSubstituteWithPat -- Execute substitutions FcConfigSubstitute -- Execute substitutions FcFontMatch -- Return best font FcFontSort -- Return list of matching fonts FcFontRenderPrepare -- Prepare pattern for loading font file FcFontList -- List fonts FcConfigFilename -- Find a config file FcConfigParseAndLoad -- load a configuration file 4.10. FcObjectType FcNameRegisterObjectTypes -- Register object types FcNameUnregisterObjectTypes -- Unregister object types FcNameGetObjectType -- Lookup an object type 4.11. FcConstant FcNameRegisterConstants -- Register symbolic constants FcNameUnregisterConstants -- Unregister symbolic constants FcNameGetConstant -- Lookup symbolic constant FcNameConstant -- Get the value for a symbolic constant 4.12. FcBlanks FcBlanksCreate -- Create an FcBlanks FcBlanksDestroy -- Destroy and FcBlanks FcBlanksAdd -- Add a character to an FcBlanks FcBlanksIsMember -- Query membership in an FcBlanks 4.13. FcAtomic FcAtomicCreate -- create an FcAtomic object FcAtomicLock -- lock a file FcAtomicNewFile -- return new temporary file name FcAtomicOrigFile -- return original file name FcAtomicReplaceOrig -- replace original with new FcAtomicDeleteNew -- delete new file FcAtomicUnlock -- unlock a file FcAtomicDestroy -- destroy an FcAtomic object 4.14. File and Directory routines FcFileScan -- scan a font file FcDirScan -- scan a font directory FcDirSave -- save a directory cache FcDirCacheValid -- check directory cache timestamp 4.15. FcStrSet and FcStrList FcStrSetCreate -- create a string set FcStrSetMember -- check set for membership FcStrSetAdd -- add to a string set FcStrSetAddFilename -- add a filename to a string set FcStrSetDel -- delete from a string set FcStrSetDestroy -- destroy a string set FcStrListCreate -- create a string iterator FcStrListNext -- get next string in iteration FcStrListDone -- destroy a string iterator 4.16. String utilities FcUtf8ToUcs4 -- convert UTF-8 to UCS4 FcUcs4ToUtf8 -- convert UCS4 to UTF-8 FcUtf8Len -- count UTF-8 encoded chars FcUtf16ToUcs4 -- convert UTF-16 to UCS4 FcUtf16Len -- count UTF-16 encoded chars FcStrCopy -- duplicate a string FcStrCopyFilename -- copy a string, expanding '~' FcStrCmpIgnoreCase -- compare UTF-8 strings ignoring ASCII case FcStrDirname -- directory part of filename FcStrBasename -- last component of filename 1. DESCRIPTION Fontconfig is a library designed to provide system-wide font configuration, customization and application access. _________________________________________________________ 2. FUNCTIONAL OVERVIEW 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. _________________________________________________________ 2.1. FONT CONFIGURATION 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. 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. 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. _________________________________________________________ 2.2. FONT PROPERTIES 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. Property Definitions Property CPP Symbol Type Description ---------------------------------------------------- family FC_FAMILY String Font family name style FC_STYLE String Font style. Overrides w eight and slant slant FC_SLANT Int Italic, oblique or roma n weight FC_WEIGHT Int Light, medium, demibold , bold or black size FC_SIZE Double Point size aspect FC_ASPECT Double Stretches glyphs horizo ntally before hinting pixelsize FC_PIXEL_SIZE Double Pixel size spacing FC_SPACING Int Proportional, monospace or charcell foundry FC_FOUNDRY String Font foundry name antialias FC_ANTIALIAS Bool Whether glyphs can be antialiased hinting FC_HINTING Bool Whether the rasterizer should use hinting verticallayout FC_VERTICAL_LAYOUT Bool Use vertical layout autohint FC_AUTOHINT Bool Use autohinter instead of normal hinter globaladvance FC_GLOBAL_ADVANCE Bool Use font global advance data file FC_FILE String The filename holding th e font index FC_INDEX Int The index of the font w ithin the file ftface FC_FT_FACE FT_Face Use the specified FreeT ype face object rasterizer FC_RASTERIZER String Which rasterizer is in use outline FC_OUTLINE Bool Whether the glyphs are outlines scalable FC_SCALABLE Bool Whether glyphs can be s caled scale FC_SCALE Double Scale factor for point- >pixel conversions dpi FC_DPI Double Target dots per inch rgba FC_RGBA Int unknown, rgb, bgr, vrgb , vbgr, none - subpixel g eometry minspace FC_MINSPACE Bool Eliminate leading from line spacing charset FC_CHARSET CharSet Unicode chars encoded b y the font lang FC_LANG String List of RFC-3066-style languages this font sup ports _________________________________________________________ 3. Datatypes Fontconfig uses abstract datatypes to hide internal implementation details for most data structures. A few structures are exposed where appropriate. _________________________________________________________ 3.1. FcChar8, FcChar16, FcChar32, FcBool 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. _________________________________________________________ 3.2. FcMatrix An FcMatrix holds an affine transformation, usually used to reshape glyphs. A small set of matrix operations are provided to manipulate these. typedef struct _FcMatrix { double xx, xy, yx, yy; } FcMatrix; _________________________________________________________ 3.3. FcCharSet 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. _________________________________________________________ 3.4. FcType Tags the kind of data stored in an FcValue. _________________________________________________________ 3.5. FcValue An FcValue object holds a single value with one of a number of different types. The 'type' tag indicates which member is valid. typedef struct _FcValue { FcType type; union { const FcChar8 *s; int i; FcBool b; double d; const FcMatrix *m; const FcCharSet *c; } u; } FcValue; FcValue Members Type Union member Datatype -------------------------------- FcTypeVoid (none) (none) FcTypeInteger i int FcTypeDouble d double FcTypeString s char * FcTypeBool b b FcTypeMatrix m FcMatrix * FcTypeCharSet c FcCharSet * _________________________________________________________ 3.6. FcPattern 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. _________________________________________________________ 3.7. FcFontSet typedef struct _FcFontSet { int nfont; int sfont; FcPattern **fonts; } FcFontSet; 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. _________________________________________________________ 3.8. FcStrSet, FcStrList 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. _________________________________________________________ 3.9. FcObjectSet typedef struct _FcObjectSet { int nobject; int sobject; const char **objects; } FcObjectSet; 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. _________________________________________________________ 3.10. FcObjectType typedef struct _FcObjectType { const char *object; FcType type; } FcObjectType; 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. _________________________________________________________ 3.11. FcConstant typedef struct _FcConstant { const FcChar8 *name; const char *object; int value; } FcConstant; Provides for symbolic constants for new pattern elements. When 'name' is seen in a font name, an 'object' element is created with value 'value'. _________________________________________________________ 3.12. FcBlanks 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. _________________________________________________________ 3.13. FcFileCache 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. _________________________________________________________ 3.14. FcConfig 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. _________________________________________________________ 3.15. FcSetName 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. _________________________________________________________ 3.16. FcResult Used as a return type for functions manipulating FcPattern objects. FcResult Values Result Code Meaning ----------------------------------------------------------- FcResultMatch Object exists with the specified ID FcResultNoMatch Object doesn't exist at all FcResultTypeMismatch Object exists, but the type doesn't mat ch FcResultNoId Object exists, but has fewer values than specified _________________________________________________________ 3.17. FcAtomic Used for locking access to config files. Provides a safe way to update configuration files. _________________________________________________________ 4. FUNCTIONS These are grouped by functionality, often using the main datatype being manipulated. _________________________________________________________ 4.1. Initialization Table of Contents FcInitLoadConfig -- load configuration FcInitLoadConfigAndFonts -- load configuration and font data FcInit -- initialize fontconfig library FcGetVersion -- library version number FcInitReinitialize -- re-initialize library FcInitBringUptoDate -- reload configuration files if needed These functions provide some control over how the library is initialized. FcInitLoadConfig Name FcInitLoadConfig -- load configuration Synopsis #include FcConfig * FcInitLoadConfig(void); Description Loads the default configuration file and returns the resulting configuration. Does not load any font information. Version Fontconfig version 2.2.3 FcInitLoadConfigAndFonts Name FcInitLoadConfigAndFonts -- load configuration and font data Synopsis #include FcConfig * FcInitLoadConfigAndFonts(void); Description Loads the default configuration file and builds information about the available fonts. Returns the resulting configuration. Version Fontconfig version 2.2.3 FcInit Name FcInit -- initialize fontconfig library Synopsis #include FcBool FcInit(void); Description 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. Version Fontconfig version 2.2.3 FcGetVersion Name FcGetVersion -- library version number Synopsis #include int FcGetVersion(void); Description Returns the version number of the library. Version Fontconfig version 2.2.3 FcInitReinitialize Name FcInitReinitialize -- re-initialize library Synopsis #include FcBool FcInitReinitialize(void); Description Forces the default configuration file to be reloaded and resets the default configuration. Version Fontconfig version 2.2.3 FcInitBringUptoDate Name FcInitBringUptoDate -- reload configuration files if needed Synopsis #include FcBool FcInitBringUptoDate(void); Description 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. Version Fontconfig version 2.2.3 _________________________________________________________ 4.2. FcPattern Table of Contents FcPatternCreate -- Create a pattern FcPatternDestroy -- Destroy a pattern FcPatternEqual -- Compare patterns FcPatternEqualSubset -- Compare portions of patterns FcPatternHash -- Compute a pattern hash value FcPatternAdd -- Add a value to a pattern FcPatternAddWeak -- Add a value to a pattern with weak binding FcPatternAdd-Type -- Add a typed value to a pattern FcPatternGet -- Return a value from a pattern FcPatternGet-Type -- Return a typed value from a pattern FcPatternBuild -- Create patterns from arguments FcPatternDel -- Delete a property from a pattern FcPatternPrint -- Print a pattern for debugging FcDefaultSubstitute -- Perform default substitutions in a pattern FcNameParse -- Parse a pattern string FcNameUnparse -- Convert a pattern back into a string that can be parsed An FcPattern is an opaque type that holds both patterns to match against the available fonts, as well as the information about each font. FcPatternCreate Name FcPatternCreate -- Create a pattern Synopsis #include FcPattern * FcPatternCreate(void); Description Creates a pattern with no properties; used to build patterns from scratch. Version Fontconfig version 2.2.3 FcPatternDestroy Name FcPatternDestroy -- Destroy a pattern Synopsis #include void FcPatternDestroy(FcPattern *p); Description Destroys a pattern, in the process destroying all related values. Version Fontconfig version 2.2.3 FcPatternEqual Name FcPatternEqual -- Compare patterns Synopsis #include FcBool FcPatternEqual(const FcPattern *pa, const FcPattern *pb); Description Returns whether pa and pb are exactly alike. Version Fontconfig version 2.2.3 FcPatternEqualSubset Name FcPatternEqualSubset -- Compare portions of patterns Synopsis #include FcBool FcPatternEqualSubset(const FcPattern *pa, const FcPattern *pb, const FcObjectSet *os); Description Returns whether pa and pb have exactly the same values for all of the objects in os. Version Fontconfig version 2.2.3 FcPatternHash Name FcPatternHash -- Compute a pattern hash value Synopsis #include FcChar32 FcPatternHash(const FcPattern *p); Description Returns a 32-bit number which is the same for any two patterns which are equal. Version Fontconfig version 2.2.3 FcPatternAdd Name FcPatternAdd -- Add a value to a pattern Synopsis #include FcBool FcPatternAdd(FcPattern *p, const char *object, FcValuevalue, FcBoolappend); Description 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. Version Fontconfig version 2.2.3 FcPatternAddWeak Name FcPatternAddWeak -- Add a value to a pattern with weak binding Synopsis #include FcBool FcPatternAddWeak(FcPattern *p, const char *object, FcValuevalue, FcBoolappend); Description FcPatternAddWeak is essentially the same as FcPatternAdd except that any values added to the list have binding weak instead of strong. Version Fontconfig version 2.2.3 FcPatternAdd-Type Name FcPatternAddInteger, FcPatternAddDouble, FcPatternAddString, FcPatternAddMatrix, FcPatternAddCharSet, FcPatternAddBool -- Add a typed value to a pattern Synopsis #include FcBool FcPatternAddInteger(FcPattern *p, const char *object, inti); FcBool FcPatternAddDouble(FcPattern *p, const char *object, doubled); FcBool FcPatternAddString(FcPattern *p, const char *object, const char *s); FcBool FcPatternAddMatrix(FcPattern *p, const char *object, const FcMatrix *m); FcBool FcPatternAddCharSet(FcPattern *p, const char *object, const FcCharSet *c); FcBool FcPatternAddBool(FcPattern *p, const char *object, FcBoolb); Description 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. Version Fontconfig version 2.2.3 FcPatternGet Name FcPatternGet -- Return a value from a pattern Synopsis #include FcResult FcPatternGet(FcPattern *p, const char *object, intid, FcValue *v); Description Returns in `v the `idth 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. Version Fontconfig version 2.2.3 FcPatternGet-Type Name FcPatternGetInteger, FcPatternGetDouble, FcPatternGetString, FcPatternGetMatrix, FcPatternGetCharSet, FcPatternGetBool -- Return a typed value from a pattern Synopsis #include FcResult FcPatternGetInteger(FcPattern *p, const char *object, intn, int *i); FcResult FcPatternGetDouble(FcPattern *p, const char *object, intn, double *d); FcResult FcPatternGetString(FcPattern *p, const char *object, intn, char **consts); FcResult FcPatternGetMatrix(FcPattern *p, const char *object, intn, FcMatrix **s); FcResult FcPatternGetCharSet(FcPattern *p, const char *object, intn, FcCharSet **c); FcResult FcPatternGetBool(FcPattern *p, const char *object, intn, FcBool *b); Description 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. Version Fontconfig version 2.2.3 FcPatternBuild Name FcPatternBuild, FcPatternVaBuild -- Create patterns from arguments Synopsis #include FcPattern * FcPatternBuild(FcPattern *orig, ...); FcPattern * FcPatternVaBuild(FcPattern *orig, va_listva); Description Builds a pattern using a list of objects, types and values. Each value to be entered in the pattern is specified with three arguments: 1. Object name, a string describing the property to be added. 2. Object type, one of the FcType enumerated values 3. Value, not an FcValue, but the raw type as passed to any of the FcPatternAdd functions. Must match the type of the second argument. 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 pattern = FcPatternBuild (0, FC_FAMILY, FtTypeString, "Times", (char *) 0); FcPatternVaBuild is used when the arguments are already in the form of a varargs value. Version Fontconfig version 2.2.3 FcPatternDel Name FcPatternDel -- Delete a property from a pattern Synopsis #include FcBool FcPatternDel(FcPattern *p, const char *object); Description Deletes all values associated with the property `object', returning whether the property existed or not. Version Fontconfig version 2.2.3 FcPatternPrint Name FcPatternPrint -- Print a pattern for debugging Synopsis #include void FcPatternPrint(const FcPattern *p); Description 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. Version Fontconfig version 2.2.3 FcDefaultSubstitute Name FcDefaultSubstitute -- Perform default substitutions in a pattern Synopsis #include void FcDefaultSubstitute(FcPattern *pattern); Description Supplies default values for underspecified font patterns: * Patterns without a specified style or weight are set to Medium * Patterns without a specified style or slant are set to Roman * Patterns without a specified pixel size are given one computed from any specified point size (default 12), dpi (default 75) and scale (default 1). Version Fontconfig version 2.2.3 FcNameParse Name FcNameParse -- Parse a pattern string Synopsis #include FcPattern * FcNameParse(const char *name); Description Converts name from the standard text format described above into a pattern. Version Fontconfig version 2.2.3 FcNameUnparse Name FcNameUnparse -- Convert a pattern back into a string that can be parsed Synopsis #include FcChar8 * FcNameUnparse(FcPattern *pat); Description 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. Version Fontconfig version 2.2.3 _________________________________________________________ 4.3. FcFontSet Table of Contents FcFontSetCreate -- Create a font set FcFontSetDestroy -- Destroy a font set FcFontSetAdd -- Add to a font set An FcFontSet simply holds a list of patterns; these are used to return the results of listing available fonts. FcFontSetCreate Name FcFontSetCreate -- Create a font set Synopsis #include FcFontSet * FcFontSetCreate(void); Description Creates an empty font set. Version Fontconfig version 2.2.3 FcFontSetDestroy Name FcFontSetDestroy -- Destroy a font set Synopsis #include void FcFontSetDestroy(FcFontSet *s); Description Destroys a font set. Note that this destroys any referenced patterns as well. Version Fontconfig version 2.2.3 FcFontSetAdd Name FcFontSetAdd -- Add to a font set Synopsis #include FcBool FcFontSetAdd(FcFontSet *s, FcPattern *font); Description Adds a pattern to a font set. Note that the pattern is not copied before being inserted into the set. Version Fontconfig version 2.2.3 _________________________________________________________ 4.4. FcObjectSet Table of Contents FcObjectSetCreate -- Create an object set FcObjectSetAdd -- Add to an object set FcObjectSetDestroy -- Destroy an object set FcObjectSetBuild -- Build object set from args 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. FcObjectSetCreate Name FcObjectSetCreate -- Create an object set Synopsis #include FcObjectSet * FcObjectSetCreate(void); Description Creates an empty set. Version Fontconfig version 2.2.3 FcObjectSetAdd Name FcObjectSetAdd -- Add to an object set Synopsis #include FcBool FcObjectSetAdd(FcObjectSet *os, const char *object); Description Adds a proprety name to the set. Version Fontconfig version 2.2.3 FcObjectSetDestroy Name FcObjectSetDestroy -- Destroy an object set Synopsis #include void FcObjectSetDestroy(FcObjectSet *os); Description Destroys an object set. Version Fontconfig version 2.2.3 FcObjectSetBuild Name FcObjectSetBuild, FcObjectSetVaBuild -- Build object set from args Synopsis #include FcObjectSet * FcObjectSetBuild(const char *first, ...); FcObjectSet * FcObjectSetVaBuild(const char *first, va_listva); Description These build an object set from a null-terminated list of property names. Version Fontconfig version 2.2.3 _________________________________________________________ 4.5. FreeType specific functions Table of Contents FcFreeTypeCharIndex -- map Unicode to glyph id FcFreeTypeCharSet -- compute unicode coverage FcFreeTypeQuery -- compute font file pattern While the fontconfig library doesn't insist that FreeType be used as the rasterization mechanism for fonts, it does provide some convenience functions. FcFreeTypeCharIndex Name FcFreeTypeCharIndex -- map Unicode to glyph id Synopsis #include #include FT_UInt FcFreeTypeCharIndex(FT_Faceface, FcChar32ucs4); Description 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. Version Fontconfig version 2.2.3 FcFreeTypeCharSet Name FcFreeTypeCharSet -- compute unicode coverage Synopsis #include #include FcCharSet * FcFreeTypeCharSet(FT_Faceface, FcBlanks *blanks); Description Scans a 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. Version Fontconfig version 2.2.3 FcFreeTypeQuery Name FcFreeTypeQuery -- compute font file pattern Synopsis #include #include FcPattern * FcFreeTypeQuery(const char *file, intid, FcBlanks *blanks, int *count); Description Constructs a pattern representing the 'id'th font in 'file'. The number of fonts in 'file' is returned in 'count'. Version Fontconfig version 2.2.3 _________________________________________________________ 4.6. FcValue Table of Contents FcValueDestroy -- Free a value FcValueSave -- Copy a value FcValue is a structure containing a type tag and a union of all possible datatypes. The tag is an enum of type FcType and is intended to provide a measure of run-time typechecking, although that depends on careful programming. FcValueDestroy Name FcValueDestroy -- Free a value Synopsis #include void FcValueDestroy(FcValuev); Description Frees any memory referenced by v. Values of type FcTypeString, FcTypeMatrix and FcTypeCharSet reference memory, the other types do not. Version Fontconfig version 2.2.3 FcValueSave Name FcValueSave -- Copy a value Synopsis #include FcValue FcValueSave(FcValuev); Description Returns a copy of v duplicating any object referenced by it so that v may be safely destroyed without harming the new value. Version Fontconfig version 2.2.3 _________________________________________________________ 4.7. FcCharSet Table of Contents FcCharSetCreate -- Create an empty character set FcCharSetDestroy -- Destroy a character set FcCharSetAddChar -- Add a character to a charset FcCharSetCopy -- Copy a charset FcCharSetEqual -- Compare two charsets FcCharSetIntersect -- Intersect charsets FcCharSetUnion -- Add charsets FcCharSetSubtract -- Subtract charsets FcCharSetHasChar -- Check a charset for a char FcCharSetCount -- Count entries in a charset FcCharSetIntersectCount -- Intersect and count charsets FcCharSetSubtractCount -- Subtract and count charsets FcCharSetIsSubset -- Test for charset inclusion FcCharSetFirstPage -- Start enumerating charset contents FcCharSetNextPage -- Continue enumerating charset contents 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. FcCharSetCreate Name FcCharSetCreate -- Create an empty character set Synopsis #include FcCharSet * FcCharSetCreate(void); Description FcCharSetCreate allocates and initializes a new empty character set object. Version Fontconfig version 2.2.3 FcCharSetDestroy Name FcCharSetDestroy -- Destroy a character set Synopsis #include void FcCharSetDestroy(FcCharSet *fcs); Description FcCharSetDestroy decrements the reference count fcs. If the reference count becomes zero, all memory referenced is freed. Version Fontconfig version 2.2.3 FcCharSetAddChar Name FcCharSetAddChar -- Add a character to a charset Synopsis #include FcBool FcCharSetAddChar(FcCharSet *fcs, FcChar32ucs4); Description FcCharSetAddChar 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. Version Fontconfig version 2.2.3 FcCharSetCopy Name FcCharSetCopy -- Copy a charset Synopsis #include FcCharSet * FcCharSetCopy(FcCharSet *src); Description Makes a copy of src; note that this may not actually do anything more than increment the reference count on src. Version Fontconfig version 2.2.3 FcCharSetEqual Name FcCharSetEqual -- Compare two charsets Synopsis #include FcBool FcCharSetEqual(const FcCharSet *a, const FcCharSet *b); Description Returns whether a and b contain the same set of unicode chars. Version Fontconfig version 2.2.3 FcCharSetIntersect Name FcCharSetIntersect -- Intersect charsets Synopsis #include FcCharSet * FcCharSetIntersect(const FcCharSet *a, const FcCharSet *b); Description Returns a set including only those chars found in both a and b. Version Fontconfig version 2.2.3 FcCharSetUnion Name FcCharSetUnion -- Add charsets Synopsis #include FcCharSet * FcCharSetUnion(const FcCharSet *a, const FcCharSet *b); Description Returns a set including only those chars found in either a or b. Version Fontconfig version 2.2.3 FcCharSetSubtract Name FcCharSetSubtract -- Subtract charsets Synopsis #include FcCharSet * FcCharSetSubtract(const FcCharSet *a, const FcCharSet *b); Description Returns a set including only those chars found in a but not b. Version Fontconfig version 2.2.3 FcCharSetHasChar Name FcCharSetHasChar -- Check a charset for a char Synopsis #include FcBool FcCharSetHasChar(const FcCharSet *fcs, FcChar32ucs4); Description Returns whether fcs contains the char ucs4. Version Fontconfig version 2.2.3 FcCharSetCount Name FcCharSetCount -- Count entries in a charset Synopsis #include FcChar32 FcCharSetCount(const FcCharSet *a); Description Returns the total number of unicode chars in a. Version Fontconfig version 2.2.3 FcCharSetIntersectCount Name FcCharSetIntersectCount -- Intersect and count charsets Synopsis #include FcChar32 FcCharSetIntersectCount(const FcCharSet *a, const FcCharSet *b); Description Returns the number of chars that are in both a and b. Version Fontconfig version 2.2.3 FcCharSetSubtractCount Name FcCharSetSubtractCount -- Subtract and count charsets Synopsis #include FcChar32 FcCharSetSubtractCount(const FcCharSet *a, const FcCharSet *b); Description Returns the number of chars that are in a but not in b. Version Fontconfig version 2.2.3 FcCharSetIsSubset Name FcCharSetIsSubset -- Test for charset inclusion Synopsis #include FcBool FcCharSetIsSubset(const FcCharSet *a, const FcCharSet *b); Description Returns whether a is a subset of b. Version Fontconfig version 2.2.3 FcCharSetFirstPage Name FcCharSetFirstPage -- Start enumerating charset contents Synopsis #include FcChar32 FcCharSetFirstPage(const FcCharSet *a, FcChar32[FC_CHARSET_MAP_SIZE]map, FcChar32 *next); Description 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. Version Fontconfig version 2.2.3 FcCharSetNextPage Name FcCharSetNextPage -- Continue enumerating charset contents Synopsis #include FcChar32 FcCharSetNextPage(const FcCharSet *a, FcChar32[FC_CHARSET_MAP_SIZE]map, FcChar32 *next); Description 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. Version Fontconfig version 2.2.3 _________________________________________________________ 4.8. FcMatrix Table of Contents FcMatrixInit -- initialize an FcMatrix structure FcMatrixCopy -- Copy a matrix FcMatrixEqual -- Compare two matrices FcMatrixMultiply -- Multiply matrices FcMatrixRotate -- Rotate a matrix FcMatrixScale -- Scale a matrix FcMatrixShear -- Shear a matrix FcMatrix structures hold an affine transformation in matrix form. FcMatrixInit Name FcMatrixInit -- initialize an FcMatrix structure Synopsis #include void FcMatrixInit(FcMatrix *matrix); Description FcMatrixInit initializes matrix to the identity matrix. Version Fontconfig version 2.2.3 FcMatrixCopy Name FcMatrixCopy -- Copy a matrix Synopsis #include void FcMatrixCopy(const FcMatrix *matrix); Description FcMatrixCopy allocates a new FcMatrix and copies mat into it. Version Fontconfig version 2.2.3 FcMatrixEqual Name FcMatrixEqual -- Compare two matrices Synopsis #include void FcMatrixEqual(const FcMatrix *matrix1, const FcMatrix *matrix2); Description FcMatrixEqual compares matrix1 and matrix2 returning FcTrue when they are equal and FcFalse when they are not. Version Fontconfig version 2.2.3 FcMatrixMultiply Name FcMatrixMultiply -- Multiply matrices Synopsis #include void FcMatrixMultiply(FcMatrix *result, const FcMatrix *matrix1, const FcMatrix *matrix2); Description FcMatrixMultiply multiplies matrix1 and matrix2 storing the result in result. Version Fontconfig version 2.2.3 FcMatrixRotate Name FcMatrixRotate -- Rotate a matrix Synopsis #include void FcMatrixRotate(FcMatrix *matrix, doublecos, doublesin); Description FcMatrixRotate rotates matrix by the angle who's sine is sin and cosine is cos. This is done by multiplying by the matrix: cos -sin sin cos Version Fontconfig version 2.2.3 FcMatrixScale Name FcMatrixScale -- Scale a matrix Synopsis #include void FcMatrixScale(FcMatrix *matrix, doublesx, doubledy); Description FcMatrixScale multiplies matrix x values by sx and y values by sy. This is done by multiplying by the matrix: sx 0 0 sy Version Fontconfig version 2.2.3 FcMatrixShear Name FcMatrixShear -- Shear a matrix Synopsis #include void FcMatrixShear(FcMatrix *matrix, doublesh, doublesv); Description FcMatrixShare shears matrix horizontally by sh and vertically by sv. This is done by multiplying by the matrix: 1 sh sv 1 Version Fontconfig version 2.2.3 _________________________________________________________ 4.9. FcConfig Table of Contents FcConfigCreate -- Create a configuration FcConfigDestroy -- Destroy a configuration FcConfigSetCurrent -- Set configuration as default FcConfigGetCurrent -- Return current configuration FcConfigUptoDate -- Check timestamps on config files FcConfigBuildFonts -- Build font database FcConfigGetConfigDirs -- Get config directories FcConfigGetFontDirs -- Get font directories FcConfigGetConfigFiles -- Get config files FcConfigGetCache -- Get cache filename FcConfigGetFonts -- Get config font set FcConfigGetBlanks -- Get config blanks FcConfigGetRescanInverval -- Get config rescan interval FcConfigSetRescanInverval -- Set config rescan interval FcConfigAppFontAddFile -- Add font file to font database FcConfigAppFontAddDir -- Add fonts from directory to font database FcConfigAppFontClear -- Remove all app fonts from font database FcConfigSubstituteWithPat -- Execute substitutions FcConfigSubstitute -- Execute substitutions FcFontMatch -- Return best font FcFontSort -- Return list of matching fonts FcFontRenderPrepare -- Prepare pattern for loading font file FcFontList -- List fonts FcConfigFilename -- Find a config file FcConfigParseAndLoad -- load a configuration file 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. FcConfigCreate Name FcConfigCreate -- Create a configuration Synopsis #include FcConfig * FcConfigCreate(void); Description Creates an empty configuration. Version Fontconfig version 2.2.3 FcConfigDestroy Name FcConfigDestroy -- Destroy a configuration Synopsis #include void FcConfigDestroy(FcConfig *config); Description 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. Version Fontconfig version 2.2.3 FcConfigSetCurrent Name FcConfigSetCurrent -- Set configuration as default Synopsis #include FcBool FcConfigSetCurrent(FcConfig *config); Description Sets the current default configuration to config. Implicitly calls FcConfigBuildFonts if necessary, returning FcFalse if that call fails. Version Fontconfig version 2.2.3 FcConfigGetCurrent Name FcConfigGetCurrent -- Return current configuration Synopsis #include FcConfig * FcConfigGetCurrent(void); Description Returns the current default configuration. Version Fontconfig version 2.2.3 FcConfigUptoDate Name FcConfigUptoDate -- Check timestamps on config files Synopsis #include FcBool FcConfigUptoDate(FcConfig *config); Description Checks all of the files related to config and returns whether the in-memory version is in sync with the disk version. Version Fontconfig version 2.2.3 FcConfigBuildFonts Name FcConfigBuildFonts -- Build font database Synopsis #include FcBool FcConfigBuildFonts(FcConfig *config); Description 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. Version Fontconfig version 2.2.3 FcConfigGetConfigDirs Name FcConfigGetConfigDirs -- Get config directories Synopsis #include FcStrList * FcConfigGetConfigDirs(FcConfig *config); Description Returns the list of font directories specified in the configuration files for config. Does not include any subdirectories. Version Fontconfig version 2.2.3 FcConfigGetFontDirs Name FcConfigGetFontDirs -- Get font directories Synopsis #include FcStrList * FcConfigGetFontDirs(FcConfig *config); Description Returns the list of font directories in config. This includes the configured font directories along with any directories below those in the filesystem. Version Fontconfig version 2.2.3 FcConfigGetConfigFiles Name FcConfigGetConfigFiles -- Get config files Synopsis #include FcStrList * FcConfigGetConfigFiles(FcConfig *config); Description Returns the list of known configuration files used to generate config. Note that this will not include any configuration done with FcConfigParse. Version Fontconfig version 2.2.3 FcConfigGetCache Name FcConfigGetCache -- Get cache filename Synopsis #include char * FcConfigGetCache(FcConfig *config); Description Returns the name of the file used to store per-user font information. Version Fontconfig version 2.2.3 FcConfigGetFonts Name FcConfigGetFonts -- Get config font set Synopsis #include FcFontSet * FcConfigGetFonts(FcConfig *config, FcSetNameset); Description Returns one of the two sets of fonts from the configuration as specified by set. Version Fontconfig version 2.2.3 FcConfigGetBlanks Name FcConfigGetBlanks -- Get config blanks Synopsis #include FcBlanks * FcConfigGetBlanks(FcConfig *config); Description Returns the FcBlanks object associated with the given configuration, if no blanks were present in the configuration, this function will return 0. Version Fontconfig version 2.2.3 FcConfigGetRescanInverval Name FcConfigGetRescanInverval -- Get config rescan interval Synopsis #include int FcConfigGetRescanInverval(FcConfig *config); Description 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. Version Fontconfig version 2.2.3 FcConfigSetRescanInverval Name FcConfigSetRescanInverval -- Set config rescan interval Synopsis #include FcBool FcConfigSetRescanInverval(FcConfig *config, intrescanInterval); Description Sets the rescan interval; returns FcFalse if an error occurred. Version Fontconfig version 2.2.3 FcConfigAppFontAddFile Name FcConfigAppFontAddFile -- Add font file to font database Synopsis #include FcBool FcConfigAppFontAddFile(FcConfig *config, const char *file); Description Adds an application-specific font to the configuration. Version Fontconfig version 2.2.3 FcConfigAppFontAddDir Name FcConfigAppFontAddDir -- Add fonts from directory to font database Synopsis #include FcBool FcConfigAppFontAddDir(FcConfig *config, const char *); Description Scans the specified directory for fonts, adding each one found to the application-specific set of fonts. Version Fontconfig version 2.2.3 FcConfigAppFontClear Name FcConfigAppFontClear -- Remove all app fonts from font database Synopsis #include void FcConfigAppFontClear(FcConfig *config); Description Clears the set of application-specific fonts. Version Fontconfig version 2.2.3 FcConfigSubstituteWithPat Name FcConfigSubstituteWithPat -- Execute substitutions Synopsis #include FcBool FcConfigSubstituteWithPat(FcConfig *config, FcPattern *p, FcPattern *p_pat, FcMatchKindkind); Description 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 elements with target=pattern. Version Fontconfig version 2.2.3 FcConfigSubstitute Name FcConfigSubstitute -- Execute substitutions Synopsis #include FcBool FcConfigSubstitute(FcConfig *config, FcPattern *p, FcMatchKindkind); Description Calls FcConfigSubstituteWithPat setting p_pat to NULL. Version Fontconfig version 2.2.3 FcFontMatch Name FcFontMatch -- Return best font Synopsis #include FcPattern * FcFontMatch(FcConfig *config, FcPattern *p, FcResult *result); Description 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. Version Fontconfig version 2.2.3 FcFontSort Name FcFontSort -- Return list of matching fonts Synopsis #include FcFontSet * FcFontSort(FcConfig *config, FcPattern *p, FcBooltrim, FcCharSet **csp, FcResult *result); Description 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. 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. The FcFontSet returned by FcFontSort is destroyed by caling FcFontSetDestroy. Version Fontconfig version 2.2.3 FcFontRenderPrepare Name FcFontRenderPrepare -- Prepare pattern for loading font file Synopsis #include FcPattern * FcFontRenderPrepare(FcConfig *config, FcPattern *pat, FcPattern *font); Description 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. Version Fontconfig version 2.2.3 FcFontList Name FcFontList -- List fonts Synopsis #include FcFontSet * FcFontList(FcConfig *config, FcPattern *p, FcObjectSet *os); Description Selects fonts matching p, creates patterns from those fonts containing only the objects in os and returns the set of unique such patterns. Version Fontconfig version 2.2.3 FcConfigFilename Name FcConfigFilename -- Find a config file Synopsis #include char * FcConfigFilename(const char *name); Description Given the specified external entity name, return the associated filename. This provides applications a way to convert various configuration file references into filename form. 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. Version Fontconfig version 2.2.3 FcConfigParseAndLoad Name FcConfigParseAndLoad -- load a configuration file Synopsis #include FcBool FcConfigParseAndLoad(FcConfig *config, const FcChar8 *file); Description 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. Version Fontconfig version 2.2.3 _________________________________________________________ 4.10. FcObjectType Table of Contents FcNameRegisterObjectTypes -- Register object types FcNameUnregisterObjectTypes -- Unregister object types FcNameGetObjectType -- Lookup an object type Provides for applcation-specified font name object types so that new pattern elements can be generated from font names. FcNameRegisterObjectTypes Name FcNameRegisterObjectTypes -- Register object types Synopsis #include FcBool FcNameRegisterObjectTypes(const FcObjectType *types, intntype); Description Register ntype new object types. Version Fontconfig version 2.2.3 FcNameUnregisterObjectTypes Name FcNameUnregisterObjectTypes -- Unregister object types Synopsis #include FcBool FcNameUnregisterObjectTypes(const FcObjectType *types, intntype); Description Unregister ntype object types. Version Fontconfig version 2.2.3 FcNameGetObjectType Name FcNameGetObjectType -- Lookup an object type Synopsis #include const FcObjectType * FcNameGetObjectType(const char *object); Description Return the object type for the pattern element named object. Version Fontconfig version 2.2.3 _________________________________________________________ 4.11. FcConstant Table of Contents FcNameRegisterConstants -- Register symbolic constants FcNameUnregisterConstants -- Unregister symbolic constants FcNameGetConstant -- Lookup symbolic constant FcNameConstant -- Get the value for a symbolic constant Provides for application-specified symbolic constants for font names. FcNameRegisterConstants Name FcNameRegisterConstants -- Register symbolic constants Synopsis #include FcBool FcNameRegisterConstants(const FcConstant *consts, intnconsts); Description Register nconsts new symbolic constants. Version Fontconfig version 2.2.3 FcNameUnregisterConstants Name FcNameUnregisterConstants -- Unregister symbolic constants Synopsis #include FcBool FcNameUnregisterConstants(const FcConstant *consts, intnconsts); Description Unregister nconsts symbolic constants. Version Fontconfig version 2.2.3 FcNameGetConstant Name FcNameGetConstant -- Lookup symbolic constant Synopsis #include const FcConstant * FcNameGetConstant(FcChar8 *string); Description Return the FcConstant structure related to symbolic constant string. Version Fontconfig version 2.2.3 FcNameConstant Name FcNameConstant -- Get the value for a symbolic constant Synopsis #include FcBool FcNameConstant(FcChar8 *string, int *result); Description Returns whether a symbolic constant with name string is registered, placing the value of the constant in result if present. Version Fontconfig version 2.2.3 _________________________________________________________ 4.12. FcBlanks Table of Contents FcBlanksCreate -- Create an FcBlanks FcBlanksDestroy -- Destroy and FcBlanks FcBlanksAdd -- Add a character to an FcBlanks FcBlanksIsMember -- Query membership in an FcBlanks 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. FcBlanksCreate Name FcBlanksCreate -- Create an FcBlanks Synopsis #include FcBlanks * FcBlanksCreate(void); Description Creates an empty FcBlanks object. Version Fontconfig version 2.2.3 FcBlanksDestroy Name FcBlanksDestroy -- Destroy and FcBlanks Synopsis #include void FcBlanksDestroy(FcBlanks *b); Description Destroys an FcBlanks object, freeing any associated memory. Version Fontconfig version 2.2.3 FcBlanksAdd Name FcBlanksAdd -- Add a character to an FcBlanks Synopsis #include FcBool FcBlanksAdd(FcBlanks *b, FcChar32ucs4); Description Adds a single character to an FcBlanks object, returning FcFalse if this process ran out of memory. Version Fontconfig version 2.2.3 FcBlanksIsMember Name FcBlanksIsMember -- Query membership in an FcBlanks Synopsis #include FcBool FcBlanksIsMember(FcBlanks *b, FcChar32ucs4); Description Returns whether the specified FcBlanks object contains the indicated Unicode value. Version Fontconfig version 2.2.3 _________________________________________________________ 4.13. FcAtomic Table of Contents FcAtomicCreate -- create an FcAtomic object FcAtomicLock -- lock a file FcAtomicNewFile -- return new temporary file name FcAtomicOrigFile -- return original file name FcAtomicReplaceOrig -- replace original with new FcAtomicDeleteNew -- delete new file FcAtomicUnlock -- unlock a file FcAtomicDestroy -- destroy an FcAtomic object 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. FcAtomicCreate Name FcAtomicCreate -- create an FcAtomic object Synopsis #include FcAtomic * FcAtomicCreate(const FcChar8 *file); Description 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. Version Fontconfig version 2.2.3 FcAtomicLock Name FcAtomicLock -- lock a file Synopsis #include FcBool FcAtomicLock(FcAtomic *atomic); Description 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. Version Fontconfig version 2.2.3 FcAtomicNewFile Name FcAtomicNewFile -- return new temporary file name Synopsis #include FcChar8 * FcAtomicNewFile(FcAtomic *atomic); Description Returns the filename for writing a new version of the file referenced by atomic. Version Fontconfig version 2.2.3 FcAtomicOrigFile Name FcAtomicOrigFile -- return original file name Synopsis #include FcChar8 * FcAtomicOrigFile(FcAtomic *atomic); Description Returns the file refernced by atomic. Version Fontconfig version 2.2.3 FcAtomicReplaceOrig Name FcAtomicReplaceOrig -- replace original with new Synopsis #include FcBool FcAtomicReplaceOrig(FcAtomic *atomic); Description Replaces the original file referenced by atomic with the new file. Version Fontconfig version 2.2.3 FcAtomicDeleteNew Name FcAtomicDeleteNew -- delete new file Synopsis #include void FcAtomicDeleteNew(FcAtomic *atomic); Description Deletes the new file. Used in error recovery to back out changes. Version Fontconfig version 2.2.3 FcAtomicUnlock Name FcAtomicUnlock -- unlock a file Synopsis #include void FcAtomicUnlock(FcAtomic *atomic); Description Unlocks the file. Version Fontconfig version 2.2.3 FcAtomicDestroy Name FcAtomicDestroy -- destroy an FcAtomic object Synopsis #include void FcAtomicDestroy(FcAtomic *atomic); Description Destroys atomic. Version Fontconfig version 2.2.3 _________________________________________________________ 4.14. File and Directory routines Table of Contents FcFileScan -- scan a font file FcDirScan -- scan a font directory FcDirSave -- save a directory cache FcDirCacheValid -- check directory cache timestamp These routines work with font files and directories, including font directory cache files. FcFileScan Name FcFileScan -- scan a font file Synopsis #include FcBool FcFileScan(FcFontSet *set, FcStrSet *dirs, FcFileCache *cache, FcBlanks *blanks, const char *file, FcBoolforce); Description 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. Version Fontconfig version 2.2.3 FcDirScan Name FcDirScan -- scan a font directory Synopsis #include FcBool FcDirScan(FcFontSet *set, FcStrSet *dirs, FcFileCache *cache, FcBlanks *blanks, const char *dir, FcBoolforce); Description 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. Version Fontconfig version 2.2.3 FcDirSave Name FcDirSave -- save a directory cache Synopsis #include FcBool FcDirSave(FcFontSet *set, FcStrSet *dirs, const char *dir); Description Creates the per-directory cache file for dir and populates it with the fonts in set and subdirectories in dirs. Version Fontconfig version 2.2.3 FcDirCacheValid Name FcDirCacheValid -- check directory cache timestamp Synopsis #include FcBool FcDirCacheValid(const FcChar8 *cache_file); Description Returns FcTrue if cache_file is no older than the directory containing it, else FcFalse. Version Fontconfig version 2.2.3 _________________________________________________________ 4.15. FcStrSet and FcStrList Table of Contents FcStrSetCreate -- create a string set FcStrSetMember -- check set for membership FcStrSetAdd -- add to a string set FcStrSetAddFilename -- add a filename to a string set FcStrSetDel -- delete from a string set FcStrSetDestroy -- destroy a string set FcStrListCreate -- create a string iterator FcStrListNext -- get next string in iteration FcStrListDone -- destroy a string iterator A data structure for enumerating strings, used to list directories while scanning the configuration as directories are added while scanning. FcStrSetCreate Name FcStrSetCreate -- create a string set Synopsis #include FcStrSet * FcStrSetCreate(void); Description Create an empty set. Version Fontconfig version 2.2.3 FcStrSetMember Name FcStrSetMember -- check set for membership Synopsis #include FcBool FcStrSetMember(FcStrSet *set, const FcChar8 *s); Description Returns whether s is a member of set. Version Fontconfig version 2.2.3 FcStrSetAdd Name FcStrSetAdd -- add to a string set Synopsis #include FcBool FcStrSetAdd(FcStrSet *set, const FcChar8 *s); Description Adds a copy of s to set. Version Fontconfig version 2.2.3 FcStrSetAddFilename Name FcStrSetAddFilename -- add a filename to a string set Synopsis #include FcBool FcStrSetAddFilename(FcStrSet *set, const FcChar8 *s); Description 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. Version Fontconfig version 2.2.3 FcStrSetDel Name FcStrSetDel -- delete from a string set Synopsis #include FcBool FcStrSetDel(FcStrSet *set, const FcChar8 *s); Description Removes s from set, returning FcTrue if s was a member else FcFalse. Version Fontconfig version 2.2.3 FcStrSetDestroy Name FcStrSetDestroy -- destroy a string set Synopsis #include void FcStrSetDestroy(FcStrSet *set); Description Destroys set. Version Fontconfig version 2.2.3 FcStrListCreate Name FcStrListCreate -- create a string iterator Synopsis #include FcStrList * FcStrListCreate(FcStrSet *set); Description Creates an iterator to list the strings in set. Version Fontconfig version 2.2.3 FcStrListNext Name FcStrListNext -- get next string in iteration Synopsis #include FcChar8 * FcStrListNext(FcStrList *list); Description Returns the next string in set. Version Fontconfig version 2.2.3 FcStrListDone Name FcStrListDone -- destroy a string iterator Synopsis #include void FcStrListDone(FcStrList *list); Description Destroys the enumerator list. Version Fontconfig version 2.2.3 _________________________________________________________ 4.16. String utilities Table of Contents FcUtf8ToUcs4 -- convert UTF-8 to UCS4 FcUcs4ToUtf8 -- convert UCS4 to UTF-8 FcUtf8Len -- count UTF-8 encoded chars FcUtf16ToUcs4 -- convert UTF-16 to UCS4 FcUtf16Len -- count UTF-16 encoded chars FcStrCopy -- duplicate a string FcStrCopyFilename -- copy a string, expanding '~' FcStrCmpIgnoreCase -- compare UTF-8 strings ignoring ASCII case FcStrDirname -- directory part of filename FcStrBasename -- last component of filename Fontconfig manipulates many UTF-8 strings represented with the FcChar8 type. These functions are exposed to help applications deal with these UTF-8 strings in a locale-insensitive manner. FcUtf8ToUcs4 Name FcUtf8ToUcs4 -- convert UTF-8 to UCS4 Synopsis #include int FcUtf8ToUcs4(FcChar8 *src, FcChar32 *dst, intlen); Description 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. Version Fontconfig version 2.2.3 FcUcs4ToUtf8 Name FcUcs4ToUtf8 -- convert UCS4 to UTF-8 Synopsis #include int FcUcs4ToUtf8(FcChar32src, FcChar8dst[FC_UTF8_MAX_LEN]); Description Converts the Unicode char from src into dst and returns the number of bytes needed to encode the char. Version Fontconfig version 2.2.3 FcUtf8Len Name FcUtf8Len -- count UTF-8 encoded chars Synopsis #include FcBool FcUtf8Len(FcChar8 *src, intlen, int *nchar, int *wchar); Description 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. Version Fontconfig version 2.2.3 FcUtf16ToUcs4 Name FcUtf16ToUcs4 -- convert UTF-16 to UCS4 Synopsis #include int FcUtf16ToUcs4(FcChar8 *src, FcEndianendian, FcChar32 *dst, intlen); Description 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. Version Fontconfig version 2.2.3 FcUtf16Len Name FcUtf16Len -- count UTF-16 encoded chars Synopsis #include FcBool FcUtf16Len(FcChar8 *src, FcEndianendian, intlen, int *nchar, int *wchar); Description 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. Version Fontconfig version 2.2.3 FcStrCopy Name FcStrCopy -- duplicate a string Synopsis #include FcChar8 * FcStrCopy(const FcChar8 *s); Description Allocates memory, copies s and returns the resulting buffer. Yes, this is strdup, but that function isn't available on every platform. Version Fontconfig version 2.2.3 FcStrCopyFilename Name FcStrCopyFilename -- copy a string, expanding '~' Synopsis #include FcChar8 * FcStrCopyFilename(const FcChar8 *s); Description Just like FcStrCopy except that it converts any leading '~' characters in s to the value of the HOME environment variable. Returns NULL if '~' is present in s and HOME is unset. Version Fontconfig version 2.2.3 FcStrCmpIgnoreCase Name FcStrCmpIgnoreCase -- compare UTF-8 strings ignoring ASCII case Synopsis #include int FcStrCmpIgnoreCase(const char *s1, const char *s2); Description 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. Version Fontconfig version 2.2.3 FcStrDirname Name FcStrDirname -- directory part of filename Synopsis #include FcChar8 * FcStrDirname(const FcChar8 *file); Description Returns the directory containing file. This is returned in newly allocated storage which should be freed when no longer needed. Version Fontconfig version 2.2.3 FcStrBasename Name FcStrBasename -- last component of filename Synopsis #include FcChar8 * FcStrBasename(const FcChar8 *file); Description Returns the filename of file stripped of any leading directory names. This is returned in newly allocated storage which should be freed when no longer needed. Version Fontconfig version 2.2.3