SUPERSEDES APPROVE COMMIT general-docs With Norbert's OK. Fire when ready, Norbert! Sorry about this big superseding patch, but I applied a bunch of patches to the work space and then realized I'd never committed the original. Index: xemacs-packages/general-docs/ChangeLog =================================================================== RCS file: /Users/steve/Software/Repositories/cvs.xemacs.org/XEmacs/packages/xemacs-packages/general-docs/ChangeLog,v retrieving revision 1.9 diff -u -r1.9 ChangeLog --- xemacs-packages/general-docs/ChangeLog 2003/10/31 16:52:56 1.9 +++ xemacs-packages/general-docs/ChangeLog 2004/11/26 15:30:08 ＠＠ -1,3 +1,66 ＠＠ +2004-11-27 Stephen J. Turnbull <stephen(a)xemacs.org&gt; + + * texi/xemacs/fontconfig.texi (Constants): New node. + (The fontconfig API): + (Data Types): + Adjust node pointers for new node Constants. + (Font Properties): Move table to Constants. + + (FcLangSet): New node. + (Functions): + (FcObjectType): + (Querying Fonts and Their Properties): + Update node pointers for new node FcLangSet. + + (Querying Fonts and Their Properties): + Clarify description of FcFontList. + + (FcPattern): Use mnemonic id instead of n in prototypes of + FcPatternGetTYPE functions. + + (Overview): Specify the version of fontconfig described. + + (FcFontSet): + (FcValue): + Add entries for debug print functions. + + (Data Types): Document FcMatchKind, FcLangResult, FcSetName, FcEndian. + + (FcObjectType): Get rid of extraneous semicolon. + +2004-11-22 Stephen J. Turnbull <stephen(a)xemacs.org&gt; + + * texi/xemacs/fontconfig.texi (FcObjectType): + (Querying Fonts and Their Properties): + (Initialization): + Split FcObjectType into FcObjectType and Querying Fonts and Their + Properties. Reorganize functions in Querying. Move descriptions + of FcConfigFilename, FcConfigCreate, FcConfigDestroy, + FcConfigSetCurrent, FcConfigGetCurrent, FcConfigUptoDate, + FcConfigBuildFonts, FcConfigGetConfigDirs, FcConfigGetFontDirs, + FcConfigGetConfigFiles, FcConfigGetCache, FcConfigGetFonts, + FcConfigGetBlanks, FcConfigGetRescanInverval, + FcConfigSetRescanInverval, FcConfigAppFontAddFile, + FcConfigAppFontAddDir, and FcConfigAppFontClear into Initialization. + (FcObjectType): + (Functions): + (Initialization): + (Top): + Update pointers for Querying Fonts and Their Properties. + + (Querying Fonts and Their Properties): + (FcObjectSet): + Fix typos. + + (Functions): + (Top): + Fix capitalization and whitespace of menus. + +2004-11-21 Stephen J. Turnbull <stephen(a)xemacs.org&gt; + + * texi/xemacs/fontconfig.texi: Add file. + * Makefile (EXPLICIT_DOCS): Add fontconfig.texi. + 2003-10-31 Norbert Koch <viteno(a)xemacs.org&gt; * Makefile (VERSION): XEmacs package 1.01 released. Index: xemacs-packages/general-docs/Makefile =================================================================== RCS file: /Users/steve/Software/Repositories/cvs.xemacs.org/XEmacs/packages/xemacs-packages/general-docs/Makefile,v retrieving revision 1.9 diff -u -r1.9 Makefile --- xemacs-packages/general-docs/Makefile 2003/10/31 16:52:56 1.9 +++ xemacs-packages/general-docs/Makefile 2004/11/26 07:03:03 ＠＠ -27,5 +27,6 ＠＠ # We'll need something like this. #EXPLICIT_DOCS = texi/*.texi texi/xemacs/*.texi texi/packages/*.texi +EXPLICIT_DOCS = texi/xemacs/fontconfig.texi include ../../XEmacs.rules Index: xemacs-packages/general-docs/texi/xemacs/fontconfig.texi =================================================================== RCS file: fontconfig.texi diff -N fontconfig.texi --- /dev/null Sat Dec 11 16:21:25 2004 +++ xemacs-packages/general-docs/texi/xemacs/fontconfig.texi Mon Nov 29 17:55:19 2004 ＠＠ -0,0 +1,2007 ＠＠ +\input texinfo.tex +＠c %**start of header +＠setfilename ../../info/fontconfig.info +＠settitle Fontconfig: Font configuration and customization library + +＠set synched-to-pkg-version 1.0 +＠set synched-to-doc-versions Package: ＠value{synched-to-package-version} +＠set last-released-month-year October 2003 +＠set last-released-date 20 October 2003 + +＠footnotestyle separate +＠paragraphindent 2 +＠c %**end of header + +＠dircategory Permissively licensed documentation +＠direntry +* fontconfig:: Managing font metainformation. +＠end direntry + +＠setchapternewpage odd + +＠shorttitlepage Fontconfig + +＠titlepage +＠title Fontconfig +＠subtitle Font configuration and customization library +＠subtitle A Rendering-Engine-Independent Library +＠subtitle for Managing Font Metainformation + +＠author Keith Packard +＠author Stephen J. Turnbull + +＠end titlepage + +＠ifinfo +＠node Top, Copying, (dir), (dir) +＠top Fontconfig + +This file documents fontconfig, a rendering-engine-independent library +for managing font metainformation (＠emph{i.e.}, everything but the glyph +data themselves). It is ＠emph{not} part of XEmacs. + +Copyright © 2002 Keith Packard, member of The XFree86 Project, Inc. +Copyright © 2003 Stephen J. Turnbull, member of the XEmacs Project + +In the following notice, the term "Authors" refers to the copyright +holders listed above, and "Documentation" refers to this version of the +documentation supplied by Keith Packard, as adapted to Texinfo by +Stephen J. Turnbull. The fontconfig library itself and the original +documentation are covered by a similar license. + +Permission to use, copy, modify, distribute, and sell this 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 copies of the Documentation, +and that the names of the Authors not be used in advertising or +publicity pertaining to distribution of the Documentation without +specific, written prior permission. The Authors make no representations +about the suitability of this Documentation for any purpose. It is +provided "as is" without express or implied warranty. + +THE AUTHORS DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS DOCUMENTATION, +INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO +EVENT SHALL THE AUTHORS 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 DOCUMENTATION. + +＠c I believe that this document can legally be distributed under the +＠c above permission. rms's opinion is that there is nothing left of +＠c `texinfo.tex' after processing this document, and therefore nothing +＠c forces this document to be distributed under GPL. + +＠c The original permissively licensed document may be obtained in +＠c distributions of the fontconfig library available from the CVS +＠c repository of the XFree86 Project in module xc/extra/fontconfig. + +＠end ifinfo + +＠menu +* Copying:: +* Overview:: +* The fontconfig API:: +* Configuration File Format:: +* Files:: +* Authors:: + +＠detailmenu + --- The Detailed Node Listing --- + +Overview + +* Font Configuration:: +* Font Properties:: +* Font Matching:: +* Font List Matching:: +* Font Names:: +* LANG Tags:: + +The fontconfig API + +* Data Types:: +* Functions:: + +Functions + +* FcMatrix:: +* FcCharSet:: +* FcValue:: +* FcPattern:: +* FcFontSet:: +* FcObjectSet:: +* FcObjectType:: +* Querying Fonts and Their Properties:: +* Initialization:: +* FcAtomic:: +* FreeType-Specific Functions:: +* XML-Specific Functions:: +* File and Directory Routines:: +* FcStrSet and FcStrList:: +* String Utilities:: + +Configuration File Format + +* Example System Configuration File:: +* Example User Configuration File:: + +＠end detailmenu +＠end menu + +＠node Copying, Overview, Top, Top +＠chapter Copying + +The fontconfig library and the accompanying documentation are covered by +the following copyright notice and license, except for this Texinfo +version which has additional authors but is otherwise substantially the +same. + +Copyright © 2002 Keith Packard, member of The XFree86 Project, Inc. + +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. + +＠node Overview, The fontconfig API, Copying, Top +＠chapter Overview + +＠c DESCRIPTION +Fontconfig is a library designed to provide system-wide font +configuration, customization and application access. + +This manual describes fontconfig version 1.0.2. + +＠c 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. + +＠menu +* Font Configuration:: +* Font Properties:: +* Font Matching:: +* Font List Matching:: +* Font Names:: +* LANG Tags:: +＠end menu + +＠node Font Configuration, Font Properties, Overview, Overview +＠section Font Configuration + +The configuration module consists of the FcConfig datatype, libexpat and +FcConfigParse which walks over an XML tree and amends 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 make +simplify and regularize font installation and customization. + +＠node Font Properties, Font Matching, Font Configuration, Overview +＠section 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. Some symbolic +constants are provided for common values or enumerated types. +＠xref{Constants}, for the list of standard properties and values. + + +＠node Font Matching, Font List Matching, Font Properties, Overview +＠section Font Matching + +Fontconfig performs matching by measuring the distance from a provided +pattern to all of the available fonts in the system. The closest matching +font is selected. This ensures that a font will always be returned, but +doesn't ensure that it is anything like the requested pattern. + +Font matching starts with an application constructed pattern. The desired +attributes of the resulting font are collected together in an FcPattern +object. Each property of the pattern can contain one or more values; these +are listed in priority order; matches earlier in the list are considered +"closer" than matches later in the list. + +The initial pattern is modified by applying the list of editing instructions +specific to patterns found in the configuration; each consists of a match +predicate and a set of editing operations. They are executed in the order +they appeared in the configuration. Each match causes the associated +sequence of editing operations to be applied. + +After the pattern has been edited, a sequence of default substitutions are +performed to canonicalize the set of available properties; this avoids the +need for the lower layers to constantly provide default values for various +font properties during rendering. + +The canonical font pattern is finally matched against all available fonts. +The distance from the pattern to the font is measured for each of several +properties: foundry, charset, family, lang, spacing, pixelsize, style, +slant, weight, antialias, rasterizer and outline. This list is in priority +order---results of comparing earlier elements of this list weigh more +heavily than later elements. + +There is one special case to this rule; family names are split into two +bindings; strong and weak. Strong family names are given greater precedence +in the match than lang elements while weak family names are given lower +precedence than lang elements. This permits the document language to drive +font selection when any document specified font is unavailable. + +The pattern representing that font is augmented to include any properties +found in the pattern but not found in the font itself; this permits the +application to pass rendering instructions or any other data through the +matching system. Finally, the list of editing instructions specific to +fonts found in the configuration are applied to the pattern. This modified +pattern is returned to the application. + +The return value contains sufficient information to locate and rasterize the +font, including the file name, pixel size and other rendering data. As +none of the information involved pertains to the FreeType library, +applications are free to use any rasterization engine or even to take +the identified font file and access it directly. + +The match/edit sequences in the configuration are performed in two passes +because there are essentially two different operations necessary -- the +first is to modify how fonts are selected; aliasing families and adding +suitable defaults. The second is to modify how the selected fonts are +rasterized. Those must apply to the selected font, not the original pattern +as false matches will often occur. + +＠node Font List Matching, Font Names, Font Matching, Overview +＠section Font List Matching + +While many applications want to locate a single font best matching their +search criteria, other applications need to build a set of fonts which can +be used to present any Unicode data. Fontconfig provides an API to generate +a list sorted by the nearness of each font to the pattern. Every font in +the system is considered, the best matching fonts are placed first. The +application then can select whether the remaining fonts are unconditionally +included in the list, or whether they are included only if they cover +portions of Unicode not covered by any of the preceeding fonts. + +The list resulting from this match is represented by references to the +original font patterns and so consumes very little memory. Using a list +entry involves creating a pattern which combines the information from the +font with the information from the original pattern and executing the font +substitutions. + +＠node Font Names, LANG Tags, Font List Matching, Overview +＠section Font Names + +Fontconfig provides a textual representation for patterns that the library +can both accept and generate. The representation is in three parts, first a +list of family names, second a list of point sizes and finally a list of +additional properties: + +＠example + <families>-<point sizes>:<name1>=<values1>:<name2>=<values2>... +＠end example + +Values in a list are separated with commas. A hyphen or comma in a family +name must be escaped with a backslash. The name needn't include either +families or point sizes; they can be elided. If the family name only is +given, the hyphen may be omitted. If there are no additional properties, +no trailing colon should be used. In addition, there are +symbolic constants that simultaneously indicate both a name and a value. +Here are some examples: + +＠example +Times-12 12 point Times Roman +Times-12:bold 12 point Times Bold +Courier:italic Courier Italic in the default size +Monospace:matrix=1 .1 0 1 The users preferred monospace font + with artificial obliquing +Mikachan\-PB-16 12 point Mikachan-PB +＠end example + +＠node LANG Tags, , Font Names, Overview +＠section LANG Tags + +Each font in the database contains a list of languages it supports. This is +computed by comparing the Unicode coverage of the font with the orthography +of each language. Languages are tagged using an RFC-3066 compatible naming +and occur in two parts -- the ISO639 language tag followed a hyphen and then +by the ISO 3166 country code. The hyphen and country code may be elided. + +Fontconfig has orthographies for several languages built into the library. +No provision has been made for adding new ones aside from rebuilding the +library. It currently supports 122 of the 139 languages named in ISO 639-1, +141 of the languages with two-letter codes from ISO 639-2 and another 30 +languages with only three-letter codes. + +＠node The fontconfig API, Configuration File Format, Overview, Top +＠chapter The fontconfig API + +＠example +#include <fontconfig/fontconfig.h> +#include <fontconfig/fcfreetype.h> +＠end example + +＠menu +* Constants:: +* Data Types:: +* Functions:: +＠end menu + +＠node Constants, Data Types, The fontconfig API, The fontconfig API + +While fontconfig is designed to be extensible, it provides a comprehensive +set of standard properties and values for fonts. + +The following table gives the list of standard font properties. The property +name is represented as a string. In C code a C preprocessor symbol may be +used to help with typo detection. + +＠example +Property CPP symbol Type Description + +family FC_FAMILY String Font family name +style FC_STYLE String Font style. Overrides weight and slant +slant FC_SLANT Int Italic, oblique or roman +weight FC_WEIGHT Int Light, medium, demibold, bold or black +size FC_SIZE Double Point size +aspect FC_ASPECT Double Stretch glyphs horizontally, then hint +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 Should glyphs be antialiased? +hinting FC_HINTING Bool Should the rasterizer 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 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 Point->pixel conversion scale factor +dpi FC_DPI Double Target dots per inch +rgba FC_RGBA Int unknown, rgb, bgr, vrgb, vbgr, none + - subpixel geometry +source FC_SOURCE String X11, freetype +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 From 'head' table +＠end example + +C code can check the fontconfig version number with the numerical +preprocessor constants ＠code{FC_MAJOR}, ＠code{FC_MINOR}, and +＠code{FC_REVISION}, or use the combined constant ＠code{FC_VERSION}, defined +as ＠code{FC_MAJOR*10000 + FC_MINOR*100 + FC_REVISION}. + +The cache version (format of ＠file{font.cache-1}?) is given by +＠code{FC_CACHE_VERSION}, and is a string, not an integer. The cache file +names are defined as ＠code{FC_DIR_CACHE_FILE} and ＠code{FC_USER_CACHE_FILE}. + +The Boolean constants are ＠code{FcFalse} (0) and ＠code{FcTrue} (1). + +Properties used to control the rasterizer, their preprocessor constants, and +their types, include: + +＠example +charwidth FC_CHAR_WIDTH Int +charheight FC_CHAR_HEIGHT Int +matrix FC_MATRIX FcMatrix +＠end example + +Preprocessor constants are defined for common standard font weights. All are +Ints. + +＠example +FC_WEIGHT_LIGHT 0 +FC_WEIGHT_MEDIUM 100 +FC_WEIGHT_DEMIBOLD 180 +FC_WEIGHT_BOLD 200 +FC_WEIGHT_BLACK 210 +＠end example + +Preprocessor constants are defined for common standard slants. All are Ints. + +＠example +FC_SLANT_ROMAN 0 +FC_SLANT_ITALIC 100 +FC_SLANT_OBLIQUE 110 +＠end example + +Preprocessor constants are defined for the three spacing types. All are +Ints, but should be treated as symbolic constants. + +＠example +FC_PROPORTIONAL 0 +FC_MONO 100 +FC_CHARCELL 110 +＠end example + +Preprocessor constants are defined for the subpixel orders. All are +Ints, but should be treated as symbolic constants. + +＠example +FC_RGBA_UNKNOWN 0 +FC_RGBA_RGB 1 +FC_RGBA_BGR 2 +FC_RGBA_VRGB 3 +FC_RGBA_VBGR 4 +FC_RGBA_NONE 5 +＠end example + + +＠node Data Types, Functions, Constants, The fontconfig API +＠section Data Types + +＠table ＠samp +＠item FcChar8 +＠itemx FcChar16 +＠itemx FcChar32 +＠itemx FcBool +These are primitive data types; 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. + +＠item FcMatrix +An FcMatrix holds an affine transformation, usually used to reshape glyphs. +A small set of matrix operations are provided to manipulate these. + +＠example + typedef struct _FcMatrix ＠{ + double xx, xy, yx, yy; + ＠} FcMatrix; +＠end example + +＠item 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. + +＠item FcType +Tags the kind of data stored in an FcValue. + +＠item FcValue +An FcValue object holds a single value with one of a number of different +types. The 'type' tag indicates which member is valid. + +＠example + typedef struct _FcValue ＠{ + FcType type; + union ＠{ + const FcChar8 *s; + int i; + FcBool b; + double d; + const FcMatrix *m; + const FcCharSet *c; + void *f; + const FcPattern *p; + const FcLangSet *l; + ＠} u; + ＠} FcValue; +＠end example + +＠example + type Union member Datatype + + FcTypeVoid (none) (none) + FcTypeInteger i int + FcTypeDouble d double + FcTypeString s TcChar8 * + FcTypeBool b b + FcTypeMatrix m FcMatrix * + FcTypeCharSet c FcCharSet * + FcTypeFTFace f void * + p FcPattern * + FcTypeLangSet l FcLangSet * +＠end example + +＠item 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. + +＠item FcFontSet + +＠example + typedef struct _FcFontSet ＠{ + int nfont; + int sfont; + FcPattern **fonts; + ＠} FcFontSet; +＠end example + +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. + +＠item FcStrSet +＠itemx 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. + +＠item FcObjectSet + +＠example + typedef struct _FcObjectSet ＠{ + int nobject; + int sobject; + const char **objects; + ＠} FcObjectSet; +＠end example +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. + +＠item FcObjectType + +＠example + typedef struct _FcObjectType ＠{ + const char *object; + FcType type; + ＠} FcObjectType; +＠end example +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. + +＠item FcConstant + +＠example + typedef struct _FcConstant ＠{ + const FcChar8 *name; + const char *object; + int value; + ＠} FcConstant; +＠end example +Provides for symbolic constants for new pattern elements. When 'name' is +seen in a font name, an 'object' element is created with value 'value'. + +＠item 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. + +＠item 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. + +＠item 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. + +＠item 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. + +＠item FcResult +Used as a return type for functions manipulating FcPattern objects. + +＠example +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 +＠end example + +＠item FcAtomic +Used for locking access to config files. Provides a safe way to update +configuration files. + +＠item FcMatchKind +An enumeration containing ＠code{FcMatchPattern} and ＠code{FcMatchFont}. + +＠item FcLangResult +An enumeration containing ＠code{FcLangEqual}, ＠code{FcLangDifferentCountry}, +and ＠code{FcLangDifferentLang}. Presumably ＠code{FcLangDifferentLang} +implies ＠code{FcLangDifferentCountry}. + +＠item FcSetName +An enumeration containing ＠code{FcSetSystem} and ＠code{FcSetApplication}. + +＠item FcEndian +An enumeration containing ＠code{FcEndianBig} and ＠code{FcEndianLittle}. +＠end table + +＠node Functions, , Data Types, The fontconfig API +＠section Functions + +＠menu +* FcMatrix:: +* FcCharSet:: +* FcValue:: +* FcPattern:: +* FcFontSet:: +* FcObjectSet:: +* FcObjectType:: +* FcLangSet:: +* Querying Fonts and Their Properties:: +* Initialization:: +* FcAtomic:: +* FreeType-Specific Functions:: +* XML-Specific Functions:: +* File and Directory Routines:: +* FcStrSet and FcStrList:: +* String Utilities:: +＠end menu + +＠node FcMatrix, FcCharSet, Functions, Functions +＠subsection FcMatrix + +FcMatrix structures hold an affine transformation in matrix form. + +＠example +#define FcMatrixInit(m) ((m)->xx = (m)->yy = 1, (m)->xy = (m)->yx = 0) +＠end example +Initializes a matrix to the identify transformation. + +＠deftypefun {FcMatrix *} FcMatrixCopy (const FcMatrix *＠var{mat}) + +Allocates a new FcMatrix and copies 'mat' into it. +＠end deftypefun + +＠deftypefun FcBool FcMatrixEqual (const FcMatrix *＠var{mat1}, const FcMatrix *var{mat2}) + +Returns FcTrue if 'mat1' and 'mat2' are equal, else FcFalse. +＠end deftypefun + +＠deftypefun void FcMatrixMultiply (FcMatrix *＠var{result}, const FcMatrix *＠var{a}, const FcMatrix *var{b}) + +Multiplies 'a' and 'b' together, placing the result in 'result'. 'result' +may refer to the sam matrix as either 'a' or 'b'. +＠end deftypefun + +＠deftypefun void FcMatrixRotate (FcMatrix *m, double c, double s) + +If 'c' is cos(angle) and 's' is sin(angle), FcMatrixRotate rotates the +matrix by 'angle'. +＠end deftypefun + +＠deftypefun void FcMatrixScale (FcMatrix *m, double sx, double sy) + +Scales 'm' by 'sx' in the horizontal dimension and 'sy' in the +vertical dimension. +＠end deftypefun + +＠deftypefun void FcMatrixShear (FcMatrix *m, double sh, double sv) +Shears 'm' by 'sh' in the horizontal direction and 'sv' in the +vertical direction. +＠end deftypefun + +＠node FcCharSet, FcValue, FcMatrix, Functions +＠subsection 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 its argument, and that CharSet may remain unmodifiable. + +＠deftypefun {FcCharSet *} FcCharSetCreate (void) + +Creates an empty FcCharSet object. +＠end deftypefun + +＠deftypefun void FcCharSetDestroy (FcCharSet *fcs) + +Frees an FcCharSet object. +＠end deftypefun + +＠deftypefun FcBool FcCharSetAddChar (FcCharSet *fcs, FcChar32 ucs4) + +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. +＠end deftypefun + +＠deftypefun {FcCharSet *} FcCharSetCopy (FcCharSet *src) + +Makes a copy of 'src'; note that this may not actually do anything more than +increment the reference count on 'src'. +＠end deftypefun + +＠deftypefun FcBool FcCharSetEqual (const FcCharSet *a, const FcCharSet *b) + +Returns whether 'a' and 'b' contain the same set of unicode chars. +＠end deftypefun + +＠deftypefun {FcCharSet *} FcCharSetIntersect (const FcCharSet *a, const FcCharSet *b) + +Returns a set including only those chars found in both 'a' and 'b'. +＠end deftypefun + +＠deftypefun {FcCharSet *} FcCharSetUnion (const FcCharSet *a, const FcCharSet *b); + +Returns a set including only those chars found in either 'a' or 'b'. +＠end deftypefun + +＠deftypefun {FcCharSet *} FcCharSetSubtract (const FcCharSet *a, const FcCharSet *b) + +Returns a set including only those chars found in 'a' but not 'b'. +＠end deftypefun + +＠deftypefun FcBool FcCharSetHasChar (const FcCharSet *fcs, FcChar32 ucs4) + +Returns whether 'fcs' contains the char 'ucs4'. +＠end deftypefun + +＠deftypefun FcChar32 FcCharSetCount (const FcCharSet *a) + +Returns the total number of unicode chars in 'a'. +＠end deftypefun + +＠deftypefun FcChar32 FcCharSetIntersectCount (const FcCharSet *a, const FcCharSet *b) + +Returns the number of chars that are in both 'a' and 'b'. +＠end deftypefun + +＠deftypefun FcChar32 FcCharSetSubtractCount (const FcCharSet *a, const FcCharSet *b) + +Returns the number of chars that are in 'a' but not in 'b'. +＠end deftypefun + +＠deftypefun FcBool FcCharSetIsSubset (const FcCharSet *a, const FcCharSet *b) + +Returns whether 'a' is a subset of 'b'. +＠end deftypefun + +＠deftypefun FcChar32 FcCharSetFirstPage (const FcCharSet *a, FcChar32 [FC_CHARSET_MAP_SIZE], FcChar32 *next) + +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. +＠end deftypefun + +＠deftypefun FcChar32 FcCharSetNextPage (const FcCharSet *a, FcChar32 [FC_CHARSET_MAP_SIZE], FcChar32 *next) + +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. +＠end deftypefun + +＠node FcValue, FcPattern, FcCharSet, Functions +＠subsection FcValue + +FcValue is a structure containing a type tag and a union of all possible +data types. 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. + +＠deftypefun void FcValueDestroy (FcValue v) + +Frees any memory referenced by `v'. Values of type FcTypeString, +FcTypeMatrix and FcTypeCharSet reference memory, the other types do not. +＠end deftypefun + +＠deftypefun FcValue FcValueSave (FcValue v) + +Returns a copy of `v' duplicating any object referenced by it so that `v' +may be safely destroyed without harming the new value. +＠end deftypefun + +＠deftypefun void FcValuePrint (const FcValue v) + +Prints an easily readable version of the value to stdout. There is +no provision for reparsing data in this format, it's just for diagnostics +and debugging. +＠end deftypefun + + +＠node FcPattern, FcFontSet, FcValue, Functions +＠subsection 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. + +＠deftypefun {FcPattern *} FcPatternCreate (void) + +Creates a pattern with no properties; used to build patterns from scratch. +＠end deftypefun + +＠deftypefun void FcPatternDestroy (FcPattern *p) + +Destroys a pattern, in the process destroying all related values. +＠end deftypefun + +＠deftypefun FcBool FcPatternEqual (const FcPattern *pa, const FcPattern *pb); + +Returns whether 'pa' and 'pb' are exactly alike. +＠end deftypefun + +＠deftypefun FcBool FcPatternEqualSubset (const FcPattern *pa, const FcPattern *pb, const FcObjectSet *os) + +Returns whether 'pa' and 'pb' have exactly the same values for all of the +objects in 'os'. +＠end deftypefun + +＠deftypefun FcChar32 FcPatternHash (const FcPattern *p) + +Returns a 32-bit number which is the same for any two patterns which are +exactly alike. +＠end deftypefun + +＠deftypefun FcBool FcPatternAdd (FcPattern *p, const char *object, FcValue value, FcBool append) + +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. +＠end deftypefun + +＠deftypefun FcBool FcPatternAddWeak (FcPattern *p, const char *object, FcValue value, FcBool append) + +FcPatternAddWeak is essentially the same as FcPatternAdd except that any +values added to the list have binding 'weak' instead of 'strong'. +＠end deftypefun + +＠deftypefun FcBool FcPatternAddInteger (FcPattern *p, const char *object, int i) +＠deftypefunx FcBool FcPatternAddDouble (FcPattern *p, const char *object, double d) +＠deftypefunx FcBool FcPatternAddString (FcPattern *p, const char *object, const char *s) +＠deftypefunx FcBool FcPatternAddMatrix (FcPattern *p, const char *object, const FcMatrix *s) +＠deftypefunx FcBool FcPatternAddCharSet (FcPattern *p, const char *object, const FcCharSet *c) +＠deftypefunx FcBool FcPatternAddBool (FcPattern *p, const char *object, FcBool b) + +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. +＠end deftypefun + +＠deftypefun FcResult FcPatternGet (FcPattern *p, const char *object, int id, FcValue *v) + +Returns in `v' the `id'th value associated with the property `object'. +The value returned is not a copy, but rather refers to the data stored +within the pattern directly. Applications must not free this value. +＠end deftypefun + +＠deftypefun FcResult FcPatternGetInteger (FcPattern *p, const char *object, int id, int *i); +＠deftypefunx FcResult FcPatternGetDouble (FcPattern *p, const char *object, int id, double *d); +＠deftypefunx FcResult FcPatternGetString (FcPattern *p, const char *object, int id, char **const s); +＠deftypefunx FcResult FcPatternGetMatrix (FcPattern *p, const char *object, int id, FcMatrix **s); +＠deftypefunx FcResult FcPatternGetCharSet (FcPattern *p, const char *object, int id, FcCharSet **c); +＠deftypefunx FcResult FcPatternGetBool (FcPattern *p, const char *object, int id, FcBool *b); + +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. +＠end deftypefun + +＠deftypefun {FcPattern *} FcPatternBuild (FcPattern *orig, ...); +＠deftypefunx FcPattern *FcPatternVaBuild (FcPattern *orig, va_list va) + +Builds a pattern using a list of objects, types and values. Each +value to be entered in the pattern is specified with three arguments: +＠enumerate +＠item +Object name, a string describing the property to be added. +＠item +Object type, one of the FcType enumerated values +＠item +Value, not an FcValue, but the raw type as passed to any of the +FcPatternAdd<type> functions. Must match the type of the second +argument. +＠end enumerate + +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: + +＠example +pattern = FcPatternBuild (0, FC_FAMILY, FtTypeString, "Times", (char *) 0); +＠end example + +FcPatternVaBuild is used when the arguments are already in the form of a +varargs value. +＠end deftypefun + +＠deftypefun FcBool FcPatternDel (FcPattern *p, const char *object) + +Deletes all values associated with the property `object', returning +whether the property existed or not. +＠end deftypefun + +＠deftypefun void FcPatternPrint (const FcPattern *p) + +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. +＠end deftypefun + +＠deftypefun void FcDefaultSubstitute (FcPattern *pattern) + +Supplies default values for underspecified font patterns: +＠itemize +＠item +Patterns without a specified style or weight are set to Medium +＠item +Patterns without a specified style or slant are set to Roman +＠item +Patterns without a specified pixel size are given one computed from +any specified point size (default 12), dpi (default 75) and scale (default +1). +＠end itemize +＠end deftypefun + +＠deftypefun {FcPattern *} FcNameParse (const char *name) + +Converts 'name' from the standard text format described above into a pattern. +＠end deftypefun + +＠deftypefun FcChar8 *FcNameUnparse (FcPattern *pat) + +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. +＠end deftypefun + +＠node FcFontSet, FcObjectSet, FcPattern, Functions +＠subsection FcFontSet + +An FcFontSet simply holds a list of patterns; these are used to return the +results of listing available fonts. + +＠deftypefun FcFontSet *FcFontSetCreate (void) + +Creates an empty font set. +＠end deftypefun + +＠deftypefun void FcFontSetDestroy (FcFontSet *s); + +Destroys a font set. Note that this destroys any referenced patterns as +well. +＠end deftypefun + +＠deftypefun FcBool FcFontSetAdd (FcFontSet *s, FcPattern *font) + +Adds a pattern to a font set. Note that the pattern is not copied before +being inserted into the set. +＠end deftypefun + +＠deftypefun void FcFontSetPrint (const FcFontSet *s) + +Prints an easily readable version of the font set to stdout. There is +no provision for reparsing data in this format, it's just for diagnostics +and debugging. +＠end deftypefun + + +＠node FcObjectSet, FcObjectType, FcFontSet, Functions +＠subsection FcObjectSet + +An FcObjectSet holds a list of pattern property names; it is used to +indicate which properties are to be returned in the patterns from +FcFontList. + +＠deftypefun FcObjectSet *FcObjectSetCreate (void) + +Creates an empty set. +＠end deftypefun + +＠deftypefun FcBool FcObjectSetAdd (FcObjectSet *os, const char *object) + +Adds a property name to the set. +＠end deftypefun + +＠deftypefun void FcObjectSetDestroy (FcObjectSet *os) + +Destroys an object set. +＠end deftypefun + +＠deftypefun FcObjectSet *FcObjectSetBuild (const char *first, ...) +＠deftypefunx FcObjectSet *FcObjectSetVaBuild (const char *first, va_list va) + +These build an object set from a null-terminated list of property names. +＠end deftypefun + +＠node FcObjectType, Querying Fonts and Their Properties, FcObjectSet, Functions +＠subsection FcObjectType + +Provides for application-specified font name object types so that new +pattern elements can be generated from font names. + +＠deftypefun FcBool FcNameRegisterObjectTypes (const FcObjectType *types, int ntype) + +Register 'ntype' new object types. +＠end deftypefun + +＠deftypefun FcBool FcNameUnregisterObjectTypes (const FcObjectType *types, int ntype) + +Unregister 'ntype' object types. +＠end deftypefun + +＠deftypefun const FcObjectType *FcNameGetObjectType (const char *object) + +Return the object type for the pattern element named 'object'. +＠end deftypefun + +FcConstant + +Provides for application-specified symbolic constants for font names. + +＠deftypefun FcBool FcNameRegisterConstants (const FcConstant *consts, int nconsts) + +Register 'nconsts' new symbolic constants. +＠end deftypefun + +＠deftypefun FcBool FcNameUnregisterConstants (const FcConstant *consts, int nconsts) + +Unregister 'nconsts' symbolic constants. +＠end deftypefun + +＠deftypefun const FcConstant *FcNameGetConstant (FcChar8 *string) + +Return the FcConstant structure related to symbolic constant 'string'. +＠end deftypefun + +＠deftypefun FcBool FcNameConstant (FcChar8 *string, int *result) + +Returns whether a symbolic constant with name 'string' is registered, +placing the value of the constant in 'result' if present. +＠end deftypefun + + +＠node FcLangSet, Querying Fonts and Their Properties, FcObjectType, Functions +＠subsection FcLangSet + +An ＠code{FcLangSet} holds a set of RFC 3066 language tags, ＠ref{LANG tags}. +This module provides functions to determine whether a given language is +fully supported by a font. Partial support can be determined using the +font's character set, ＠ref{FcCharSet}. + +＠deftypefun FcLangSet *FcLangSetCreate (void); + +Create an empty ＠code{FcLangSet}. +＠end deftypefun + +＠deftypefun void FcLangSetDestroy (FcLangSet *ls); + +Destroy a ＠code{FcLangSet}, freeing any associated storage. +＠end deftypefun + +＠deftypefun FcLangSet *FcLangSetCopy (const FcLangSet *ls); + +Copy ＠var{ls} to a newly allocated ＠code{FcLangSet}. +＠end deftypefun + +＠deftypefun FcBool FcLangSetAdd (FcLangSet *ls, const FcChar8 *lang); + +Add ＠var{lang} to ＠code{FcLangSet} ＠var{ls}. +＠end deftypefun + +＠deftypefun FcLangResult FcLangSetHasLang (const FcLangSet *ls, const FcChar8 *lang); + +Check whether ＠var{lang} is a member of ＠code{FcLangSet} ＠var{ls}. Note that +the return value is a ＠code{FcLangResult}, not a Boolean. +＠end deftypefun + +＠deftypefun FcLangResult FcLangSetCompare (const FcLangSet *lsa, const FcLangSet *lsb); + +#### Document me. +＠end deftypefun + +＠deftypefun FcBool FcLangSetEqual (const FcLangSet *lsa, const FcLangSet *lsb); + +Check whether the ＠code{FcLangSet}s ＠var{lsa} and ＠var{lsb} contain the same +members. +＠end deftypefun + +＠deftypefun FcChar32 FcLangSetHash (const FcLangSet *ls); + +Return a hash value; two ＠code{FcLangSet}s which hash to different values +cannot contain the same members. +＠end deftypefun + + +＠node Querying Fonts and Their Properties, Initialization, FcLangSet, Functions +＠subsection Querying Fonts and Their Properties + +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. + +＠deftypefun FcBlanks *FcBlanksCreate (void) + +Creates an empty FcBlanks object. +＠end deftypefun + +＠deftypefun void FcBlanksDestroy (FcBlanks *b) + +Destroys an FcBlanks object, freeing any associated memory. +＠end deftypefun + +＠deftypefun FcBool FcBlanksAdd (FcBlanks *b, FcChar32 ucs4) + +Adds a single character to an FcBlanks object, returning FcFalse +if this process ran out of memory. +＠end deftypefun + +＠deftypefun FcBool FcBlanksIsMember (FcBlanks *b, FcChar32 ucs4) + +Returns whether the specified FcBlanks object contains the indicated Unicode +value. +＠end deftypefun + +The site or user may specify substitutions for certain font patterns, +for convenience or to get more accurate results for the local +installation or preferences. These functions execute the substitution +based on a specified configuration. + +＠deftypefun FcBool FcConfigSubstituteWithPat (FcConfig *config, FcPattern *p, FcPattern *p_pat FcMatchKind kind) + +Performs the sequence of pattern modification operations, if 'kind' is +FcMatchPattern, then those tagged as pattern operations are applied, else +if 'kind' is FcMatchFont, those tagged as font operations are applied and +p_pat is used for <test> elements with target=pattern. +＠end deftypefun + +＠deftypefun FcBool FcConfigSubstitute (FcConfig *config, FcPattern *p, FcMatchKind kind) + +Calls FcConfigSubstituteWithPat setting p_pat to NULL. +＠end deftypefun + +The following functions return fonts that match a certain pattern. +＠code{FcFontRenderPrepare} and ＠code{FcFontMatch} always return a single +best match. ＠code{FcFontList} returns the list of fonts that match a a +given pattern on a certain set of properties. ＠code{FcFontSort} returns +the entire list of fonts, sorted in order of match quality, possibly +filtering out fonts that do not provide additional characters beyond +those provided by preferred fonts. + +＠deftypefun {FcPattern *} FcFontRenderPrepare (FcConfig *config, FcPattern *pat, FcPattern *font) + +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. +＠end deftypefun + +＠deftypefun {FcPattern *} FcFontMatch (FcConfig *config, FcPattern *p, FcResult *result) + +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. +＠end deftypefun + +＠deftypefun FcFontSet *FcFontList (FcConfig *config, FcPattern *p, FcObjectSet *os) + +Selects fonts matching 'p', creates patterns containing only the objects in +'os' from those fonts, and returns the set of unique such patterns. + +The FcFontSet returned by FcFontList is destroyed by calling FcFontSetDestroy. +＠end deftypefun + +＠deftypefun FcFontSet *FcFontSort (FcConfig *config, FcPattern *p, FcBool trim, FcCharSet **csp, FcResult *result) + +Returns the list of all 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 calling FcFontSetDestroy. +＠end deftypefun + + +＠node Initialization, FcAtomic, Querying Fonts and Their Properties, Functions +＠subsection Initialization + +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. + +＠deftypefun FcConfig *FcConfigCreate (void) + +Creates an empty configuration. +＠end deftypefun + +＠deftypefun void FcConfigDestroy (FcConfig *config) + +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. +＠end deftypefun + +＠deftypefun FcBool FcConfigSetCurrent (FcConfig *config) + +Sets the current default configuration to 'config'. Implicitly calls +FcConfigBuildFonts if necessary, returning FcFalse if that call fails. +＠end deftypefun + +＠deftypefun FcConfig *FcConfigGetCurrent (void) + +Returns the current default configuration. +＠end deftypefun + +＠deftypefun FcBool FcConfigUptoDate (FcConfig *config) + +Checks all of the files related to 'config' and returns whether the +in-memory version is in sync with the disk version. +＠end deftypefun + +＠deftypefun FcBool FcConfigBuildFonts (FcConfig *config) + +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. +＠end deftypefun + +＠deftypefun FcStrList *FcConfigGetConfigDirs (FcConfig *config) + +Returns the list of font directories specified in the configuration files +for 'config'. Does not include any subdirectories. +＠end deftypefun + +＠deftypefun FcStrList *FcConfigGetFontDirs (FcConfig *config) + +Returns the list of font directories in 'config'. This includes the +configured font directories along with any directories below those in the +filesystem. +＠end deftypefun + +＠deftypefun FcStrList *FcConfigGetConfigFiles (FcConfig *config) + +Returns the list of known configuration files used to generate 'config'. +Note that this will not include any configuration done with FcConfigParse. +＠end deftypefun + +＠deftypefun char *FcConfigGetCache (FcConfig *config) + +Returns the name of the file used to store per-user font information. +＠end deftypefun + +＠deftypefun FcFontSet *FcConfigGetFonts (FcConfig *config, FcSetName set) + +Returns one of the two sets of fonts from the configuration as specified +by 'set'. +＠end deftypefun + +＠deftypefun FcBlanks *FcConfigGetBlanks (FcConfig *config) + +Returns the FcBlanks object associated with the given configuration, if no +blanks were present in the configuration, this function will return 0. +＠end deftypefun + +＠deftypefun int FcConfigGetRescanInverval (FcConfig *config) + +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. +＠end deftypefun + +＠deftypefun FcBool FcConfigSetRescanInverval (FcConfig *config, int rescanInterval) + +Sets the rescan interval; returns FcFalse if an error occurred. +＠end deftypefun + +＠deftypefun FcBool FcConfigAppFontAddFile (FcConfig *config, const char *file) + +Adds an application-specific font to the configuration. +＠end deftypefun + +＠deftypefun FcBool FcConfigAppFontAddDir (FcConfig *config, const char *dir) + +Scans the specified directory for fonts, adding each one found to the +application-specific set of fonts. +＠end deftypefun + +＠deftypefun void FcConfigAppFontClear (FcConfig *config) + +Clears the set of application-specific fonts. +＠end deftypefun + +These functions provide some control over how the default configuration of +the library is initialized. (This configuration is normally implicitly +initialized.) + +＠deftypefun char *FcConfigFilename (const char *name) + +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. +＠end deftypefun + +＠deftypefun FcConfig *FcInitLoadConfig (void) + +Loads the default configuration file and returns the resulting configuration. +Does not load any font information. +＠end deftypefun + +＠deftypefun FcConfig *FcInitLoadConfigAndFonts (void) + +Loads the default configuration file and builds information about the +available fonts. Returns the resulting configuration. +＠end deftypefun + +＠deftypefun FcBool FcInit (void) + +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. +＠end deftypefun + +＠deftypefun int FcGetVersion (void) + +Returns the version number of the library. +＠end deftypefun + +＠deftypefun FcBool FcInitReinitialize (void) + +Forces the default configuration file to be reloaded and resets the default +configuration. +＠end deftypefun + +＠deftypefun FcBool FcInitBringUptoDate (void) + +Checks the rescan interval in the default configuration, checking the +configuration if the interval has passed and reloading the configuration +when any changes are detected. +＠end deftypefun + + +＠node FcAtomic, FreeType-Specific Functions, Initialization, Functions +＠subsection 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. + +＠deftypefun FcAtomic * FcAtomicCreate (const FcChar8 *file) + +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. +＠end deftypefun + +＠deftypefun FcBool FcAtomicLock (FcAtomic *atomic) + +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. +＠end deftypefun + +＠deftypefun FcChar8 *FcAtomicNewFile (FcAtomic *atomic) + +Returns the filename for writing a new version of the file referenced +by 'atomic'. +＠end deftypefun + +＠deftypefun FcChar8 *FcAtomicOrigFile (FcAtomic *atomic) + +Returns the file refernced by 'atomic'. +＠end deftypefun + +＠deftypefun FcBool FcAtomicReplaceOrig (FcAtomic *atomic) + +Replaces the original file referenced by 'atomic' with the new file. +＠end deftypefun + +＠deftypefun void FcAtomicDeleteNew (FcAtomic *atomic) + +Deletes the new file. +＠end deftypefun + +＠deftypefun void FcAtomicUnlock (FcAtomic *atomic) + +Unlocks the file. +＠end deftypefun + +＠deftypefun void FcAtomicDestroy (FcAtomic *atomic) + +Destroys 'atomic'. +＠end deftypefun + +＠node FreeType-Specific Functions, XML-Specific Functions, FcAtomic, Functions +＠subsection FreeType-Specific Functions + +＠example +#include <fontconfig/fcfreetype.h> +＠end example + +While the fontconfig library doesn't insist that FreeType be used as the +rasterization mechanism for fonts, it does provide some convenience +functions. + +＠deftypefun FT_UInt FcFreeTypeCharIndex (FT_Face face, FcChar32 ucs4) + +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. +＠end deftypefun + +＠deftypefun {FcCharSet *} FcFreeTypeCharSet (FT_Face face, FcBlanks *blanks) 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. +＠end deftypefun + +＠deftypefun {FcPattern *} FcFreeTypeQuery (const char *file, int id, FcBlanks *blanks, int *count) + +Constructs a pattern representing the 'id'th font in 'file'. The number +of fonts in 'file' is returned in 'count'. +＠end deftypefun + +＠node XML-Specific Functions, File and Directory Routines, FreeType-Specific Functions, Functions +＠subsection XML-Specific Functions + +＠deftypefun FcBool FcConfigParseAndLoad (FcConfig *config, const FcChar8 *file, FcBool complain) + +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. +＠end deftypefun + +＠node File and Directory Routines, FcStrSet and FcStrList, XML-Specific Functions, Functions +＠subsection File and Directory Routines + +＠deftypefun FcBool FcFileScan (FcFontSet *set, FcStrSet *dirs, FcFileCache *cache, FcBlanks *blanks, const char *file, FcBool force) + +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'. +＠end deftypefun + +＠deftypefun FcBool FcDirScan (FcFontSet *set, FcStrSet *dirs, FcFileCache *cache, FcBlanks *blanks, const char *dir, FcBool force) + +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'. +＠end deftypefun + +＠deftypefun FcBool FcDirSave (FcFontSet *set, FcStrSet *dirs, const char *dir) + +Creates the per-directory cache file for 'dir' and populates it with the +fonts in 'set' and subdirectories in 'dirs'. +＠end deftypefun + +＠deftypefun FcBool FcDirCacheValid (const FcChar8 *cache_file) + +Returns FcTrue if 'cache_file' is no older than the directory containing it, +else FcFalse. +＠end deftypefun + +＠node FcStrSet and FcStrList, String Utilities, File and Directory Routines, Functions +＠subsection FcStrSet and FcStrList + +A data structure for enumerating strings, used to list directories while +scanning the configuration as directories are added while scanning. + +＠deftypefun FcStrSet *FcStrSetCreate (void) + +Create an empty set. +＠end deftypefun + +＠deftypefun FcBool FcStrSetMember (FcStrSet *set, const FcChar8 *s) + +Returns whether 's' is a member of 'set'. +＠end deftypefun + +＠deftypefun FcBool FcStrSetAdd (FcStrSet *set, const FcChar8 *s) + +Adds a copy of 's' to 'set'. +＠end deftypefun + +＠deftypefun FcBool FcStrSetAddFilename (FcStrSet *set, const FcChar8 *s) + +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. +＠end deftypefun + +＠deftypefun FcBool FcStrSetDel (FcStrSet *set, const FcChar8 *s) + +Removes 's' from 'set', returning FcTrue if 's' was a member else FcFalse. +＠end deftypefun + +＠deftypefun void FcStrSetDestroy (FcStrSet *set) + +Destroys 'set'. +＠end deftypefun + +＠deftypefun FcStrList *FcStrListCreate (FcStrSet *set) + +Creates an enumerator to list the strings in 'set'. +＠end deftypefun + +＠deftypefun FcChar8 *FcStrListNext (FcStrList *list) + +Returns the next string in 'set'. +＠end deftypefun + +＠deftypefun void FcStrListDone (FcStrList *list) + +Destroys the enumerator 'list'. +＠end deftypefun + +＠node String Utilities, , FcStrSet and FcStrList, Functions +＠subsection String Utilities + +＠deftypefun int FcUtf8ToUcs4 (FcChar8 *src, FcChar32 *dst, int len) + +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. +＠end deftypefun + +＠deftypefun int FcUcs4ToUtf8 (FcChar32 src, FcChar8 dst[FC_UTF8_MAX_LEN]) + +Converts the Unicode char from 'src' into 'dst' and returns the +number of bytes needed to encode the char. +＠end deftypefun + +＠deftypefun FcBool FcUtf8Len (FcChar8 *src, int len, int *nchar, int *wchar) + +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. +＠end deftypefun + +＠deftypefun int FcUtf16ToUcs4 (FcChar8 *src, FcEndian endian, FcChar32 *dst, int len) + +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'. +＠end deftypefun + +＠deftypefun FcBool FcUtf16Len (FcChar8 *src, FcEndian endian, int len, int *nchar, int *wchar) + +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. +＠end deftypefun + +＠deftypefun FcChar8 *FcStrCopy (const FcChar8 *s) + +Allocates memory, copies 's' and returns the resulting buffer. Yes, this +is 'strdup', but that function isn't available on every platform. +＠end deftypefun + +＠deftypefun FcChar8 *FcStrCopyFilename (const FcChar8 *s) + +Just like FcStrCopy except that it converts any leading '~' characters +in 's' to the value of the HOME environment variable. +＠end deftypefun + +＠deftypefun int FcStrCmpIgnoreCase (const char *s1, const char *s2) + +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. +＠end deftypefun + +＠deftypefun FcChar8 *FcStrDirname (const FcChar8 *file) + +Returns the directory containing 'file'. +＠end deftypefun + +＠deftypefun FcChar8 *FcStrBasename (const FcChar8 *file) + +Returns the filename of 'file' stripped of any leading directory names. +＠end deftypefun + +＠node Configuration File Format, Files, The fontconfig API, Top +＠chapter Configuration File Format + +Configuration files for fontconfig are stored in XML format; this +format makes external configuration tools easier to write and ensures that +they will generate syntactically correct configuration files. As XML +files are plain text, they can also be manipulated by the expert user using +a text editor. + +The fontconfig document type definition resides in the external entity +(a)samp{fonts.dtd}; this is normally stored in the default font configuration +directory (＠file{/etc/fonts}). Each configuration file should contain the +following structure: + +＠example + <?xml version="1.0"?> + <!DOCTYPE fontconfig SYSTEM "fonts.dtd"> + <fontconfig> + ... + </fontconfig> +＠end example + +＠table ＠samp +＠item <fontconfig> +This is the top level element for a font configuration and can contain +＠samp{<dir>}, ＠samp{<cache>}, ＠samp{<include>}, ＠samp{<match>} and ＠samp{<alias>} elements in any order. + +＠item <dir> +This element contains a directory name which will be scanned for font files +to include in the set of available fonts. The scan does not recurse into +subdirectories. + +＠item <cache> +This element contains a file name for the per-user cache of font +information. If it starts with '~', it refers to a file in the users +home directory. This file is used to hold information about fonts that +isn't present in the per-directory cache files. It is automatically +maintained by the fontconfig library. The default for this file +is ``~/.fonts.cache-<version>'', where <version> is the font configuration +file version number (currently 1). + +＠item <include ignore_missing="no"> +This element contains the name of an additional configuration file. When +the XML datatype is traversed by FcConfigParse, the contents of the file +will also be incorporated into the configuration by passing the filename to +FcConfigLoadAndParse. If 'ignore_missing' is set to "yes" instead of the +default "no", a missing file will elicit no warning message from the library. + +＠item <config> +This element provides a place to consolidate additional configuration +information. ＠samp{<config>} can contain ＠samp{<blank>} and ＠samp{<rescan>} elements in any +order. + +＠item <blank> +Fonts often include "broken" glyphs which appear in the encoding but are +drawn as blanks on the screen. Within the ＠samp{<blank>} element, place each +Unicode characters which is supposed to be blank in an ＠samp{<int>} element. +Characters outside of this set which are drawn as blank will be elided from +the set of characters supported by the font. + +＠item <rescan> +The ＠samp{<rescan>} element holds an ＠samp{<int>} element which indicates the default +interval between automatic checks for font configuration changes. +Fontconfig will validate all of the configuration files and directories and +automatically rebuild the internal datastructures when this interval passes. + +＠item <match target="pattern"> +This element holds first a (possibly empty) list of ＠samp{<test>} elements and then +a (possibly empty) list of ＠samp{<edit>} elements. Patterns which match all of the +tests are subjected to all the edits. If 'target' is set to "font" instead +of the default "pattern", then this element applies to the font name +resulting from a match rather than a font pattern to be matched. + +＠item <test qual="any" name="property" compare="eq"> +This element contains a single value which is compared with the pattern +property "property" (substitute any of the property names seen +above). 'compare' can be one of "eq", "not_eq", "less", "less_eq", "more", or +"more_eq". 'qual' may either be the default, "any", in which case the match +succeeds if any value associated with the property matches the test value, or +"all", in which case all of the values associated with the property must +match the test value. + +＠item <edit name="property" mode="assign" binding="weak"> +This element contains a list of expression elements (any of the value or +operator elements). The expression elements are evaluated at run-time and +modify the property "property". The modification depends on whether +"property" was matched by one of the associated ＠samp{<test>} elements, if so, the +modification may affect the first matched value. Any values inserted into +the property are given the indicated binding. 'mode' is one of: + +＠example +Mode Operation with match Operation without match + +"assign" Replace matching value Replace all values +"assign_replace" Replace all values Replace all values +"prepend" Insert before matching value Insert at head of list +"prepend_first" Insert at head of list Insert at head of list +"append" Append after matching value Append at end of list +"append_last" Append at end of list Append at end of list +＠end example + +＠item <int> +＠itemx <double> +＠itemx <string> +＠itemx <bool> +These elements hold a single value of the indicated type. ＠samp{<bool>} elements +hold either true or false. + +＠item <matrix> + +This element holds the four ＠samp{<double>} elements of an affine transformation. + +＠item <name> +Holds a property name. Evaluates to the first value from the property of +the font, not the pattern. + +＠item <const> +Holds the name of a constant; these are always integers and serve as +symbolic names for common font values: + +＠example +Constant Property CPP symbol + +light weight FC_WEIGHT_LIGHT +medium weight FC_WEIGHT_MEDIUM +demibold weight FC_WEIGHT_DEMIBOLD +bold weight FC_WEIGHT_BOLD +black weight FC_WEIGHT_BLACK +roman slant FC_SLANT_ROMAN +italic slant FC_SLANT_ITALIC +oblique slant FC_SLANT_OBLIQUE +proportional spacing FC_PROPORTIONAL +mono spacing FC_MONO +charcell spacing FC_CHARCELL +unknown rgba FC_RGBA_UNKNOWN +rgb rgba FC_RGBA_RGB +bgr rgba FC_RGBA_BGR +vrgb rgba FC_RGBA_VRGB +vbgr rgba FC_RGBA_VBGR +none rgba FC_RGBA_NONE +＠end example + +＠item <or> +＠itemx <and> +＠itemx <plus> +＠itemx <minus> +＠itemx <times> +＠itemx <divide> +These elements perform the specified operation on a list of expression +elements. ＠samp{<or>} and ＠samp{<and>} are boolean, not bitwise. + +＠item <eq> +＠itemx <not_eq> +＠itemx <less> +＠itemx <less_eq> +＠itemx <more> +＠itemx <more_eq> +These elements compare two values, producing a boolean result. + +＠item <not> +Inverts the boolean sense of its one expression element + +＠item <if> +This element takes three expression elements; if the value of the first is +true, it produces the value of the second, otherwise it produces the value +of the third. + +＠item <alias> +Alias elements provide a shorthand notation for the set of common match +operations needed to substitute one font family for another. They contain a +＠samp{<family>} element followed by optional ＠samp{<prefer>}, ＠samp{<accept>} and ＠samp{<default>} +elements. Fonts matching the ＠samp{<family>} element are edited to prepend the +list of ＠samp{<prefer>}ed families before the matching ＠samp{<family>}, append the +＠samp{<accept>}able families after the matching ＠samp{<family>} and append the ＠samp{<default>} +families to the end of the family list. + +＠item <family> +Holds a single font family name + +＠item <prefer> +＠itemx <accept> +＠itemx <default> +These each hold a list of ＠samp{<family>} elements to be used by the ＠samp{<alias>} +element. +＠end table + +＠menu +* Example System Configuration File:: +* Example User Configuration File:: +＠end menu + +＠node Example System Configuration File, Example User Configuration File, Configuration File Format, Configuration File Format +＠section Example System Configuration File + +This is an example of a system-wide configuration file: + +＠example +<?xml version="1.0"?> +<!DOCTYPE fontconfig SYSTEM "fonts.dtd"> +<!-- /etc/fonts/fonts.conf file to configure system font access --> +<fontconfig> +<!-- + Find fonts in these directories +--> +<dir>/usr/X11R6/lib/X11/fonts/truetype</dir> +<dir>/usr/X11R6/lib/X11/fonts/Type1</dir> + +<!-- + Accept deprecated 'mono' alias, replacing it with 'monospace' +--> +<match target="pattern"> + <test qual="any" name="family"><string>mono</string></test> + <edit name="family" mode="assign"><string>monospace</string></edit> +</match> + +<!-- + Names not including any well known alias are given 'sans' +--> +<match target="pattern"> + <test qual="all" name="family" mode="not_eq">sans</test> + <test qual="all" name="family" mode="not_eq">serif</test> + <test qual="all" name="family" mode="not_eq">monospace</test> + <edit name="family" mode="append_last"><string>sans</string></edit> +</match> + +<!-- + Load per-user customization file, but don't complain + if it doesn't exist +--> +<include ignore_missing="yes">~/.fonts.conf</include> + +<!-- + Alias well known font names to available TrueType fonts. + These substitute TrueType faces for similar Type1 + faces to improve screen appearance. +--> +<alias> + <family>Times</family> + <prefer><family>Times New Roman</family></prefer> + <default><family>serif</family></default> +</alias> +<alias> + <family>Helvetica</family> + <prefer><family>Verdana</family></prefer> + <default><family>sans</family></default> +</alias> +<alias> + <family>Courier</family> + <prefer><family>Courier New</family></prefer> + <default><family>monospace</family></default> +</alias> + +<!-- + Provide required aliases for standard names + Do these after the users configuration file so that + any aliases there are used preferentially +--> +<alias> + <family>serif</family> + <prefer><family>Times New Roman</family></prefer> +</alias> +<alias> + <family>sans</family> + <prefer><family>Verdana</family></prefer> +</alias> +<alias> + <family>monospace</family> + <prefer><family>Andale Mono</family></prefer> +</alias> +</fontconfig> +＠end example + +＠node Example User Configuration File, , Example System Configuration File, Configuration File Format +＠section Example User Configuration File + +This is an example of a per-user configuration file that lives in +(a)file{~/.fonts.conf}: + +＠example +<?xml version="1.0"?> +<!DOCTYPE fontconfig SYSTEM "fonts.dtd"> +<!-- ~/.fonts.conf for per-user font configuration --> +<fontconfig> + +<!-- + Private font directory +--> +<dir>~/misc/fonts</dir> + +<!-- + use rgb sub-pixel ordering to improve glyph appearance on + LCD screens. Changes affecting rendering, but not matching, + should always use target="font". +--> +<match target="font"> + <edit name="rgba" mode="assign"><const>rgb</const></edit> +</match> +</fontconfig> +＠end example + +＠node Files, Authors, Configuration File Format, Top +＠chapter Files + +＠table ＠file +＠item fonts.dtd +is a DTD that describes the format of the configuration files. + +＠item fonts.conf +is the default system-wide font configuration file. It +contains configuration information for the fontconfig library +consisting of directories to look at for font information as well as +instructions on editing program specified font patterns before attempting to +match the available fonts. It is in xml format, with DTD ＠file{fonts.dtd}. + +＠item local.conf +is the conventional default location for local font configuration. It +is sourced by the default system-wide fonts.conf file. +Note that the normal 'make install' procedure for XFree86 is to +replace any existing fonts.conf file with the new version. Place +any local customizations in local.conf which this file references. +It is in xml format, with DTD ＠file{fonts.dtd}. + +＠item ~/.fonts.conf +is the conventional location for per-user font configuration, although the +actual location is specified in the global fonts.conf file. +It is in xml format, with DTD ＠file{fonts.dtd}. + +＠item fonts.cache-* +is found in each font directory where fonts were found. This file is +automatically maintained by fontconfig. It is a flat text table, and +should be treated as opaque. + +＠item ~/.fonts.cache-* +is the conventional repository of font information that isn't found in the +per-directory caches. This file is automatically maintained by fontconfig. +It is a flat text table, and should be treated as opaque. +＠end table + +＠node Authors, , Files, Top +＠chapter Authors + +＠table ＠strong +＠item Keith Packard +member of the XFree86 Project, Inc. + +＠item Stephen J. Turnbull +member of the XEmacs Project +＠end table + +＠bye + +＠c Local variables: +＠c mode: texinfo +＠c End: + +＠c arch-tag: 108A3E8B-1CE1-11D9-9957-000A959E994E + +＠c end of fontconfig.texi -- Institute of Policy and Planning Sciences http://turnbull.sk.tsukuba.ac.jp University of Tsukuba Tennodai 1-1-1 Tsukuba 305-8573 JAPAN Ask not how you can "do" free software business; ask what your business can "do for" free software.