3 @c This @setfilename tells makeinfo to DTRT for the *installed* .texi file.
4 @setfilename fontconfig.info
5 @settitle Fontconfig: Font configuration and customization library
7 @set synched-to-pkg-version 1.0
8 @set synched-to-doc-versions Package: @value{synched-to-package-version}
9 @set last-released-month-year October 2003
10 @set last-released-date 20 October 2003
12 @footnotestyle separate
16 @dircategory Permissively licensed documentation
18 * fontconfig:: Managing font metainformation.
21 @setchapternewpage odd
23 @shorttitlepage Fontconfig
27 @subtitle Font configuration and customization library
28 @subtitle A Rendering-Engine-Independent Library
29 @subtitle for Managing Font Metainformation
32 @author Stephen J. Turnbull
37 @node Top, Copying, (dir), (dir)
40 This file documents fontconfig, a rendering-engine-independent library
41 for managing font metainformation (@emph{i.e.}, everything but the glyph
42 data themselves). It is @emph{not} part of XEmacs.
44 Copyright © 2002 Keith Packard, member of The XFree86 Project, Inc.
45 Copyright © 2003 Stephen J. Turnbull, member of the XEmacs Project
47 In the following notice, the term "Authors" refers to the copyright
48 holders listed above, and "Documentation" refers to this version of the
49 documentation supplied by Keith Packard, as adapted to Texinfo by
50 Stephen J. Turnbull. The fontconfig library itself and the original
51 documentation are covered by a similar license.
53 Permission to use, copy, modify, distribute, and sell this Documentation
54 for any purpose is hereby granted without fee, provided that the above
55 copyright notice appear in all copies and that both that copyright
56 notice and this permission notice appear in copies of the Documentation,
57 and that the names of the Authors not be used in advertising or
58 publicity pertaining to distribution of the Documentation without
59 specific, written prior permission. The Authors make no representations
60 about the suitability of this Documentation for any purpose. It is
61 provided "as is" without express or implied warranty.
63 THE AUTHORS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS DOCUMENTATION,
64 INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
65 EVENT SHALL THE AUTHORS BE LIABLE FOR ANY SPECIAL, INDIRECT OR
66 CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
67 DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
68 TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
69 PERFORMANCE OF THIS DOCUMENTATION.
71 @c I believe that this document can legally be distributed under the
72 @c above permission. rms's opinion is that there is nothing left of
73 @c `texinfo.tex' after processing this document, and therefore nothing
74 @c forces this document to be distributed under GPL.
76 @c The original permissively licensed document may be obtained in
77 @c distributions of the fontconfig library available from the CVS
78 @c repository of the XFree86 Project in module xc/extra/fontconfig.
85 * The fontconfig API::
86 * Configuration File Format::
91 --- The Detailed Node Listing ---
95 * Font Configuration::
98 * Font List Matching::
116 * Querying Fonts and Their Properties::
119 * FreeType-Specific Functions::
120 * XML-Specific Functions::
121 * File and Directory Routines::
122 * FcStrSet and FcStrList::
125 Configuration File Format
127 * Example System Configuration File::
128 * Example User Configuration File::
133 @node Copying, Overview, Top, Top
136 The fontconfig library and the accompanying documentation are covered by
137 the following copyright notice and license, except for this Texinfo
138 version which has additional authors but is otherwise substantially the
141 Copyright © 2002 Keith Packard, member of The XFree86 Project, Inc.
143 Permission to use, copy, modify, distribute, and sell this software and its
144 documentation for any purpose is hereby granted without fee, provided that
145 the above copyright notice appear in all copies and that both that
146 copyright notice and this permission notice appear in supporting
147 documentation, and that the name of Keith Packard not be used in
148 advertising or publicity pertaining to distribution of the software without
149 specific, written prior permission. Keith Packard makes no
150 representations about the suitability of this software for any purpose. It
151 is provided "as is" without express or implied warranty.
153 KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
154 INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
155 EVENT SHALL KEITH PACKARD BE LIABLE FOR ANY SPECIAL, INDIRECT OR
156 CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
157 DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
158 TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
159 PERFORMANCE OF THIS SOFTWARE.
161 @node Overview, The fontconfig API, Copying, Top
165 Fontconfig is a library designed to provide system-wide font
166 configuration, customization and application access.
168 This manual describes fontconfig version 1.0.2.
170 @c FUNCTIONAL OVERVIEW
171 Fontconfig contains two essential modules, the configuration module which
172 builds an internal configuration from XML files and the matching module
173 which accepts font patterns and returns the nearest matching font.
176 * Font Configuration::
179 * Font List Matching::
184 @node Font Configuration, Font Properties, Overview, Overview
185 @section Font Configuration
187 The configuration module consists of the FcConfig datatype, libexpat and
188 FcConfigParse which walks over an XML tree and amends a configuration with
189 data found within. From an external perspective, configuration of the
190 library consists of generating a valid XML tree and feeding that to
191 FcConfigParse. The only other mechanism provided to applications for
192 changing the running configuration is to add fonts and directories to the
193 list of application-provided font files.
195 The intent is to make font configuration relatively static, and shared by
196 as many applications as possible. It is hoped that this will lead to more
197 stable font selection when passing names from one application to another.
198 XML was chosen as a configuration file format because it provides a format
199 which is easy for external agents to edit while retaining the correct
200 structure and syntax.
202 Font configuration is separate from font matching; applications needing to
203 do their own matching can access the available fonts from the library and
204 perform private matching. The intent is to permit applications to pick and
205 choose appropriate functionality from the library instead of forcing them to
206 choose between this library and a private configuration mechanism. The hope
207 is that this will ensure that configuration of fonts for all applications
208 can be centralized in one place. Centralizing font configuration will
209 simplify and regularize font installation and customization.
211 @node Font Properties, Font Matching, Font Configuration, Overview
212 @section Font Properties
214 While font patterns may contain essentially any properties, there are some
215 well known properties with associated types. Fontconfig uses some of these
216 properties for font matching and font completion. Others are provided as a
217 convenience for the applications rendering mechanism. Some symbolic
218 constants are provided for common values or enumerated types.
219 @xref{Constants}, for the list of standard properties and values.
222 @node Font Matching, Font List Matching, Font Properties, Overview
223 @section Font Matching
225 Fontconfig performs matching by measuring the distance from a provided
226 pattern to all of the available fonts in the system. The closest matching
227 font is selected. This ensures that a font will always be returned, but
228 doesn't ensure that it is anything like the requested pattern.
230 Font matching starts with an application constructed pattern. The desired
231 attributes of the resulting font are collected together in an FcPattern
232 object. Each property of the pattern can contain one or more values; these
233 are listed in priority order; matches earlier in the list are considered
234 "closer" than matches later in the list.
236 The initial pattern is modified by applying the list of editing instructions
237 specific to patterns found in the configuration; each consists of a match
238 predicate and a set of editing operations. They are executed in the order
239 they appeared in the configuration. Each match causes the associated
240 sequence of editing operations to be applied.
242 After the pattern has been edited, a sequence of default substitutions are
243 performed to canonicalize the set of available properties; this avoids the
244 need for the lower layers to constantly provide default values for various
245 font properties during rendering.
247 The canonical font pattern is finally matched against all available fonts.
248 The distance from the pattern to the font is measured for each of several
249 properties: foundry, charset, family, lang, spacing, pixelsize, style,
250 slant, weight, antialias, rasterizer and outline. This list is in priority
251 order---results of comparing earlier elements of this list weigh more
252 heavily than later elements.
254 There is one special case to this rule; family names are split into two
255 bindings; strong and weak. Strong family names are given greater precedence
256 in the match than lang elements while weak family names are given lower
257 precedence than lang elements. This permits the document language to drive
258 font selection when any document specified font is unavailable.
260 The pattern representing that font is augmented to include any properties
261 found in the pattern but not found in the font itself; this permits the
262 application to pass rendering instructions or any other data through the
263 matching system. Finally, the list of editing instructions specific to
264 fonts found in the configuration are applied to the pattern. This modified
265 pattern is returned to the application.
267 The return value contains sufficient information to locate and rasterize the
268 font, including the file name, pixel size and other rendering data. As
269 none of the information involved pertains to the FreeType library,
270 applications are free to use any rasterization engine or even to take
271 the identified font file and access it directly.
273 The match/edit sequences in the configuration are performed in two passes
274 because there are essentially two different operations necessary -- the
275 first is to modify how fonts are selected; aliasing families and adding
276 suitable defaults. The second is to modify how the selected fonts are
277 rasterized. Those must apply to the selected font, not the original pattern
278 as false matches will often occur.
280 @node Font List Matching, Font Names, Font Matching, Overview
281 @section Font List Matching
283 While many applications want to locate a single font best matching their
284 search criteria, other applications need to build a set of fonts which can
285 be used to present any Unicode data. Fontconfig provides an API to generate
286 a list sorted by the nearness of each font to the pattern. Every font in
287 the system is considered, the best matching fonts are placed first. The
288 application then can select whether the remaining fonts are unconditionally
289 included in the list, or whether they are included only if they cover
290 portions of Unicode not covered by any of the preceeding fonts.
292 The list resulting from this match is represented by references to the
293 original font patterns and so consumes very little memory. Using a list
294 entry involves creating a pattern which combines the information from the
295 font with the information from the original pattern and executing the font
298 @node Font Names, LANG Tags, Font List Matching, Overview
301 Fontconfig provides a textual representation for patterns that the library
302 can both accept and generate. The representation is in three parts, first a
303 list of family names, second a list of point sizes and finally a list of
304 additional properties:
307 <families>-<point sizes>:<name1>=<values1>:<name2>=<values2>...
310 Values in a list are separated with commas. A hyphen or comma in a family
311 name must be escaped with a backslash. The name needn't include either
312 families or point sizes; they can be elided. If the family name only is
313 given, the hyphen may be omitted. If there are no additional properties,
314 no trailing colon should be used. In addition, there are
315 symbolic constants that simultaneously indicate both a name and a value.
316 Here are some examples:
319 Times-12 12 point Times Roman
320 Times-12:bold 12 point Times Bold
321 Courier:italic Courier Italic in the default size
322 Monospace:matrix=1 .1 0 1 The users preferred monospace font
323 with artificial obliquing
324 Mikachan\-PB-16 12 point Mikachan-PB
327 @node LANG Tags, , Font Names, Overview
330 Each font in the database contains a list of languages it supports. This is
331 computed by comparing the Unicode coverage of the font with the orthography
332 of each language. Languages are tagged using an RFC-3066 compatible naming
333 and occur in two parts -- the ISO639 language tag followed a hyphen and then
334 by the ISO 3166 country code. The hyphen and country code may be elided.
336 Fontconfig has orthographies for several languages built into the library.
337 No provision has been made for adding new ones aside from rebuilding the
338 library. It currently supports 122 of the 139 languages named in ISO 639-1,
339 141 of the languages with two-letter codes from ISO 639-2 and another 30
340 languages with only three-letter codes.
342 @node The fontconfig API, Configuration File Format, Overview, Top
343 @chapter The fontconfig API
346 #include <fontconfig/fontconfig.h>
347 #include <fontconfig/fcfreetype.h>
356 @node Constants, Data Types, The fontconfig API, The fontconfig API
358 While fontconfig is designed to be extensible, it provides a comprehensive
359 set of standard properties and values for fonts.
361 The following table gives the list of standard font properties. The property
362 name is represented as a string. In C code a C preprocessor symbol may be
363 used to help with typo detection.
366 Property CPP symbol Type Description
368 family FC_FAMILY String Font family name
369 style FC_STYLE String Font style. Overrides weight and slant
370 slant FC_SLANT Int Italic, oblique or roman
371 weight FC_WEIGHT Int Light, medium, demibold, bold or black
372 size FC_SIZE Double Point size
373 aspect FC_ASPECT Double Stretch glyphs horizontally, then hint
374 pixelsize FC_PIXEL_SIZE Double Pixel size
375 spacing FC_SPACING Int Proportional, monospace or charcell
376 foundry FC_FOUNDRY String Font foundry name
377 antialias FC_ANTIALIAS Bool Should glyphs be antialiased?
378 hinting FC_HINTING Bool Should the rasterizer use hinting?
379 verticallayout FC_VERTICAL_LAYOUT Bool Use vertical layout
380 autohint FC_AUTOHINT Bool Use autohinter instead of normal hinter
381 globaladvance FC_GLOBAL_ADVANCE Bool Use font global advance data
382 file FC_FILE String The filename holding the font
383 index FC_INDEX Int The index of the font within the file
384 ftface FC_FT_FACE FT_Face Use the specified FreeType face object
385 rasterizer FC_RASTERIZER String Which rasterizer is in use
386 outline FC_OUTLINE Bool Whether the glyphs are outlines
387 scalable FC_SCALABLE Bool Whether glyphs can be scaled
388 scale FC_SCALE Double Point->pixel conversion scale factor
389 dpi FC_DPI Double Target dots per inch
390 rgba FC_RGBA Int unknown, rgb, bgr, vrgb, vbgr, none
392 source FC_SOURCE String X11, freetype
393 minspace FC_MINSPACE Bool Eliminate leading from line spacing
394 charset FC_CHARSET CharSet Unicode chars encoded by the font
395 lang FC_LANG String List of RFC-3066-style languages
397 fontversion FC_FONTVERSION Int From 'head' table
400 C code can check the fontconfig version number with the numerical
401 preprocessor constants @code{FC_MAJOR}, @code{FC_MINOR}, and
402 @code{FC_REVISION}, or use the combined constant @code{FC_VERSION}, defined
403 as @code{FC_MAJOR*10000 + FC_MINOR*100 + FC_REVISION}.
405 @c fontconfig.h details what FC_CACHE_VERSION is, exactly.
406 The cache version is given by @code{FC_CACHE_VERSION}, and is a string, not
407 an integer. This is normally appended to the end of the cache file name, so
408 multiple versions of fontconfig can peacefully co-exist. The cache file
409 names are defined as @code{FC_DIR_CACHE_FILE} and @code{FC_USER_CACHE_FILE}.
411 The Boolean constants are @code{FcFalse} (0) and @code{FcTrue} (1).
413 Properties used to control the rasterizer, their preprocessor constants, and
414 their types, include:
417 charwidth FC_CHAR_WIDTH Int
418 charheight FC_CHAR_HEIGHT Int
419 matrix FC_MATRIX FcMatrix
422 Preprocessor constants are defined for common standard font weights. All are
428 FC_WEIGHT_DEMIBOLD 180
433 Preprocessor constants are defined for common standard slants. All are Ints.
441 Preprocessor constants are defined for the three spacing types. All are
442 Ints, but should be treated as symbolic constants.
450 Preprocessor constants are defined for the subpixel orders. All are
451 Ints, but should be treated as symbolic constants.
463 @node Data Types, Functions, Constants, The fontconfig API
471 These are primitive data types; the FcChar* types hold precisely the number
472 of bits stated (if supported by the C implementation). FcBool holds
473 one of two CPP symbols: FcFalse or FcTrue.
476 An FcMatrix holds an affine transformation, usually used to reshape glyphs.
477 A small set of matrix operations are provided to manipulate these.
480 typedef struct _FcMatrix @{
481 double xx, xy, yx, yy;
486 An FcCharSet is an abstract type that holds the set of encoded unicode chars
487 in a font. Operations to build and compare these sets are provided.
490 Tags the kind of data stored in an FcValue.
493 An FcValue object holds a single value with one of a number of different
494 types. The 'type' tag indicates which member is valid.
497 typedef struct _FcValue @{
514 type Union member Datatype
516 FcTypeVoid (none) (none)
518 FcTypeDouble d double
519 FcTypeString s TcChar8 *
521 FcTypeMatrix m FcMatrix *
522 FcTypeCharSet c FcCharSet *
523 FcTypeFTFace f void *
525 FcTypeLangSet l FcLangSet *
529 holds a set of names with associated value lists; each name refers to a
530 property of a font. FcPatterns are used as inputs to the matching code as
531 well as holding information about specific fonts. Each property can hold
532 one or more values; conventionally all of the same type, although the
533 interface doesn't demand that.
538 typedef struct _FcFontSet @{
545 An FcFontSet contains a list of FcPatterns. Internally fontconfig uses this
546 data structure to hold sets of fonts. Externally, fontconfig returns the
547 results of listing fonts in this format. 'nfont' holds the number of
548 patterns in the 'fonts' array; 'sfont' is used to indicate the size of that
553 FcStrSet holds a list of strings that can be appended to and enumerated.
554 Its unique characteristic is that the enumeration works even while strings
555 are appended during enumeration. FcStrList is used during enumeration to
556 safely and correctly walk the list of strings even while that list is edited
557 in the middle of enumeration.
562 typedef struct _FcObjectSet @{
565 const char **objects;
568 holds a set of names and is used to specify which fields from fonts are
569 placed in the the list of returned patterns when listing fonts.
574 typedef struct _FcObjectType @{
579 marks the type of a pattern element generated when parsing font names.
580 Applications can add new object types so that font names may contain the new
586 typedef struct _FcConstant @{
592 Provides for symbolic constants for new pattern elements. When 'name' is
593 seen in a font name, an 'object' element is created with value 'value'.
596 holds a list of Unicode chars which are expected to be blank; unexpectedly
597 blank chars are assumed to be invalid and are elided from the charset
598 associated with the font.
601 holds the per-user cache information for use while loading the font
602 database. This is built automatically for the current configuration when
603 that is loaded. Applications must always pass '0' when one is requested.
606 holds a complete configuration of the library; there is one default
607 configuration, other can be constructed from XML data structures. All
608 public entry points that need global data can take an optional FcConfig*
609 argument; passing 0 uses the default configuration. FcConfig objects hold two
610 sets of fonts, the first contains those specified by the configuration, the
611 second set holds those added by the application at run-time. Interfaces
612 that need to reference a particulat set use one of the FcSetName enumerated
616 Specifies one of the two sets of fonts available in a configuration;
617 FcSetSystem for those fonts specified in the configuration and
618 FcSetApplication which holds fonts provided by the application.
621 Used as a return type for functions manipulating FcPattern objects.
625 FcResultMatch Object exists with the specified ID
626 FcResultNoMatch Object doesn't exist at all
627 FcResultTypeMismatch Object exists, but the type doesn't match
628 FcResultNoId Object exists, but has fewer values than specified
632 Used for locking access to config files. Provides a safe way to update
636 An enumeration containing @code{FcMatchPattern} and @code{FcMatchFont}.
639 An enumeration containing @code{FcLangEqual}, @code{FcLangDifferentCountry},
640 and @code{FcLangDifferentLang}. Presumably @code{FcLangDifferentLang}
641 implies @code{FcLangDifferentCountry}.
644 An enumeration containing @code{FcSetSystem} and @code{FcSetApplication}.
647 An enumeration containing @code{FcEndianBig} and @code{FcEndianLittle}.
650 @node Functions, , Data Types, The fontconfig API
662 * Querying Fonts and Their Properties::
665 * FreeType-Specific Functions::
666 * XML-Specific Functions::
667 * File and Directory Routines::
668 * FcStrSet and FcStrList::
672 @node FcMatrix, FcCharSet, Functions, Functions
675 FcMatrix structures hold an affine transformation in matrix form.
678 #define FcMatrixInit(m) ((m)->xx = (m)->yy = 1, (m)->xy = (m)->yx = 0)
680 Initializes a matrix to the identify transformation.
682 @deftypefun {FcMatrix *} FcMatrixCopy (const FcMatrix *@var{mat})
684 Allocates a new FcMatrix and copies 'mat' into it.
687 @deftypefun FcBool FcMatrixEqual (const FcMatrix *@var{mat1}, const FcMatrix *var{mat2})
689 Returns FcTrue if 'mat1' and 'mat2' are equal, else FcFalse.
692 @deftypefun void FcMatrixMultiply (FcMatrix *@var{result}, const FcMatrix *@var{a}, const FcMatrix *var{b})
694 Multiplies 'a' and 'b' together, placing the result in 'result'. 'result'
695 may refer to the same matrix as either 'a' or 'b'.
698 @deftypefun void FcMatrixRotate (FcMatrix *m, double c, double s)
700 If 'c' is cos(angle) and 's' is sin(angle), FcMatrixRotate rotates the
704 @deftypefun void FcMatrixScale (FcMatrix *m, double sx, double sy)
706 Scales 'm' by 'sx' in the horizontal dimension and 'sy' in the
710 @deftypefun void FcMatrixShear (FcMatrix *m, double sh, double sv)
711 Shears 'm' by 'sh' in the horizontal direction and 'sv' in the
715 @node FcCharSet, FcValue, FcMatrix, Functions
716 @subsection FcCharSet
718 An FcCharSet is a boolean array indicating a set of unicode chars. Those
719 associated with a font are marked constant and cannot be edited.
720 FcCharSets may be reference counted internally to reduce memory consumption;
721 this may be visible to applications as the result of FcCharSetCopy may
722 return its argument, and that CharSet may remain unmodifiable.
724 When represented as a string, an FcCharSet is not a pure bitmap; octet
725 values are limited such that FcCharSet objects, when printed, are valid
728 @deftypefun {FcCharSet *} FcCharSetCreate (void)
730 Creates an empty FcCharSet object.
733 @deftypefun void FcCharSetDestroy (FcCharSet *fcs)
735 Frees an FcCharSet object.
738 @deftypefun FcBool FcCharSetAddChar (FcCharSet *fcs, FcChar32 ucs4)
740 Adds a single unicode char to the set, returning FcFalse on
741 failure, either as a result of a constant set or from running out of memory.
744 @deftypefun {FcCharSet *} FcCharSetCopy (FcCharSet *src)
746 Makes a copy of 'src'; note that this may not actually do anything more than
747 increment the reference count on 'src'.
750 @deftypefun FcBool FcCharSetEqual (const FcCharSet *a, const FcCharSet *b)
752 Returns whether 'a' and 'b' contain the same set of unicode chars.
755 @deftypefun {FcCharSet *} FcCharSetIntersect (const FcCharSet *a, const FcCharSet *b)
757 Returns a set including only those chars found in both 'a' and 'b'.
760 @deftypefun {FcCharSet *} FcCharSetUnion (const FcCharSet *a, const FcCharSet *b);
762 Returns a set including only those chars found in either 'a' or 'b'.
765 @deftypefun {FcCharSet *} FcCharSetSubtract (const FcCharSet *a, const FcCharSet *b)
767 Returns a set including only those chars found in 'a' but not 'b'.
770 @deftypefun FcBool FcCharSetHasChar (const FcCharSet *fcs, FcChar32 ucs4)
772 Returns whether 'fcs' contains the char 'ucs4'.
775 @deftypefun FcChar32 FcCharSetCount (const FcCharSet *a)
777 Returns the total number of unicode chars in 'a'.
780 @deftypefun FcChar32 FcCharSetIntersectCount (const FcCharSet *a, const FcCharSet *b)
782 Returns the number of chars that are in both 'a' and 'b'.
785 @deftypefun FcChar32 FcCharSetSubtractCount (const FcCharSet *a, const FcCharSet *b)
787 Returns the number of chars that are in 'a' but not in 'b'.
790 @deftypefun FcBool FcCharSetIsSubset (const FcCharSet *a, const FcCharSet *b)
792 Returns whether 'a' is a subset of 'b'.
795 @deftypefun FcChar32 FcCharSetFirstPage (const FcCharSet *a, FcChar32 [FC_CHARSET_MAP_SIZE], FcChar32 *next)
797 Builds an array of bits marking the first page of Unicode coverage of 'a'.
798 Returns the base of the array. 'next' contains the next page in the font.
801 @deftypefun FcChar32 FcCharSetNextPage (const FcCharSet *a, FcChar32 [FC_CHARSET_MAP_SIZE], FcChar32 *next)
803 Builds an array of bits marking the Unicode coverage of 'a' for page '*next'.
804 Returns the base of the array. 'next' contains the next page in the font.
807 @node FcValue, FcPattern, FcCharSet, Functions
810 FcValue is a structure containing a type tag and a union of all possible
811 data types. The tag is an enum of type FcType and is intended to provide
812 a measure of run-time typechecking, although that depends on careful
815 @deftypefun void FcValueDestroy (FcValue v)
817 Frees any memory referenced by `v'. Values of type FcTypeString,
818 FcTypeMatrix and FcTypeCharSet reference memory, the other types do not.
821 @deftypefun FcValue FcValueSave (FcValue v)
823 Returns a copy of `v' duplicating any object referenced by it so that `v'
824 may be safely destroyed without harming the new value.
827 @deftypefun void FcValuePrint (const FcValue v)
829 Prints an easily readable version of the value to stdout. There is
830 no provision for reparsing data in this format, it's just for diagnostics
835 @node FcPattern, FcFontSet, FcValue, Functions
836 @subsection FcPattern
838 An FcPattern is an opaque type that holds both patterns to match against the
839 available fonts, as well as the information about each font.
841 @deftypefun {FcPattern *} FcPatternCreate (void)
843 Creates a pattern with no properties; used to build patterns from scratch.
846 @deftypefun void FcPatternDestroy (FcPattern *p)
848 Destroys a pattern, in the process destroying all related values.
851 @deftypefun FcBool FcPatternEqual (const FcPattern *pa, const FcPattern *pb);
853 Returns whether 'pa' and 'pb' are exactly alike.
856 @deftypefun FcBool FcPatternEqualSubset (const FcPattern *pa, const FcPattern *pb, const FcObjectSet *os)
858 Returns whether 'pa' and 'pb' have exactly the same values for all of the
862 @deftypefun FcChar32 FcPatternHash (const FcPattern *p)
864 Returns a 32-bit number which is the same for any two patterns which are
868 @deftypefun FcBool FcPatternAdd (FcPattern *p, const char *object, FcValue value, FcBool append)
870 Adds a single value to the list of values associated with the property named
871 `object'. If `append' is FcTrue, the value is added at the end of any
872 existing list, otherwise it is inserted at the begining. `value' is saved
873 (with FcValueSave) when inserted into the pattern so that the library
874 retains no reference to any application-supplied data structure.
877 @deftypefun FcBool FcPatternAddWeak (FcPattern *p, const char *object, FcValue value, FcBool append)
879 FcPatternAddWeak is essentially the same as FcPatternAdd except that any
880 values added to the list have binding 'weak' instead of 'strong'.
883 @deftypefun FcBool FcPatternAddInteger (FcPattern *p, const char *object, int i)
884 @deftypefunx FcBool FcPatternAddDouble (FcPattern *p, const char *object, double d)
885 @deftypefunx FcBool FcPatternAddString (FcPattern *p, const char *object, const char *s)
886 @deftypefunx FcBool FcPatternAddMatrix (FcPattern *p, const char *object, const FcMatrix *s)
887 @deftypefunx FcBool FcPatternAddCharSet (FcPattern *p, const char *object, const FcCharSet *c)
888 @deftypefunx FcBool FcPatternAddBool (FcPattern *p, const char *object, FcBool b)
890 These are all convenience functions that insert objects of the specified
891 type into the pattern. Use these in preference to FcPatternAdd as they
892 will provide compile-time typechecking. These all append values to
893 any existing list of values.
896 @deftypefun FcResult FcPatternGet (FcPattern *p, const char *object, int id, FcValue *v)
898 Returns in `v' the `id'th value associated with the property `object'.
899 The value returned is not a copy, but rather refers to the data stored
900 within the pattern directly. Applications must not free this value.
903 @deftypefun FcResult FcPatternGetInteger (FcPattern *p, const char *object, int id, int *i);
904 @deftypefunx FcResult FcPatternGetDouble (FcPattern *p, const char *object, int id, double *d);
905 @deftypefunx FcResult FcPatternGetString (FcPattern *p, const char *object, int id, char **const s);
906 @deftypefunx FcResult FcPatternGetMatrix (FcPattern *p, const char *object, int id, FcMatrix **s);
907 @deftypefunx FcResult FcPatternGetCharSet (FcPattern *p, const char *object, int id, FcCharSet **c);
908 @deftypefunx FcResult FcPatternGetBool (FcPattern *p, const char *object, int id, FcBool *b);
910 These are convenience functions that call FcPatternGet and verify that the
911 returned data is of the expected type. They return FcResultTypeMismatch if
912 this is not the case. Note that these (like FcPatternGet) do not make a
913 copy of any data structure referenced by the return value. Use these
914 in preference to FcPatternGet to provide compile-time typechecking.
917 @deftypefun {FcPattern *} FcPatternBuild (FcPattern *orig, ...);
918 @deftypefunx FcPattern *FcPatternVaBuild (FcPattern *orig, va_list va)
920 Builds a pattern using a list of objects, types and values. Each
921 value to be entered in the pattern is specified with three arguments:
924 Object name, a string describing the property to be added.
926 Object type, one of the FcType enumerated values
928 Value, not an FcValue, but the raw type as passed to any of the
929 FcPatternAdd<type> functions. Must match the type of the second
933 The argument list is terminated by a null object name, no object type nor
934 value need be passed for this. The values are added to `pattern', if
935 `pattern' is null, a new pattern is created. In either case, the pattern is
939 pattern = FcPatternBuild (0, FC_FAMILY, FtTypeString, "Times", (char *) 0);
942 FcPatternVaBuild is used when the arguments are already in the form of a
946 @deftypefun FcBool FcPatternDel (FcPattern *p, const char *object)
948 Deletes all values associated with the property `object', returning
949 whether the property existed or not.
952 @deftypefun void FcPatternPrint (const FcPattern *p)
954 Prints an easily readable version of the pattern to stdout. There is
955 no provision for reparsing data in this format, it's just for diagnostics
959 @deftypefun void FcDefaultSubstitute (FcPattern *pattern)
961 Supplies default values for underspecified font patterns:
964 Patterns without a specified style or weight are set to Medium
966 Patterns without a specified style or slant are set to Roman
968 Patterns without a specified pixel size are given one computed from
969 any specified point size (default 12), dpi (default 75) and scale (default
974 @deftypefun {FcPattern *} FcNameParse (const char *name)
976 Converts 'name' from the standard text format described above into a pattern.
979 @deftypefun FcChar8 *FcNameUnparse (FcPattern *pat)
981 Converts the given pattern into the standard text format described above.
982 The return value is not static, but instead refers to newly allocated memory
983 which should be freed by the caller.
986 @node FcFontSet, FcObjectSet, FcPattern, Functions
987 @subsection FcFontSet
989 An FcFontSet simply holds a list of patterns; these are used to return the
990 results of listing available fonts.
992 @deftypefun FcFontSet *FcFontSetCreate (void)
994 Creates an empty font set.
997 @deftypefun void FcFontSetDestroy (FcFontSet *s);
999 Destroys a font set. Note that this destroys any referenced patterns as
1003 @deftypefun FcBool FcFontSetAdd (FcFontSet *s, FcPattern *font)
1005 Adds a pattern to a font set. Note that the pattern is not copied before
1006 being inserted into the set.
1009 @deftypefun void FcFontSetPrint (const FcFontSet *s)
1011 Prints an easily readable version of the font set to stdout. There is
1012 no provision for reparsing data in this format, it's just for diagnostics
1017 @node FcObjectSet, FcObjectType, FcFontSet, Functions
1018 @subsection FcObjectSet
1020 An FcObjectSet holds a list of pattern property names; it is used to
1021 indicate which properties are to be returned in the patterns from
1024 @deftypefun FcObjectSet *FcObjectSetCreate (void)
1026 Creates an empty set.
1029 @deftypefun FcBool FcObjectSetAdd (FcObjectSet *os, const char *object)
1031 Adds a property name to the set.
1034 @deftypefun void FcObjectSetDestroy (FcObjectSet *os)
1036 Destroys an object set.
1039 @deftypefun FcObjectSet *FcObjectSetBuild (const char *first, ...)
1040 @deftypefunx FcObjectSet *FcObjectSetVaBuild (const char *first, va_list va)
1042 These build an object set from a null-terminated list of property names.
1045 @node FcObjectType, FcLangSet, FcObjectSet, Functions
1046 @subsection FcObjectType
1048 Provides for application-specified font name object types so that new
1049 pattern elements can be generated from font names.
1051 @deftypefun FcBool FcNameRegisterObjectTypes (const FcObjectType *types, int ntype)
1053 Register 'ntype' new object types.
1056 @deftypefun FcBool FcNameUnregisterObjectTypes (const FcObjectType *types, int ntype)
1058 Unregister 'ntype' object types.
1061 @deftypefun const FcObjectType *FcNameGetObjectType (const char *object)
1063 Return the object type for the pattern element named 'object'.
1068 Provides for application-specified symbolic constants for font names.
1070 @deftypefun FcBool FcNameRegisterConstants (const FcConstant *consts, int nconsts)
1072 Register 'nconsts' new symbolic constants.
1075 @deftypefun FcBool FcNameUnregisterConstants (const FcConstant *consts, int nconsts)
1077 Unregister 'nconsts' symbolic constants.
1080 @deftypefun const FcConstant *FcNameGetConstant (FcChar8 *string)
1082 Return the FcConstant structure related to symbolic constant 'string'.
1085 @deftypefun FcBool FcNameConstant (FcChar8 *string, int *result)
1087 Returns whether a symbolic constant with name 'string' is registered,
1088 placing the value of the constant in 'result' if present.
1092 @node FcLangSet, Querying Fonts and Their Properties, FcObjectType, Functions
1093 @subsection FcLangSet
1095 An @code{FcLangSet} holds a set of RFC 3066 language tags, @ref{LANG Tags}.
1096 This module provides functions to determine whether a given language is
1097 fully supported by a font. Partial support can be determined using the
1098 font's character set, @ref{FcCharSet}.
1100 @deftypefun FcLangSet *FcLangSetCreate (void);
1102 Create an empty @code{FcLangSet}.
1105 @deftypefun void FcLangSetDestroy (FcLangSet *ls);
1107 Destroy a @code{FcLangSet}, freeing any associated storage.
1110 @deftypefun FcLangSet *FcLangSetCopy (const FcLangSet *ls);
1112 Copy @var{ls} to a newly allocated @code{FcLangSet}.
1115 @deftypefun FcBool FcLangSetAdd (FcLangSet *ls, const FcChar8 *lang);
1117 Add @var{lang} to @code{FcLangSet} @var{ls}.
1120 @deftypefun FcLangResult FcLangSetHasLang (const FcLangSet *ls, const FcChar8 *lang);
1122 Check whether @var{lang} is a member of @code{FcLangSet} @var{ls}. Note that
1123 the return value is a @code{FcLangResult}, not a Boolean.
1126 @deftypefun FcLangResult FcLangSetCompare (const FcLangSet *lsa, const FcLangSet *lsb);
1127 @c The actual code isn't remotely clear either. And I suspect it's buggy;
1128 @c cf this in FcLangSetEqual:
1130 @c for (i = 0; i < NUM_LANG_SET_MAP; i++)
1132 @c if (lsa->map[i] != lsb->map[i])
1136 @c vs. this in FcLangSetCompare:
1138 @c for (i = 0; i < NUM_LANG_SET_MAP; i++)
1139 @c if (lsa->map[i] & lsb->map[i])
1140 @c return FcLangEqual;
1145 @deftypefun FcBool FcLangSetEqual (const FcLangSet *lsa, const FcLangSet *lsb);
1147 Check whether the @code{FcLangSet}s @var{lsa} and @var{lsb} contain the same
1151 @deftypefun FcChar32 FcLangSetHash (const FcLangSet *ls);
1153 Return a hash value; two @code{FcLangSet}s which hash to different values
1154 cannot contain the same members.
1158 @node Querying Fonts and Their Properties, Initialization, FcLangSet, Functions
1159 @subsection Querying Fonts and Their Properties
1161 An FcBlanks object holds a list of Unicode chars which are expected to
1162 be blank when drawn. When scanning new fonts, any glyphs which are
1163 empty and not in this list will be assumed to be broken and not placed in
1164 the FcCharSet associated with the font. This provides a significantly more
1165 accurate CharSet for applications.
1167 @deftypefun FcBlanks *FcBlanksCreate (void)
1169 Creates an empty FcBlanks object.
1172 @deftypefun void FcBlanksDestroy (FcBlanks *b)
1174 Destroys an FcBlanks object, freeing any associated memory.
1177 @deftypefun FcBool FcBlanksAdd (FcBlanks *b, FcChar32 ucs4)
1179 Adds a single character to an FcBlanks object, returning FcFalse
1180 if this process ran out of memory.
1183 @deftypefun FcBool FcBlanksIsMember (FcBlanks *b, FcChar32 ucs4)
1185 Returns whether the specified FcBlanks object contains the indicated Unicode
1189 The site or user may specify substitutions for certain font patterns,
1190 for convenience or to get more accurate results for the local
1191 installation or preferences. These functions execute the substitution
1192 based on a specified configuration.
1194 @deftypefun FcBool FcConfigSubstituteWithPat (FcConfig *config, FcPattern *p, FcPattern *p_pat FcMatchKind kind)
1196 Performs the sequence of pattern modification operations, if 'kind' is
1197 FcMatchPattern, then those tagged as pattern operations are applied, else
1198 if 'kind' is FcMatchFont, those tagged as font operations are applied and
1199 p_pat is used for <test> elements with target=pattern.
1202 @deftypefun FcBool FcConfigSubstitute (FcConfig *config, FcPattern *p, FcMatchKind kind)
1204 Calls FcConfigSubstituteWithPat setting p_pat to NULL.
1207 The following functions return fonts that match a certain pattern.
1208 @code{FcFontRenderPrepare} and @code{FcFontMatch} always return a single
1209 best match. @code{FcFontList} returns the list of fonts that match a a
1210 given pattern on a certain set of properties. @code{FcFontSort} returns
1211 the entire list of fonts, sorted in order of match quality, possibly
1212 filtering out fonts that do not provide additional characters beyond
1213 those provided by preferred fonts.
1215 @deftypefun {FcPattern *} FcFontRenderPrepare (FcConfig *config, FcPattern *pat, FcPattern *font)
1217 Creates a new pattern consisting of elements of 'font' not appearing
1218 in 'pat', elements of 'pat' not appearing in 'font' and the best matching
1219 value from 'pat' for elements appearing in both. The result is passed to
1220 FcConfigSubstitute with 'kind' FcMatchFont and then returned.
1223 @deftypefun {FcPattern *} FcFontMatch (FcConfig *config, FcPattern *p, FcResult *result)
1225 Returns the font in 'config' most close matching 'p'. This function
1226 should be called only after FcConfigSubstitute and FcDefaultSubstitute have
1227 been called for 'p'; otherwise the results will not be correct.
1230 @deftypefun FcFontSet *FcFontList (FcConfig *config, FcPattern *p, FcObjectSet *os)
1232 Selects fonts matching 'p', creates patterns containing only the objects in
1233 'os' from those fonts, and returns the set of unique such patterns.
1235 The FcFontSet returned by FcFontList is destroyed by calling FcFontSetDestroy.
1238 @deftypefun FcFontSet *FcFontSort (FcConfig *config, FcPattern *p, FcBool trim, FcCharSet **csp, FcResult *result)
1240 Returns the list of all fonts sorted by closeness to 'p'. If 'trim' is
1241 FcTrue, elements in the list which don't include Unicode coverage not
1242 provided by earlier elements in the list are elided. The union of
1243 Unicode coverage of all of the fonts is returned in 'csp', if 'csp' is
1244 not NULL. This function should be called only after FcConfigSubstitute
1245 and FcDefaultSubstitute have been called for 'p'; otherwise the results
1246 will not be correct.
1248 The returned FcFontSet references FcPattern structures which may be shared
1249 by the return value from multiple FcFontSort calls, applications must not
1250 modify these patterns. Instead, they should be passed, along with 'p' to
1251 FcFontRenderPrepare which combines them into a complete pattern.
1253 The FcFontSet returned by FcFontSort is destroyed by calling FcFontSetDestroy.
1257 @node Initialization, FcAtomic, Querying Fonts and Their Properties, Functions
1258 @subsection Initialization
1260 An FcConfig object holds the internal representation of a configuration.
1261 There is a default configuration which applications may use by passing 0 to
1262 any function using the data within an FcConfig.
1264 @deftypefun FcConfig *FcConfigCreate (void)
1266 Creates an empty configuration.
1269 @deftypefun void FcConfigDestroy (FcConfig *config)
1271 Destroys a configuration and any data associated with it. Note that calling
1272 this function with the return value from FcConfigGetCurrent will place the
1273 library in an indeterminate state.
1276 @deftypefun FcBool FcConfigSetCurrent (FcConfig *config)
1278 Sets the current default configuration to 'config'. Implicitly calls
1279 FcConfigBuildFonts if necessary, returning FcFalse if that call fails.
1282 @deftypefun FcConfig *FcConfigGetCurrent (void)
1284 Returns the current default configuration.
1287 @deftypefun FcBool FcConfigUptoDate (FcConfig *config)
1289 Checks all of the files related to 'config' and returns whether the
1290 in-memory version is in sync with the disk version.
1293 @deftypefun FcBool FcConfigBuildFonts (FcConfig *config)
1295 Builds the set of available fonts for the given configuration. Note that
1296 any changes to the configuration after this call have indeterminate effects.
1297 Returns FcFalse if this operation runs out of memory.
1300 @deftypefun FcStrList *FcConfigGetConfigDirs (FcConfig *config)
1302 Returns the list of font directories specified in the configuration files
1303 for 'config'. Does not include any subdirectories.
1306 @deftypefun FcStrList *FcConfigGetFontDirs (FcConfig *config)
1308 Returns the list of font directories in 'config'. This includes the
1309 configured font directories along with any directories below those in the
1313 @deftypefun FcStrList *FcConfigGetConfigFiles (FcConfig *config)
1315 Returns the list of known configuration files used to generate 'config'.
1316 Note that this will not include any configuration done with FcConfigParse.
1319 @deftypefun char *FcConfigGetCache (FcConfig *config)
1321 Returns the name of the file used to store per-user font information.
1324 @deftypefun FcFontSet *FcConfigGetFonts (FcConfig *config, FcSetName set)
1326 Returns one of the two sets of fonts from the configuration as specified
1330 @deftypefun FcBlanks *FcConfigGetBlanks (FcConfig *config)
1332 Returns the FcBlanks object associated with the given configuration, if no
1333 blanks were present in the configuration, this function will return 0.
1336 @deftypefun int FcConfigGetRescanInverval (FcConfig *config)
1338 Returns the interval between automatic checks of the configuration (in
1339 seconds) specified in 'config'. The configuration is checked during
1340 a call to FcFontList when this interval has passed since the last check.
1343 @deftypefun FcBool FcConfigSetRescanInverval (FcConfig *config, int rescanInterval)
1345 Sets the rescan interval; returns FcFalse if an error occurred.
1348 @deftypefun FcBool FcConfigAppFontAddFile (FcConfig *config, const char *file)
1350 Adds an application-specific font to the configuration.
1353 @deftypefun FcBool FcConfigAppFontAddDir (FcConfig *config, const char *dir)
1355 Scans the specified directory for fonts, adding each one found to the
1356 application-specific set of fonts.
1359 @deftypefun void FcConfigAppFontClear (FcConfig *config)
1361 Clears the set of application-specific fonts.
1364 These functions provide some control over how the default configuration of
1365 the library is initialized. (This configuration is normally implicitly
1368 @deftypefun char *FcConfigFilename (const char *name)
1370 Given the specified external entity name, return the associated filename.
1371 This provides applications a way to convert various configuration file
1372 references into filename form.
1374 A null or empty 'name' indicates that the default configuration file should
1375 be used; which file this references can be overridden with the
1376 FC_CONFIG_FILE environment variable. Next, if the name starts with '~', it
1377 refers to a file in the current users home directory. Otherwise if the name
1378 doesn't start with '/', it refers to a file in the default configuration
1379 directory; the built-in default directory can be overridden with the
1380 FC_CONFIG_DIR environment variable.
1383 @deftypefun FcConfig *FcInitLoadConfig (void)
1385 Loads the default configuration file and returns the resulting configuration.
1386 Does not load any font information.
1389 @deftypefun FcConfig *FcInitLoadConfigAndFonts (void)
1391 Loads the default configuration file and builds information about the
1392 available fonts. Returns the resulting configuration.
1395 @deftypefun FcBool FcInit (void)
1397 Loads the default configuration file and the fonts referenced therein and
1398 sets the default configuration to that result. Returns whether this
1399 process succeeded or not. If the default configuration has already
1400 been loaded, this routine does nothing and returns FcTrue.
1403 @deftypefun int FcGetVersion (void)
1405 Returns the version number of the library.
1408 @deftypefun FcBool FcInitReinitialize (void)
1410 Forces the default configuration file to be reloaded and resets the default
1414 @deftypefun FcBool FcInitBringUptoDate (void)
1416 Checks the rescan interval in the default configuration, checking the
1417 configuration if the interval has passed and reloading the configuration
1418 when any changes are detected.
1422 @node FcAtomic, FreeType-Specific Functions, Initialization, Functions
1423 @subsection FcAtomic
1425 These functions provide a safe way to update config files, allowing ongoing
1426 reading of the old config file while locked for writing and ensuring that a
1427 consistent and complete version of the config file is always available.
1429 @deftypefun FcAtomic * FcAtomicCreate (const FcChar8 *file)
1431 Creates a data structure containing data needed to control access to 'file'.
1432 Writing is done to a separate file. Once that file is complete, the
1433 original configuration file is atomically replaced so that reading processes
1434 always see a consistent and complete file without the need to lock for
1438 @deftypefun FcBool FcAtomicLock (FcAtomic *atomic)
1440 Attempts to lock the file referenced by 'atomic'. Returns FcFalse if the
1441 file is locked by another process, else returns FcTrue and leaves the file
1445 @deftypefun FcChar8 *FcAtomicNewFile (FcAtomic *atomic)
1447 Returns the filename for writing a new version of the file referenced
1451 @deftypefun FcChar8 *FcAtomicOrigFile (FcAtomic *atomic)
1453 Returns the file refernced by 'atomic'.
1456 @deftypefun FcBool FcAtomicReplaceOrig (FcAtomic *atomic)
1458 Replaces the original file referenced by 'atomic' with the new file.
1461 @deftypefun void FcAtomicDeleteNew (FcAtomic *atomic)
1463 Deletes the new file.
1466 @deftypefun void FcAtomicUnlock (FcAtomic *atomic)
1471 @deftypefun void FcAtomicDestroy (FcAtomic *atomic)
1476 @node FreeType-Specific Functions, XML-Specific Functions, FcAtomic, Functions
1477 @subsection FreeType-Specific Functions
1480 #include <fontconfig/fcfreetype.h>
1483 While the fontconfig library doesn't insist that FreeType be used as the
1484 rasterization mechanism for fonts, it does provide some convenience
1487 @deftypefun FT_UInt FcFreeTypeCharIndex (FT_Face face, FcChar32 ucs4)
1489 Maps a Unicode char to a glyph index. This function uses information from
1490 several possible underlying encoding tables to work around broken fonts.
1491 As a result, this function isn't designed to be used in performance
1492 sensitive areas; results from this function are intended to be cached by
1493 higher level functions.
1496 @deftypefun {FcCharSet *} FcFreeTypeCharSet (FT_Face face, FcBlanks *blanks) Scans a
1498 FreeType face and returns the set of encoded Unicode chars. This scans
1499 several encoding tables to build as complete a list as possible.
1500 If 'blanks' is not 0, the glyphs in the font are examined and any blank glyphs
1501 not in 'blanks' are not placed in the returned FcCharSet.
1504 @deftypefun {FcPattern *} FcFreeTypeQuery (const char *file, int id, FcBlanks *blanks, int *count)
1506 Constructs a pattern representing the 'id'th font in 'file'. The number
1507 of fonts in 'file' is returned in 'count'.
1510 @node XML-Specific Functions, File and Directory Routines, FreeType-Specific Functions, Functions
1511 @subsection XML-Specific Functions
1513 @deftypefun FcBool FcConfigParseAndLoad (FcConfig *config, const FcChar8 *file, FcBool complain)
1515 Walks the configuration in 'file' and constructs the internal representation
1516 in 'config'. Any include files referenced from within 'file' will be loaded
1517 with FcConfigLoad and also parsed. If 'complain' is FcFalse, no warning
1518 will be displayed if 'file' does not exist.
1521 @node File and Directory Routines, FcStrSet and FcStrList, XML-Specific Functions, Functions
1522 @subsection File and Directory Routines
1524 @deftypefun FcBool FcFileScan (FcFontSet *set, FcStrSet *dirs, FcFileCache *cache, FcBlanks *blanks, const char *file, FcBool force)
1526 Scans a single file and adds all fonts found to 'set'. If 'force' is FcTrue,
1527 then the file is scanned even if associated information is found in 'cache'.
1528 If 'file' is a directory, it is added to 'dirs'.
1531 @deftypefun FcBool FcDirScan (FcFontSet *set, FcStrSet *dirs, FcFileCache *cache, FcBlanks *blanks, const char *dir, FcBool force)
1533 Scans an entire directory and adds all fonts found to 'set'. If 'force' is
1534 FcTrue, then the directory and all files within it are scanned even if
1535 information is present in the per-directory cache file or 'cache'. Any
1536 subdirectories found are added to 'dirs'.
1539 @deftypefun FcBool FcDirSave (FcFontSet *set, FcStrSet *dirs, const char *dir)
1541 Creates the per-directory cache file for 'dir' and populates it with the
1542 fonts in 'set' and subdirectories in 'dirs'.
1545 @deftypefun FcBool FcDirCacheValid (const FcChar8 *cache_file)
1547 Returns FcTrue if 'cache_file' is no older than the directory containing it,
1551 @node FcStrSet and FcStrList, String Utilities, File and Directory Routines, Functions
1552 @subsection FcStrSet and FcStrList
1554 A data structure for enumerating strings, used to list directories while
1555 scanning the configuration as directories are added while scanning.
1557 @deftypefun FcStrSet *FcStrSetCreate (void)
1559 Create an empty set.
1562 @deftypefun FcBool FcStrSetMember (FcStrSet *set, const FcChar8 *s)
1564 Returns whether 's' is a member of 'set'.
1567 @deftypefun FcBool FcStrSetAdd (FcStrSet *set, const FcChar8 *s)
1569 Adds a copy of 's' to 'set'.
1572 @deftypefun FcBool FcStrSetAddFilename (FcStrSet *set, const FcChar8 *s)
1574 Adds a copy of 's' to 'set', The copy is created with FcStrCopyFilename
1575 so that leading '~' values are replaced with the value of the HOME
1576 environment variable.
1579 @deftypefun FcBool FcStrSetDel (FcStrSet *set, const FcChar8 *s)
1581 Removes 's' from 'set', returning FcTrue if 's' was a member else FcFalse.
1584 @deftypefun void FcStrSetDestroy (FcStrSet *set)
1589 @deftypefun FcStrList *FcStrListCreate (FcStrSet *set)
1591 Creates an enumerator to list the strings in 'set'.
1594 @deftypefun FcChar8 *FcStrListNext (FcStrList *list)
1596 Returns the next string in 'set'.
1599 @deftypefun void FcStrListDone (FcStrList *list)
1601 Destroys the enumerator 'list'.
1604 @node String Utilities, , FcStrSet and FcStrList, Functions
1605 @subsection String Utilities
1607 @deftypefun int FcUtf8ToUcs4 (FcChar8 *src, FcChar32 *dst, int len)
1609 Converts the next Unicode char from 'src' into 'dst' and returns the number
1610 of bytes containing the char. 'src' must be at least 'len' bytes long.
1613 @deftypefun int FcUcs4ToUtf8 (FcChar32 src, FcChar8 dst[FC_UTF8_MAX_LEN])
1615 Converts the Unicode char from 'src' into 'dst' and returns the
1616 number of bytes needed to encode the char.
1619 @deftypefun FcBool FcUtf8Len (FcChar8 *src, int len, int *nchar, int *wchar)
1621 Counts the number of Unicode chars in 'len' bytes of 'src'. Places that
1622 count in 'nchar'. 'wchar' contains 1, 2 or 4 depending on the number of
1623 bytes needed to hold the largest unicode char counted. The return value
1624 indicates whether 'src' is a well-formed UTF8 string.
1627 @deftypefun int FcUtf16ToUcs4 (FcChar8 *src, FcEndian endian, FcChar32 *dst, int len)
1629 Converts the next Unicode char from 'src' into 'dst' and returns the
1630 number of bytes containing the char. 'src' must be at least 'len' bytes
1631 long. Bytes of 'src' are combined into 16-bit units according to 'endian'.
1634 @deftypefun FcBool FcUtf16Len (FcChar8 *src, FcEndian endian, int len, int *nchar, int *wchar)
1636 Counts the number of Unicode chars in 'len' bytes of 'src'. Bytes of 'src'
1637 are combined into 16-bit units according to 'endian'. Places that
1638 count in 'nchar'. 'wchar' contains 1, 2 or 4 depending on the number of
1639 bytes needed to hold the largest unicode char counted. The return value
1640 indicates whether 'string' is a well-formed UTF16 string.
1643 @deftypefun FcChar8 *FcStrCopy (const FcChar8 *s)
1645 Allocates memory, copies 's' and returns the resulting buffer. Yes, this
1646 is 'strdup', but that function isn't available on every platform.
1649 @deftypefun FcChar8 *FcStrCopyFilename (const FcChar8 *s)
1651 Just like FcStrCopy except that it converts any leading '~' characters
1652 in 's' to the value of the HOME environment variable.
1655 @deftypefun int FcStrCmpIgnoreCase (const char *s1, const char *s2)
1657 Returns the usual <0, 0, >0 result of comparing 's1' and 's2'. This test
1658 is case-insensitive in the ASCII range and will operate properly with UTF8
1659 encoded strings, although it does not check for well formed strings.
1662 @deftypefun FcChar8 *FcStrDirname (const FcChar8 *file)
1664 Returns the directory containing 'file'.
1667 @deftypefun FcChar8 *FcStrBasename (const FcChar8 *file)
1669 Returns the filename of 'file' stripped of any leading directory names.
1672 @node Configuration File Format, Files, The fontconfig API, Top
1673 @chapter Configuration File Format
1675 Configuration files for fontconfig are stored in XML format; this
1676 format makes external configuration tools easier to write and ensures that
1677 they will generate syntactically correct configuration files. As XML
1678 files are plain text, they can also be manipulated by the expert user using
1681 The fontconfig document type definition resides in the external entity
1682 @samp{fonts.dtd}; this is normally stored in the default font configuration
1683 directory (@file{/etc/fonts}). Each configuration file should contain the
1684 following structure:
1687 <?xml version="1.0"?>
1688 <!DOCTYPE fontconfig SYSTEM "fonts.dtd">
1696 This is the top level element for a font configuration and can contain
1697 @samp{<dir>}, @samp{<cache>}, @samp{<include>}, @samp{<match>} and @samp{<alias>} elements in any order.
1700 This element contains a directory name which will be scanned for font files
1701 to include in the set of available fonts. The scan does not recurse into
1705 This element contains a file name for the per-user cache of font
1706 information. If it starts with '~', it refers to a file in the users
1707 home directory. This file is used to hold information about fonts that
1708 isn't present in the per-directory cache files. It is automatically
1709 maintained by the fontconfig library. The default for this file
1710 is ``~/.fonts.cache-<version>'', where <version> is the font configuration
1711 file version number (currently 1).
1713 @item <include ignore_missing="no">
1714 This element contains the name of an additional configuration file. When
1715 the XML datatype is traversed by FcConfigParse, the contents of the file
1716 will also be incorporated into the configuration by passing the filename to
1717 FcConfigLoadAndParse. If 'ignore_missing' is set to "yes" instead of the
1718 default "no", a missing file will elicit no warning message from the library.
1721 This element provides a place to consolidate additional configuration
1722 information. @samp{<config>} can contain @samp{<blank>} and @samp{<rescan>} elements in any
1726 Fonts often include "broken" glyphs which appear in the encoding but are
1727 drawn as blanks on the screen. Within the @samp{<blank>} element, place each
1728 Unicode characters which is supposed to be blank in an @samp{<int>} element.
1729 Characters outside of this set which are drawn as blank will be elided from
1730 the set of characters supported by the font.
1733 The @samp{<rescan>} element holds an @samp{<int>} element which indicates the default
1734 interval between automatic checks for font configuration changes.
1735 Fontconfig will validate all of the configuration files and directories and
1736 automatically rebuild the internal datastructures when this interval passes.
1738 @item <match target="pattern">
1739 This element holds first a (possibly empty) list of @samp{<test>} elements and then
1740 a (possibly empty) list of @samp{<edit>} elements. Patterns which match all of the
1741 tests are subjected to all the edits. If 'target' is set to "font" instead
1742 of the default "pattern", then this element applies to the font name
1743 resulting from a match rather than a font pattern to be matched.
1745 @item <test qual="any" name="property" compare="eq">
1746 This element contains a single value which is compared with the pattern
1747 property "property" (substitute any of the property names seen
1748 above). 'compare' can be one of "eq", "not_eq", "less", "less_eq", "more", or
1749 "more_eq". 'qual' may either be the default, "any", in which case the match
1750 succeeds if any value associated with the property matches the test value, or
1751 "all", in which case all of the values associated with the property must
1752 match the test value.
1754 @item <edit name="property" mode="assign" binding="weak">
1755 This element contains a list of expression elements (any of the value or
1756 operator elements). The expression elements are evaluated at run-time and
1757 modify the property "property". The modification depends on whether
1758 "property" was matched by one of the associated @samp{<test>} elements, if so, the
1759 modification may affect the first matched value. Any values inserted into
1760 the property are given the indicated binding. 'mode' is one of:
1763 Mode Operation with match Operation without match
1765 "assign" Replace matching value Replace all values
1766 "assign_replace" Replace all values Replace all values
1767 "prepend" Insert before matching value Insert at head of list
1768 "prepend_first" Insert at head of list Insert at head of list
1769 "append" Append after matching value Append at end of list
1770 "append_last" Append at end of list Append at end of list
1777 These elements hold a single value of the indicated type. @samp{<bool>} elements
1778 hold either true or false.
1782 This element holds the four @samp{<double>} elements of an affine transformation.
1785 Holds a property name. Evaluates to the first value from the property of
1786 the font, not the pattern.
1789 Holds the name of a constant; these are always integers and serve as
1790 symbolic names for common font values:
1793 Constant Property CPP symbol
1795 light weight FC_WEIGHT_LIGHT
1796 medium weight FC_WEIGHT_MEDIUM
1797 demibold weight FC_WEIGHT_DEMIBOLD
1798 bold weight FC_WEIGHT_BOLD
1799 black weight FC_WEIGHT_BLACK
1800 roman slant FC_SLANT_ROMAN
1801 italic slant FC_SLANT_ITALIC
1802 oblique slant FC_SLANT_OBLIQUE
1803 proportional spacing FC_PROPORTIONAL
1804 mono spacing FC_MONO
1805 charcell spacing FC_CHARCELL
1806 unknown rgba FC_RGBA_UNKNOWN
1807 rgb rgba FC_RGBA_RGB
1808 bgr rgba FC_RGBA_BGR
1809 vrgb rgba FC_RGBA_VRGB
1810 vbgr rgba FC_RGBA_VBGR
1811 none rgba FC_RGBA_NONE
1820 These elements perform the specified operation on a list of expression
1821 elements. @samp{<or>} and @samp{<and>} are boolean, not bitwise.
1829 These elements compare two values, producing a boolean result.
1832 Inverts the boolean sense of its one expression element
1835 This element takes three expression elements; if the value of the first is
1836 true, it produces the value of the second, otherwise it produces the value
1840 Alias elements provide a shorthand notation for the set of common match
1841 operations needed to substitute one font family for another. They contain a
1842 @samp{<family>} element followed by optional @samp{<prefer>}, @samp{<accept>} and @samp{<default>}
1843 elements. Fonts matching the @samp{<family>} element are edited to prepend the
1844 list of @samp{<prefer>}ed families before the matching @samp{<family>}, append the
1845 @samp{<accept>}able families after the matching @samp{<family>} and append the @samp{<default>}
1846 families to the end of the family list.
1849 Holds a single font family name
1854 These each hold a list of @samp{<family>} elements to be used by the @samp{<alias>}
1859 * Example System Configuration File::
1860 * Example User Configuration File::
1863 @node Example System Configuration File, Example User Configuration File, Configuration File Format, Configuration File Format
1864 @section Example System Configuration File
1866 This is an example of a system-wide configuration file:
1869 <?xml version="1.0"?>
1870 <!DOCTYPE fontconfig SYSTEM "fonts.dtd">
1871 <!-- /etc/fonts/fonts.conf file to configure system font access -->
1874 Find fonts in these directories
1876 <dir>/usr/X11R6/lib/X11/fonts/truetype</dir>
1877 <dir>/usr/X11R6/lib/X11/fonts/Type1</dir>
1880 Accept deprecated 'mono' alias, replacing it with 'monospace'
1882 <match target="pattern">
1883 <test qual="any" name="family"><string>mono</string></test>
1884 <edit name="family" mode="assign"><string>monospace</string></edit>
1888 Names not including any well known alias are given 'sans'
1890 <match target="pattern">
1891 <test qual="all" name="family" mode="not_eq">sans</test>
1892 <test qual="all" name="family" mode="not_eq">serif</test>
1893 <test qual="all" name="family" mode="not_eq">monospace</test>
1894 <edit name="family" mode="append_last"><string>sans</string></edit>
1898 Load per-user customization file, but don't complain
1901 <include ignore_missing="yes">~/.fonts.conf</include>
1904 Alias well known font names to available TrueType fonts.
1905 These substitute TrueType faces for similar Type1
1906 faces to improve screen appearance.
1909 <family>Times</family>
1910 <prefer><family>Times New Roman</family></prefer>
1911 <default><family>serif</family></default>
1914 <family>Helvetica</family>
1915 <prefer><family>Verdana</family></prefer>
1916 <default><family>sans</family></default>
1919 <family>Courier</family>
1920 <prefer><family>Courier New</family></prefer>
1921 <default><family>monospace</family></default>
1925 Provide required aliases for standard names
1926 Do these after the users configuration file so that
1927 any aliases there are used preferentially
1930 <family>serif</family>
1931 <prefer><family>Times New Roman</family></prefer>
1934 <family>sans</family>
1935 <prefer><family>Verdana</family></prefer>
1938 <family>monospace</family>
1939 <prefer><family>Andale Mono</family></prefer>
1944 @node Example User Configuration File, , Example System Configuration File, Configuration File Format
1945 @section Example User Configuration File
1947 This is an example of a per-user configuration file that lives in
1948 @file{~/.fonts.conf}:
1951 <?xml version="1.0"?>
1952 <!DOCTYPE fontconfig SYSTEM "fonts.dtd">
1953 <!-- ~/.fonts.conf for per-user font configuration -->
1957 Private font directory
1959 <dir>~/misc/fonts</dir>
1962 use rgb sub-pixel ordering to improve glyph appearance on
1963 LCD screens. Changes affecting rendering, but not matching,
1964 should always use target="font".
1966 <match target="font">
1967 <edit name="rgba" mode="assign"><const>rgb</const></edit>
1972 @node Files, Authors, Configuration File Format, Top
1977 is a DTD that describes the format of the configuration files.
1980 is the default system-wide font configuration file. It
1981 contains configuration information for the fontconfig library
1982 consisting of directories to look at for font information as well as
1983 instructions on editing program specified font patterns before attempting to
1984 match the available fonts. It is in xml format, with DTD @file{fonts.dtd}.
1987 is the conventional default location for local font configuration. It
1988 is sourced by the default system-wide fonts.conf file.
1989 Note that the normal 'make install' procedure for XFree86 is to
1990 replace any existing fonts.conf file with the new version. Place
1991 any local customizations in local.conf which this file references.
1992 It is in xml format, with DTD @file{fonts.dtd}.
1995 is the conventional location for per-user font configuration, although the
1996 actual location is specified in the global fonts.conf file.
1997 It is in xml format, with DTD @file{fonts.dtd}.
2000 is found in each font directory where fonts were found. This file is
2001 automatically maintained by fontconfig. It is a flat text table, and
2002 should be treated as opaque.
2004 @item ~/.fonts.cache-*
2005 is the conventional repository of font information that isn't found in the
2006 per-directory caches. This file is automatically maintained by fontconfig.
2007 It is a flat text table, and should be treated as opaque.
2010 @node Authors, , Files, Top
2015 member of the XFree86 Project, Inc.
2017 @item Stephen J. Turnbull
2018 member of the XEmacs Project
2027 @c arch-tag: 108A3E8B-1CE1-11D9-9957-000A959E994E
2029 @c end of fontconfig.texi