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
FcFini -- finalize fonconfig 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.

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
FcPatternRemove -- Remove one object of the specified type from the 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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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
FcStrDowncase -- create a lower case translation of a string
FcStrCopyFilename -- copy a string, expanding '~'
FcStrCmpIgnoreCase -- compare UTF-8 strings ignoring ASCII case
FcStrStr -- locate UTF-8 substring
FcStrStrIgnoreCase -- locate UTF-8 substring 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.