# Fontconfig Developers Reference, Version &version;

Keith
Packard
HP Cambridge Research Lab
KRP
Fontconfig &version;

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.

## DESCRIPTION

Fontconfig is a library designed to provide system-wide font configuration, customization and application access.

## 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.

### 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.

### 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 names
        familylang     FC_FAMILYLANG        String  Language cooresponding to
                                                    each family name
        style          FC_STYLE             String  Font style. Overrides weight
                                                    and slant
        stylelang      FC_STYLELANG         String  Language cooresponding to
                                                    each style name
        fullname       FC_FULLNAME          String  Font face full name where
                                                    different from family and
                                                    family + style
        fullnamelang   FC_FULLNAMELANG      String  Language cooresponding to
                                                    each fullname
        slant          FC_SLANT             Int     Italic, oblique or roman
        weight         FC_WEIGHT            Int     Light, medium, demibold,
                                                    bold or black
        size           FC_SIZE              Double  Point size
        width          FC_WIDTH             Int     Condensed, normal or expanded
        aspect         FC_ASPECT            Double  Stretches glyphs horizontally
                                                    before hinting
        pixelsize      FC_PIXEL_SIZE        Double  Pixel size
        spacing        FC_SPACING           Int     Proportional, dual-width,
                                                    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
        hintstyle      FC_HINT_STYLE        Int     Automatic hinting style
        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 the font
        index          FC_INDEX             Int     The index of the font within
                                                    the file
        ftface         FC_FT_FACE           FT_Face Use the specified FreeType
                                                    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 scaled
        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 geometry
        minspace       FC_MINSPACE          Bool    Eliminate leading from line
                                                    spacing
        charset        FC_CHARSET           CharSet Unicode chars encoded by
                                                    the font
        lang           FC_LANG              String  List of RFC-3066-style
                                                    languages this font supports
        fontversion    FC_FONTVERSION       Int     Version number of the font
        capability     FC_CAPABILITY        String  List of layout capabilities in
                                                    the font
        embolden       FC_EMBOLDEN          Bool    Rasterizer should
                                                    synthetically embolden the font

## Datatypes

Fontconfig uses abstract datatypes to hide internal implementation details for most data structures. A few structures are exposed where appropriate.

### 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.

### 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;

### 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.

### FcType

Tags the kind of data stored in an FcValue.

### 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 *

### 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.

### 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.

### 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.

### 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.

### 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.

### 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'.

### 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.

### 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.

### 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.

### 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.

### 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 match
            FcResultNoId            Object exists, but has fewer values
                                    than specified
            FcResultOutOfMemory     Malloc failed

### FcAtomic

Used for locking access to config files. Provides a safe way to update configuration files.

## FUNCTIONS

These are grouped by functionality, often using the main datatype being manipulated.

### Initialization

These functions provide some control over how the library is initialized.

&fcinit;

### FcPattern

An FcPattern is an opaque type that holds both patterns to match against the available fonts, as well as the information about each font.

&fcpattern;

### FcFontSet

An FcFontSet simply holds a list of patterns; these are used to return the results of listing available fonts.

&fcfontset;

### FcObjectSet

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.

&fcobjectset;

### FreeType specific functions

While the fontconfig library doesn't insist that FreeType be used as the rasterization mechanism for fonts, it does provide some convenience functions.

&fcfreetype;

### FcValue

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.

&fcvalue;

### FcCharSet

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.

&fccharset;

### FcMatrix

FcMatrix structures hold an affine transformation in matrix form.

&fcmatrix;

### FcConfig

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.

&fcconfig;

### FcObjectType

Provides for applcation-specified font name object types so that new pattern elements can be generated from font names.

&fcobjecttype;

### FcConstant

Provides for application-specified symbolic constants for font names.

&fcconstant;

### 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.

&fcblanks;

### FcAtomic

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.

&fcatomic;

### File and Directory routines

These routines work with font files and directories, including font directory cache files.

&fcfile;

### FcStrSet and FcStrList

A data structure for enumerating strings, used to list directories while scanning the configuration as directories are added while scanning.

&fcstrset;

### String utilities

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.

&fcstring;