758 lines
31 KiB
Plaintext
758 lines
31 KiB
Plaintext
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
|
|
<!ENTITY fcmatrix SYSTEM "fcmatrix.sgml">
|
|
<!ENTITY fccharset SYSTEM "fccharset.sgml">
|
|
<!ENTITY fcvalue SYSTEM "fcvalue.sgml">
|
|
<!ENTITY fcpattern SYSTEM "fcpattern.sgml">
|
|
<!ENTITY fcfontset SYSTEM "fcfontset.sgml">
|
|
<!ENTITY fcobjectset SYSTEM "fcobjectset.sgml">
|
|
<!ENTITY fcobjecttype SYSTEM "fcobjecttype.sgml">
|
|
<!ENTITY fcconstant SYSTEM "fcconstant.sgml">
|
|
<!ENTITY fcblanks SYSTEM "fcblanks.sgml">
|
|
<!ENTITY fcconfig SYSTEM "fcconfig.sgml">
|
|
]>
|
|
<!--
|
|
$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>
|
|
<title>Fontconfig Developers Reference</title>
|
|
<artheader>
|
|
<author>
|
|
<firstname>Keith</firstname>
|
|
<surname>Packard</surname>
|
|
<affiliation><orgname>
|
|
HP Cambridge Research Lab
|
|
</orgname></affiliation>
|
|
</author>
|
|
<authorinitials>KRP</authorinitials>
|
|
<productname>Fontconfig</productname>
|
|
<productnumber>2.1.91</productnumber>
|
|
<LegalNotice>
|
|
<simpara>
|
|
Copyright © 2002 Keith Packard
|
|
</simpara><simpara>
|
|
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.
|
|
</simpara><simpara>
|
|
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.
|
|
</simpara>
|
|
</LegalNotice>
|
|
</artheader>
|
|
<!--
|
|
<refsynopsisdiv>
|
|
<synopsis>
|
|
#include <fontconfig/fontconfig.h>
|
|
#include <fontconfig/fcfreetype.h>
|
|
</synopsis>
|
|
</refsynopsisdiv>
|
|
-->
|
|
<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>
|
|
<programlisting>
|
|
Property Definitions
|
|
|
|
Property CPP Symbol Type Description
|
|
----------------------------------------------------
|
|
family FC_FAMILY String Font family name
|
|
style FC_STYLE String Font style. Overrides weight
|
|
and slant
|
|
slant FC_SLANT Int Italic, oblique or roman
|
|
weight FC_WEIGHT Int Light, medium, demibold,
|
|
bold or black
|
|
size FC_SIZE Double Point size
|
|
aspect FC_ASPECT Double Stretches glyphs horizontally
|
|
before hinting
|
|
pixelsize FC_PIXEL_SIZE Double Pixel size
|
|
spacing FC_SPACING Int Proportional, monospace or
|
|
charcell
|
|
foundry FC_FOUNDRY String Font foundry name
|
|
antialias FC_ANTIALIAS Bool Whether glyphs can be
|
|
antialiased
|
|
hinting FC_HINTING Bool Whether the rasterizer should
|
|
use hinting
|
|
verticallayout FC_VERTICAL_LAYOUT Bool Use vertical layout
|
|
autohint FC_AUTOHINT Bool Use autohinter instead of
|
|
normal hinter
|
|
globaladvance FC_GLOBAL_ADVANCE Bool Use font global advance data
|
|
file FC_FILE String The filename holding the font
|
|
index FC_INDEX Int The index of the font within
|
|
the file
|
|
ftface FC_FT_FACE FT_Face Use the specified FreeType
|
|
face object
|
|
rasterizer FC_RASTERIZER String Which rasterizer is in use
|
|
outline FC_OUTLINE Bool Whether the glyphs are outlines
|
|
scalable FC_SCALABLE Bool Whether glyphs can be scaled
|
|
scale FC_SCALE Double Scale factor for point->pixel
|
|
conversions
|
|
dpi FC_DPI Double Target dots per inch
|
|
rgba FC_RGBA Int unknown, rgb, bgr, vrgb,
|
|
vbgr, none - subpixel geometry
|
|
minspace FC_MINSPACE Bool Eliminate leading from line
|
|
spacing
|
|
charset FC_CHARSET CharSet Unicode chars encoded by
|
|
the font
|
|
lang FC_LANG String List of RFC-3066-style
|
|
languages this font supports
|
|
</programlisting>
|
|
</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>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>FcChar8<term>
|
|
<term>FcChar16<term>
|
|
<term>FcChar32<term>
|
|
<term>FcBool</term>
|
|
<listitem>
|
|
<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>
|
|
</listitem></varlistentry>
|
|
<varlistentry><term>FcMatrix</term><listitem>
|
|
<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>
|
|
</listitem></varlistentry>
|
|
<varlistentry><term>FcCharSet</term><listitem>
|
|
<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>
|
|
</listitem></varlistentry>
|
|
<varlistentry><term>FcType</term><listitem>
|
|
<para>
|
|
Tags the kind of data stored in an FcValue.
|
|
</para>
|
|
</listitem></varlistentry>
|
|
<varlistentry><term>FcValue</term><listitem>
|
|
<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>
|
|
<programlisting>
|
|
FcValue Members
|
|
|
|
Type Union member Datatype
|
|
--------------------------------
|
|
FcTypeVoid (none) (none)
|
|
FcTypeInteger i int
|
|
FcTypeDouble d double
|
|
FcTypeString s char *
|
|
FcTypeBool b b
|
|
FcTypeMatrix m FcMatrix *
|
|
FcTypeCharSet c FcCharSet *
|
|
</programlisting>
|
|
</para>
|
|
</listitem></varlistentry>
|
|
<varlistentry><term>FcPattern</term><listitem>
|
|
<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>
|
|
</listitem></varlistentry>
|
|
<varlistentry><term>FcFontSet</term><listitem>
|
|
<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>
|
|
</listitem></varlistentry>
|
|
<varlistentry><term>FcStrSet</term><term>FcStrList</term><listitem>
|
|
<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>
|
|
</listitem></varlistentry>
|
|
<varlistentry><term>FcObjectSet</term><listitem>
|
|
<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>
|
|
</listitem></varlistentry>
|
|
<varlistentry><term>FcObjectType</term><listitem>
|
|
<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>
|
|
</listitem></varlistentry>
|
|
<varlistentry><term>FcConstant</term><listitem>
|
|
<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>
|
|
</listitem></varlistentry>
|
|
<varlistentry><term>FcBlanks</term><listitem>
|
|
<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>
|
|
</listitem></varlistentry>
|
|
<varlistentry><term>FcFileCache</term><listitem>
|
|
<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>
|
|
</listitem></varlistentry>
|
|
<varlistentry><term>FcConfig</term><listitem>
|
|
<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>
|
|
</listitem></varlistentry>
|
|
<varlistentry><term>FcSetName</term><listitem>
|
|
<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>
|
|
</listitem></varlistentry>
|
|
<varlistentry><term>FcResult</term><listitem>
|
|
<para>
|
|
Used as a return type for functions manipulating FcPattern objects.
|
|
<programlisting>
|
|
FcResult Values
|
|
Result Code Meaning
|
|
-----------------------------------------------------------
|
|
FcResultMatch Object exists with the specified ID
|
|
FcResultNoMatch Object doesn't exist at all
|
|
FcResultTypeMismatch Object exists, but the type doesn't match
|
|
FcResultNoId Object exists, but has fewer values
|
|
than specified
|
|
</programlisting>
|
|
</para>
|
|
</listitem></varlistentry>
|
|
<varlistentry><term>FcAtomic</term><listitem>
|
|
<para>
|
|
Used for locking access to config files. Provides a safe way to update
|
|
configuration files.
|
|
</para>
|
|
</listitem></varlistentry>
|
|
</variablelist>
|
|
</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>
|
|
&fcmatrix;
|
|
</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>
|
|
&fccharset;
|
|
</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>
|
|
&fcvalue;
|
|
</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>
|
|
&fcpattern;
|
|
</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>
|
|
&fcfontset;
|
|
</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>
|
|
&fcobjectset;
|
|
</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>
|
|
&fcobjecttype;
|
|
</sect2>
|
|
<sect2><title>FcConstant</title>
|
|
<para>
|
|
Provides for application-specified symbolic constants for font names.
|
|
</para>
|
|
&fcconstant;
|
|
</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>
|
|
&fcblanks;
|
|
</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>
|
|
&fcconfig;
|
|
</sect2>
|
|
<sect2><title>Initialization</title>
|
|
<para>
|
|
These functions provide some control over how the library is initialized.
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry><term>
|
|
FcConfig *FcInitLoadConfig (void);
|
|
</term><listitem><para>
|
|
Loads the default configuration file and returns the resulting configuration.
|
|
Does not load any font information.
|
|
</para></listitem></varlistentry>
|
|
<varlistentry><term>
|
|
FcConfig *FcInitLoadConfigAndFonts (void);
|
|
</term><listitem><para>
|
|
Loads the default configuration file and builds information about the
|
|
available fonts. Returns the resulting configuration.
|
|
</para></listitem></varlistentry>
|
|
<varlistentry><term>
|
|
FcBool FcInit (void);
|
|
</term><listitem><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></listitem></varlistentry>
|
|
<varlistentry><term>
|
|
int FcGetVersion (void);
|
|
</term><listitem><para>
|
|
Returns the version number of the library.
|
|
</para></listitem></varlistentry>
|
|
<varlistentry><term>
|
|
FcBool FcInitReinitialize (void);
|
|
</term><listitem><para>
|
|
Forces the default configuration file to be reloaded and resets the default
|
|
configuration.
|
|
</para></listitem></varlistentry>
|
|
<varlistentry><term>
|
|
FcBool FcInitBringUptoDate (void);
|
|
</term><listitem><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></listitem></varlistentry>
|
|
</variablelist></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>
|
|
<variablelist>
|
|
<varlistentry><term>
|
|
FcAtomic * FcAtomicCreate (const FcChar8 *file);
|
|
</term><listitem><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></listitem></varlistentry>
|
|
<varlistentry><term>
|
|
FcBool FcAtomicLock (FcAtomic *atomic);
|
|
</term><listitem><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></listitem></varlistentry>
|
|
<varlistentry><term>
|
|
FcChar8 *FcAtomicNewFile (FcAtomic *atomic);
|
|
</term><listitem><para>
|
|
Returns the filename for writing a new version of the file referenced
|
|
by 'atomic'.
|
|
</para></listitem></varlistentry>
|
|
<varlistentry><term>
|
|
FcChar8 *FcAtomicOrigFile (FcAtomic *atomic);
|
|
</term><listitem><para>
|
|
Returns the file refernced by 'atomic'.
|
|
</para></listitem></varlistentry>
|
|
<varlistentry><term>
|
|
FcBool FcAtomicReplaceOrig (FcAtomic *atomic);
|
|
</term><listitem><para>
|
|
Replaces the original file referenced by 'atomic' with the new file.
|
|
</para></listitem></varlistentry>
|
|
<varlistentry><term>
|
|
void FcAtomicDeleteNew (FcAtomic *atomic);
|
|
</term><listitem><para>
|
|
Deletes the new file.
|
|
</para></listitem></varlistentry>
|
|
<varlistentry><term>
|
|
void FcAtomicUnlock (FcAtomic *atomic);
|
|
</term><listitem><para>
|
|
Unlocks the file.
|
|
</para></listitem></varlistentry>
|
|
<varlistentry><term>
|
|
void FcAtomicDestroy (FcAtomic *atomic);
|
|
</term><listitem><para>
|
|
Destroys 'atomic'.
|
|
</para></listitem></varlistentry>
|
|
</variablelist></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>
|
|
<variablelist>
|
|
<varlistentry><term>
|
|
FT_UInt FcFreeTypeCharIndex (FT_Face face, FcChar32 ucs4);
|
|
</term><listitem><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></listitem></varlistentry>
|
|
<varlistentry><term>
|
|
FcCharSet *FcFreeTypeCharSet (FT_Face face, FcBlanks *blanks) Scans a
|
|
</term><listitem><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></listitem></varlistentry>
|
|
<varlistentry><term>
|
|
FcPattern *FcFreeTypeQuery (const char *file, int id, FcBlanks *blanks, int *count);
|
|
</term><listitem><para>
|
|
Constructs a pattern representing the 'id'th font in 'file'. The number
|
|
of fonts in 'file' is returned in 'count'.
|
|
</para></listitem></varlistentry>
|
|
</variablelist></sect2>
|
|
<sect2><title>XML specific functions</title>
|
|
<variablelist>
|
|
<varlistentry><term>
|
|
FcBool FcConfigParseAndLoad (FcConfig *config, const FcChar8 *file, FcBool complain);
|
|
</term><listitem><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></listitem></varlistentry>
|
|
</variablelist></sect2>
|
|
<sect2><title>File and Directory routines</title>
|
|
<variablelist>
|
|
<varlistentry><term>
|
|
FcBool FcFileScan (FcFontSet *set, FcStrSet *dirs, FcFileCache *cache, FcBlanks *blanks, const char *file, FcBool force);
|
|
</term><listitem><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></listitem></varlistentry>
|
|
<varlistentry><term>
|
|
FcBool FcDirScan (FcFontSet *set, FcStrSet *dirs, FcFileCache *cache, FcBlanks *blanks, const char *dir, FcBool force);
|
|
</term><listitem><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></listitem></varlistentry>
|
|
<varlistentry><term>
|
|
FcBool FcDirSave (FcFontSet *set, FcStrSet *dirs, const char *dir);
|
|
</term><listitem><para>
|
|
Creates the per-directory cache file for 'dir' and populates it with the
|
|
fonts in 'set' and subdirectories in 'dirs'.
|
|
</para></listitem></varlistentry>
|
|
<varlistentry><term>
|
|
FcBool FcDirCacheValid (const FcChar8 *cache_file);
|
|
</term><listitem><para>
|
|
Returns FcTrue if 'cache_file' is no older than the directory containing it,
|
|
else FcFalse.
|
|
</para></listitem></varlistentry>
|
|
</variablelist></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>
|
|
<variablelist>
|
|
<varlistentry><term>
|
|
FcStrSet *FcStrSetCreate (void);
|
|
</term><listitem><para>
|
|
Create an empty set.
|
|
</para></listitem></varlistentry>
|
|
<varlistentry><term>
|
|
FcBool FcStrSetMember (FcStrSet *set, const FcChar8 *s);
|
|
</term><listitem><para>
|
|
Returns whether 's' is a member of 'set'.
|
|
</para></listitem></varlistentry>
|
|
<varlistentry><term>
|
|
FcBool FcStrSetAdd (FcStrSet *set, const FcChar8 *s);
|
|
</term><listitem><para>
|
|
Adds a copy of 's' to 'set'.
|
|
</para></listitem></varlistentry>
|
|
<varlistentry><term>
|
|
FcBool FcStrSetAddFilename (FcStrSet *set, const FcChar8 *s);
|
|
</term><listitem><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></listitem></varlistentry>
|
|
<varlistentry><term>
|
|
FcBool FcStrSetDel (FcStrSet *set, const FcChar8 *s);
|
|
</term><listitem><para>
|
|
Removes 's' from 'set', returning FcTrue if 's' was a member else FcFalse.
|
|
</para></listitem></varlistentry>
|
|
<varlistentry><term>
|
|
void FcStrSetDestroy (FcStrSet *set);
|
|
</term><listitem><para>
|
|
Destroys 'set'.
|
|
</para></listitem></varlistentry>
|
|
<varlistentry><term>
|
|
FcStrList *FcStrListCreate (FcStrSet *set);
|
|
</term><listitem><para>
|
|
Creates an enumerator to list the strings in 'set'.
|
|
</para></listitem></varlistentry>
|
|
<varlistentry><term>
|
|
FcChar8 *FcStrListNext (FcStrList *list);
|
|
</term><listitem><para>
|
|
Returns the next string in 'set'.
|
|
</para></listitem></varlistentry>
|
|
<varlistentry><term>
|
|
void FcStrListDone (FcStrList *list);
|
|
</term><listitem><para>
|
|
Destroys the enumerator 'list'.
|
|
</para></listitem></varlistentry>
|
|
</variablelist></sect2>
|
|
<sect2><title>String utilities</title>
|
|
<variablelist>
|
|
<varlistentry><term>
|
|
int FcUtf8ToUcs4 (FcChar8 *src, FcChar32 *dst, int len);
|
|
</term><listitem>
|
|
<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></listitem></varlistentry>
|
|
<varlistentry><term>
|
|
int FcUcs4ToUtf8 (FcChar32 src, FcChar8 dst[FC_UTF8_MAX_LEN]);
|
|
</term><listitem><para>
|
|
Converts the Unicode char from 'src' into 'dst' and returns the
|
|
number of bytes needed to encode the char.
|
|
</para></listitem></varlistentry>
|
|
<varlistentry><term>
|
|
FcBool FcUtf8Len (FcChar8 *src, int len, int *nchar, int *wchar);
|
|
</term><listitem><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></listitem></varlistentry>
|
|
<varlistentry><term>
|
|
int FcUtf16ToUcs4 (FcChar8 *src, FcEndian endian, FcChar32 *dst, int len);
|
|
</term><listitem><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></listitem></varlistentry>
|
|
<varlistentry><term>
|
|
FcBool FcUtf16Len (FcChar8 *src, FcEndian endian, int len, int *nchar, int *wchar);
|
|
</term><listitem><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></listitem></varlistentry>
|
|
<varlistentry><term>
|
|
FcChar8 *FcStrCopy (const FcChar8 *s);
|
|
</term><listitem><para>
|
|
Allocates memory, copies 's' and returns the resulting buffer. Yes, this
|
|
is 'strdup', but that function isn't available on every platform.
|
|
</para></listitem></varlistentry>
|
|
<varlistentry><term>
|
|
FcChar8 *FcStrCopyFilename (const FcChar8 *s);
|
|
</term><listitem><para>
|
|
Just like FcStrCopy except that it converts any leading '~' characters
|
|
in 's' to the value of the HOME environment variable.
|
|
</para></listitem></varlistentry>
|
|
<varlistentry><term>
|
|
int FcStrCmpIgnoreCase (const char *s1, const char *s2);
|
|
</term><listitem><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></listitem></varlistentry>
|
|
<varlistentry><term>
|
|
FcChar8 *FcStrDirname (const FcChar8 *file);
|
|
</term><listitem><para>
|
|
Returns the directory containing 'file'.
|
|
</para></listitem></varlistentry>
|
|
<varlistentry><term>
|
|
FcChar8 *FcStrBasename (const FcChar8 *file);
|
|
</term><listitem><para>
|
|
Returns the filename of 'file' stripped of any leading directory names.
|
|
</para></listitem></varlistentry>
|
|
</variablelist></sect2>
|
|
</sect1>
|
|
</article>
|