1263 lines
55 KiB
Plaintext
1263 lines
55 KiB
Plaintext
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
|
|
<!--
|
|
$Id$
|
|
|
|
Copyright © 2002 Keith Packard
|
|
|
|
Permission to use, copy, modify, distribute, and sell this software and its
|
|
documentation for any purpose is hereby granted without fee, provided that
|
|
the above copyright notice appear in all copies and that both that
|
|
copyright notice and this permission notice appear in supporting
|
|
documentation, and that the name of Keith Packard not be used in
|
|
advertising or publicity pertaining to distribution of the software without
|
|
specific, written prior permission. Keith Packard makes no
|
|
representations about the suitability of this software for any purpose. It
|
|
is provided "as is" without express or implied warranty.
|
|
|
|
KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
|
|
INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
|
|
EVENT SHALL KEITH PACKARD BE LIABLE FOR ANY SPECIAL, INDIRECT OR
|
|
CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
|
|
DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
|
|
TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
|
|
PERFORMANCE OF THIS SOFTWARE.
|
|
-->
|
|
<article>
|
|
<artheader>
|
|
<title>Fontconfig Developers Guide</title>
|
|
<titleabbrev>Fontconfig</titleabbrev>
|
|
<author><firstname>Keith</><surname>Packard</></author>
|
|
<authorinitials>krp</authorinitials>
|
|
</artheader>
|
|
<sect1><title>NAME</title>
|
|
<para>
|
|
fontconfig - Font configuration and customization library
|
|
</para>
|
|
</sect1>
|
|
<sect1><title>SYNOPSIS</title>
|
|
<programlisting>
|
|
#include <fontconfig/fontconfig.h>
|
|
#include <fontconfig/fcfreetype.h>
|
|
</programlisting>
|
|
</sect1>
|
|
<sect1><title>DESCRIPTION</title>
|
|
<para>
|
|
Fontconfig is a library designed to provide system-wide font configuration,
|
|
customization and application access.
|
|
</para>
|
|
</sect1>
|
|
<sect1><title>FUNCTIONAL OVERVIEW</title>
|
|
<para>
|
|
Fontconfig contains two essential modules, the configuration module which
|
|
builds an internal configuration from XML files and the matching module
|
|
which accepts font patterns and returns the nearest matching font.
|
|
</para>
|
|
<sect2><title>FONT CONFIGURATION</title>
|
|
<para>
|
|
The configuration module consists of the FcConfig datatype, libexpat and
|
|
FcConfigParse which walks over an XML tree and ammends a configuration with
|
|
data found within. From an external perspective, configuration of the
|
|
library consists of generating a valid XML tree and feeding that to
|
|
FcConfigParse. The only other mechanism provided to applications for
|
|
changing the running configuration is to add fonts and directories to the
|
|
list of application-provided font files.
|
|
</para><para>
|
|
The intent is to make font configurations relatively static, and shared by
|
|
as many applications as possible. It is hoped that this will lead to more
|
|
stable font selection when passing names from one application to another.
|
|
XML was chosen as a configuration file format because it provides a format
|
|
which is easy for external agents to edit while retaining the correct
|
|
structure and syntax.
|
|
</para><para>
|
|
Font configuration is separate from font matching; applications needing to
|
|
do their own matching can access the available fonts from the library and
|
|
perform private matching. The intent is to permit applications to pick and
|
|
choose appropriate functionality from the library instead of forcing them to
|
|
choose between this library and a private configuration mechanism. The hope
|
|
is that this will ensure that configuration of fonts for all applications
|
|
can be centralized in one place. Centralizing font configuration will
|
|
simplify and regularize font installation and customization.
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>FONT PROPERTIES</title>
|
|
<para>
|
|
While font patterns may contain essentially any properties, there are some
|
|
well known properties with associated types. Fontconfig uses some of these
|
|
properties for font matching and font completion. Others are provided as a
|
|
convenience for the applications rendering mechanism.
|
|
</para>
|
|
<table>
|
|
<title>Property Definitions</title>
|
|
<tgroup cols=4 align=left colsep=1 rowsep=1>
|
|
<colspec colname=Property>
|
|
<colspec colname=CPP>
|
|
<colspec colname=Type>
|
|
<colspec colname=Description>
|
|
<thead>
|
|
<row>
|
|
<entry>Property</entry>
|
|
<entry>CPP Symbol</entry>
|
|
<entry>Type</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row><entry>family</entry><entry>FC_FAMILY</entry><entry>String</entry><entry>Font family name</entry></row>
|
|
<row><entry>style</entry><entry>FC_STYLE</entry><entry>String</entry><entry>Font style. Overrides weight and slant</entry></row>
|
|
<row><entry>slant</entry><entry>FC_SLANT</entry><entry>Int</entry><entry>Italic, oblique or roman</entry></row>
|
|
<row><entry>weight</entry><entry>FC_WEIGHT</entry><entry>Int</entry><entry>Light, medium, demibold, bold or black</entry></row>
|
|
<row><entry>size</entry><entry>FC_SIZE</entry><entry>Double</entry><entry>Point size</entry></row>
|
|
<row><entry>aspect</entry><entry>FC_ASPECT</entry><entry>Double</entry><entry>Stretches glyphs horizontally before hinting</entry></row>
|
|
<row><entry>pixelsize</entry><entry>FC_PIXEL_SIZE</entry><entry>Double</entry><entry>Pixel size</entry></row>
|
|
<row><entry>spacing</entry><entry>FC_SPACING</entry><entry>Int</entry><entry>Proportional, monospace or charcell</entry></row>
|
|
<row><entry>foundry</entry><entry>FC_FOUNDRY</entry><entry>String</entry><entry>Font foundry name</entry></row>
|
|
<row><entry>antialias</entry><entry>FC_ANTIALIAS</entry><entry>Bool</entry><entry>Whether glyphs can be antialiased</entry></row>
|
|
<row><entry>hinting</entry><entry>FC_HINTING</entry><entry>Bool</entry><entry>Whether the rasterizer should use hinting</entry></row>
|
|
<row><entry>verticallayout</entry><entry>FC_VERTICAL_LAYOUT</entry><entry>Bool</entry><entry>Use vertical layout</entry></row>
|
|
<row><entry>autohint</entry><entry>FC_AUTOHINT</entry><entry>Bool</entry><entry>Use autohinter instead of normal hinter</entry></row>
|
|
<row><entry>globaladvance</entry><entry>FC_GLOBAL_ADVANCE</entry><entry>Bool</entry><entry>Use font global advance data</entry></row>
|
|
<row><entry>file</entry><entry>FC_FILE</entry><entry>String</entry><entry>The filename holding the font</entry></row>
|
|
<row><entry>index</entry><entry>FC_INDEX</entry><entry>Int</entry><entry>The index of the font within the file</entry></row>
|
|
<row><entry>ftface</entry><entry>FC_FT_FACE</entry><entry>FT_Face</entry><entry>Use the specified FreeType face object</entry></row>
|
|
<row><entry>rasterizer</entry><entry>FC_RASTERIZER</entry><entry>String</entry><entry>Which rasterizer is in use</entry></row>
|
|
<row><entry>outline</entry><entry>FC_OUTLINE</entry><entry>Bool</entry><entry>Whether the glyphs are outlines</entry></row>
|
|
<row><entry>scalable</entry><entry>FC_SCALABLE</entry><entry>Bool</entry><entry>Whether glyphs can be scaled</entry></row>
|
|
<row><entry>scale</entry><entry>FC_SCALE</entry><entry>Double</entry><entry>Scale factor for point->pixel conversions</entry></row>
|
|
<row><entry>dpi</entry><entry>FC_DPI</entry><entry>Double</entry><entry>Target dots per inch</entry></row>
|
|
<row><entry>rgba</entry><entry>FC_RGBA</entry><entry>Int</entry><entry>unknown, rgb, bgr, vrgb, vbgr, none - subpixel geometry</entry></row>
|
|
<row><entry>minspace</entry><entry>FC_MINSPACE</entry><entry>Bool</entry><entry>Eliminate leading from line spacing</entry></row>
|
|
<row><entry>charset</entry><entry>FC_CHARSET</entry><entry>CharSet</entry><entry>Unicode chars encoded by the font</entry></row>
|
|
<row><entry>lang</entry><entry>FC_LANG</entry><entry>String</entry><entry>List of RFC-3066-style languages this font supports</entry></row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1><title>DATATYPES</title>
|
|
<para>
|
|
Fontconfig uses abstract datatypes to hide internal implementation details
|
|
for most data structures. A few structures are exposed where appropriate.
|
|
</para>
|
|
<sect2><title>FcChar8, FcChar16, FcChar32, FcBool</title>
|
|
<para>
|
|
These are primitive datatypes; the FcChar* types hold precisely the number
|
|
of bits stated (if supported by the C implementation). FcBool holds
|
|
one of two CPP symbols: FcFalse or FcTrue.
|
|
</para>
|
|
</sect2>
|
|
<sect2><title>FcMatrix</title>
|
|
<para>
|
|
An FcMatrix holds an affine transformation, usually used to reshape glyphs.
|
|
A small set of matrix operations are provided to manipulate these.
|
|
<programlisting>
|
|
typedef struct _FcMatrix {
|
|
double xx, xy, yx, yy;
|
|
} FcMatrix;
|
|
</programlisting>
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>FcCharSet</title>
|
|
<para>
|
|
An FcCharSet is an abstract type that holds the set of encoded unicode chars
|
|
in a font. Operations to build and compare these sets are provided.
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>FcType</title>
|
|
<para>
|
|
Tags the kind of data stored in an FcValue.
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>FcValue</title>
|
|
<para>
|
|
An FcValue object holds a single value with one of a number of different
|
|
types. The 'type' tag indicates which member is valid.
|
|
<programlisting>
|
|
typedef struct _FcValue {
|
|
FcType type;
|
|
union {
|
|
const FcChar8 *s;
|
|
int i;
|
|
FcBool b;
|
|
double d;
|
|
const FcMatrix *m;
|
|
const FcCharSet *c;
|
|
} u;
|
|
} FcValue;
|
|
</programlisting>
|
|
<table colsep=0 rowsep=0>
|
|
<title>FcValue Members</title>
|
|
<tgroup cols=3 align=left colsep=0 rowsep=0>
|
|
<thead><row>
|
|
<entry>Type</entry>
|
|
<entry>Union member</entry>
|
|
<entry>Datatype</entry>
|
|
</row></thead>
|
|
<tbody>
|
|
<row><entry>FcTypeVoid</entry><entry>(none)</entry><entry>(none)</entry></row>
|
|
<row><entry>FcTypeInteger</entry><entry>i</entry><entry>int</entry></row>
|
|
<row><entry>FcTypeDouble</entry><entry>d</entry><entry>double</entry></row>
|
|
<row><entry>FcTypeString</entry><entry>s</entry><entry>char *</entry></row>
|
|
<row><entry>FcTypeBool</entry><entry>b</entry><entry>b</entry></row>
|
|
<row><entry>FcTypeMatrix</entry><entry>m</entry><entry>FcMatrix *</entry></row>
|
|
<row><entry>FcTypeCharSet</entry><entry>c</entry><entry>FcCharSet *</entry></row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>FcPattern</title>
|
|
<para>
|
|
holds a set of names with associated value lists; each name refers to a
|
|
property of a font. FcPatterns are used as inputs to the matching code as
|
|
well as holding information about specific fonts. Each property can hold
|
|
one or more values; conventionally all of the same type, although the
|
|
interface doesn't demand that.
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>FcFontSet</title>
|
|
<para>
|
|
<programlisting>
|
|
typedef struct _FcFontSet {
|
|
int nfont;
|
|
int sfont;
|
|
FcPattern **fonts;
|
|
} FcFontSet;
|
|
</programlisting>
|
|
An FcFontSet contains a list of FcPatterns. Internally fontconfig uses this
|
|
data structure to hold sets of fonts. Externally, fontconfig returns the
|
|
results of listing fonts in this format. 'nfont' holds the number of
|
|
patterns in the 'fonts' array; 'sfont' is used to indicate the size of that
|
|
array.
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>FcStrSet, FcStrList</title>
|
|
<para>
|
|
FcStrSet holds a list of strings that can be appended to and enumerated.
|
|
Its unique characteristic is that the enumeration works even while strings
|
|
are appended during enumeration. FcStrList is used during enumeration to
|
|
safely and correctly walk the list of strings even while that list is edited
|
|
in the middle of enumeration.
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>FcObjectSet</title>
|
|
<para>
|
|
<programlisting>
|
|
typedef struct _FcObjectSet {
|
|
int nobject;
|
|
int sobject;
|
|
const char **objects;
|
|
} FcObjectSet;
|
|
</programlisting>
|
|
holds a set of names and is used to specify which fields from fonts are
|
|
placed in the the list of returned patterns when listing fonts.
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>FcObjectType</title>
|
|
<para>
|
|
<programlisting>
|
|
typedef struct _FcObjectType {
|
|
const char *object;
|
|
FcType type;
|
|
} FcObjectType;
|
|
</programlisting>
|
|
marks the type of a pattern element generated when parsing font names.
|
|
Applications can add new object types so that font names may contain the new
|
|
elements.
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>FcConstant</title>
|
|
<para>
|
|
<programlisting>
|
|
typedef struct _FcConstant {
|
|
const FcChar8 *name;
|
|
const char *object;
|
|
int value;
|
|
} FcConstant;
|
|
</programlisting>
|
|
Provides for symbolic constants for new pattern elements. When 'name' is
|
|
seen in a font name, an 'object' element is created with value 'value'.
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>FcBlanks</title>
|
|
<para>
|
|
holds a list of Unicode chars which are expected to be blank; unexpectedly
|
|
blank chars are assumed to be invalid and are elided from the charset
|
|
associated with the font.
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>FcFileCache</title>
|
|
<para>
|
|
holds the per-user cache information for use while loading the font
|
|
database. This is built automatically for the current configuration when
|
|
that is loaded. Applications must always pass '0' when one is requested.
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>FcConfig</title>
|
|
<para>
|
|
holds a complete configuration of the library; there is one default
|
|
configuration, other can be constructed from XML data structures. All
|
|
public entry points that need global data can take an optional FcConfig*
|
|
argument; passing 0 uses the default configuration. FcConfig objects hold two
|
|
sets of fonts, the first contains those specified by the configuration, the
|
|
second set holds those added by the application at run-time. Interfaces
|
|
that need to reference a particulat set use one of the FcSetName enumerated
|
|
values.
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>FcSetName</title>
|
|
<para>
|
|
Specifies one of the two sets of fonts available in a configuration;
|
|
FcSetSystem for those fonts specified in the configuration and
|
|
FcSetApplication which holds fonts provided by the application.
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>FcResult</title>
|
|
<para>
|
|
Used as a return type for functions manipulating FcPattern objects.
|
|
<table colsep=0 rowsep=0>
|
|
<title>FcResult Values</title>
|
|
<tgroup cols=2 align=left colsep=0 rowsep=0>
|
|
<thead><row>
|
|
<entry>Result Code</entry>
|
|
<entry>Meaning</entry>
|
|
</row></thead>
|
|
<tbody>
|
|
<row><entry>FcResultMatch</entry><entry>Object exists with the specified ID</entry></row>
|
|
<row><entry>FcResultNoMatch</entry><entry>Object doesn't exist at all</entry></row>
|
|
<row><entry>FcResultTypeMismatch</entry><entry>Object exists, but the type doesn't match</entry></row>
|
|
<row><entry>FcResultNoId</entry><entry>Object exists, but has fewer values than specified</entry></row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>FcAtomic</title>
|
|
<para>
|
|
Used for locking access to config files. Provides a safe way to update
|
|
configuration files.
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1><title>FUNCTIONS</title>
|
|
<para>
|
|
Functions are grouped by the main datatype involved
|
|
</para>
|
|
<sect2><title>FcMatrix</title>
|
|
<para>
|
|
FcMatrix structures hold an affine transformation in matrix form.
|
|
</para>
|
|
<sect3><title>FcMatrixInit</title><programlisting>
|
|
#define FcMatrixInit(m) ((m)->xx = (m)->yy = 1, (m)->xy = (m)->yx = 0)
|
|
</programlisting><para>
|
|
Initializes a matrix to the identify transformation.
|
|
</para></sect3>
|
|
<sect3><title>FcMatrixCopy</title><programlisting>
|
|
FcMatrix *FcMatrixCopy (const FcMatrix *mat)
|
|
</programlisting><para>
|
|
Allocates a new FcMatrix and copies 'mat' into it.
|
|
</para></sect3>
|
|
<sect3><title>FcMatrixEqual</title><programlisting>
|
|
FcBool FcMatrixEqual (const FcMatrix *mat1, const FcMatrix *mat2)
|
|
</programlisting><para>
|
|
Returns FcTrue if 'mat1' and 'mat2' are equal, else FcFalse.
|
|
</para></sect3>
|
|
<sect3><title>FcMatrixMultiply</title><programlisting>
|
|
void FcMatrixMultiply (FcMatrix *result, const FcMatrix *a, const FcMatrix *b)
|
|
</programlisting><para>
|
|
Multiplies 'a' and 'b' together, placing the result in 'result'. 'result'
|
|
may refer to the sam matrix as either 'a' or 'b'.
|
|
</para></sect3>
|
|
<sect3><title>FcMatrixRotate</title><programlisting>
|
|
void FcMatrixRotate (FcMatrix *m, double c, double s)
|
|
</programlisting><para>
|
|
If 'c' is cos(angle) and 's' is sin(angle), FcMatrixRotate rotates the
|
|
matrix by 'angle'.
|
|
</para></sect3>
|
|
<sect3><title>FcMatrixScale</title><programlisting>
|
|
void FcMatrixScale (FcMatrix *m, double sx, double sy)
|
|
</programlisting><para>
|
|
Scales 'm' by 'sx' in the horizontal dimension and 'sy' in the
|
|
vertical dimension.
|
|
</para></sect3>
|
|
<sect3><title>FcMatrixShear</title><programlisting>
|
|
void FcMatrixShear (FcMatrix *m, double sh, double sv)
|
|
</programlisting><para>
|
|
Shears 'm' by 'sh' in the horizontal direction and 'sv' in the
|
|
vertical direction.
|
|
</para></sect3>
|
|
</sect2>
|
|
<sect2><title>FcCharSet</title>
|
|
<para>
|
|
An FcCharSet is a boolean array indicating a set of unicode chars. Those
|
|
associated with a font are marked constant and cannot be edited.
|
|
FcCharSets may be reference counted internally to reduce memory consumption;
|
|
this may be visible to applications as the result of FcCharSetCopy may
|
|
return it's argument, and that CharSet may remain unmodifiable.
|
|
</para>
|
|
<sect3><title>FcCharSetCreate</title><programlisting>
|
|
FcCharSet *FcCharSetCreate (void)
|
|
</programlisting><para>
|
|
Creates an empty FcCharSet object.
|
|
</para></sect3>
|
|
<sect3><title>FcCharSetDestroy</title><programlisting>
|
|
void FcCharSetDestroy (FcCharSet *fcs)
|
|
</programlisting><para>
|
|
Frees an FcCharSet object.
|
|
</para></sect3>
|
|
<sect3><title>FcCharSetAddChar</title><programlisting>
|
|
FcBool FcCharSetAddChar (FcCharSet *fcs, FcChar32 ucs4)
|
|
</programlisting><para>
|
|
Adds a single unicode char to the set, returning FcFalse on
|
|
failure, either as a result of a constant set or from running out of memory.
|
|
</para></sect3>
|
|
<sect3><title>FcCharSetCopy</title><programlisting>
|
|
FcCharSet *FcCharSetCopy (FcCharSet *src)
|
|
</programlisting><para>
|
|
Makes a copy of 'src'; note that this may not actually do anything more than
|
|
increment the reference count on 'src'.
|
|
</para></sect3>
|
|
<sect3><title>FcCharSetEqual</title><programlisting>
|
|
FcBool FcCharSetEqual (const FcCharSet *a, const FcCharSet *b)
|
|
</programlisting><para>
|
|
Returns whether 'a' and 'b' contain the same set of unicode chars.
|
|
</para></sect3>
|
|
<sect3><title>FcCharSetIntersect</title><programlisting>
|
|
FcCharSet *FcCharSetIntersect (const FcCharSet *a, const FcCharSet *b)
|
|
</programlisting><para>
|
|
Returns a set including only those chars found in both 'a' and 'b'.
|
|
</para></sect3>
|
|
<sect3><title>FcCharSetUnion</title><programlisting>
|
|
FcCharSet *FcCharSetUnion (const FcCharSet *a, const FcCharSet *b);
|
|
</programlisting><para>
|
|
Returns a set including only those chars found in either 'a' or 'b'.
|
|
</para></sect3>
|
|
<sect3><title>FcCharSetSubtract</title><programlisting>
|
|
FcCharSet *FcCharSetSubtract (const FcCharSet *a, const FcCharSet *b)
|
|
</programlisting><para>
|
|
Returns a set including only those chars found in 'a' but not 'b'.
|
|
</para></sect3>
|
|
<sect3><title>FcCharSetHasChar</title><programlisting>
|
|
FcBool FcCharSetHasChar (const FcCharSet *fcs, FcChar32 ucs4)
|
|
</programlisting><para>
|
|
Returns whether 'fcs' contains the char 'ucs4'.
|
|
</para></sect3>
|
|
<sect3><title>FcCharSetCount</title><programlisting>
|
|
FcChar32 FcCharSetCount (const FcCharSet *a)
|
|
</programlisting><para>
|
|
Returns the total number of unicode chars in 'a'.
|
|
</para></sect3>
|
|
<sect3><title>FcCharSetIntersectCount</title><programlisting>
|
|
FcChar32 FcCharSetIntersectCount (const FcCharSet *a, const FcCharSet *b)
|
|
</programlisting><para>
|
|
Returns the number of chars that are in both 'a' and 'b'.
|
|
</para></sect3>
|
|
<sect3><title>FcCharSetSubtractCount</title><programlisting>
|
|
FcChar32 FcCharSetSubtractCount (const FcCharSet *a, const FcCharSet *b)
|
|
</programlisting><para>
|
|
Returns the number of chars that are in 'a' but not in 'b'.
|
|
</para></sect3>
|
|
<sect3><title>FcCharSetIsSubset</title><programlisting>
|
|
FcBool FcCharSetIsSubset (const FcCharSet *a, const FcCharSet *b)
|
|
</programlisting><para>
|
|
Returns whether 'a' is a subset of 'b'.
|
|
</para></sect3>
|
|
<sect3><title>FcCharSetFirstPage</title><programlisting>
|
|
FcChar32 FcCharSetFirstPage (const FcCharSet *a, FcChar32 [FC_CHARSET_MAP_SIZE], FcChar32 *next)
|
|
</programlisting><para>
|
|
Builds an array of bits marking the first page of Unicode coverage of 'a'.
|
|
Returns the base of the array. 'next' contains the next page in the font.
|
|
</para></sect3>
|
|
<sect3><title>FcCharSetNextPage</title><programlisting>
|
|
FcChar32 FcCharSetNextPage (const FcCharSet *a, FcChar32 [FC_CHARSET_MAP_SIZE], FcChar32 *next)
|
|
</programlisting><para>
|
|
Builds an array of bits marking the Unicode coverage of 'a' for page '*next'.
|
|
Returns the base of the array. 'next' contains the next page in the font.
|
|
</para></sect3>
|
|
</sect2>
|
|
<sect2><title>FcValue</title>
|
|
<para>
|
|
FcValue is a structure containing a type tag and a union of all possible
|
|
datatypes. The tag is an enum of type
|
|
<emphasis>FcType</emphasis>
|
|
and is intended to provide a measure of run-time
|
|
typechecking, although that depends on careful programming.
|
|
</para>
|
|
<sect3><title>FcValueDestroy</title><programlisting>
|
|
void FcValueDestroy (FcValue v)
|
|
</programlisting><para>
|
|
Frees any memory referenced by `v'. Values of type FcTypeString,
|
|
FcTypeMatrix and FcTypeCharSet reference memory, the other types do not.
|
|
</para></sect3>
|
|
<sect3><title>FcValueSave</title><programlisting>
|
|
FcValue FcValueSave (FcValue v)
|
|
</programlisting><para>
|
|
Returns a copy of `v' duplicating any object referenced by it so that `v'
|
|
may be safely destroyed without harming the new value.
|
|
</para></sect3>
|
|
</sect2>
|
|
<sect2><title>FcPattern</title>
|
|
<para>
|
|
An FcPattern is an opaque type that holds both patterns to match against the
|
|
available fonts, as well as the information about each font.
|
|
</para>
|
|
<sect3><title>FcPatternCreate</title><programlisting>
|
|
FcPattern *FcPatternCreate (void)
|
|
</programlisting><para>
|
|
Creates a pattern with no properties; used to build patterns from scratch.
|
|
</para></sect3>
|
|
<sect3><title>FcPatternDestroy</title><programlisting>
|
|
void FcPatternDestroy (FcPattern *p)
|
|
</programlisting><para>
|
|
Destroys a pattern, in the process destroying all related values.
|
|
</para></sect3>
|
|
<sect3><title>FcPatternEqual</title><programlisting>
|
|
FcBool FcPatternEqual (const FcPattern *pa, const FcPattern *pb);
|
|
</programlisting><para>
|
|
Returns whether 'pa' and 'pb' are exactly alike.
|
|
</para></sect3>
|
|
<sect3><title>FcPatternEqualSubset</title><programlisting>
|
|
FcBool FcPatternEqualSubset (const FcPattern *pa, const FcPattern *pb, const FcObjectSet *os)
|
|
</programlisting><para>
|
|
Returns whether 'pa' and 'pb' have exactly the same values for all of the
|
|
objects in 'os'.
|
|
</para></sect3>
|
|
<sect3><title>FcPatternHash</title><programlisting>
|
|
FcChar32 FcPatternHash (const FcPattern *p)
|
|
</programlisting><para>
|
|
Returns a 32-bit number which is the same for any two patterns which are
|
|
exactly alike.
|
|
</para></sect3>
|
|
<sect3><title>FcPatternAdd</title><programlisting>
|
|
FcBool FcPatternAdd (FcPattern *p, const char *object, FcValue value, FcBool append)
|
|
</programlisting><para>
|
|
Adds a single value to the list of values associated with the property named
|
|
`object'. If `append' is FcTrue, the value is added at the end of any
|
|
existing list, otherwise it is inserted at the begining. `value' is saved
|
|
(with FcValueSave) when inserted into the pattern so that the library
|
|
retains no reference to any application-supplied data structure.
|
|
</para></sect3>
|
|
<sect3><title>FcPatternAddWeak</title><programlisting>
|
|
FcBool FcPatternAddWeak (FcPattern *p, const char *object, FcValue value, FcBool append)
|
|
</programlisting><para>
|
|
FcPatternAddWeak is essentially the same as FcPatternAdd except that any
|
|
values added to the list have binding 'weak' instead of 'strong'.
|
|
</para></sect3>
|
|
<sect3><title>FcPatternAdd <emphasis>Type</emphasis></title><programlisting>
|
|
FcBool FcPatternAddInteger (FcPattern *p, const char *object, int i)
|
|
FcBool FcPatternAddDouble (FcPattern *p, const char *object, double d)
|
|
FcBool FcPatternAddString (FcPattern *p, const char *object, const char *s)
|
|
FcBool FcPatternAddMatrix (FcPattern *p, const char *object, const FcMatrix *s)
|
|
FcBool FcPatternAddCharSet (FcPattern *p, const char *object, const FcCharSet *c)
|
|
FcBool FcPatternAddBool (FcPattern *p, const char *object, FcBool b)
|
|
</programlisting><para>
|
|
These are all convenience functions that insert objects of the specified
|
|
type into the pattern. Use these in preference to FcPatternAdd as they
|
|
will provide compile-time typechecking. These all append values to
|
|
any existing list of values.
|
|
</para></sect3>
|
|
<sect3><title>FcPatternGet</title><programlisting>
|
|
FcResult FcPatternGet (FcPattern *p, const char *object, int id, FcValue *v)
|
|
</programlisting><para>
|
|
Returns in `v' the `id'th value associated with the property `object'.
|
|
The value returned is not a copy, but rather refers to the data stored
|
|
within the pattern directly. Applications must not free this value.
|
|
</para></sect3>
|
|
<sect3><title>FcPatternGet <emphasis>Type</emphasis></title><programlisting>
|
|
FcResult FcPatternGetInteger (FcPattern *p, const char *object, int n, int *i);
|
|
FcResult FcPatternGetDouble (FcPattern *p, const char *object, int n, double *d);
|
|
FcResult FcPatternGetString (FcPattern *p, const char *object, int n, char **const s);
|
|
FcResult FcPatternGetMatrix (FcPattern *p, const char *object, int n, FcMatrix **s);
|
|
FcResult FcPatternGetCharSet (FcPattern *p, const char *object, int n, FcCharSet **c);
|
|
FcResult FcPatternGetBool (FcPattern *p, const char *object, int n, FcBool *b);
|
|
</programlisting><para>
|
|
These are convenience functions that call FcPatternGet and verify that the
|
|
returned data is of the expected type. They return FcResultTypeMismatch if
|
|
this is not the case. Note that these (like FcPatternGet) do not make a
|
|
copy of any data structure referenced by the return value. Use these
|
|
in preference to FcPatternGet to provide compile-time typechecking.
|
|
</para></sect3>
|
|
<sect3><title>FcPatternBuild, FcPatternVaBuild</title><programlisting>
|
|
FcPattern *FcPatternBuild (FcPattern *orig, ...);
|
|
FcPattern *FcPatternVaBuild (FcPattern *orig, va_list va)
|
|
</programlisting><para>
|
|
Builds a pattern using a list of objects, types and values. Each
|
|
value to be entered in the pattern is specified with three arguments:
|
|
</para>
|
|
<orderedlist>
|
|
<listitem><para>
|
|
Object name, a string describing the property to be added.
|
|
</para></listitem><listitem><para>
|
|
Object type, one of the FcType enumerated values
|
|
</para></listitem><listitem><para>
|
|
Value, not an FcValue, but the raw type as passed to any of the
|
|
FcPatternAdd<type> functions. Must match the type of the second
|
|
argument.
|
|
</para></listitem>
|
|
</orderedlist>
|
|
<para>
|
|
The argument list is terminated by a null object name, no object type nor
|
|
value need be passed for this. The values are added to `pattern', if
|
|
`pattern' is null, a new pattern is created. In either case, the pattern is
|
|
returned. Example
|
|
</para>
|
|
<programlisting>
|
|
pattern = FcPatternBuild (0, FC_FAMILY, FtTypeString, "Times", (char *) 0);
|
|
</programlisting>
|
|
<para>
|
|
FcPatternVaBuild is used when the arguments are already in the form of a
|
|
varargs value.
|
|
</para></sect3>
|
|
<sect3><title>FcPatternDel</title><programlisting>
|
|
FcBool FcPatternDel (FcPattern *p, const char *object)
|
|
</programlisting><para>
|
|
Deletes all values associated with the property `object', returning
|
|
whether the property existed or not.
|
|
</para></sect3>
|
|
<sect3><title>FcPatternPrint</title><programlisting>
|
|
void FcPatternPrint (const FcPattern *p)
|
|
</programlisting><para>
|
|
Prints an easily readable version of the pattern to stdout. There is
|
|
no provision for reparsing data in this format, it's just for diagnostics
|
|
and debugging.
|
|
</para></sect3>
|
|
<sect3><title>FcDefaultSubstitute</title><programlisting>
|
|
void FcDefaultSubstitute (FcPattern *pattern)
|
|
</programlisting><para>
|
|
Supplies default values for underspecified font patterns:
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
Patterns without a specified style or weight are set to Medium
|
|
</para></listitem>
|
|
<listitem><para>
|
|
Patterns without a specified style or slant are set to Roman
|
|
</para></listitem>
|
|
<listitem><para>
|
|
Patterns without a specified pixel size are given one computed from any
|
|
specified point size (default 12), dpi (default 75) and scale (default 1).
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</para></sect3>
|
|
<sect3><title>FcNameParse</title><programlisting>
|
|
FcPattern *FcNameParse (const char *name)
|
|
</programlisting><para>
|
|
Converts 'name' from the standard text format described above into a pattern.
|
|
</para></sect3>
|
|
<sect3><title>FcNameUnparse</title><programlisting>
|
|
FcChar8 *FcNameUnparse (FcPattern *pat)
|
|
</programlisting><para>
|
|
Converts the given pattern into the standard text format described above.
|
|
The return value is not static, but instead refers to newly allocated memory
|
|
which should be freed by the caller.
|
|
</para></sect3>
|
|
</sect2>
|
|
<sect2><title>FcFontSet</title>
|
|
<para>
|
|
An FcFontSet simply holds a list of patterns; these are used to return the
|
|
results of listing available fonts.
|
|
</para>
|
|
<sect3><title>FcFontSetCreate</title><programlisting>
|
|
FcFontSet *FcFontSetCreate (void)
|
|
</programlisting><para>
|
|
Creates an empty font set.
|
|
</para></sect3>
|
|
<sect3><title>FcFontSetDestroy</title><programlisting>
|
|
void FcFontSetDestroy (FcFontSet *s);
|
|
</programlisting><para>
|
|
Destroys a font set. Note that this destroys any referenced patterns as
|
|
well.
|
|
</para></sect3>
|
|
<sect3><title>FcFontSetAdd</title><programlisting>
|
|
FcBool FcFontSetAdd (FcFontSet *s, FcPattern *font)
|
|
</programlisting><para>
|
|
Adds a pattern to a font set. Note that the pattern is not copied before
|
|
being inserted into the set.
|
|
</para></sect3>
|
|
</sect2>
|
|
<sect2><title>FcObjectSet</title>
|
|
<para>
|
|
An FcObjectSet holds a list of pattern property names; it is used to
|
|
indiciate which properties are to be returned in the patterns from
|
|
FcFontList.
|
|
</para>
|
|
<sect3><title>FcObjectSetCreate</title><programlisting>
|
|
FcObjectSet *FcObjectSetCreate (void)
|
|
</programlisting><para>
|
|
Creates an empty set.
|
|
</para></sect3>
|
|
<sect3><title>FcObjectSetAdd</title><programlisting>
|
|
FcBool FcObjectSetAdd (FcObjectSet *os, const char *object)
|
|
</programlisting><para>
|
|
Adds a proprety name to the set.
|
|
</para></sect3>
|
|
<sect3><title>FcObjectSetDestroy</title><programlisting>
|
|
void FcObjectSetDestroy (FcObjectSet *os)
|
|
</programlisting><para>
|
|
Destroys an object set.
|
|
</para></sect3>
|
|
<sect3><title>FcObjectSetBuild, FcObjectSetVaBuild</title><programlisting>
|
|
FcObjectSet *FcObjectSetBuild (const char *first, ...)
|
|
FcObjectSet *FcObjectSetVaBuild (const char *first, va_list va)
|
|
</programlisting><para>
|
|
These build an object set from a null-terminated list of property names.
|
|
</para></sect3>
|
|
</sect2>
|
|
<sect2><title>FcObjectType</title>
|
|
<para>
|
|
Provides for applcation-specified font name object types so that new
|
|
pattern elements can be generated from font names.
|
|
</para>
|
|
<sect3><title>FcNameRegisterObjectTypes</title><programlisting>
|
|
FcBool FcNameRegisterObjectTypes (const FcObjectType *types, int ntype)
|
|
</programlisting><para>
|
|
Register 'ntype' new object types.
|
|
</para></sect3>
|
|
<sect3><title>FcNameUnregisterObjectTypes</title><programlisting>
|
|
FcBool FcNameUnregisterObjectTypes (const FcObjectType *types, int ntype)
|
|
</programlisting><para>
|
|
Unregister 'ntype' object types.
|
|
</para></sect3>
|
|
<sect3><title>FcNameGetObjectType</title><programlisting>
|
|
const FcObjectType *FcNameGetObjectType (const char *object)
|
|
</programlisting><para>
|
|
Return the object type for the pattern element named 'object'.
|
|
</para></sect3>
|
|
</sect2>
|
|
<sect2><title>FcConstant</title>
|
|
<para>
|
|
Provides for application-specified symbolic constants for font names.
|
|
</para>
|
|
<sect3><title>FcNameRegisterConstants</title><programlisting>
|
|
FcBool FcNameRegisterConstants (const FcConstant *consts, int nconsts)
|
|
</programlisting><para>
|
|
Register 'nconsts' new symbolic constants.
|
|
</para></sect3>
|
|
<sect3><title>FcNameUnregisterConstants</title><programlisting>
|
|
FcBool FcNameUnregisterConstants (const FcConstant *consts, int nconsts)
|
|
</programlisting><para>
|
|
Unregister 'nconsts' symbolic constants.
|
|
</para></sect3>
|
|
<sect3><title>FcNameGetConstant</title><programlisting>
|
|
const FcConstant *FcNameGetConstant (FcChar8 *string)
|
|
</programlisting><para>
|
|
Return the FcConstant structure related to symbolic constant 'string'.
|
|
</para></sect3>
|
|
<sect3><title>FcNameConstant</title><programlisting>
|
|
FcBool FcNameConstant (FcChar8 *string, int *result);
|
|
</programlisting><para>
|
|
Returns whether a symbolic constant with name 'string' is registered,
|
|
placing the value of the constant in 'result' if present.
|
|
</para></sect3>
|
|
</sect2>
|
|
<sect2><title>FcBlanks</title>
|
|
<para>
|
|
An FcBlanks object holds a list of Unicode chars which are expected to
|
|
be blank when drawn. When scanning new fonts, any glyphs which are
|
|
empty and not in this list will be assumed to be broken and not placed in
|
|
the FcCharSet associated with the font. This provides a significantly more
|
|
accurate CharSet for applications.
|
|
</para>
|
|
<sect3><title>FcBlanksCreate</title><programlisting>
|
|
FcBlanks *FcBlanksCreate (void)
|
|
</programlisting><para>
|
|
Creates an empty FcBlanks object.
|
|
</para></sect3>
|
|
<sect3><title>FcBlanksDestroy</title><programlisting>
|
|
void FcBlanksDestroy (FcBlanks *b)
|
|
</programlisting><para>
|
|
Destroys an FcBlanks object, freeing any associated memory.
|
|
</para></sect3>
|
|
<sect3><title>FcBlanksAdd</title><programlisting>
|
|
FcBool FcBlanksAdd (FcBlanks *b, FcChar32 ucs4)
|
|
</programlisting><para>
|
|
Adds a single character to an FcBlanks object, returning FcFalse
|
|
if this process ran out of memory.
|
|
</para></sect3>
|
|
<sect3><title>FcBlanksIsMember</title><programlisting>
|
|
FcBool FcBlanksIsMember (FcBlanks *b, FcChar32 ucs4)
|
|
</programlisting><para>
|
|
Returns whether the specified FcBlanks object contains the indicated Unicode
|
|
value.
|
|
</para></sect3>
|
|
</sect2>
|
|
<sect2><title>FcConfig</title>
|
|
<para>
|
|
An FcConfig object holds the internal representation of a configuration.
|
|
There is a default configuration which applications may use by passing 0 to
|
|
any function using the data within an FcConfig.
|
|
</para>
|
|
<sect3><title>FcConfigCreate</title><programlisting>
|
|
FcConfig *FcConfigCreate (void)
|
|
</programlisting><para>
|
|
Creates an empty configuration.
|
|
</para></sect3>
|
|
<sect3><title>FcConfigDestroy</title><programlisting>
|
|
void FcConfigDestroy (FcConfig *config)
|
|
</programlisting><para>
|
|
Destroys a configuration and any data associated with it. Note that calling
|
|
this function with the return from FcConfigGetCurrent will place the library
|
|
in an indeterminate state.
|
|
</para></sect3>
|
|
<sect3><title>FcConfigSetCurrent</title><programlisting>
|
|
FcBool FcConfigSetCurrent (FcConfig *config)
|
|
</programlisting><para>
|
|
Sets the current default configuration to 'config'. Implicitly calls
|
|
FcConfigBuildFonts if necessary, returning FcFalse if that call fails.
|
|
</para></sect3>
|
|
<sect3><title>FcConfigGetCurrent</title><programlisting>
|
|
FcConfig *FcConfigGetCurrent (void)
|
|
</programlisting><para>
|
|
Returns the current default configuration.
|
|
</para></sect3>
|
|
<sect3><title>FcConfigUptoDate</title><programlisting>
|
|
FcBool FcConfigUptoDate (FcConfig *config)
|
|
</programlisting><para>
|
|
Checks all of the files related to 'config' and returns whether the
|
|
in-memory version is in sync with the disk version.
|
|
</para></sect3>
|
|
<sect3><title>FcConfigBuildFonts</title><programlisting>
|
|
FcBool FcConfigBuildFonts (FcConfig *config)
|
|
</programlisting><para>
|
|
Builds the set of available fonts for the given configuration. Note that
|
|
any changes to the configuration after this call have indeterminate effects.
|
|
Returns FcFalse if this operation runs out of memory.
|
|
</para></sect3>
|
|
<sect3><title>FcConfigGetConfigDirs</title><programlisting>
|
|
FcStrList *FcConfigGetConfigDirs (FcConfig *config)
|
|
</programlisting><para>
|
|
Returns the list of font directories specified in the configuration files
|
|
for 'config'. Does not include any subdirectories.
|
|
</para></sect3>
|
|
<sect3><title>FcConfigGetFontDirs</title><programlisting>
|
|
FcStrList *FcConfigGetFontDirs (FcConfig *config)
|
|
</programlisting><para>
|
|
Returns the list of font directories in 'config'. This includes the
|
|
configured font directories along with any directories below those in the
|
|
filesystem.
|
|
</para></sect3>
|
|
<sect3><title>FcConfigGetConfigFiles</title><programlisting>
|
|
FcStrList *FcConfigGetConfigFiles (FcConfig *config)
|
|
</programlisting><para>
|
|
Returns the list of known configuration files used to generate 'config'.
|
|
Note that this will not include any configuration done with FcConfigParse.
|
|
</para></sect3>
|
|
<sect3><title>FcConfigGetCache</title><programlisting>
|
|
char *FcConfigGetCache (FcConfig *config)
|
|
</programlisting><para>
|
|
Returns the name of the file used to store per-user font information.
|
|
</para></sect3>
|
|
<sect3><title>FcConfigGetFonts</title><programlisting>
|
|
FcFontSet *FcConfigGetFonts (FcConfig *config, FcSetName set)
|
|
</programlisting><para>
|
|
Returns one of the two sets of fonts from the configuration as specified
|
|
by 'set'.
|
|
</para></sect3>
|
|
<sect3><title>FcConfigGetBlanks</title><programlisting>
|
|
FcBlanks *FcConfigGetBlanks (FcConfig *config)
|
|
</programlisting><para>
|
|
Returns the FcBlanks object associated with the given configuration, if no
|
|
blanks were present in the configuration, this function will return 0.
|
|
</para></sect3>
|
|
<sect3><title>FcConfigGetRescanInverval</title><programlisting>
|
|
int FcConfigGetRescanInverval (FcConfig *config)
|
|
</programlisting><para>
|
|
Returns the interval between automatic checks of the configuration (in
|
|
seconds) specified in 'config'. The configuration is checked during
|
|
a call to FcFontList when this interval has passed since the last check.
|
|
</para></sect3>
|
|
<sect3><title>FcConfigSetRescanInverval</title><programlisting>
|
|
FcBool FcConfigSetRescanInverval (FcConfig *config, int rescanInterval)
|
|
</programlisting><para>
|
|
Sets the rescan interval; returns FcFalse if an error occurred.
|
|
</para></sect3>
|
|
<sect3><title>FcConfigAppFontAddFile</title><programlisting>
|
|
FcBool FcConfigAppFontAddFile (FcConfig *config, const char *file)
|
|
</programlisting><para>
|
|
Adds an application-specific font to the configuration.
|
|
</para></sect3>
|
|
<sect3><title>FcConfigAppFontAddDir</title><programlisting>
|
|
FcBool FcConfigAppFontAddDir (FcConfig *config, const char *dir)
|
|
</programlisting><para>
|
|
Scans the specified directory for fonts, adding each one found to the
|
|
application-specific set of fonts.
|
|
</para></sect3>
|
|
<sect3><title>FcConfigAppFontClear</title><programlisting>
|
|
void FcConfigAppFontClear (FcConfig *config)
|
|
</programlisting><para>
|
|
Clears the set of application-specific fonts.
|
|
</para></sect3>
|
|
<sect3><title>FcConfigSubstituteWithPat</title><programlisting>
|
|
FcBool FcConfigSubstituteWithPat (FcConfig *config, FcPattern *p, FcPattern *p_pat FcMatchKind kind)
|
|
</programlisting><para>
|
|
Performs the sequence of pattern modification operations, if 'kind' is
|
|
FcMatchPattern, then those tagged as pattern operations are applied, else
|
|
if 'kind' is FcMatchFont, those tagged as font operations are applied and
|
|
p_pat is used for <test> elements with target=pattern.
|
|
</para></sect3>
|
|
<sect3><title>FcConfigSubstitute</title><programlisting>
|
|
FcBool FcConfigSubstitute (FcConfig *config, FcPattern *p, FcMatchKind kind)
|
|
</programlisting><para>
|
|
Calls FcConfigSubstituteWithPat setting p_pat to NULL.
|
|
</para></sect3>
|
|
<sect3><title>FcFontMatch</title><programlisting>
|
|
FcPattern *FcFontMatch (FcConfig *config, FcPattern *p, FcResult *result)
|
|
</programlisting><para>
|
|
Returns the font in 'config' most close matching 'p'. This function
|
|
should be called only after FcConfigSubstitute and FcDefaultSubstitute have
|
|
been called for 'p'; otherwise the results will not be correct.
|
|
</para></sect3>
|
|
<sect3><title>FcFontSort</title><programlisting>
|
|
FcFontSet *FcFontSort (FcConfig *config, FcPattern *p, FcBool trim, FcCharSet **csp, FcResult *result)
|
|
</programlisting><para>
|
|
Returns the list of fonts sorted by closeness to 'p'. If 'trim' is FcTrue,
|
|
elements in the list which don't include Unicode coverage not provided by
|
|
earlier elements in the list are elided. The union of Unicode coverage of
|
|
all of the fonts is returned in 'csp', if 'csp' is not NULL. This function
|
|
should be called only after FcConfigSubstitute and FcDefaultSubstitute have
|
|
been called for 'p'; otherwise the results will not be correct.
|
|
</para><para>
|
|
The returned FcFontSet references FcPattern structures which may be shared
|
|
by the return value from multiple FcFontSort calls, applications must not
|
|
modify these patterns. Instead, they should be passed, along with 'p' to
|
|
FcFontRenderPrepare which combines them into a complete pattern.
|
|
</para><para>
|
|
The FcFontSet returned by FcFontSort is destroyed by caling FcFontSetDestroy.
|
|
</para></sect3>
|
|
<sect3><title>FcFontRenderPrepare</title><programlisting>
|
|
FcPattern *FcFontRenderPrepare (FcConfig *config, FcPattern *pat, FcPattern *font)
|
|
</programlisting><para>
|
|
Creates a new pattern consisting of elements of 'font' not appearing
|
|
in 'pat', elements of 'pat' not appearing in 'font' and the best matching
|
|
value from 'pat' for elements appearing in both. The result is passed to
|
|
FcConfigSubstitute with 'kind' FcMatchFont and then returned.
|
|
</para></sect3>
|
|
<sect3><title>FcFontList</title><programlisting>
|
|
FcFontSet *FcFontList (FcConfig *config, FcPattern *p, FcObjectSet *os)
|
|
</programlisting><para>
|
|
Selects fonts matching 'p', creates patterns from those fonts containing
|
|
only the objects in 'os' and returns the set of unique such patterns.
|
|
</para></sect3>
|
|
<sect3><title>FcConfigFilename</title><programlisting>
|
|
char *FcConfigFilename (const char *name)
|
|
</programlisting><para>
|
|
Given the specified external entity name, return the associated filename.
|
|
This provides applications a way to convert various configuration file
|
|
references into filename form.
|
|
</para><para>
|
|
A null or empty 'name' indicates that the default configuration file should
|
|
be used; which file this references can be overridden with the
|
|
FC_CONFIG_FILE environment variable. Next, if the name starts with '~', it
|
|
refers to a file in the current users home directory. Otherwise if the name
|
|
doesn't start with '/', it refers to a file in the default configuration
|
|
directory; the built-in default directory can be overridden with the
|
|
FC_CONFIG_DIR environment variable.
|
|
</para></sect3>
|
|
</sect2>
|
|
<sect2><title>Initialization</title>
|
|
<para>
|
|
These functions provide some control over how the library is initialized.
|
|
</para>
|
|
<sect3><title>FcInitLoadConfig</title><programlisting>
|
|
FcConfig *FcInitLoadConfig (void)
|
|
</programlisting><para>
|
|
Loads the default configuration file and returns the resulting configuration.
|
|
Does not load any font information.
|
|
</para></sect3>
|
|
<sect3><title>FcInitLoadConfigAndFonts</title><programlisting>
|
|
FcConfig *FcInitLoadConfigAndFonts (void)
|
|
</programlisting><para>
|
|
Loads the default configuration file and builds information about the
|
|
available fonts. Returns the resulting configuration.
|
|
</para></sect3>
|
|
<sect3><title>FcInit</title><programlisting>
|
|
FcBool FcInit (void)
|
|
</programlisting><para>
|
|
Loads the default configuration file and the fonts referenced therein and
|
|
sets the default configuration to that result. Returns whether this
|
|
process succeeded or not. If the default configuration has already
|
|
been loaded, this routine does nothing and returns FcTrue.
|
|
</para></sect3>
|
|
<sect3><title>FcGetVersion</title><programlisting>
|
|
int FcGetVersion (void)
|
|
</programlisting><para>
|
|
Returns the version number of the library.
|
|
</para></sect3>
|
|
<sect3><title>FcInitReinitialize</title><programlisting>
|
|
FcBool FcInitReinitialize (void)
|
|
</programlisting><para>
|
|
Forces the default configuration file to be reloaded and resets the default
|
|
configuration.
|
|
</para></sect3>
|
|
<sect3><title>FcInitBringUptoDate</title><programlisting>
|
|
FcBool FcInitBringUptoDate (void)
|
|
</programlisting><para>
|
|
Checks the rescan interval in the default configuration, checking the
|
|
configuration if the interval has passed and reloading the configuration if
|
|
when any changes are detected.
|
|
</para></sect3>
|
|
</sect2>
|
|
<sect2><title>FcAtomic</title>
|
|
<para>
|
|
These functions provide a safe way to update config files, allowing ongoing
|
|
reading of the old config file while locked for writing and ensuring that a
|
|
consistent and complete version of the config file is always available.
|
|
</para>
|
|
<sect3><title>FcAtomicCreate</title><programlisting>
|
|
FcAtomic * FcAtomicCreate (const FcChar8 *file)
|
|
</programlisting><para>
|
|
Creates a data structure containing data needed to control access to 'file'.
|
|
Writing is done to a separate file. Once that file is complete, the original
|
|
configuration file is atomically replaced so that reading process always see
|
|
a consistent and complete file without the need to lock for reading.
|
|
</para></sect3>
|
|
<sect3><title>FcAtomicLock</title><programlisting>
|
|
FcBool FcAtomicLock (FcAtomic *atomic)
|
|
</programlisting><para>
|
|
Attempts to lock the file referenced by 'atomic'. Returns FcFalse if the
|
|
file is locked by another process, else returns FcTrue and leaves the file
|
|
locked.
|
|
</para></sect3>
|
|
<sect3><title>FcAtomicNewFile</title><programlisting>
|
|
FcChar8 *FcAtomicNewFile (FcAtomic *atomic)
|
|
</programlisting><para>
|
|
Returns the filename for writing a new version of the file referenced
|
|
by 'atomic'.
|
|
</para></sect3>
|
|
<sect3><title>FcAtomicOrigFile</title><programlisting>
|
|
FcChar8 *FcAtomicOrigFile (FcAtomic *atomic)
|
|
</programlisting><para>
|
|
Returns the file refernced by 'atomic'.
|
|
</para></sect3>
|
|
<sect3><title>FcAtomicReplaceOrig</title><programlisting>
|
|
FcBool FcAtomicReplaceOrig (FcAtomic *atomic)
|
|
</programlisting><para>
|
|
Replaces the original file referenced by 'atomic' with the new file.
|
|
</para></sect3>
|
|
<sect3><title>FcAtomicDeleteNew</title><programlisting>
|
|
void FcAtomicDeleteNew (FcAtomic *atomic)
|
|
</programlisting><para>
|
|
Deletes the new file.
|
|
</para></sect3>
|
|
<sect3><title>FcAtomicUnlock</title><programlisting>
|
|
void FcAtomicUnlock (FcAtomic *atomic)
|
|
</programlisting><para>
|
|
Unlocks the file.
|
|
</para></sect3>
|
|
<sect3><title>FcAtomicDestroy</title><programlisting>
|
|
void FcAtomicDestroy (FcAtomic *atomic)
|
|
</programlisting><para>
|
|
Destroys 'atomic'.
|
|
</para></sect3>
|
|
</sect2>
|
|
<sect2><title>FreeType specific functions</title>
|
|
<para>
|
|
<programlisting>
|
|
#include <fontconfig/fcfreetype.h>
|
|
</programlisting>
|
|
While the fontconfig library doesn't insist that FreeType be used as the
|
|
rasterization mechanism for fonts, it does provide some convenience
|
|
functions.
|
|
</para>
|
|
<sect3><title>FcFreeTypeCharIndex</title><programlisting>
|
|
FT_UInt FcFreeTypeCharIndex (FT_Face face, FcChar32 ucs4)
|
|
</programlisting><para>
|
|
Maps a Unicode char to a glyph index. This function uses information from
|
|
several possible underlying encoding tables to work around broken fonts.
|
|
As a result, this function isn't designed to be used in performance
|
|
sensitive areas; results from this function are intended to be cached by
|
|
higher level functions.
|
|
</para></sect3>
|
|
<sect3><title>FcFreeTypeCharSet</title><programlisting>
|
|
FcCharSet *FcFreeTypeCharSet (FT_Face face, FcBlanks *blanks) Scans a
|
|
</programlisting><para>
|
|
FreeType face and returns the set of encoded Unicode chars. This scans
|
|
several encoding tables to build as complete a list as possible.
|
|
If 'blanks' is not 0, the glyphs in the font are examined and any blank glyphs
|
|
not in 'blanks' are not placed in the returned FcCharSet.
|
|
</para></sect3>
|
|
<sect3><title>FcFreeTypeQuery</title><programlisting>
|
|
FcPattern *FcFreeTypeQuery (const char *file, int id, FcBlanks *blanks, int *count)
|
|
</programlisting><para>
|
|
Constructs a pattern representing the 'id'th font in 'file'. The number
|
|
of fonts in 'file' is returned in 'count'.
|
|
</para></sect3>
|
|
</sect2>
|
|
<sect2><title>XML specific functions</title>
|
|
<sect3><title>FcConfigParseAndLoad</title><programlisting>
|
|
FcBool FcConfigParseAndLoad (FcConfig *config, const FcChar8 *file, FcBool complain)
|
|
</programlisting><para>
|
|
Walks the configuration in 'file' and constructs the internal representation
|
|
in 'config'. Any include files referenced from within 'file' will be loaded
|
|
with FcConfigLoad and also parsed. If 'complain' is FcFalse, no warning
|
|
will be displayed if 'file' does not exist.
|
|
</para></sect3>
|
|
</sect2>
|
|
<sect2><title>File and Directory routines</title>
|
|
<sect3><title>FcFileScan</title><programlisting>
|
|
FcBool FcFileScan (FcFontSet *set, FcStrSet *dirs, FcFileCache *cache, FcBlanks *blanks, const char *file, FcBool force)
|
|
</programlisting><para>
|
|
Scans a single file and adds all fonts found to 'set'. If 'force' is FcTrue,
|
|
then the file is scanned even if associated information is found in 'cache'.
|
|
If 'file' is a directory, it is added to 'dirs'.
|
|
</para></sect3>
|
|
<sect3><title>FcDirScan</title><programlisting>
|
|
FcBool FcDirScan (FcFontSet *set, FcStrSet *dirs, FcFileCache *cache, FcBlanks *blanks, const char *dir, FcBool force)
|
|
</programlisting><para>
|
|
Scans an entire directory and adds all fonts found to 'set'. If 'force' is
|
|
FcTrue, then the directory and all files within it are scanned even if
|
|
information is present in the per-directory cache file or 'cache'. Any
|
|
subdirectories found are added to 'dirs'.
|
|
</para></sect3>
|
|
<sect3><title>FcDirSave</title><programlisting>
|
|
FcBool FcDirSave (FcFontSet *set, FcStrSet *dirs, const char *dir)
|
|
</programlisting><para>
|
|
Creates the per-directory cache file for 'dir' and populates it with the
|
|
fonts in 'set' and subdirectories in 'dirs'.
|
|
</para></sect3>
|
|
<sect3><title>FcDirCacheValid</title><programlisting>
|
|
FcBool FcDirCacheValid (const FcChar8 *cache_file)
|
|
</programlisting><para>
|
|
Returns FcTrue if 'cache_file' is no older than the directory containing it,
|
|
else FcFalse.
|
|
</para></sect3>
|
|
</sect2>
|
|
<sect2><title>FcStrSet and FcStrList</title>
|
|
<para>
|
|
A data structure for enumerating strings, used to list directories while
|
|
scanning the configuration as directories are added while scanning.
|
|
</para>
|
|
<sect3><title>FcStrSetCreate</title><programlisting>
|
|
FcStrSet *FcStrSetCreate (void)
|
|
</programlisting><para>
|
|
Create an empty set.
|
|
</para></sect3>
|
|
<sect3><title>FcStrSetMember</title><programlisting>
|
|
FcBool FcStrSetMember (FcStrSet *set, const FcChar8 *s)
|
|
</programlisting><para>
|
|
Returns whether 's' is a member of 'set'.
|
|
</para></sect3>
|
|
<sect3><title>FcStrSetAdd</title><programlisting>
|
|
FcBool FcStrSetAdd (FcStrSet *set, const FcChar8 *s)
|
|
</programlisting><para>
|
|
Adds a copy of 's' to 'set'.
|
|
</para></sect3>
|
|
<sect3><title>FcStrSetAddFilename</title><programlisting>
|
|
FcBool FcStrSetAddFilename (FcStrSet *set, const FcChar8 *s)
|
|
</programlisting><para>
|
|
Adds a copy 's' to 'set', The copy is created with FcStrCopyFilename
|
|
so that leading '~' values are replaced with the value of the HOME
|
|
environment variable.
|
|
</para></sect3>
|
|
<sect3><title>FcStrSetDel</title><programlisting>
|
|
FcBool FcStrSetDel (FcStrSet *set, const FcChar8 *s)
|
|
</programlisting><para>
|
|
Removes 's' from 'set', returning FcTrue if 's' was a member else FcFalse.
|
|
</para></sect3>
|
|
<sect3><title>FcStrSetDestroy</title><programlisting>
|
|
void FcStrSetDestroy (FcStrSet *set)
|
|
</programlisting><para>
|
|
Destroys 'set'.
|
|
</para></sect3>
|
|
<sect3><title>FcStrListCreate</title><programlisting>
|
|
FcStrList *FcStrListCreate (FcStrSet *set)
|
|
</programlisting><para>
|
|
Creates an enumerator to list the strings in 'set'.
|
|
</para></sect3>
|
|
<sect3><title>FcStrListNext</title><programlisting>
|
|
FcChar8 *FcStrListNext (FcStrList *list)
|
|
</programlisting><para>
|
|
Returns the next string in 'set'.
|
|
</para></sect3>
|
|
<sect3><title>FcStrListDone</title><programlisting>
|
|
void FcStrListDone (FcStrList *list)
|
|
</programlisting><para>
|
|
Destroys the enumerator 'list'.
|
|
</para></sect3>
|
|
</sect2>
|
|
<sect2><title>String utilities</title>
|
|
<sect3><title>FcUtf8ToUcs4</title>
|
|
<programlisting>
|
|
int FcUtf8ToUcs4 (FcChar8 *src, FcChar32 *dst, int len)
|
|
</programlisting>
|
|
<para>
|
|
Converts the next Unicode char from 'src' into 'dst' and returns the number
|
|
of bytes containing the char. 'src' nust be at least 'len' bytes long.
|
|
</para></sect3>
|
|
<sect3><title>FcUcs4ToUtf8</title><programlisting>
|
|
int FcUcs4ToUtf8 (FcChar32 src, FcChar8 dst[FC_UTF8_MAX_LEN])
|
|
</programlisting><para>
|
|
Converts the Unicode char from 'src' into 'dst' and returns the
|
|
number of bytes needed to encode the char.
|
|
</para></sect3>
|
|
<sect3><title>FcUtf8Len</title><programlisting>
|
|
FcBool FcUtf8Len (FcChar8 *src, int len, int *nchar, int *wchar)
|
|
</programlisting><para>
|
|
Counts the number of Unicode chars in 'len' bytes of 'src'. Places that
|
|
count in 'nchar'. 'wchar' contains 1, 2 or 4 depending on the number of
|
|
bytes needed to hold the largest unicode char counted. The return value
|
|
indicates whether 'src' is a well-formed UTF8 string.
|
|
</para></sect3>
|
|
<sect3><title>FcUtf16ToUcs4</title><programlisting>
|
|
int FcUtf16ToUcs4 (FcChar8 *src, FcEndian endian, FcChar32 *dst, int len)
|
|
</programlisting><para>
|
|
Converts the next Unicode char from 'src' into 'dst' and returns the
|
|
number of bytes containing the char. 'src' must be at least 'len' bytes
|
|
long. Bytes of 'src' are combined into 16-bit units according to 'endian'.
|
|
</para></sect3>
|
|
<sect3><title>FcUtf16Len</title><programlisting>
|
|
FcBool FcUtf16Len (FcChar8 *src, FcEndian endian, int len, int *nchar, int *wchar)
|
|
</programlisting><para>
|
|
Counts the number of Unicode chars in 'len' bytes of 'src'. Bytes of 'src'
|
|
are combined into 16-bit units according to 'endian'. Places that
|
|
count in 'nchar'. 'wchar' contains 1, 2 or 4 depending on the number of
|
|
bytes needed to hold the largest unicode char counted. The return value
|
|
indicates whether 'string' is a well-formed UTF16 string.
|
|
</para></sect3>
|
|
<sect3><title>FcStrCopy</title><programlisting>
|
|
FcChar8 *FcStrCopy (const FcChar8 *s)
|
|
</programlisting><para>
|
|
Allocates memory, copies 's' and returns the resulting buffer. Yes, this
|
|
is 'strdup', but that function isn't available on every platform.
|
|
</para></sect3>
|
|
<sect3><title>FcStrCopyFilename</title><programlisting>
|
|
FcChar8 *FcStrCopyFilename (const FcChar8 *s)
|
|
</programlisting><para>
|
|
Just like FcStrCopy except that it converts any leading '~' characters
|
|
in 's' to the value of the HOME environment variable.
|
|
</para></sect3>
|
|
<sect3><title>FcStrCmpIgnoreCase</title><programlisting>
|
|
int FcStrCmpIgnoreCase (const char *s1, const char *s2)
|
|
</programlisting><para>
|
|
Returns the usual <0, 0, >0 result of comparing 's1' and 's2'. This test
|
|
is case-insensitive in the ASCII range and will operate properly with UTF8
|
|
encoded strings, although it does not check for well formed strings.
|
|
</para></sect3>
|
|
<sect3><title>FcStrDirname</title><programlisting>
|
|
FcChar8 *FcStrDirname (const FcChar8 *file)
|
|
</programlisting><para>
|
|
Returns the directory containing 'file'.
|
|
</para></sect3>
|
|
<sect3><title>FcStrBasename</title><programlisting>
|
|
FcChar8 *FcStrBasename (const FcChar8 *file)
|
|
</programlisting><para>
|
|
Returns the filename of 'file' stripped of any leading directory names.
|
|
</para></sect3>
|
|
</sect2>
|
|
</sect1>
|
|
</article>
|