2 .\" $XFree86: fontconfig.man,v 1.2 2000/11/30 06:59:45 keithp Exp $
4 .\" Copyright © 2002 Keith Packard, member of The XFree86 Project, Inc.
6 .\" Permission to use, copy, modify, distribute, and sell this software and its
7 .\" documentation for any purpose is hereby granted without fee, provided that
8 .\" the above copyright notice appear in all copies and that both that
9 .\" copyright notice and this permission notice appear in supporting
10 .\" documentation, and that the name of Keith Packard not be used in
11 .\" advertising or publicity pertaining to distribution of the software without
12 .\" specific, written prior permission. Keith Packard makes no
13 .\" representations about the suitability of this software for any purpose. It
14 .\" is provided "as is" without express or implied warranty.
16 .\" KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
17 .\" INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
18 .\" EVENT SHALL KEITH PACKARD BE LIABLE FOR ANY SPECIAL, INDIRECT OR
19 .\" CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
20 .\" DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
21 .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
22 .\" PERFORMANCE OF THIS SOFTWARE.
29 .TH FONTCONFIG 3 "Version 1.0" "XFree86"
32 fontconfig \- Font configuration and customization library
36 .B #include <fontconfig/fontconfig.h>
37 .B #include <fontconfig/fcfreetype.h>
38 .B #include <fontconfig/fcxml.h>
42 is a library designed to provide system-wide font configuration,
43 customization and application access.
45 .SH FUNCTIONAL OVERVIEW
46 Fontconfig contains two essential modules, the configuration module which
47 builds an internal configuration from XML files and the matching module
48 which accepts font patterns and returns the nearest matching font.
50 .SS FONT CONFIGURATION
51 The configuration module consists of the FcConfig datatype, libxml2 and
52 FcConfigParse which walks over an XML tree and ammends a configuration with
53 data found within. From an external perspective, configuration of the
54 library consists of generating a valid XML tree and feeding that to
55 FcConfigParse. The only other mechanism provided to applications for
56 changing the running configuration is to add fonts and directories to the
57 list of application-provided font files.
59 The intent is to make font configurations relatively static, and shared by
60 as many applications as possible. It is hoped that this will lead to more
61 stable font selection when passing names from one application to another.
62 XML was chosen as a configuration file format because it provides a format
63 which is easy for external agents to edit while retaining the correct
66 Font configuration is separate from font matching; applications needing to
67 do their own matching can access the available fonts from the library and
68 perform private matching. The intent is to permit applications to pick and
69 choose appropriate functionality from the library instead of forcing them to
70 choose between this library and a private configuration mechanism. The hope
71 is that this will ensure that configuration of fonts for all applications
72 can be centralized in one place. Centralizing font configuration will make
73 simplify and regularize font installation and customization.
76 While font patterns may contain essentially any properties, there are some
77 well known properties with associated types. Fontconfig uses some of these
78 properties for font matching and font completion. Others are provided as a
79 convenience for the applications rendering mechanism.
82 .ta 1i 2.75i 3.5i 5.5i
84 Property CPP symbol Type Description
86 family FC_FAMILY String Font family name
87 style FC_STYLE String Font style. Overrides weight and slant
88 slant FC_SLANT Int Italic, oblique or roman
89 weight FC_WEIGHT Int Light, medium, demibold, bold or black
90 size FC_SIZE Double Point size
91 pixelsize FC_PIXEL_SIZE Double Pixel size
92 spacing FC_SPACING Int Proportional, monospace or charcell
93 foundry FC_FOUNDRY String Font foundry name
94 antialias FC_ANTIALIAS Bool Whether glyphs can be antialiased
95 hinting FC_HINTING Bool Whether the rasterizer should use hinting
96 verticallayout FC_VERTICAL_LAYOUT Bool Use vertical layout
97 globaladvance FC_GLOBAL_ADVANCE Bool Use font global advance data
98 file FC_FILE String The filename holding the font
99 index FC_INDEX Int The index of the font within the file
100 rasterizer FC_RASTERIZER String Which rasterizer is in use
101 outline FC_OUTLINE Bool Whether the glyphs are outlines
102 scalable FC_SCALABLE Bool Whether glyphs can be scaled
103 scale FC_SCALE Double Scale factor for point->pixel conversions
104 dpi FC_DPI Double Target dots per inch
105 rgba FC_RGBA Int rgb, bgr, vrgb, vbgr - subpixel geometry
106 minspace FC_MINSPACE Bool Eliminate leading from line spacing
107 charset FC_CHARSET CharSet Unicode chars encoded by the font
108 lang FC_LANG String List of language groups this font is designed for
113 Fontconfig performs matching by measuring the distance from a provided
114 pattern to all of the available fonts in the system. The closest matching
115 font is selected. This ensures that a font will always be returned, but
116 doesn't ensure that it is anything like the requested pattern.
118 Font matching starts with an application constructed pattern. The desired
119 attributes of the resulting font are collected together in an FcPattern
120 object. Each property of the pattern can contain one or more values; these
121 are listed in priority order; matches earlier in the list are considered
122 "closer" than matches later in the list.
124 The initial pattern is modified by applying the list of editing instructions
125 specific to patterns found in the configuration; each consists of a match
126 predicate and a set of editing operations. They are executed in the order
127 they appeared in the configuration. Each match causes the associated
128 sequence of editing operations to be applied.
130 After the pattern has been edited, a sequence of default substitutions are
131 performed to canonicalize the set of available properties; this avoids the
132 need for the lower layers to constantly provide default values for various
133 font properties during rendering.
135 The canonical font pattern is finally matched against all available fonts.
136 The distance from the pattern to the font is measured for each of several
137 properties: foundry, charset, antialias, family, spacing, pixelsize, style,
138 slant, weight, rasterizer and outline. This list is in priority order --
139 results of comparing earlier elements of this list weigh more heavily than
142 The pattern representing that font is augmented to include any properties
143 found in the pattern but not found in the font itself; this permits the
144 application to pass rendering instructions or any other data through the
145 matching system. Finally, the list of editing instructions specific to
146 fonts found in the configuration are applied to the pattern. This modified
147 pattern is returned to the application.
149 The return value contains sufficient information to locate and rasterize the
150 font, including the file name, pixel size and other rendering data. As
151 none of the information involved pertains to the FreeType library,
152 applications are free to use any rasterization engine or even to take
153 the identified font file and access it directly.
155 The match/edit sequences in the configuration are performed in two passes
156 because there are essentially two different operations necessary -- the
157 first is to modify how fonts are selected; aliasing families and adding
158 suitable defaults. The second is to modify how the selected fonts are
159 rasterized. Those must apply to the selected font, not the original pattern
160 as false matches will often occur.
162 Fontconfig provides a textual representation for patterns that the library
163 can both accept and generate. The representation is in three parts, first a
164 list of family names, second a list of point sizes and finally a list of
165 additional properties:
167 <families>-<point sizes>:<name1>=<values1>:<name2>=<values2>...
169 Values in a list are separated with commas. The name needn't include either
170 families or point sizes; they can be elided. In addition, there are
171 symbolic constants that simultaneously indicate both a name and a value.
172 Here are some examples:
176 Times-12 12 point Times Roman
177 Times-12:bold 12 point Times Bold
178 Courier:italic Courier Italic in the default size
179 Monospace:matrix=1 .1 0 1 The users preferred monospace font
180 with artificial obliquing
194 These are primitive datatypes; the FcChar* types hold precisely the number
195 of bits stated (if supported by the C implementation). FcBool holds
196 one of two CPP symbols: FcFalse or FcTrue.
200 An FcMatrix holds an affine transformation, usually used to reshape glyphs.
201 A small set of matrix operations are provided to manipulate these.
204 typedef struct _FcMatrix {
205 double xx, xy, yx, yy;
211 An FcCharSet is an abstract type that holds the set of encoded unicode chars
212 in a font. Operations to build and compare these sets are provided.
216 Tags the kind of data stored in an FcValue.
220 An FcValue object holds a single value with one of a number of different
221 types. The 'type' tag indicates which member is valid.
224 typedef struct _FcValue {
240 type Union member Datatype
242 FcTypeVoid (none) (none)
244 FcTypeDouble d double
245 FcTypeString s char *
247 FcTypeMatrix m FcMatrix *
248 FcTypeCharSet c FcCharSet *
253 holds a set of names with associated value lists; each name refers to a
254 property of a font. FcPatterns are used as inputs to the matching code as
255 well as holding information about specific fonts. Each property can hold
256 one or more values; conventionally all of the same type, although the
257 interface doesn't demand that.
263 typedef struct _FcFontSet {
269 An FcFontSet contains a list of FcPatterns. Internally fontconfig uses this
270 data structure to hold sets of fonts. Externally, fontconfig returns the
271 results of listing fonts in this format. 'nfont' holds the number of
272 patterns in the 'fonts' array; 'sfont' is used to indicate the size of that
279 typedef struct _FcObjectSet {
282 const char **objects;
285 holds a set of names and is used to specify which fields from fonts are
286 placed in the the list of returned patterns when listing fonts.
290 holds a list of Unicode chars which are expected to be blank; unexpectedly
291 blank chars are assumed to be invalid and are elided from the charset
292 associated with the font.
296 holds the per-user cache information for use while loading the font
297 database. This is built automatically for the current configuration when
298 that is loaded. Applications must always pass '0' when one is requested.
302 holds a complete configuration of the library; there is one default
303 configuration, other can be constructed from XML data structures. All
304 public entry points that need global data can take an optional FcConfig*
305 argument; passing 0 uses the default configuration. FcConfig objects hold two
306 sets of fonts, the first contains those specified by the configuration, the
307 second set holds those added by the application at run-time. Interfaces
308 that need to reference a particulat set use one of the FcSetName enumerated
313 Specifies one of the two sets of fonts available in a configuration;
314 FcSetSystem for those fonts specified in the configuration and
315 FcSetApplication which holds fonts provided by the application.
319 Used as a return type for functions manipulating FcPattern objects.
327 FcResultMatch Object exists with the specified ID
329 FcResultNoMatch Object doesn't exist at all
331 FcResultTypeMismatch Object exists, but the type doesn't match
333 FcResultNoId Object exists, but has fewer values than specified
340 FcMatrix structures hold an affine transformation in matrix form.
342 #define FcMatrixInit(m) ((m)->xx = (m)->yy = 1, (m)->xy = (m)->yx = 0)
343 Initializes a matrix to the identify transformation.
346 FcMatrix *FcMatrixCopy (const FcMatrix *mat)
347 Allocates a new FcMatrix and copies 'mat' into it.
350 FcBool FcMatrixEqual (const FcMatrix *mat1, const FcMatrix *mat2)
351 Returns FcTrue if 'mat1' and 'mat2' are equal, else FcFalse.
354 void FcMatrixMultiply (FcMatrix *result, const FcMatrix *a, const FcMatrix *b)
355 Multiplies 'a' and 'b' together, placing the result in
356 'result'. 'result' may refer to the sam matrix as either 'a' or 'b'.
359 void FcMatrixRotate (FcMatrix *m, double c, double s)
360 If 'c' is cos(angle) and 's' is sin(angle), FcMatrixRotate rotates the
364 void FcMatrixScale (FcMatrix *m, double sx, double sy)
365 Scales 'm' by 'sx' in the horizontal dimension and 'sy' in the
369 void FcMatrixShear (FcMatrix *m, double sh, double sv)
370 Shears 'm' by 'sh' in the horizontal direction and 'sv' in the
374 An FcCharSet is a boolean array indicating a set of unicode chars. Those
375 associated with a font are marked constant and cannot be edited.
376 FcCharSets may be reference counted internally to reduce memory consumption;
377 this may be visible to applications as the result of FcCharSetCopy may
378 return it's argument, and that CharSet may remain unmodifiable.
381 FcCharSet *FcCharSetCreate (void)
382 Creates an empty FcCharSet object.
385 void FcCharSetDestroy (FcCharSet *fcs)
386 Frees an FcCharSet object.
389 FcBool FcCharSetAddChar (FcCharSet *fcs, FcChar32 ucs4)
390 Adds a single unicode char to the set, returning FcFalse on
391 failure, either as a result of a constant set or from running out of memory.
394 FcCharSet *FcCharSetCopy (FcCharSet *src)
395 Makes a copy of 'src'; note that this may not actually do anything more than
396 increment the reference count on 'src'.
399 FcBool FcCharSetEqual (const FcCharSet *a, const FcCharSet *b)
400 Returns whether 'a' and 'b' contain the same set of unicode chars.
403 FcCharSet *FcCharSetIntersect (const FcCharSet *a, const FcCharSet *b)
404 Returns a set including only those chars found in both 'a' and 'b'.
407 FcCharSet *FcCharSetUnion (const FcCharSet *a, const FcCharSet *b);
408 Returns a set including only those chars found in either 'a' or 'b'.
411 FcCharSet *FcCharSetSubtract (const FcCharSet *a, const FcCharSet *b)
412 Returns a set including only those chars found in 'a' but not 'b'.
415 FcBool FcCharSetHasChar (const FcCharSet *fcs, FcChar32 ucs4)
416 Returns whether 'fcs' contains the char 'ucs4'.
419 FcChar32 FcCharSetCount (const FcCharSet *a)
420 Returns the total number of unicode chars in 'a'.
423 FcChar32 FcCharSetIntersectCount (const FcCharSet *a, const FcCharSet *b)
424 Returns the number of chars that are in both 'a' and 'b'.
427 FcChar32 FcCharSetSubtractCount (const FcCharSet *a, const FcCharSet *b)
428 Returns the number of chars that are in 'a' but not in 'b'.
431 FcValue is a structure containing a type tag and a union of all possible
432 datatypes. The tag is an enum of type
434 and is intended to provide a measure of run-time
435 typechecking, although that depends on careful programming.
438 void FcValueDestroy (FcValue v)
439 Frees any memory referenced by `v'. Values of type FcTypeString,
440 FcTypeMatrix and FcTypeCharSet reference memory, the other types do not.
443 FcValue FcValueSave (FcValue v)
444 Returns a copy of `v' duplicating any object referenced by it so that `v'
445 may be safely destroyed without harming the new value.
448 An FcPattern is an opaque type that holds both patterns to match against the
449 available fonts, as well as the information about each font.
452 FcPattern *FcPatternCreate (void)
453 Creates a pattern with no properties; used to build patterns from scratch.
456 void FcPatternDestroy (FcPattern *p)
457 Destroys a pattern, in the process destroying all related values.
460 FcBool FcPatternAdd (FcPattern *p, const char *object, FcValue value, FcBool append)
461 Adds a single value to the list of values associated with the property named
462 `object'. If `append' is FcTrue, the value is added at the end of any
463 existing list, otherwise it is inserted at the begining. `value' is saved
464 (with FcValueSave) when inserted into the pattern so that the library
465 retains no reference to any application-supplied data structure.
468 FcBool FcPatternAddInteger (FcPattern *p, const char *object, int i)
470 FcBool FcPatternAddDouble (FcPattern *p, const char *object, double d)
472 FcBool FcPatternAddString (FcPattern *p, const char *object, const char *s)
474 FcBool FcPatternAddMatrix (FcPattern *p, const char *object, const FcMatrix *s)
476 FcBool FcPatternAddCharSet (FcPattern *p, const char *object, const FcCharSet *c)
478 FcBool FcPatternAddBool (FcPattern *p, const char *object, FcBool b)
479 These are all convenience functions that insert objects of the specified
480 type into the pattern. Use these in preference to FcPatternAdd as they
481 will provide compile-time typechecking. These all append values to
482 any existing list of values.
485 FcResult FcPatternGet (FcPattern *p, const char *object, int id, FcValue *v)
486 Returns in `v' the `id'th value associated with the property `object'.
487 The value returned is not a copy, but rather refers to the data stored
488 within the pattern directly. Applications must not free this value.
491 FcResult FcPatternGetInteger (FcPattern *p, const char *object, int n, int *i);
493 FcResult FcPatternGetDouble (FcPattern *p, const char *object, int n, double *d);
495 FcResult FcPatternGetString (FcPattern *p, const char *object, int n, char **const s);
497 FcResult FcPatternGetMatrix (FcPattern *p, const char *object, int n, FcMatrix **s);
499 FcResult FcPatternGetCharSet (FcPattern *p, const char *object, int n, FcCharSet **c);
501 FcResult FcPatternGetBool (FcPattern *p, const char *object, int n, FcBool *b);
502 These are convenience functions that call FcPatternGet and verify that the
503 returned data is of the expected type. They return FcResultTypeMismatch if
504 this is not the case. Note that these (like FcPatternGet) do not make a
505 copy of any data structure referenced by the return value. Use these
506 in preference to FcPatternGet to provide compile-time typechecking.
509 FcPattern *FcPatternBuild (FcPattern *orig, ...);
511 FcPattern *FcPatternVaBuild (FcPattern *orig, va_list va)
512 Builds a pattern using a list of objects, types and values. Each
513 value to be entered in the pattern is specified with three arguments:
515 1. Object name, a string describing the property to be added.
517 2. Object type, one of the FcType enumerated values
519 3. Value, not an FcValue, but the raw type as passed to any of the
520 FcPatternAdd<type> functions. Must match the type of the second argument.
522 The argument list is terminated by a null object name, no object type nor
523 value need be passed for this. The values are added to `pattern', if
524 `pattern' is null, a new pattern is created. In either case, the pattern is
528 pattern = FcPatternBuild (0, FC_FAMILY, FtTypeString, "Times", (char *) 0);
531 FcPatternVaBuild is used when the arguments are already in the form of a
535 FcBool FcPatternDel (FcPattern *p, const char *object)
536 Deletes all values associated with the property `object', returning
537 whether the property existed or not.
540 void FcPatternPrint (FcPattern *p)
541 Prints an easily readable version of the pattern to stdout. There is
542 no provision for reparsing data in this format, it's just for diagnostics
546 void FcDefaultSubstitute (FcPattern *pattern)
547 Supplies default values for underspecified font patterns:
550 Patterns without a specified style or weight are set to Medium
552 Patterns without a specified style or slant are set to Roman
554 Patterns without a specified pixel size are given one computed from
555 any specified point size (default 12), dpi (default 75) and scale (default
560 FcPattern *FcNameParse (const char *name)
561 Converts 'name' from the standard text format described above into a pattern.
564 FcChar8 *FcNameUnparse (FcPattern *pat)
565 Converts the given pattern into the standard text format described above.
566 The return value is not static, but instead refers to newly allocated memory
567 which should be freed by the caller.
570 An FcFontSet simply holds a list of patterns; these are used to return the
571 results of listing available fonts.
573 FcFontSet *FcFontSetCreate (void)
574 Creates an empty font set.
577 void FcFontSetDestroy (FcFontSet *s);
578 Destroys a font set. Note that this destroys any referenced patterns as
582 FcBool FcFontSetAdd (FcFontSet *s, FcPattern *font)
583 Adds a pattern to a font set. Note that the pattern is not copied before
584 being inserted into the set.
587 An FcObjectSet holds a list of pattern property names; it is used to
588 indiciate which properties are to be returned in the patterns from
592 FcObjectSet *FcObjectSetCreate (void)
593 Creates an empty set.
596 FcBool FcObjectSetAdd (FcObjectSet *os, const char *object)
597 Adds a proprety name to the set.
600 void FcObjectSetDestroy (FcObjectSet *os)
601 Destroys an object set.
605 FcObjectSet *FcObjectSetBuild (const char *first, ...)
607 FcObjectSet *FcObjectSetVaBuild (const char *first, va_list va)
608 These build an object set from a null-terminated list of property names.
611 An FcBlanks object holds a list of Unicode chars which are expected to
612 be blank when drawn. When scanning new fonts, any glyphs which are
613 empty and not in this list will be assumed to be broken and not placed in
614 the FcCharSet associated with the font. This provides a significantly more
615 accurate CharSet for applications.
618 FcBlanks *FcBlanksCreate (void)
619 Creates an empty FcBlanks object.
622 void FcBlanksDestroy (FcBlanks *b)
623 Destroys an FcBlanks object, freeing any associated memory.
626 FcBool FcBlanksAdd (FcBlanks *b, FcChar32 ucs4)
627 Adds a single character to an FcBlanks object, returning FcFalse
628 if this process ran out of memory.
631 FcBool FcBlanksIsMember (FcBlanks *b, FcChar32 ucs4)
632 Returns whether the specified FcBlanks object contains the indicated Unicode
636 An FcConfig object holds the internal representation of a configuration.
637 There is a default configuration which applications may use by passing 0 to
638 any function using the data within an FcConfig.
641 FcConfig *FcConfigCreate (void)
642 Creates an empty configuration.
645 void FcConfigDestroy (FcConfig *config)
646 Destroys a configuration and any data associated with it. Note that calling
647 this function with the return from FcConfigGetCurrent will place the library
648 in an indeterminate state.
651 FcBool FcConfigSetCurrent (FcConfig *config)
652 Sets the current default configuration to 'config'. Implicitly calls
653 FcConfigBuildFonts if necessary, returning FcFalse if that call fails.
656 FcConfig *FcConfigGetCurrent (void)
657 Returns the current default configuration.
660 FcBool FcConfigBuildFonts (FcConfig *config)
661 Builds the set of available fonts for the given configuration. Note that
662 any changes to the configuration after this call have indeterminate effects.
663 Returns FcFalse if this operation runs out of memory.
666 char **FcConfigGetDirs (FcConfig *config)
667 Returns the list of font directories specified in 'config'.
670 char **FcConfigGetConfigFiles (FcConfig *config)
671 Returns the list of known configuration files used to generate 'config'.
672 Note that this will not include any configuration done with FcConfigParse.
675 char *FcConfigGetCache (FcConfig *config)
676 Returns the name of the file used to store per-user font information.
679 FcFontSet *FcConfigGetFonts (FcConfig *config, FcSetName set)
680 Returns one of the two sets of fonts from the configuration as specified
684 FcBlanks *FcConfigGetBlanks (FcConfig *config)
685 Returns the FcBlanks object associated with the given configuration, if no
686 blanks were present in the configuration, this function will return 0.
689 FcBool FcConfigAppFontAddFile (FcConfig *config, const char *file)
690 Adds an application-specific font to the configuration.
693 FcBool FcConfigAppFontAddDir (FcConfig *config, const char *dir)
694 Scans the specified directory for fonts, adding each one found to the
695 application-specific set of fonts.
698 void FcConfigAppFontClear (FcConfig *config)
699 Clears the set of application-specific fonts.
702 FcBool FcConfigSubstitute (FcConfig *config, FcPattern *p, FcMatchKind kind)
703 Performs the sequence of pattern modification operations, if 'kind' is
704 FcMatchPattern, then those tagged as pattern operations are applied, else
705 if 'kind' is FcMatchFont, those tagged as font operations are applied.
708 FcPattern *FcFontMatch (FcConfig *config, FcPattern *p, FcResult *result)
709 Returns the font in 'config' most close matching 'p'. This function
710 should be called only after FcConfigSubstitute and FcDefaultSubstitute have
711 been called; otherwise the results will be less useful.
714 FcFontSet *FcFontList (FcConfig *config, FcPattern *p, FcObjectSet *os)
715 Selects fonts matching 'p', creates patterns from those fonts containing
716 only the objects in 'os' and returns the set of unique such patterns.
719 char *FcConfigFilename (const char *name)
720 Given the specified external entity name, return the associated filename.
721 This provides applications a way to convert various configuration file
722 references into filename form.
724 A null or empty 'name' indicates that the default configuration file should
725 be used; which file this references can be overridden with the
726 FC_CONFIG_FILE environment variable. Next, if the name starts with '~', it
727 refers to a file in the current users home directory. Otherwise if the name
728 doesn't start with '/', it refers to a file in the default configuration
729 directory; the built-in default directory can be overridden with the
730 FC_CONFIG_DIR environment variable.
733 These functions provide some control over how the library is initialized.
736 FcBool FcInitConfig (void)
737 Initializes the default configuration using the default configuration file
740 FcBool FcInitFonts (void)
741 Initializes the set of fonts available in the default configuration
745 Calls FcInitConfig and FcInitFonts to completely initialize the default
748 .SS FreeType specific functions
750 .B #include <fontconfig/fcfreetype.h>
752 While the fontconfig library doesn't insist that FreeType be used as the
753 rasterization mechanism for fonts, it does provide some convenience
757 FT_UInt FcFreeTypeCharIndex (FT_Face face, FcChar32 ucs4)
758 Maps a Unicode char to a glyph index. This function uses information from
759 several possible underlying encoding tables to work around broken fonts.
760 As a result, this function isn't designed to be used in performance
761 sensitive areas; results from this function are intended to be cached by
762 higher level functions.
765 FcCharSet *FcFreeTypeCharSet (FT_Face face, FcBlanks *blanks) Scans a
766 FreeType face and returns the set of encoded Unicode chars. This scans
767 several encoding tables to build as complete a list as possible. If
768 'blanks' is not 0, the glyphs in the font are examined and any blank glyphs
769 not in 'blanks' are not placed in the returned FcCharSet.
772 FcPattern *FcFreeTypeQuery (const char *file, int id, FcBlanks *blanks, int *count)
773 Constructs a pattern representing the 'id'th font in 'file'. The number
774 of fonts in 'file' is returned in 'count'.
776 .SS XML specific functions
778 .B #include <fontconfig/fcxml.h>
780 These functions expose the libxml2 datatypes used for font configuration.
783 xmlDocPtr FcConfigLoad (const char *file)
784 Loads a configuration file mapping 'file' into a filename with
785 FcConfigFilename. This doesn't load a complete configuration as any
786 include files referenced from 'file' will not be loaded.
789 FcBool FcConfigParse (FcConfig *config, xmlDocPtr doc)
790 Walks the given configuration and constructs the internal representation in
791 'config'. Any include files referenced from within 'doc' will be loaded
792 with FcConfigLoad and also parsed.
794 .SS File and Directory routines
797 FcBool FcFileScan (FcFontSet *set, FcFileCache *cache, FcBlanks *blanks, const char *file, FcBool force)
798 Scans a single file and adds all fonts found to 'set'. If 'force' is FcTrue,
799 then the file is scanned even if associated information is found in 'cache'.
802 FcBool FcDirScan (FcFontSet *set, FcFileCache *cache, FcBlanks *blanks, const char *dir, FcBool force)
803 Scans an entire directory and adds all fonts found to 'set'. If 'force' is
804 FcTrue, then the directory and all files within it are scanned even if
805 information is present in the per-directory cache file or 'cache'.
808 FcBool FcDirSave (FcFontSet *set, const char *dir)
809 Creates the per-directory cache file for 'dir' and populates it with the
815 int FcUtf8ToUcs4 (FcChar8 *src, FcChar32 *dst, int len)
816 Converts the next Unicode char from 'src' into 'dst' and returns the number
817 of bytes containing the char. 'src' nust be at least 'len' bytes long.
820 FcBool FcUtf8Len (FcChar8 *string, int len, int *nchar, int *wchar)
821 Counts the number of Unicode chars in 'len' bytes of 'string'. Places that
822 count in 'nchar'. 'wchar' contains 1, 2 or 4 depending on the number of
823 bytes needed to hold the largest unicode char counted. The return value
824 indicates whether 'string' is a well-formed UTF8 string.
827 char *FcStrCopy (const char *s)
828 Allocates memory, copies 's' and returns the resulting buffer. Yes, this is
829 'strdup', but that function isn't available on every platform.
832 int FcStrCmpIgnoreCase (const char *s1, const char *s2)
833 Returns the usual <0, 0, >0 result of comparing 's1' and 's2'. This test
834 is case-insensitive in the ASCII range and will operate properly with UTF8
835 encoded strings, although it does not check for well formed strings.
837 .SH CONFIGURATION FILE FORMAT
838 Configuration files for fontconfig are stored in XML format; this
839 format makes external configuration tools easier to write and ensures that
840 they will generate syntactically correct configuration files. As XML
841 files are plain text, they can also be manipulated by the expert user using
844 The fontconfig document type definition resides in the external entity
845 "fonts.dtd"; this is normally stored in the default font configuration
846 directory (/etc/fonts). Each configuration file should contain the
850 <?xml version="1.0"?>
851 <!DOCTYPE fontconfig SYSTEM "fonts.dtd">
858 This is the top level element for a font configuration and can contain
859 <dir>, <cache>, <include>, <match> and <alias> elements in any order.
862 This element contains a directory name which will be scanned for font files
863 to include in the set of available fonts.
866 This element contains a file name for the per-user cache of font
867 information. If it starts with '~', it refers to a file in the users
868 home directory. This file is used to hold information about fonts that
869 isn't present in the per-directory cache files. It is automatically
870 maintained by the fontconfig library. The default for this file
871 is ``~/.fonts.cache''.
873 .SS <include ignore_missing="no">
874 This element contains the name of an additional configuration file. When
875 the XML datatype is traversed by FcConfigParse, the contents of the file
876 will also be incorporated into the configuration by passing the filename to
877 FcConfigLoadAndParse. If 'ignore_missing' is set to "yes" instead of the
878 default "no", a missing file will elicit no warning message from the library.
880 .SS <match target="pattern">
881 This element holds first a (possibly empty) list of tests and then a
882 (possibly empty) list of edits. Patterns which match all of the tests are
883 subjected to all the edits. If 'target' is set to "font" instead of the
884 default "pattern", then this element applies to the font name resulting from
885 a match rather than a font pattern to be matched.
887 .SS <test qual="any" name="property" compare="eq">
888 This element contains a single value which is compared with the pattern
889 property "property" (substitute any of the property names seen above).
890 'compare' can be one of "eq", "not_eq", "less", "less_eq", "more", or
891 "more_eq". 'qual' may either be the default, "any", in which case the match
892 succeeds if any value associated with the property matches the test value, or
893 "all", in which case all of the values associated with the property must
894 match the test value.
896 .SS <edit name="property" mode="assign">
897 This element contains a list of expression elements (any of the value or
898 operator elements). The expression elements are evaluated at run-time and
899 modify the property "property". The modification depends on whether
900 "property" was matched by one of the associated <test> elements, if so, the
901 modification may affect the first matched value. 'mode' is one of:
905 Mode Operation with match Operation without match
907 "assign" Replace matching value Replace all values
908 "assign_replace" Replace all values Replace all values
909 "prepend" Insert before matching value Insert at head of list
910 "prepend_first" Insert at head of list Insert at head of list
911 "append" Append after matching value Append at end of list
912 "append_last" Append at end of list Append at end of list
920 These elements hold a single value of the indicated type. <bool> elements
921 hold either true or false.
923 This element holds the four <double> elements of an affine transformation.
925 Holds a property name. Evaluates to the first value from the property of
926 the font, not the pattern.
928 Holds the name of a constant; these are always integers and serve as
929 symbolic names for common font values:
935 Constant Property CPP symbol
937 light weight FC_WEIGHT_LIGHT
938 medium weight FC_WEIGHT_MEDIUM
939 demibold weight FC_WEIGHT_DEMIBOLD
940 bold weight FC_WEIGHT_BOLD
941 black weight FC_WEIGHT_BLACK
942 roman slant FC_SLANT_ROMAN
943 italic slant FC_SLANT_ITALIC
944 oblique slant FC_SLANT_OBLIQUE
945 proportional spacing FC_PROPORTIONAL
947 charcell spacing FC_CHARCELL
950 vrgb rgba FC_RGBA_VRGB
951 vbgr rgba FC_RGBA_VBGR
961 These elements perform the specified operation on a list of expression
962 elements. <or> and <and> are boolean, not bitwise.
969 These elements compare two values, producing a boolean result.
971 Inverts the boolean sense of its one expression element
973 This element takes three expression elements; if the value of the first is
974 true, it produces the value of the second, otherwise it produces the value
977 Alias elements provide a shorthand notation for the set of common match
978 operations needed to substitute one font family for another. They contain a
979 <family> element followed by optional <prefer>, <accept> and <default>
980 elements. Fonts matching the <family> element are edited to prepend the
981 list of <prefer>ed families before the matching <family>, append the
982 <accept>able familys after the matching <family> and append the <default>
983 families to the end of the family list.
985 Holds a single font family name
989 These hold a list of <family> elements to be used by the <alias> element.
990 .SH EXAMPLE CONFIGURATION FILE
991 .SS System configuration file
992 This is an example of a system-wide configuration file
995 <?xml version="1.0"?>
996 <!DOCTYPE fontconfig SYSTEM "fonts.dtd">
997 <!-- /etc/fonts/fonts.conf file to configure system font access -->
1000 Find fonts in these directories
1002 <dir>/usr/X11R6/lib/X11/fonts/truetype</dir>
1003 <dir>/usr/X11R6/lib/X11/fonts/Type1</dir>
1006 Accept deprecated 'mono' alias, replacing it with 'monospace'
1008 <match target="pattern">
1009 <test qual="any" name="family"><string>mono</string></test>
1010 <edit name="family" mode="assign"><string>monospace</string></edit>
1014 Names not including any well known alias are given 'sans'
1016 <match target="pattern">
1017 <test qual="all" name="family" mode="not_eq">sans</test>
1018 <test qual="all" name="family" mode="not_eq">serif</test>
1019 <test qual="all" name="family" mode="not_eq">monospace</test>
1020 <edit name="family" mode="append_last"><string>sans</string></edit>
1024 Load per-user customization file, but don't complain
1027 <include ignore_missing="yes">~/.fonts.conf</include>
1030 Alias well known font names to available TrueType fonts.
1031 These substitute TrueType faces for similar Type1
1032 faces to improve screen appearance.
1035 <family>Times</family>
1036 <prefer><family>Times New Roman</family></prefer>
1037 <default><family>serif</family></default>
1040 <family>Helvetica</family>
1041 <prefer><family>Verdana</family></prefer>
1042 <default><family>sans</family></default>
1045 <family>Courier</family>
1046 <prefer><family>Courier New</family></prefer>
1047 <default><family>monospace</family></default>
1051 Provide required aliases for standard names
1052 Do these after the users configuration file so that
1053 any aliases there are used preferentially
1056 <family>serif</family>
1057 <prefer><family>Times New Roman</family></prefer>
1060 <family>sans</family>
1061 <prefer><family>Verdana</family></prefer>
1064 <family>monospace</family>
1065 <prefer><family>Andale Mono</family></prefer>
1069 .SS User configuration file
1070 This is an example of a per-user configuration file that lives in
1074 <?xml version="1.0"?>
1075 <!DOCTYPE fontconfig SYSTEM "fonts.dtd">
1076 <!-- ~/.fonts.conf for per-user font configuration -->
1080 Private font directory
1082 <dir>~/misc/fonts</dir>
1085 use rgb sub-pixel ordering to improve glyph appearance on
1086 LCD screens. Changes affecting rendering, but not matching
1087 should always use target="font".
1089 <match target="font">
1090 <edit name="rgba" mode="assign"><const>rgb</const></edit>
1096 contains configuration information for the fontconfig library
1097 consisting of directories to look at for font information as well as
1098 instructions on editing program specified font patterns before attempting to
1099 match the available fonts. It is in xml format.
1102 is a DTD that describes the format of the configuration files.
1105 is the conventional location for per-user font configuration, although the
1106 actual location is specified in the global fonts.conf file.
1109 is the conventional repository of font information that isn't found in the
1110 per-directory caches. This file is automatically maintained by fontconfig.
1113 Keith Packard, member of the XFree86 Project, Inc.
git.wh0rd.org / fontconfig.git / blob