Fontconfig Developers Reference, Version 2.8.0
Keith Packard
HP Cambridge Research Lab
__________________________________________________________
Table of Contents
1. DESCRIPTION
2. FUNCTIONAL OVERVIEW
2.1. FONT CONFIGURATION
2.2. FONT PROPERTIES
3. Datatypes
3.1. FcChar8, FcChar16, FcChar32, FcBool
3.2. FcMatrix
3.3. FcCharSet
3.4. FcLangSet
3.5. FcLangResult
3.6. FcType
3.7. FcValue
3.8. FcPattern
3.9. FcFontSet
3.10. FcStrSet, FcStrList
3.11. FcObjectSet
3.12. FcObjectType
3.13. FcConstant
3.14. FcBlanks
3.15. FcFileCache
3.16. FcConfig
3.17. FcSetName
3.18. FcResult
3.19. FcAtomic
3.20. FcCache
4. FUNCTIONS
4.1. Initialization
FcInitLoadConfig -- load configuration
FcInitLoadConfigAndFonts -- load configuration and
font data
FcInit -- initialize fontconfig library
FcFini -- finalize fonconfig library
FcGetVersion -- library version number
FcInitReinitialize -- re-initialize library
FcInitBringUptoDate -- reload configuration files if
needed
4.2. FcPattern
FcPatternCreate -- Create a pattern
FcPatternDuplicate -- Copy a pattern
FcPatternReference -- Increment pattern reference
count
FcPatternDestroy -- Destroy a pattern
FcPatternEqual -- Compare patterns
FcPatternEqualSubset -- Compare portions of patterns
FcPatternFilter -- Filter the objects of pattern
FcPatternHash -- Compute a pattern hash value
FcPatternAdd -- Add a value to a pattern
FcPatternAddWeak -- Add a value to a pattern with
weak binding
FcPatternAdd-Type -- Add a typed value to a pattern
FcPatternGet -- Return a value from a pattern
FcPatternGet-Type -- Return a typed value from a
pattern
FcPatternBuild -- Create patterns from arguments
FcPatternDel -- Delete a property from a pattern
FcPatternRemove -- Remove one object of the
specified type from the pattern
FcPatternPrint -- Print a pattern for debugging
FcDefaultSubstitute -- Perform default substitutions
in a pattern
FcNameParse -- Parse a pattern string
FcNameUnparse -- Convert a pattern back into a
string that can be parsed
FcPatternFormat -- Format a pattern into a string
according to a format specifier
4.3. FcFontSet
FcFontSetCreate -- Create a font set
FcFontSetDestroy -- Destroy a font set
FcFontSetAdd -- Add to a font set
FcFontSetList -- List fonts from a set of font sets
FcFontSetMatch -- Return the best font from a set of
font sets
FcFontSetPrint -- Print a set of patterns to stdout
FcFontSetSort -- Add to a font set
FcFontSetSortDestroy -- DEPRECATED destroy a font
set
4.4. FcObjectSet
FcObjectSetCreate -- Create an object set
FcObjectSetAdd -- Add to an object set
FcObjectSetDestroy -- Destroy an object set
FcObjectSetBuild -- Build object set from args
4.5. FreeType specific functions
FcFreeTypeCharIndex -- map Unicode to glyph id
FcFreeTypeCharSet -- compute unicode coverage
FcFreeTypeCharSetAndSpacing -- compute unicode
coverage and spacing type
FcFreeTypeQuery -- compute pattern from font file
(and index)
FcFreeTypeQueryFace -- compute pattern from FT_Face
4.6. FcValue
FcValueDestroy -- Free a value
FcValueSave -- Copy a value
FcValuePrint -- Print a value to stdout
FcValueEqual -- Test two values for equality
4.7. FcCharSet
FcCharSetCreate -- Create an empty character set
FcCharSetDestroy -- Destroy a character set
FcCharSetAddChar -- Add a character to a charset
FcCharSetCopy -- Copy a charset
FcCharSetEqual -- Compare two charsets
FcCharSetIntersect -- Intersect charsets
FcCharSetUnion -- Add charsets
FcCharSetSubtract -- Subtract charsets
FcCharSetMerge -- Merge charsets
FcCharSetHasChar -- Check a charset for a char
FcCharSetCount -- Count entries in a charset
FcCharSetIntersectCount -- Intersect and count
charsets
FcCharSetSubtractCount -- Subtract and count
charsets
FcCharSetIsSubset -- Test for charset inclusion
FcCharSetFirstPage -- Start enumerating charset
contents
FcCharSetNextPage -- Continue enumerating charset
contents
FcCharSetCoverage -- DEPRECATED return coverage for
a Unicode page
FcCharSetNew -- DEPRECATED alias for FcCharSetCreate
4.8. FcLangSet
FcLangSetCreate -- create a langset object
FcLangSetDestroy -- destroy a langset object
FcLangSetCopy -- copy a langset object
FcLangSetAdd -- add a language to a langset
FcLangSetCompare -- compare language sets
FcLangSetContains -- check langset subset relation
FcLangSetEqual -- test for matching langsets
FcLangSetHash -- return a hash value for a langset
FcLangSetHasLang -- test langset for language
support
FcLangSetGetLangs -- get the list of languages in
the langset
FcGetLangs -- Get list of languages
FcLangGetCharSet -- Get character map for a language
4.9. FcMatrix
FcMatrixInit -- initialize an FcMatrix structure
FcMatrixCopy -- Copy a matrix
FcMatrixEqual -- Compare two matrices
FcMatrixMultiply -- Multiply matrices
FcMatrixRotate -- Rotate a matrix
FcMatrixScale -- Scale a matrix
FcMatrixShear -- Shear a matrix
4.10. FcConfig
FcConfigCreate -- Create a configuration
FcConfigReference -- Increment config reference
count
FcConfigDestroy -- Destroy a configuration
FcConfigSetCurrent -- Set configuration as default
FcConfigGetCurrent -- Return current configuration
FcConfigUptoDate -- Check timestamps on config files
FcConfigHome -- return the current home directory.
FcConfigEnableHome -- controls use of the home
directory.
FcConfigBuildFonts -- Build font database
FcConfigGetConfigDirs -- Get config directories
FcConfigGetFontDirs -- Get font directories
FcConfigGetConfigFiles -- Get config files
FcConfigGetCache -- DEPRECATED used to return
per-user cache filename
FcConfigGetCacheDirs -- return the list of
directories searched for cache files
FcConfigGetFonts -- Get config font set
FcConfigGetBlanks -- Get config blanks
FcConfigGetRescanInterval -- Get config rescan
interval
FcConfigSetRescanInterval -- Set config rescan
interval
FcConfigAppFontAddFile -- Add font file to font
database
FcConfigAppFontAddDir -- Add fonts from directory to
font database
FcConfigAppFontClear -- Remove all app fonts from
font database
FcConfigSubstituteWithPat -- Execute substitutions
FcConfigSubstitute -- Execute substitutions
FcFontMatch -- Return best font
FcFontSort -- Return list of matching fonts
FcFontRenderPrepare -- Prepare pattern for loading
font file
FcFontList -- List fonts
FcConfigFilename -- Find a config file
FcConfigParseAndLoad -- load a configuration file
4.11. FcObjectType
FcNameRegisterObjectTypes -- Register object types
FcNameUnregisterObjectTypes -- Unregister object
types
FcNameGetObjectType -- Lookup an object type
4.12. FcConstant
FcNameRegisterConstants -- Register symbolic
constants
FcNameUnregisterConstants -- Unregister symbolic
constants
FcNameGetConstant -- Lookup symbolic constant
FcNameConstant -- Get the value for a symbolic
constant
4.13. FcBlanks
FcBlanksCreate -- Create an FcBlanks
FcBlanksDestroy -- Destroy and FcBlanks
FcBlanksAdd -- Add a character to an FcBlanks
FcBlanksIsMember -- Query membership in an FcBlanks
4.14. FcAtomic
FcAtomicCreate -- create an FcAtomic object
FcAtomicLock -- lock a file
FcAtomicNewFile -- return new temporary file name
FcAtomicOrigFile -- return original file name
FcAtomicReplaceOrig -- replace original with new
FcAtomicDeleteNew -- delete new file
FcAtomicUnlock -- unlock a file
FcAtomicDestroy -- destroy an FcAtomic object
4.15. File and Directory routines
FcFileScan -- scan a font file
FcFileIsDir -- check whether a file is a directory
FcDirScan -- scan a font directory without caching
it
FcDirSave -- DEPRECATED: formerly used to save a
directory cache
FcDirCacheUnlink -- Remove all caches related to dir
FcDirCacheValid -- check directory cache
FcDirCacheLoad -- load a directory cache
FcDirCacheRead -- read or construct a directory
cache
FcDirCacheLoadFile -- load a cache file
FcDirCacheUnload -- unload a cache file
4.16. FcCache routines
FcCacheDir -- Return directory of cache
FcCacheCopySet -- Returns a copy of the fontset from
cache
FcCacheSubdir -- Return the i'th subdirectory.
FcCacheNumSubdir -- Return the number of
subdirectories in cache.
FcCacheNumFont -- Returns the number of fonts in
cache.
4.17. FcStrSet and FcStrList
FcStrSetCreate -- create a string set
FcStrSetMember -- check set for membership
FcStrSetEqual -- check sets for equality
FcStrSetAdd -- add to a string set
FcStrSetAddFilename -- add a filename to a string
set
FcStrSetDel -- delete from a string set
FcStrSetDestroy -- destroy a string set
FcStrListCreate -- create a string iterator
FcStrListNext -- get next string in iteration
FcStrListDone -- destroy a string iterator
4.18. String utilities
FcUtf8ToUcs4 -- convert UTF-8 to UCS4
FcUcs4ToUtf8 -- convert UCS4 to UTF-8
FcUtf8Len -- count UTF-8 encoded chars
FcUtf16ToUcs4 -- convert UTF-16 to UCS4
FcUtf16Len -- count UTF-16 encoded chars
FcIsLower -- check for lower case ASCII character
FcIsUpper -- check for upper case ASCII character
FcToLower -- convert upper case ASCII to lower case
FcStrCopy -- duplicate a string
FcStrDowncase -- create a lower case translation of
a string
FcStrCopyFilename -- create a complete path from a
filename
FcStrCmp -- compare UTF-8 strings
FcStrCmpIgnoreCase -- compare UTF-8 strings ignoring
case
FcStrStr -- locate UTF-8 substring
FcStrStrIgnoreCase -- locate UTF-8 substring
ignoring ASCII case
FcStrPlus -- concatenate two strings
FcStrFree -- free a string
FcStrDirname -- directory part of filename
FcStrBasename -- last component of filename
1. DESCRIPTION
Fontconfig is a library designed to provide system-wide font
configuration, customization and application access.
__________________________________________________________
2. FUNCTIONAL OVERVIEW
Fontconfig contains two essential modules, the configuration
module which builds an internal configuration from XML files
and the matching module which accepts font patterns and returns
the nearest matching font.
__________________________________________________________
2.1. FONT CONFIGURATION
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.
The intent is to make font configurations relatively static,
and shared by as many applications as possible. It is hoped
that this will lead to more stable font selection when passing
names from one application to another. XML was chosen as a
configuration file format because it provides a format which is
easy for external agents to edit while retaining the correct
structure and syntax.
Font configuration is separate from font matching; applications
needing to do their own matching can access the available fonts
from the library and perform private matching. The intent is to
permit applications to pick and choose appropriate
functionality from the library instead of forcing them to
choose between this library and a private configuration
mechanism. The hope is that this will ensure that configuration
of fonts for all applications can be centralized in one place.
Centralizing font configuration will simplify and regularize
font installation and customization.
__________________________________________________________
2.2. FONT PROPERTIES
While font patterns may contain essentially any properties,
there are some well known properties with associated types.
Fontconfig uses some of these properties for font matching and
font completion. Others are provided as a convenience for the
applications rendering mechanism.
Property Definitions
Property CPP Symbol Type Description
----------------------------------------------------
family FC_FAMILY String Font family names
familylang FC_FAMILYLANG String Language cooresponding t
o
each family name
style FC_STYLE String Font style. Overrides we
ight
and slant
stylelang FC_STYLELANG String Language cooresponding t
o
each style name
fullname FC_FULLNAME String Font face full name wher
e
different from family an
d
family + style
fullnamelang FC_FULLNAMELANG String Language cooresponding t
o
each fullname
slant FC_SLANT Int Italic, oblique or roman
weight FC_WEIGHT Int Light, medium, demibold,
bold or black
size FC_SIZE Double Point size
width FC_WIDTH Int Condensed, normal or exp
anded
aspect FC_ASPECT Double Stretches glyphs horizon
tally
before hinting
pixelsize FC_PIXEL_SIZE Double Pixel size
spacing FC_SPACING Int Proportional, dual-width
,
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 s
hould
use hinting
hintstyle FC_HINT_STYLE Int Automatic hinting style
verticallayout FC_VERTICAL_LAYOUT Bool Use vertical layout
autohint FC_AUTOHINT Bool Use autohinter instead o
f
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 wi
thin
the file
ftface FC_FT_FACE FT_Face Use the specified FreeTy
pe
face object
rasterizer FC_RASTERIZER String Which rasterizer is in u
se
outline FC_OUTLINE Bool Whether the glyphs are o
utlines
scalable FC_SCALABLE Bool Whether glyphs can be sc
aled
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 ge
ometry
lcdfilter FC_LCD_FILTER Int Type of LCD filter
minspace FC_MINSPACE Bool Eliminate leading from l
ine
spacing
charset FC_CHARSET CharSet Unicode chars encoded by
the font
lang FC_LANG LangSet Set of RFC-3066-style
languages this font supp
orts
fontversion FC_FONTVERSION Int Version number of the fo
nt
capability FC_CAPABILITY String List of layout capabilit
ies in
the font
embolden FC_EMBOLDEN Bool Rasterizer should
synthetically embolden t
he font
__________________________________________________________
3. Datatypes
Fontconfig uses abstract datatypes to hide internal
implementation details for most data structures. A few
structures are exposed where appropriate.
__________________________________________________________
3.1. FcChar8, FcChar16, FcChar32, FcBool
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.
__________________________________________________________
3.2. FcMatrix
An FcMatrix holds an affine transformation, usually used to
reshape glyphs. A small set of matrix operations are provided
to manipulate these.
typedef struct _FcMatrix {
double xx, xy, yx, yy;
} FcMatrix;
__________________________________________________________
3.3. FcCharSet
An FcCharSet is an abstract type that holds the set of encoded
unicode chars in a font. Operations to build and compare these
sets are provided.
__________________________________________________________
3.4. FcLangSet
An FcLangSet is an abstract type that holds the set of
languages supported by a font. Operations to build and compare
these sets are provided. These are computed for a font based on
orthographic information built into the fontconfig library.
Fontconfig has orthographies for all of the ISO 639-1 languages
except for MS, NA, PA, PS, QU, RN, RW, SD, SG, SN, SU and ZA.
If you have orthographic information for any of these
languages, please submit them.
__________________________________________________________
3.5. FcLangResult
An FcLangResult is an enumeration used to return the results of
comparing two language strings or FcLangSet objects.
FcLangEqual means the objects match language and territory.
FcLangDifferentTerritory means the objects match in language
but differ in territory. FcLangDifferentLang means the objects
differ in language.
__________________________________________________________
3.6. FcType
Tags the kind of data stored in an FcValue.
__________________________________________________________
3.7. FcValue
An FcValue object holds a single value with one of a number of
different types. The 'type' tag indicates which member is
valid.
typedef struct _FcValue {
FcType type;
union {
const FcChar8 *s;
int i;
FcBool b;
double d;
const FcMatrix *m;
const FcCharSet *c;
void *f;
const FcLangSet *l;
} u;
} FcValue;
FcValue Members
Type Union member Datatype
--------------------------------
FcTypeVoid (none) (none)
FcTypeInteger i int
FcTypeDouble d double
FcTypeString s FcChar8 *
FcTypeBool b b
FcTypeMatrix m FcMatrix *
FcTypeCharSet c FcCharSet *
FcTypeFTFace f void * (FT_Face)
FcTypeLangSet l FcLangSet *
__________________________________________________________
3.8. FcPattern
holds a set of names with associated value lists; each name
refers to a property of a font. FcPatterns are used as inputs
to the matching code as well as holding information about
specific fonts. Each property can hold one or more values;
conventionally all of the same type, although the interface
doesn't demand that.
__________________________________________________________
3.9. FcFontSet
typedef struct _FcFontSet {
int nfont;
int sfont;
FcPattern **fonts;
} FcFontSet;
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.
__________________________________________________________
3.10. FcStrSet, FcStrList
FcStrSet holds a list of strings that can be appended to and
enumerated. Its unique characteristic is that the enumeration
works even while strings are appended during enumeration.
FcStrList is used during enumeration to safely and correctly
walk the list of strings even while that list is edited in the
middle of enumeration.
__________________________________________________________
3.11. FcObjectSet
typedef struct _FcObjectSet {
int nobject;
int sobject;
const char **objects;
} FcObjectSet;
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.
__________________________________________________________
3.12. FcObjectType
typedef struct _FcObjectType {
const char *object;
FcType type;
} FcObjectType;
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.
__________________________________________________________
3.13. FcConstant
typedef struct _FcConstant {
const FcChar8 *name;
const char *object;
int value;
} FcConstant;
Provides for symbolic constants for new pattern elements. When
'name' is seen in a font name, an 'object' element is created
with value 'value'.
__________________________________________________________
3.14. FcBlanks
holds a list of Unicode chars which are expected to be blank;
unexpectedly blank chars are assumed to be invalid and are
elided from the charset associated with the font.
__________________________________________________________
3.15. FcFileCache
holds the per-user cache information for use while loading the
font database. This is built automatically for the current
configuration when that is loaded. Applications must always
pass '0' when one is requested.
__________________________________________________________
3.16. FcConfig
holds a complete configuration of the library; there is one
default configuration, other can be constructed from XML data
structures. All public entry points that need global data can
take an optional FcConfig* argument; passing 0 uses the default
configuration. FcConfig objects hold two sets of fonts, the
first contains those specified by the configuration, the second
set holds those added by the application at run-time.
Interfaces that need to reference a particulat set use one of
the FcSetName enumerated values.
__________________________________________________________
3.17. FcSetName
Specifies one of the two sets of fonts available in a
configuration; FcSetSystem for those fonts specified in the
configuration and FcSetApplication which holds fonts provided
by the application.
__________________________________________________________
3.18. FcResult
Used as a return type for functions manipulating FcPattern
objects.
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 matc
h
FcResultNoId Object exists, but has fewer values
than specified
FcResultOutOfMemory Malloc failed
__________________________________________________________
3.19. FcAtomic
Used for locking access to config files. Provides a safe way to
update configuration files.
__________________________________________________________
3.20. FcCache
Holds information about the fonts contained in a single
directory. Normal applications need not worry about this as
caches for font access are automatically managed by the
library. Applications dealing with cache management may want to
use some of these objects in their work, however the included
'fc-cache' program generally suffices for all of that.
__________________________________________________________
4. FUNCTIONS
These are grouped by functionality, often using the main
datatype being manipulated.
__________________________________________________________
4.1. Initialization
Table of Contents
FcInitLoadConfig -- load configuration
FcInitLoadConfigAndFonts -- load configuration and font data
FcInit -- initialize fontconfig library
FcFini -- finalize fonconfig library
FcGetVersion -- library version number
FcInitReinitialize -- re-initialize library
FcInitBringUptoDate -- reload configuration files if needed
These functions provide some control over how the library is
initialized.
FcInitLoadConfig
Name
FcInitLoadConfig -- load configuration
Synopsis
#include <fontconfig.h>
FcConfig * FcInitLoadConfig(void);
Description
Loads the default configuration file and returns the resulting
configuration. Does not load any font information.
Version
Fontconfig version 2.8.0
FcInitLoadConfigAndFonts
Name
FcInitLoadConfigAndFonts -- load configuration and font data
Synopsis
#include <fontconfig.h>
FcConfig * FcInitLoadConfigAndFonts(void);
Description
Loads the default configuration file and builds information
about the available fonts. Returns the resulting configuration.
Version
Fontconfig version 2.8.0
FcInit
Name
FcInit -- initialize fontconfig library
Synopsis
#include <fontconfig.h>
FcBool FcInit(void);
Description
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.
Version
Fontconfig version 2.8.0
FcFini
Name
FcFini -- finalize fonconfig library
Synopsis
#include <fontconfig.h>
void FcFini(void);
Description
Frees all data structures allocated by previous calls to
fontconfig functions. Fontconfig returns to an uninitialized
state, requiring a new call to one of the FcInit functions
before any other fontconfig function may be called.
Version
Fontconfig version 2.8.0
FcGetVersion
Name
FcGetVersion -- library version number
Synopsis
#include <fontconfig.h>
int FcGetVersion(void);
Description
Returns the version number of the library.
Version
Fontconfig version 2.8.0
FcInitReinitialize
Name
FcInitReinitialize -- re-initialize library
Synopsis
#include <fontconfig.h>
FcBool FcInitReinitialize(void);
Description
Forces the default configuration file to be reloaded and resets
the default configuration. Returns FcFalse if the configuration
cannot be reloaded (due to config file errors, allocation
failures or other issues) and leaves the existing configuration
unchanged. Otherwise returns FcTrue.
Version
Fontconfig version 2.8.0
FcInitBringUptoDate
Name
FcInitBringUptoDate -- reload configuration files if needed
Synopsis
#include <fontconfig.h>
FcBool FcInitBringUptoDate(void);
Description
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.
Returns FcFalse if the configuration cannot be reloaded (see
FcInitReinitialize). Otherwise returns FcTrue.
Version
Fontconfig version 2.8.0
__________________________________________________________
4.2. FcPattern
Table of Contents
FcPatternCreate -- Create a pattern
FcPatternDuplicate -- Copy a pattern
FcPatternReference -- Increment pattern reference count
FcPatternDestroy -- Destroy a pattern
FcPatternEqual -- Compare patterns
FcPatternEqualSubset -- Compare portions of patterns
FcPatternFilter -- Filter the objects of pattern
FcPatternHash -- Compute a pattern hash value
FcPatternAdd -- Add a value to a pattern
FcPatternAddWeak -- Add a value to a pattern with weak binding
FcPatternAdd-Type -- Add a typed value to a pattern
FcPatternGet -- Return a value from a pattern
FcPatternGet-Type -- Return a typed value from a pattern
FcPatternBuild -- Create patterns from arguments
FcPatternDel -- Delete a property from a pattern
FcPatternRemove -- Remove one object of the specified type from
the pattern
FcPatternPrint -- Print a pattern for debugging
FcDefaultSubstitute -- Perform default substitutions in a
pattern
FcNameParse -- Parse a pattern string
FcNameUnparse -- Convert a pattern back into a string that can
be parsed
FcPatternFormat -- Format a pattern into a string according to
a format specifier
An FcPattern is an opaque type that holds both patterns to
match against the available fonts, as well as the information
about each font.
FcPatternCreate
Name
FcPatternCreate -- Create a pattern
Synopsis
#include <fontconfig.h>
FcPattern * FcPatternCreate(void);
Description
Creates a pattern with no properties; used to build patterns
from scratch.
Version
Fontconfig version 2.8.0
FcPatternDuplicate
Name
FcPatternDuplicate -- Copy a pattern
Synopsis
#include <fontconfig.h>
FcPattern * FcPatternDuplicate(const FcPattern *p);
Description
Copy a pattern, returning a new pattern that matches p. Each
pattern may be modified without affecting the other.
Version
Fontconfig version 2.8.0
FcPatternReference
Name
FcPatternReference -- Increment pattern reference count
Synopsis
#include <fontconfig.h>
void FcPatternReference(FcPattern *p);
Description
Add another reference to p. Patterns are freed only when the
reference count reaches zero.
Version
Fontconfig version 2.8.0
FcPatternDestroy
Name
FcPatternDestroy -- Destroy a pattern
Synopsis
#include <fontconfig.h>
void FcPatternDestroy(FcPattern *p);
Description
Decrement the pattern reference count. If all references are
gone, destroys the pattern, in the process destroying all
related values.
Version
Fontconfig version 2.8.0
FcPatternEqual
Name
FcPatternEqual -- Compare patterns
Synopsis
#include <fontconfig.h>
FcBool FcPatternEqual(const FcPattern *pa, const FcPattern
*pb);
Description
Returns whether pa and pb are exactly alike.
Version
Fontconfig version 2.8.0
FcPatternEqualSubset
Name
FcPatternEqualSubset -- Compare portions of patterns
Synopsis
#include <fontconfig.h>
FcBool FcPatternEqualSubset(const FcPattern *pa, const
FcPattern *pb, const FcObjectSet *os);
Description
Returns whether pa and pb have exactly the same values for all
of the objects in os.
Version
Fontconfig version 2.8.0
FcPatternFilter
Name
FcPatternFilter -- Filter the objects of pattern
Synopsis
#include <fontconfig.h>
FcPattern * FcPatternFilter(FcPattern *p, const FcObjectSet *);
Description
Returns a new pattern that only has those objects from p that
are in os. If os is NULL, a duplicate of p is returned.
Version
Fontconfig version 2.8.0
FcPatternHash
Name
FcPatternHash -- Compute a pattern hash value
Synopsis
#include <fontconfig.h>
FcChar32 FcPatternHash(const FcPattern *p);
Description
Returns a 32-bit number which is the same for any two patterns
which are equal.
Version
Fontconfig version 2.8.0
FcPatternAdd
Name
FcPatternAdd -- Add a value to a pattern
Synopsis
#include <fontconfig.h>
FcBool FcPatternAdd(FcPattern *p, const char *object, FcValue
value, FcBool append);
Description
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.
Version
Fontconfig version 2.8.0
FcPatternAddWeak
Name
FcPatternAddWeak -- Add a value to a pattern with weak binding
Synopsis
#include <fontconfig.h>
FcBool FcPatternAddWeak(FcPattern *p, const char *object,
FcValue value, FcBool append);
Description
FcPatternAddWeak is essentially the same as FcPatternAdd except
that any values added to the list have binding weak instead of
strong.
Version
Fontconfig version 2.8.0
FcPatternAdd-Type
Name
FcPatternAddInteger, FcPatternAddDouble, FcPatternAddString,
FcPatternAddMatrix, FcPatternAddCharSet, FcPatternAddBool,
FcPatternAddFTFace, FcPatternAddLangSet -- Add a typed value to
a pattern
Synopsis
#include <fontconfig.h>
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 FcChar8 *s);
FcBool FcPatternAddMatrix(FcPattern *p, const char *object,
const FcMatrix *m);
FcBool FcPatternAddCharSet(FcPattern *p, const char *object,
const FcCharSet *c);
FcBool FcPatternAddBool(FcPattern *p, const char *object,
FcBool b);
FcBool FcPatternAddFTFace(FcPattern *p, const char *object,
const FT_Facef);
FcBool FcPatternAddLangSet(FcPattern *p, const char *object,
const FcLangSet *l);
Description
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.
Version
Fontconfig version 2.8.0
FcPatternGet
Name
FcPatternGet -- Return a value from a pattern
Synopsis
#include <fontconfig.h>
FcResult FcPatternGet(FcPattern *p, const char *object, int id,
FcValue *v);
Description
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.
Version
Fontconfig version 2.8.0
FcPatternGet-Type
Name
FcPatternGetInteger, FcPatternGetDouble, FcPatternGetString,
FcPatternGetMatrix, FcPatternGetCharSet, FcPatternGetBool,
FcPatternGetFTFace, FcPatternGetLangSet -- Return a typed value
from a pattern
Synopsis
#include <fontconfig.h>
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, FcChar8 **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);
FcResult FcPatternGetFTFace(FcPattern *p, const char *object,
int n);
FcResult FcPatternGetLangSet(FcPattern *p, const char *object,
FT_Face *f);
Description
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.
Version
Fontconfig version 2.8.0
FcPatternBuild
Name
FcPatternBuild, FcPatternVaBuild, FcPatternVapBuild -- Create
patterns from arguments
Synopsis
#include <fontconfig.h>
FcPattern * FcPatternBuild(FcPattern *pattern, ...);
FcPattern * FcPatternVaBuild(FcPattern *pattern, va_list va);
void FcPatternVapBuild(FcPattern *result, FcPattern *pattern,
va_list va);
Description
Builds a pattern using a list of objects, types and values.
Each value to be entered in the pattern is specified with three
arguments:
1. Object name, a string describing the property to be added.
2. Object type, one of the FcType enumerated values
3. 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.
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
pattern = FcPatternBuild (0, FC_FAMILY, FcTypeString, "Times", (char *)
0);
FcPatternVaBuild is used when the arguments are already in the
form of a varargs value. FcPatternVapBuild is a macro version
of FcPatternVaBuild which returns its result directly in the
result variable.
Version
Fontconfig version 2.8.0
FcPatternDel
Name
FcPatternDel -- Delete a property from a pattern
Synopsis
#include <fontconfig.h>
FcBool FcPatternDel(FcPattern *p, const char *object);
Description
Deletes all values associated with the property `object',
returning whether the property existed or not.
Version
Fontconfig version 2.8.0
FcPatternRemove
Name
FcPatternRemove -- Remove one object of the specified type from
the pattern
Synopsis
#include <fontconfig.h>
FcBool FcPatternRemove(FcPattern *p, const char *object, int
id);
Description
Removes the value associated with the property `object' at
position `id', returning whether the property existed and had a
value at that position or not.
Version
Fontconfig version 2.8.0
FcPatternPrint
Name
FcPatternPrint -- Print a pattern for debugging
Synopsis
#include <fontconfig.h>
void FcPatternPrint(const FcPattern *p);
Description
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.
Version
Fontconfig version 2.8.0
FcDefaultSubstitute
Name
FcDefaultSubstitute -- Perform default substitutions in a
pattern
Synopsis
#include <fontconfig.h>
void FcDefaultSubstitute(FcPattern *pattern);
Description
Supplies default values for underspecified font patterns:
* Patterns without a specified style or weight are set to
Medium
* Patterns without a specified style or slant are set to
Roman
* Patterns without a specified pixel size are given one
computed from any specified point size (default 12), dpi
(default 75) and scale (default 1).
Version
Fontconfig version 2.8.0
FcNameParse
Name
FcNameParse -- Parse a pattern string
Synopsis
#include <fontconfig.h>
FcPattern * FcNameParse(const FcChar8 *name);
Description
Converts name from the standard text format described above
into a pattern.
Version
Fontconfig version 2.8.0
FcNameUnparse
Name
FcNameUnparse -- Convert a pattern back into a string that can
be parsed
Synopsis
#include <fontconfig.h>
FcChar8 * FcNameUnparse(FcPattern *pat);
Description
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 using free().
Version
Fontconfig version 2.8.0
FcPatternFormat
Name
FcPatternFormat -- Format a pattern into a string according to
a format specifier
Synopsis
#include <fontconfig.h>
FcChar8 * FcPatternFormat(FcPattern *pat, const FcChar8
*format);
Description
Converts given pattern pat into text described by the format
specifier format. The return value refers to newly allocated
memory which should be freed by the caller using free(), or
NULL if format is invalid.
The format is loosely modelled after printf-style format
string. The format string is composed of zero or more
directives: ordinary characters (not "%"), which are copied
unchanged to the output stream; and tags which are interpreted
to construct text from the pattern in a variety of ways
(explained below). Special characters can be escaped using
backslash. C-string style special characters like \n and \r are
also supported (this is useful when the format string is not a
C string literal). It is advisable to always escape curly
braces that are meant to be copied to the output as ordinary
characters.
Each tags is introduced by the character "%", followed by an
optional minimum field width, followed by tag contents in curly
braces ({}). If the minimum field width value is provided the
tag will be expanded and the result padded to achieve the
minimum width. If the minimum field width is positive, the
padding will right-align the text. Negative field width will
left-align. The rest of this section describes various
supported tag contents and their expansion.
A simple tag is one where the content is an identifier. When
simple tags are expanded, the named identifier will be looked
up in pattern and the resulting list of values returned, joined
together using comma. For example, to print the family name and
style the pattern, use the format "%{family} %{style}\n". To
extend the family column to forty characters use
"%-40{family}%{style}\n".
Simple tags expand to list of all values for an element. To
only choose one of the values, one can index using the syntax
"%{elt[idx]}". For example, to get the first family name only,
use "%{family[0]}".
If a simple tag ends with "=" and the element is found in the
pattern, the name of the element followed by "=" will be output
before the list of values. For example, "%{weight=}" may expand
to the string "weight=80". Or to the empty string if pattern
does not have weight set.
If a simple tag starts with ":" and the element is found in the
pattern, ":" will be printed first. For example, combining this
with the =, the format "%{:weight=}" may expand to ":weight=80"
or to the empty string if pattern does not have weight set.
If a simple tag contains the string ":-", the rest of the the
tag contents will be used as a default string. The default
string is output if the element is not found in the pattern.
For example, the format "%{:weight=:-123}" may expand to
":weight=80" or to the string ":weight=123" if pattern does not
have weight set.
A count tag is one that starts with the character "#" followed
by an element name, and expands to the number of values for the
element in the pattern. For example, "%{#family}" expands to
the number of family names pattern has set, which may be zero.
A sub-expression tag is one that expands a sub-expression. The
tag contents are the sub-expression to expand placed inside
another set of curly braces. Sub-expression tags are useful for
aligning an entire sub-expression, or to apply converters
(explained later) on an entire sub-expression. For example, the
format "%40{{%{family} %{style}}}" expands the sub-expression
to construct the family name followed by the style, then takes
the entire string and pads it on the left to be at least forty
characters.
A filter-out tag is one starting with the character "-"
followed by a comma-separated list of element names, followed
by a sub-expression enclosed in curly braces. The
sub-expression will be expanded but with a pattern that has the
listed elements removed from it. For example, the format
"%{-size,pixelsize{sub-expr}}" will expand "sub-expr" with
pattern sans the size and pixelsize elements.
A filter-in tag is one starting with the character "+" followed
by a comma-separated list of element names, followed by a
sub-expression enclosed in curly braces. The sub-expression
will be expanded but with a pattern that only has the listed
elements from the surrounding pattern. For example, the format
"%{+family,familylang{sub-expr}}" will expand "sub-expr" with a
sub-pattern consisting only the family and family lang elements
of pattern.
A conditional tag is one starting with the character "?"
followed by a comma-separated list of element conditions,
followed by two sub-expression enclosed in curly braces. An
element condition can be an element name, in which case it
tests whether the element is defined in pattern, or the
character "!" followed by an element name, in which case the
test is negated. The conditional passes if all the element
conditions pass. The tag expands the first sub-expression if
the conditional passes, and expands the second sub-expression
otherwise. For example, the format
"%{?size,dpi,!pixelsize{pass}{fail}}" will expand to "pass" if
pattern has size and dpi elements but no pixelsize element, and
to "fail" otherwise.
An enumerate tag is one starting with the string "[]" followed
by a comma-separated list of element names, followed by a
sub-expression enclosed in curly braces. The list of values for
the named elements are walked in parallel and the
sub-expression expanded each time with a pattern just having a
single value for those elements, starting from the first value
and continuing as long as any of those elements has a value.
For example, the format "%{[]family,familylang{%{family}
(%{familylang})\n}}" will expand the pattern "%{family}
(%{familylang})\n" with a pattern having only the first value
of the family and familylang elemtns, then expands it with the
second values, then the third, etc.
As a special case, if an enumerate tag has only one element,
and that element has only one value in the pattern, and that
value is of type FcLangSet, the individual languages in the
language set are enumerated.
A builtin tag is one starting with the character "=" followed
by a builtin name. The following builtins are defined:
unparse
Expands to the result of calling FcNameUnparse() on the
pattern.
fcmatch
Expands to the output of the default output format of
the fc-match command on the pattern, without the final
newline.
fclist
Expands to the output of the default output format of
the fc-list command on the pattern, without the final
newline.
pkgkit
Expands to the list of PackageKit font() tags for the
pattern. Currently this includes tags for each family
name, and each language from the pattern, enumerated and
sanitized into a set of tags terminated by newline.
Package management systems can use these tags to tag
their packages accordingly.
For example, the format "%{+family,style{%{=unparse}}}\n" will
expand to an unparsed name containing only the family and style
element values from pattern.
The contents of any tag can be followed by a set of zero or
more converters. A converter is specified by the character "|"
followed by the converter name and arguments. The following
converters are defined:
basename
Replaces text with the results of calling
FcStrBasename() on it.
dirname
Replaces text with the results of calling FcStrDirname()
on it.
downcase
Replaces text with the results of calling
FcStrDowncase() on it.
shescape
Escapes text for one level of shell expansion. (Escapes
single-quotes, also encloses text in single-quotes.)
cescape
Escapes text such that it can be used as part of a C
string literal. (Escapes backslash and double-quotes.)
xmlescape
Escapes text such that it can be used in XML and HTML.
(Escapes less-than, greater-than, and ampersand.)
delete(chars)
Deletes all occurrences of each of the characters in
chars from the text. FIXME: This converter is not UTF-8
aware yet.
escape(chars)
Escapes all occurrences of each of the characters in
chars by prepending it by the first character in chars.
FIXME: This converter is not UTF-8 aware yet.
translate(from,to)
Translates all occurrences of each of the characters in
from by replacing them with their corresponding
character in to. If to has fewer characters than from,
it will be extended by repeating its last character.
FIXME: This converter is not UTF-8 aware yet.
For example, the format "%{family|downcase|delete( )}\n" will
expand to the values of the family element in pattern,
lower-cased and with spaces removed.
Version
Fontconfig version 2.8.0
__________________________________________________________
4.3. FcFontSet
Table of Contents
FcFontSetCreate -- Create a font set
FcFontSetDestroy -- Destroy a font set
FcFontSetAdd -- Add to a font set
FcFontSetList -- List fonts from a set of font sets
FcFontSetMatch -- Return the best font from a set of font sets
FcFontSetPrint -- Print a set of patterns to stdout
FcFontSetSort -- Add to a font set
FcFontSetSortDestroy -- DEPRECATED destroy a font set
An FcFontSet simply holds a list of patterns; these are used to
return the results of listing available fonts.
FcFontSetCreate
Name
FcFontSetCreate -- Create a font set
Synopsis
#include <fontconfig.h>
FcFontSet * FcFontSetCreate(void);
Description
Creates an empty font set.
Version
Fontconfig version 2.8.0
FcFontSetDestroy
Name
FcFontSetDestroy -- Destroy a font set
Synopsis
#include <fontconfig.h>
void FcFontSetDestroy(FcFontSet *s);
Description
Destroys a font set. Note that this destroys any referenced
patterns as well.
Version
Fontconfig version 2.8.0
FcFontSetAdd
Name
FcFontSetAdd -- Add to a font set
Synopsis
#include <fontconfig.h>
FcBool FcFontSetAdd(FcFontSet *s, FcPattern *font);
Description
Adds a pattern to a font set. Note that the pattern is not
copied before being inserted into the set. Returns FcFalse if
the pattern cannot be inserted into the set (due to allocation
failure). Otherwise returns FcTrue.
Version
Fontconfig version 2.8.0
FcFontSetList
Name
FcFontSetList -- List fonts from a set of font sets
Synopsis
#include <fontconfig.h>
FcFontSet * FcFontSetList(FcConfig *config, FcFontSet **sets,
intnsets, FcPattern *pattern, FcObjectSet *object_set);
Description
Selects fonts matching pattern from sets, creates patterns from
those fonts containing only the objects in object_set and
returns the set of unique such patterns. If config is NULL, the
default configuration is checked to be up to date, and used.
Version
Fontconfig version 2.8.0
FcFontSetMatch
Name
FcFontSetMatch -- Return the best font from a set of font sets
Synopsis
#include <fontconfig.h>
FcPattern * FcFontSetMatch(FcConfig *config, FcFontSet **sets,
intnsets, FcPattern *pattern, FcResult *result);
Description
Finds the font in sets most closely matching pattern and
returns the result of FcFontRenderPrepare for that font and the
provided pattern. This function should be called only after
FcConfigSubstitute and FcDefaultSubstitute have been called for
pattern; otherwise the results will not be correct. If config
is NULL, the current configuration is used. Returns NULL if an
error occurs during this process.
Version
Fontconfig version 2.8.0
FcFontSetPrint
Name
FcFontSetPrint -- Print a set of patterns to stdout
Synopsis
#include <fontconfig.h>
void FcFontSetPrint(FcFontSet *set);
Description
This function is useful for diagnosing font related issues,
printing the complete contents of every pattern in set. The
format of the output is designed to be of help to users and
developers, and may change at any time.
Version
Fontconfig version 2.8.0
FcFontSetSort
Name
FcFontSetSort -- Add to a font set
Synopsis
#include <fontconfig.h>
FcFontSetSort(FcConfig *config, FcFontSet **sets, intnsets,
FcPattern *pattern, FcBool trim, FcCharSet **csp, FcResult
*result);
Description
Returns the list of fonts from sets sorted by closeness to
pattern. If trim is FcTrue, elements in the list which don't
include Unicode coverage not provided by earlier elements in
the list are elided. The union of Unicode coverage of all of
the fonts is returned in csp, if csp is not NULL. This function
should be called only after FcConfigSubstitute and
FcDefaultSubstitute have been called for p; otherwise the
results will not be correct.
The returned FcFontSet references FcPattern structures which
may be shared by the return value from multiple FcFontSort
calls, applications cannot modify these patterns. Instead, they
should be passed, along with pattern to FcFontRenderPrepare
which combines them into a complete pattern.
The FcFontSet returned by FcFontSetSort is destroyed by caling
FcFontSetDestroy.
Version
Fontconfig version 2.8.0
FcFontSetSortDestroy
Name
FcFontSetSortDestroy -- DEPRECATED destroy a font set
Synopsis
#include <fontconfig.h>
FcFontSetSortDestroy(FcFontSet *set);
Description
This function is DEPRECATED. FcFontSetSortDestroy destroys set
by calling FcFontSetDestroy. Applications should use
FcFontSetDestroy directly instead.
Version
Fontconfig version 2.8.0
__________________________________________________________
4.4. FcObjectSet
Table of Contents
FcObjectSetCreate -- Create an object set
FcObjectSetAdd -- Add to an object set
FcObjectSetDestroy -- Destroy an object set
FcObjectSetBuild -- Build object set from args
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.
FcObjectSetCreate
Name
FcObjectSetCreate -- Create an object set
Synopsis
#include <fontconfig.h>
FcObjectSet * FcObjectSetCreate(void);
Description
Creates an empty set.
Version
Fontconfig version 2.8.0
FcObjectSetAdd
Name
FcObjectSetAdd -- Add to an object set
Synopsis
#include <fontconfig.h>
FcBool FcObjectSetAdd(FcObjectSet *os, const char *object);
Description
Adds a proprety name to the set. Returns FcFalse if the
property name cannot be inserted into the set (due to
allocation failure). Otherwise returns FcTrue.
Version
Fontconfig version 2.8.0
FcObjectSetDestroy
Name
FcObjectSetDestroy -- Destroy an object set
Synopsis
#include <fontconfig.h>
void FcObjectSetDestroy(FcObjectSet *os);
Description
Destroys an object set.
Version
Fontconfig version 2.8.0
FcObjectSetBuild
Name
FcObjectSetBuild, FcObjectSetVaBuild,
FcObjectSetVapBuild -- Build object set from args
Synopsis
#include <fontconfig.h>
FcObjectSet * FcObjectSetBuild(const char *first, ...);
FcObjectSet * FcObjectSetVaBuild(const char *first, va_list
va);
void FcObjectSetVapBuild(FcObjectSet *result, const char
*first, va_list va);
Description
These build an object set from a null-terminated list of
property names. FcObjectSetVapBuild is a macro version of
FcObjectSetVaBuild which returns the result in the result
variable directly.
Version
Fontconfig version 2.8.0
__________________________________________________________
4.5. FreeType specific functions
Table of Contents
FcFreeTypeCharIndex -- map Unicode to glyph id
FcFreeTypeCharSet -- compute unicode coverage
FcFreeTypeCharSetAndSpacing -- compute unicode coverage and
spacing type
FcFreeTypeQuery -- compute pattern from font file (and index)
FcFreeTypeQueryFace -- compute pattern from FT_Face
While the fontconfig library doesn't insist that FreeType be
used as the rasterization mechanism for fonts, it does provide
some convenience functions.
FcFreeTypeCharIndex
Name
FcFreeTypeCharIndex -- map Unicode to glyph id
Synopsis
#include <fontconfig.h>
#include <fcfreetype.h>
FT_UInt FcFreeTypeCharIndex(FT_Face face, FcChar32 ucs4);
Description
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.
Version
Fontconfig version 2.8.0
FcFreeTypeCharSet
Name
FcFreeTypeCharSet -- compute unicode coverage
Synopsis
#include <fontconfig.h>
#include <fcfreetype.h>
FcCharSet * FcFreeTypeCharSet(FT_Face face, FcBlanks *blanks);
Description
Scans a FreeType face and returns the set of encoded Unicode
chars. This scans several encoding tables to build as complete
a list as possible. If 'blanks' is not 0, the glyphs in the
font are examined and any blank glyphs not in 'blanks' are not
placed in the returned FcCharSet.
Version
Fontconfig version 2.8.0
FcFreeTypeCharSetAndSpacing
Name
FcFreeTypeCharSetAndSpacing -- compute unicode coverage and
spacing type
Synopsis
#include <fontconfig.h>
#include <fcfreetype.h>
FcCharSet * FcFreeTypeCharSetAndSpacing(FT_Face face, FcBlanks
*blanks, int *spacing);
Description
Scans a FreeType face and returns the set of encoded Unicode
chars. This scans several encoding tables to build as complete
a list as possible. If 'blanks' is not 0, the glyphs in the
font are examined and any blank glyphs not in 'blanks' are not
placed in the returned FcCharSet. spacing receives the computed
spacing type of the font, one of FC_MONO for a font where all
glyphs have the same width, FC_DUAL, where the font has glyphs
in precisely two widths, one twice as wide as the other, or
FC_PROPORTIONAL where the font has glyphs of many widths.
Version
Fontconfig version 2.8.0
FcFreeTypeQuery
Name
FcFreeTypeQuery -- compute pattern from font file (and index)
Synopsis
#include <fontconfig.h>
#include <fcfreetype.h>
FcPattern * FcFreeTypeQuery(const FcChar8 *file, int id,
FcBlanks *blanks, int *count);
Description
Constructs a pattern representing the 'id'th font in 'file'.
The number of fonts in 'file' is returned in 'count'.
Version
Fontconfig version 2.8.0
FcFreeTypeQueryFace
Name
FcFreeTypeQueryFace -- compute pattern from FT_Face
Synopsis
#include <fontconfig.h>
#include <fcfreetype.h>
FcPattern * FcFreeTypeQueryFace(const FT_Face face, const
FcChar8 *file, int id, FcBlanks *blanks);
Description
Constructs a pattern representing 'face'. 'file' and 'id' are
used solely as data for pattern elements (FC_FILE, FC_INDEX and
sometimes FC_FAMILY).
Version
Fontconfig version 2.8.0
__________________________________________________________
4.6. FcValue
Table of Contents
FcValueDestroy -- Free a value
FcValueSave -- Copy a value
FcValuePrint -- Print a value to stdout
FcValueEqual -- Test two values for equality
FcValue is a structure containing a type tag and a union of all
possible datatypes. The tag is an enum of type FcType and is
intended to provide a measure of run-time typechecking,
although that depends on careful programming.
FcValueDestroy
Name
FcValueDestroy -- Free a value
Synopsis
#include <fontconfig.h>
void FcValueDestroy(FcValue v);
Description
Frees any memory referenced by v. Values of type FcTypeString,
FcTypeMatrix and FcTypeCharSet reference memory, the other
types do not.
Version
Fontconfig version 2.8.0
FcValueSave
Name
FcValueSave -- Copy a value
Synopsis
#include <fontconfig.h>
FcValue FcValueSave(FcValue v);
Description
Returns a copy of v duplicating any object referenced by it so
that v may be safely destroyed without harming the new value.
Version
Fontconfig version 2.8.0
FcValuePrint
Name
FcValuePrint -- Print a value to stdout
Synopsis
#include <fontconfig.h>
void FcValuePrint(FcValue v);
Description
Prints a human-readable representation of v to stdout. The
format should not be considered part of the library
specification as it may change in the future.
Version
Fontconfig version 2.8.0
FcValueEqual
Name
FcValueEqual -- Test two values for equality
Synopsis
#include <fontconfig.h>
FcBool FcValueEqual(FcValue v_a, FcValue v_b);
Description
Compares two values. Integers and Doubles are compared as
numbers; otherwise the two values have to be the same type to
be considered equal. Strings are compared ignoring case.
Version
Fontconfig version 2.8.0
__________________________________________________________
4.7. FcCharSet
Table of Contents
FcCharSetCreate -- Create an empty character set
FcCharSetDestroy -- Destroy a character set
FcCharSetAddChar -- Add a character to a charset
FcCharSetCopy -- Copy a charset
FcCharSetEqual -- Compare two charsets
FcCharSetIntersect -- Intersect charsets
FcCharSetUnion -- Add charsets
FcCharSetSubtract -- Subtract charsets
FcCharSetMerge -- Merge charsets
FcCharSetHasChar -- Check a charset for a char
FcCharSetCount -- Count entries in a charset
FcCharSetIntersectCount -- Intersect and count charsets
FcCharSetSubtractCount -- Subtract and count charsets
FcCharSetIsSubset -- Test for charset inclusion
FcCharSetFirstPage -- Start enumerating charset contents
FcCharSetNextPage -- Continue enumerating charset contents
FcCharSetCoverage -- DEPRECATED return coverage for a Unicode
page
FcCharSetNew -- DEPRECATED alias for FcCharSetCreate
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.
FcCharSetCreate
Name
FcCharSetCreate -- Create an empty character set
Synopsis
#include <fontconfig.h>
FcCharSet * FcCharSetCreate(void);
Description
FcCharSetCreate allocates and initializes a new empty character
set object.
Version
Fontconfig version 2.8.0
FcCharSetDestroy
Name
FcCharSetDestroy -- Destroy a character set
Synopsis
#include <fontconfig.h>
void FcCharSetDestroy(FcCharSet *fcs);
Description
FcCharSetDestroy decrements the reference count fcs. If the
reference count becomes zero, all memory referenced is freed.
Version
Fontconfig version 2.8.0
FcCharSetAddChar
Name
FcCharSetAddChar -- Add a character to a charset
Synopsis
#include <fontconfig.h>
FcBool FcCharSetAddChar(FcCharSet *fcs, FcChar32 ucs4);
Description
FcCharSetAddChar 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.
Version
Fontconfig version 2.8.0
FcCharSetCopy
Name
FcCharSetCopy -- Copy a charset
Synopsis
#include <fontconfig.h>
FcCharSet * FcCharSetCopy(FcCharSet *src);
Description
Makes a copy of src; note that this may not actually do
anything more than increment the reference count on src.
Version
Fontconfig version 2.8.0
FcCharSetEqual
Name
FcCharSetEqual -- Compare two charsets
Synopsis
#include <fontconfig.h>
FcBool FcCharSetEqual(const FcCharSet *a, const FcCharSet *b);
Description
Returns whether a and b contain the same set of unicode chars.
Version
Fontconfig version 2.8.0
FcCharSetIntersect
Name
FcCharSetIntersect -- Intersect charsets
Synopsis
#include <fontconfig.h>
FcCharSet * FcCharSetIntersect(const FcCharSet *a, const
FcCharSet *b);
Description
Returns a set including only those chars found in both a and b.
Version
Fontconfig version 2.8.0
FcCharSetUnion
Name
FcCharSetUnion -- Add charsets
Synopsis
#include <fontconfig.h>
FcCharSet * FcCharSetUnion(const FcCharSet *a, const FcCharSet
*b);
Description
Returns a set including only those chars found in either a or
b.
Version
Fontconfig version 2.8.0
FcCharSetSubtract
Name
FcCharSetSubtract -- Subtract charsets
Synopsis
#include <fontconfig.h>
FcCharSet * FcCharSetSubtract(const FcCharSet *a, const
FcCharSet *b);
Description
Returns a set including only those chars found in a but not b.
Version
Fontconfig version 2.8.0
FcCharSetMerge
Name
FcCharSetMerge -- Merge charsets
Synopsis
#include <fontconfig.h>
FcBool FcCharSetMerge(FcCharSet *a, const FcCharSet *b, FcBool
*changed);
Description
Adds all chars in b to a. In other words, this is an in-place
version of FcCharSetUnion. If changed is not NULL, then it
returns whether any new chars from b were added to a. Returns
FcFalse on failure, either when a is a constant set or from
running out of memory.
Version
Fontconfig version 2.8.0
FcCharSetHasChar
Name
FcCharSetHasChar -- Check a charset for a char
Synopsis
#include <fontconfig.h>
FcBool FcCharSetHasChar(const FcCharSet *fcs, FcChar32 ucs4);
Description
Returns whether fcs contains the char ucs4.
Version
Fontconfig version 2.8.0
FcCharSetCount
Name
FcCharSetCount -- Count entries in a charset
Synopsis
#include <fontconfig.h>
FcChar32 FcCharSetCount(const FcCharSet *a);
Description
Returns the total number of unicode chars in a.
Version
Fontconfig version 2.8.0
FcCharSetIntersectCount
Name
FcCharSetIntersectCount -- Intersect and count charsets
Synopsis
#include <fontconfig.h>
FcChar32 FcCharSetIntersectCount(const FcCharSet *a, const
FcCharSet *b);
Description
Returns the number of chars that are in both a and b.
Version
Fontconfig version 2.8.0
FcCharSetSubtractCount
Name
FcCharSetSubtractCount -- Subtract and count charsets
Synopsis
#include <fontconfig.h>
FcChar32 FcCharSetSubtractCount(const FcCharSet *a, const
FcCharSet *b);
Description
Returns the number of chars that are in a but not in b.
Version
Fontconfig version 2.8.0
FcCharSetIsSubset
Name
FcCharSetIsSubset -- Test for charset inclusion
Synopsis
#include <fontconfig.h>
FcBool FcCharSetIsSubset(const FcCharSet *a, const FcCharSet
*b);
Description
Returns whether a is a subset of b.
Version
Fontconfig version 2.8.0
FcCharSetFirstPage
Name
FcCharSetFirstPage -- Start enumerating charset contents
Synopsis
#include <fontconfig.h>
FcChar32 FcCharSetFirstPage(const FcCharSet *a,
FcChar32[FC_CHARSET_MAP_SIZE] map, FcChar32 *next);
Description
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.
Version
Fontconfig version 2.8.0
FcCharSetNextPage
Name
FcCharSetNextPage -- Continue enumerating charset contents
Synopsis
#include <fontconfig.h>
FcChar32 FcCharSetNextPage(const FcCharSet *a,
FcChar32[FC_CHARSET_MAP_SIZE] map, FcChar32 *next);
Description
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.
Version
Fontconfig version 2.8.0
FcCharSetCoverage
Name
FcCharSetCoverage -- DEPRECATED return coverage for a Unicode
page
Synopsis
#include <fontconfig.h>
FcChar32 FcCharSetCoverage(const FcCharSet *a, FcChar32page,
FcChar32[8]result);
Description
DEPRECATED This function returns a bitmask in result which
indicates which code points in page are included in a.
FcCharSetCoverage returns the next page in the charset which
has any coverage.
Version
Fontconfig version 2.8.0
FcCharSetNew
Name
FcCharSetNew -- DEPRECATED alias for FcCharSetCreate
Synopsis
#include <fontconfig.h>
FcCharSet * FcCharSetNew(void);
Description
FcCharSetNew is a DEPRECATED alias for FcCharSetCreate.
Version
Fontconfig version 2.8.0
__________________________________________________________
4.8. FcLangSet
Table of Contents
FcLangSetCreate -- create a langset object
FcLangSetDestroy -- destroy a langset object
FcLangSetCopy -- copy a langset object
FcLangSetAdd -- add a language to a langset
FcLangSetCompare -- compare language sets
FcLangSetContains -- check langset subset relation
FcLangSetEqual -- test for matching langsets
FcLangSetHash -- return a hash value for a langset
FcLangSetHasLang -- test langset for language support
FcLangSetGetLangs -- get the list of languages in the langset
FcGetLangs -- Get list of languages
FcLangGetCharSet -- Get character map for a language
An FcLangSet is a set of language names (each of which include
language and an optional territory). They are used when
selecting fonts to indicate which languages the fonts need to
support. Each font is marked, using language orthography
information built into fontconfig, with the set of supported
languages.
FcLangSetCreate
Name
FcLangSetCreate -- create a langset object
Synopsis
#include <fontconfig.h>
FcLangSet * FcLangSetCreate(void);
Description
FcLangSetCreate creates a new FcLangSet object.
Version
Fontconfig version 2.8.0
FcLangSetDestroy
Name
FcLangSetDestroy -- destroy a langset object
Synopsis
#include <fontconfig.h>
void FcLangSetDestroy(FcLangSet *ls);
Description
FcLangSetDestroy destroys a FcLangSet object, freeing all
memory associated with it.
Version
Fontconfig version 2.8.0
FcLangSetCopy
Name
FcLangSetCopy -- copy a langset object
Synopsis
#include <fontconfig.h>
FcLangSet * FcLangSetCopy(const FcLangSet *ls);
Description
FcLangSetCopy creates a new FcLangSet object and populates it
with the contents of ls.
Version
Fontconfig version 2.8.0
FcLangSetAdd
Name
FcLangSetAdd -- add a language to a langset
Synopsis
#include <fontconfig.h>
FcBool FcLangSetAdd(FcLangSet *ls, const FcChar8 *lang);
Description
lang is added to ls. lang should be of the form Ll-Tt where Ll
is a two or three letter language from ISO 639 and Tt is a
territory from ISO 3166.
Version
Fontconfig version 2.8.0
FcLangSetCompare
Name
FcLangSetCompare -- compare language sets
Synopsis
#include <fontconfig.h>
FcLangResult FcLangSetCompare(const FcLangSet *ls_a, const
FcLangSet *ls_b);
Description
FcLangSetCompare compares language coverage for ls_a and ls_b.
If they share any language and territory pair, this function
returns FcLangEqual. If they share a language but differ in
which territory that language is for, this function returns
FcLangDiffentTerritory. If they share no languages in common,
this function returns FcLangDifferentLang.
Version
Fontconfig version 2.8.0
FcLangSetContains
Name
FcLangSetContains -- check langset subset relation
Synopsis
#include <fontconfig.h>
FcBool FcLangSetContains(const FcLangSet *ls_a, const FcLangSet
*ls_b);
Description
FcLangSetContains returns FcTrue if ls_a contains every
language in ls_b. ls_a will 'contain' a language from ls_b if
ls_a has exactly the language, or either the language or ls_a
has no territory.
Version
Fontconfig version 2.8.0
FcLangSetEqual
Name
FcLangSetEqual -- test for matching langsets
Synopsis
#include <fontconfig.h>
FcBool FcLangSetEqual(const FcLangSet *ls_a, const FcLangSet
*ls_b);
Description
Returns FcTrue if and only if ls_a supports precisely the same
language and territory combinations as ls_b.
Version
Fontconfig version 2.8.0
FcLangSetHash
Name
FcLangSetHash -- return a hash value for a langset
Synopsis
#include <fontconfig.h>
FcChar32 FcLangSetHash(const FcLangSet *ls);
Description
This function returns a value which depends solely on the
languages supported by ls. Any language which equals ls will
have the same result from FcLangSetHash. However, two langsets
with the same hash value may not be equal.
Version
Fontconfig version 2.8.0
FcLangSetHasLang
Name
FcLangSetHasLang -- test langset for language support
Synopsis
#include <fontconfig.h>
FcLangResult FcLangSetHasLang(const FcLangSet *ls, const
FcChar8 *lang);
Description
FcLangSetHasLang checks whether ls supports lang. If ls has a
matching language and territory pair, this function returns
FcLangEqual. If ls has a matching language but differs in which
territory that language is for, this function returns
FcLangDiffentTerritory. If ls has no matching language, this
function returns FcLangDifferentLang.
Version
Fontconfig version 2.8.0
FcLangSetGetLangs
Name
FcLangSetGetLangs -- get the list of languages in the langset
Synopsis
#include <fontconfig.h>
FcStrSet * FcLangSetGetLangs(const FcLangSet *ls);
Description
Returns a string set of all languages in langset.
Version
Fontconfig version 2.8.0
FcGetLangs
Name
FcGetLangs -- Get list of languages
Synopsis
#include <fontconfig.h>
FcStrSet * FcGetLangs(void);
Description
Returns a string set of all known languages.
Version
Fontconfig version 2.8.0
FcLangGetCharSet
Name
FcLangGetCharSet -- Get character map for a language
Synopsis
#include <fontconfig.h>
const FcCharSet * FcLangGetCharSet(const FcChar8 *lang);
Description
Returns the FcCharMap for a language.
Version
Fontconfig version 2.8.0
__________________________________________________________
4.9. FcMatrix
Table of Contents
FcMatrixInit -- initialize an FcMatrix structure
FcMatrixCopy -- Copy a matrix
FcMatrixEqual -- Compare two matrices
FcMatrixMultiply -- Multiply matrices
FcMatrixRotate -- Rotate a matrix
FcMatrixScale -- Scale a matrix
FcMatrixShear -- Shear a matrix
FcMatrix structures hold an affine transformation in matrix
form.
FcMatrixInit
Name
FcMatrixInit -- initialize an FcMatrix structure
Synopsis
#include <fontconfig.h>
void FcMatrixInit(FcMatrix *matrix);
Description
FcMatrixInit initializes matrix to the identity matrix.
Version
Fontconfig version 2.8.0
FcMatrixCopy
Name
FcMatrixCopy -- Copy a matrix
Synopsis
#include <fontconfig.h>
void FcMatrixCopy(const FcMatrix *matrix);
Description
FcMatrixCopy allocates a new FcMatrix and copies mat into it.
Version
Fontconfig version 2.8.0
FcMatrixEqual
Name
FcMatrixEqual -- Compare two matrices
Synopsis
#include <fontconfig.h>
void FcMatrixEqual(const FcMatrix *matrix1, const FcMatrix
*matrix2);
Description
FcMatrixEqual compares matrix1 and matrix2 returning FcTrue
when they are equal and FcFalse when they are not.
Version
Fontconfig version 2.8.0
FcMatrixMultiply
Name
FcMatrixMultiply -- Multiply matrices
Synopsis
#include <fontconfig.h>
void FcMatrixMultiply(FcMatrix *result, const FcMatrix
*matrix1, const FcMatrix *matrix2);
Description
FcMatrixMultiply multiplies matrix1 and matrix2 storing the
result in result.
Version
Fontconfig version 2.8.0
FcMatrixRotate
Name
FcMatrixRotate -- Rotate a matrix
Synopsis
#include <fontconfig.h>
void FcMatrixRotate(FcMatrix *matrix, double cos, double sin);
Description
FcMatrixRotate rotates matrix by the angle who's sine is sin
and cosine is cos. This is done by multiplying by the matrix:
cos -sin
sin cos
Version
Fontconfig version 2.8.0
FcMatrixScale
Name
FcMatrixScale -- Scale a matrix
Synopsis
#include <fontconfig.h>
void FcMatrixScale(FcMatrix *matrix, double sx, double dy);
Description
FcMatrixScale multiplies matrix x values by sx and y values by
sy. This is done by multiplying by the matrix:
sx 0
0 sy
Version
Fontconfig version 2.8.0
FcMatrixShear
Name
FcMatrixShear -- Shear a matrix
Synopsis
#include <fontconfig.h>
void FcMatrixShear(FcMatrix *matrix, double sh, double sv);
Description
FcMatrixShare shears matrix horizontally by sh and vertically
by sv. This is done by multiplying by the matrix:
1 sh
sv 1
Version
Fontconfig version 2.8.0
__________________________________________________________
4.10. FcConfig
Table of Contents
FcConfigCreate -- Create a configuration
FcConfigReference -- Increment config reference count
FcConfigDestroy -- Destroy a configuration
FcConfigSetCurrent -- Set configuration as default
FcConfigGetCurrent -- Return current configuration
FcConfigUptoDate -- Check timestamps on config files
FcConfigHome -- return the current home directory.
FcConfigEnableHome -- controls use of the home directory.
FcConfigBuildFonts -- Build font database
FcConfigGetConfigDirs -- Get config directories
FcConfigGetFontDirs -- Get font directories
FcConfigGetConfigFiles -- Get config files
FcConfigGetCache -- DEPRECATED used to return per-user cache
filename
FcConfigGetCacheDirs -- return the list of directories searched
for cache files
FcConfigGetFonts -- Get config font set
FcConfigGetBlanks -- Get config blanks
FcConfigGetRescanInterval -- Get config rescan interval
FcConfigSetRescanInterval -- Set config rescan interval
FcConfigAppFontAddFile -- Add font file to font database
FcConfigAppFontAddDir -- Add fonts from directory to font
database
FcConfigAppFontClear -- Remove all app fonts from font database
FcConfigSubstituteWithPat -- Execute substitutions
FcConfigSubstitute -- Execute substitutions
FcFontMatch -- Return best font
FcFontSort -- Return list of matching fonts
FcFontRenderPrepare -- Prepare pattern for loading font file
FcFontList -- List fonts
FcConfigFilename -- Find a config file
FcConfigParseAndLoad -- load a configuration file
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.
FcConfigCreate
Name
FcConfigCreate -- Create a configuration
Synopsis
#include <fontconfig.h>
FcConfig * FcConfigCreate(void);
Description
Creates an empty configuration.
Version
Fontconfig version 2.8.0
FcConfigReference
Name
FcConfigReference -- Increment config reference count
Synopsis
#include <fontconfig.h>
FcConfig * FcConfigReference(FcConfig *config);
Description
Add another reference to config. Configs are freed only when
the reference count reaches zero. If config is NULL, the
current configuration is used. In that case this function will
be similar to FcConfigGetCurrent() except that it increments
the reference count before returning and the user is
responsible for destroying the configuration when not needed
anymore.
Version
Fontconfig version 2.8.0
FcConfigDestroy
Name
FcConfigDestroy -- Destroy a configuration
Synopsis
#include <fontconfig.h>
void FcConfigDestroy(FcConfig *config);
Description
Decrements the config reference count. If all references are
gone, destroys the configuration and any data associated with
it. Note that calling this function with the return from
FcConfigGetCurrent will cause a new configuration to be created
for use as current configuration.
Version
Fontconfig version 2.8.0
FcConfigSetCurrent
Name
FcConfigSetCurrent -- Set configuration as default
Synopsis
#include <fontconfig.h>
FcBool FcConfigSetCurrent(FcConfig *config);
Description
Sets the current default configuration to config. Implicitly
calls FcConfigBuildFonts if necessary, returning FcFalse if
that call fails.
Version
Fontconfig version 2.8.0
FcConfigGetCurrent
Name
FcConfigGetCurrent -- Return current configuration
Synopsis
#include <fontconfig.h>
FcConfig * FcConfigGetCurrent(void);
Description
Returns the current default configuration.
Version
Fontconfig version 2.8.0
FcConfigUptoDate
Name
FcConfigUptoDate -- Check timestamps on config files
Synopsis
#include <fontconfig.h>
FcBool FcConfigUptoDate(FcConfig *config);
Description
Checks all of the files related to config and returns whether
any of them has been modified since the configuration was
created. If config is NULL, the current configuration is used.
Version
Fontconfig version 2.8.0
FcConfigHome
Name
FcConfigHome -- return the current home directory.
Synopsis
#include <fontconfig.h>
FcChar8 * FcConfigHome(void);
Description
Return the current user's home directory, if it is available,
and if using it is enabled, and NULL otherwise. See also
FcConfigEnableHome).
Version
Fontconfig version 2.8.0
FcConfigEnableHome
Name
FcConfigEnableHome -- controls use of the home directory.
Synopsis
#include <fontconfig.h>
FcBol FcConfigEnableHome(FcBool enable);
Description
If enable is FcTrue, then Fontconfig will use various files
which are specified relative to the user's home directory
(using the ~ notation in the configuration). When enable is
FcFalse, then all use of the home directory in these contexts
will be disabled. The previous setting of the value is
returned.
Version
Fontconfig version 2.8.0
FcConfigBuildFonts
Name
FcConfigBuildFonts -- Build font database
Synopsis
#include <fontconfig.h>
FcBool FcConfigBuildFonts(FcConfig *config);
Description
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. If config is NULL, the current configuration is
used.
Version
Fontconfig version 2.8.0
FcConfigGetConfigDirs
Name
FcConfigGetConfigDirs -- Get config directories
Synopsis
#include <fontconfig.h>
FcStrList * FcConfigGetConfigDirs(FcConfig *config);
Description
Returns the list of font directories specified in the
configuration files for config. Does not include any
subdirectories. If config is NULL, the current configuration is
used.
Version
Fontconfig version 2.8.0
FcConfigGetFontDirs
Name
FcConfigGetFontDirs -- Get font directories
Synopsis
#include <fontconfig.h>
FcStrList * FcConfigGetFontDirs(FcConfig *config);
Description
Returns the list of font directories in config. This includes
the configured font directories along with any directories
below those in the filesystem. If config is NULL, the current
configuration is used.
Version
Fontconfig version 2.8.0
FcConfigGetConfigFiles
Name
FcConfigGetConfigFiles -- Get config files
Synopsis
#include <fontconfig.h>
FcStrList * FcConfigGetConfigFiles(FcConfig *config);
Description
Returns the list of known configuration files used to generate
config. If config is NULL, the current configuration is used.
Version
Fontconfig version 2.8.0
FcConfigGetCache
Name
FcConfigGetCache -- DEPRECATED used to return per-user cache
filename
Synopsis
#include <fontconfig.h>
FcChar8 * FcConfigGetCache(FcConfig *config);
Description
With fontconfig no longer using per-user cache files, this
function now simply returns NULL to indicate that no per-user
file exists.
Version
Fontconfig version 2.8.0
FcConfigGetCacheDirs
Name
FcConfigGetCacheDirs -- return the list of directories searched
for cache files
Synopsis
#include <fontconfig.h>
FcStrList * FcConfigGetCacheDirs(FcConfig *config);
Description
FcConfigGetCacheDirs returns a string list containing all of
the directories that fontconfig will search when attempting to
load a cache file for a font directory. If config is NULL, the
current configuration is used.
Version
Fontconfig version 2.8.0
FcConfigGetFonts
Name
FcConfigGetFonts -- Get config font set
Synopsis
#include <fontconfig.h>
FcFontSet * FcConfigGetFonts(FcConfig *config, FcSetName set);
Description
Returns one of the two sets of fonts from the configuration as
specified by set. This font set is owned by the library and
must not be modified or freed. If config is NULL, the current
configuration is used.
Version
Fontconfig version 2.8.0
FcConfigGetBlanks
Name
FcConfigGetBlanks -- Get config blanks
Synopsis
#include <fontconfig.h>
FcBlanks * FcConfigGetBlanks(FcConfig *config);
Description
Returns the FcBlanks object associated with the given
configuration, if no blanks were present in the configuration,
this function will return 0. The returned FcBlanks object if
not NULL, is valid as long as the owning FcConfig is alive. If
config is NULL, the current configuration is used.
Version
Fontconfig version 2.8.0
FcConfigGetRescanInterval
Name
FcConfigGetRescanInterval -- Get config rescan interval
Synopsis
#include <fontconfig.h>
int FcConfigGetRescanInterval(FcConfig *config);
Description
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. An interval setting
of zero disables automatic checks. If config is NULL, the
current configuration is used.
Version
Fontconfig version 2.8.0
FcConfigSetRescanInterval
Name
FcConfigSetRescanInterval -- Set config rescan interval
Synopsis
#include <fontconfig.h>
FcBool FcConfigSetRescanInterval(FcConfig *config, int
rescanInterval);
Description
Sets the rescan interval. Returns FcFalse if the interval
cannot be set (due to allocation failure). Otherwise returns
FcTrue. An interval setting of zero disables automatic checks.
If config is NULL, the current configuration is used.
Version
Fontconfig version 2.8.0
FcConfigAppFontAddFile
Name
FcConfigAppFontAddFile -- Add font file to font database
Synopsis
#include <fontconfig.h>
FcBool FcConfigAppFontAddFile(FcConfig *config, const FcChar8
*file);
Description
Adds an application-specific font to the configuration. Returns
FcFalse if the fonts cannot be added (due to allocation
failure). Otherwise returns FcTrue. If config is NULL, the
current configuration is used.
Version
Fontconfig version 2.8.0
FcConfigAppFontAddDir
Name
FcConfigAppFontAddDir -- Add fonts from directory to font
database
Synopsis
#include <fontconfig.h>
FcBool FcConfigAppFontAddDir(FcConfig *config, const FcChar8
*dir);
Description
Scans the specified directory for fonts, adding each one found
to the application-specific set of fonts. Returns FcFalse if
the fonts cannot be added (due to allocation failure).
Otherwise returns FcTrue. If config is NULL, the current
configuration is used.
Version
Fontconfig version 2.8.0
FcConfigAppFontClear
Name
FcConfigAppFontClear -- Remove all app fonts from font database
Synopsis
#include <fontconfig.h>
void FcConfigAppFontClear(FcConfig *config);
Description
Clears the set of application-specific fonts. If config is
NULL, the current configuration is used.
Version
Fontconfig version 2.8.0
FcConfigSubstituteWithPat
Name
FcConfigSubstituteWithPat -- Execute substitutions
Synopsis
#include <fontconfig.h>
FcBool FcConfigSubstituteWithPat(FcConfig *config, FcPattern
*p, FcPattern *p_pat, FcMatchKind kind);
Description
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. Returns FcFalse if the substitution cannot
be performed (due to allocation failure). Otherwise returns
FcTrue. If config is NULL, the current configuration is used.
Version
Fontconfig version 2.8.0
FcConfigSubstitute
Name
FcConfigSubstitute -- Execute substitutions
Synopsis
#include <fontconfig.h>
FcBool FcConfigSubstitute(FcConfig *config, FcPattern *p,
FcMatchKind kind);
Description
Calls FcConfigSubstituteWithPat setting p_pat to NULL. Returns
FcFalse if the substitution cannot be performed (due to
allocation failure). Otherwise returns FcTrue. If config is
NULL, the current configuration is used.
Version
Fontconfig version 2.8.0
FcFontMatch
Name
FcFontMatch -- Return best font
Synopsis
#include <fontconfig.h>
FcPattern * FcFontMatch(FcConfig *config, FcPattern *p,
FcResult *result);
Description
Finds the font in sets most closely matching pattern and
returns the result of FcFontRenderPrepare for that font and the
provided pattern. This function should be called only after
FcConfigSubstitute and FcDefaultSubstitute have been called for
p; otherwise the results will not be correct. If config is
NULL, the current configuration is used.
Version
Fontconfig version 2.8.0
FcFontSort
Name
FcFontSort -- Return list of matching fonts
Synopsis
#include <fontconfig.h>
FcFontSet * FcFontSort(FcConfig *config, FcPattern *p, FcBool
trim, FcCharSet **csp, FcResult *result);
Description
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.
The returned FcFontSet references FcPattern structures which
may be shared by the return value from multiple FcFontSort
calls, applications must not modify these patterns. Instead,
they should be passed, along with p to FcFontRenderPrepare
which combines them into a complete pattern.
The FcFontSet returned by FcFontSort is destroyed by caling
FcFontSetDestroy. If config is NULL, the current configuration
is used.
Version
Fontconfig version 2.8.0
FcFontRenderPrepare
Name
FcFontRenderPrepare -- Prepare pattern for loading font file
Synopsis
#include <fontconfig.h>
FcPattern * FcFontRenderPrepare(FcConfig *config, FcPattern
*pat, FcPattern *font);
Description
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 FcConfigSubstituteWithPat with kind
FcMatchFont and then returned.
Version
Fontconfig version 2.8.0
FcFontList
Name
FcFontList -- List fonts
Synopsis
#include <fontconfig.h>
FcFontSet * FcFontList(FcConfig *config, FcPattern *p,
FcObjectSet *os);
Description
Selects fonts matching p, creates patterns from those fonts
containing only the objects in os and returns the set of unique
such patterns. If config is NULL, the default configuration is
checked to be up to date, and used.
Version
Fontconfig version 2.8.0
FcConfigFilename
Name
FcConfigFilename -- Find a config file
Synopsis
#include <fontconfig.h>
FcChar8 * FcConfigFilename(const FcChar8 *name);
Description
Given the specified external entity name, return the associated
filename. This provides applications a way to convert various
configuration file references into filename form.
A null or empty name indicates that the default configuration
file should be used; which file this references can be
overridden with the FC_CONFIG_FILE environment variable. Next,
if the name starts with ~, it refers to a file in the current
users home directory. Otherwise if the name doesn't start with
'/', it refers to a file in the default configuration
directory; the built-in default directory can be overridden
with the FC_CONFIG_DIR environment variable.
Version
Fontconfig version 2.8.0
FcConfigParseAndLoad
Name
FcConfigParseAndLoad -- load a configuration file
Synopsis
#include <fontconfig.h>
FcBool FcConfigParseAndLoad(FcConfig *config, const FcChar8
*file, FcBool complain);
Description
Walks the configuration in 'file' and constructs the internal
representation in 'config'. Any include files referenced from
within 'file' will be loaded and parsed. If 'complain' is
FcFalse, no warning will be displayed if 'file' does not exist.
Error and warning messages will be output to stderr. Returns
FcFalse if some error occurred while loading the file, either a
parse error, semantic error or allocation failure. Otherwise
returns FcTrue.
Version
Fontconfig version 2.8.0
__________________________________________________________
4.11. FcObjectType
Table of Contents
FcNameRegisterObjectTypes -- Register object types
FcNameUnregisterObjectTypes -- Unregister object types
FcNameGetObjectType -- Lookup an object type
Provides for applcation-specified font name object types so
that new pattern elements can be generated from font names.
FcNameRegisterObjectTypes
Name
FcNameRegisterObjectTypes -- Register object types
Synopsis
#include <fontconfig.h>
FcBool FcNameRegisterObjectTypes(const FcObjectType *types, int
ntype);
Description
Register ntype new object types. Returns FcFalse if some of the
names cannot be registered (due to allocation failure).
Otherwise returns FcTrue.
Version
Fontconfig version 2.8.0
FcNameUnregisterObjectTypes
Name
FcNameUnregisterObjectTypes -- Unregister object types
Synopsis
#include <fontconfig.h>
FcBool FcNameUnregisterObjectTypes(const FcObjectType *types,
int ntype);
Description
Unregister ntype object types. Returns FcTrue.
Version
Fontconfig version 2.8.0
FcNameGetObjectType
Name
FcNameGetObjectType -- Lookup an object type
Synopsis
#include <fontconfig.h>
const FcObjectType * FcNameGetObjectType(const char *object);
Description
Return the object type for the pattern element named object.
Version
Fontconfig version 2.8.0
__________________________________________________________
4.12. FcConstant
Table of Contents
FcNameRegisterConstants -- Register symbolic constants
FcNameUnregisterConstants -- Unregister symbolic constants
FcNameGetConstant -- Lookup symbolic constant
FcNameConstant -- Get the value for a symbolic constant
Provides for application-specified symbolic constants for font
names.
FcNameRegisterConstants
Name
FcNameRegisterConstants -- Register symbolic constants
Synopsis
#include <fontconfig.h>
FcBool FcNameRegisterConstants(const FcConstant *consts, int
nconsts);
Description
Register nconsts new symbolic constants. Returns FcFalse if the
constants cannot be registered (due to allocation failure).
Otherwise returns FcTrue.
Version
Fontconfig version 2.8.0
FcNameUnregisterConstants
Name
FcNameUnregisterConstants -- Unregister symbolic constants
Synopsis
#include <fontconfig.h>
FcBool FcNameUnregisterConstants(const FcConstant *consts, int
nconsts);
Description
Unregister nconsts symbolic constants. Returns FcFalse if the
specified constants were not registered. Otherwise returns
FcTrue.
Version
Fontconfig version 2.8.0
FcNameGetConstant
Name
FcNameGetConstant -- Lookup symbolic constant
Synopsis
#include <fontconfig.h>
const FcConstant * FcNameGetConstant(FcChar8 *string);
Description
Return the FcConstant structure related to symbolic constant
string.
Version
Fontconfig version 2.8.0
FcNameConstant
Name
FcNameConstant -- Get the value for a symbolic constant
Synopsis
#include <fontconfig.h>
FcBool FcNameConstant(FcChar8 *string, int *result);
Description
Returns whether a symbolic constant with name string is
registered, placing the value of the constant in result if
present.
Version
Fontconfig version 2.8.0
__________________________________________________________
4.13. FcBlanks
Table of Contents
FcBlanksCreate -- Create an FcBlanks
FcBlanksDestroy -- Destroy and FcBlanks
FcBlanksAdd -- Add a character to an FcBlanks
FcBlanksIsMember -- Query membership in an FcBlanks
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.
FcBlanksCreate
Name
FcBlanksCreate -- Create an FcBlanks
Synopsis
#include <fontconfig.h>
FcBlanks * FcBlanksCreate(void);
Description
Creates an empty FcBlanks object.
Version
Fontconfig version 2.8.0
FcBlanksDestroy
Name
FcBlanksDestroy -- Destroy and FcBlanks
Synopsis
#include <fontconfig.h>
void FcBlanksDestroy(FcBlanks *b);
Description
Destroys an FcBlanks object, freeing any associated memory.
Version
Fontconfig version 2.8.0
FcBlanksAdd
Name
FcBlanksAdd -- Add a character to an FcBlanks
Synopsis
#include <fontconfig.h>
FcBool FcBlanksAdd(FcBlanks *b, FcChar32 ucs4);
Description
Adds a single character to an FcBlanks object, returning
FcFalse if this process ran out of memory.
Version
Fontconfig version 2.8.0
FcBlanksIsMember
Name
FcBlanksIsMember -- Query membership in an FcBlanks
Synopsis
#include <fontconfig.h>
FcBool FcBlanksIsMember(FcBlanks *b, FcChar32 ucs4);
Description
Returns whether the specified FcBlanks object contains the
indicated Unicode value.
Version
Fontconfig version 2.8.0
__________________________________________________________
4.14. FcAtomic
Table of Contents
FcAtomicCreate -- create an FcAtomic object
FcAtomicLock -- lock a file
FcAtomicNewFile -- return new temporary file name
FcAtomicOrigFile -- return original file name
FcAtomicReplaceOrig -- replace original with new
FcAtomicDeleteNew -- delete new file
FcAtomicUnlock -- unlock a file
FcAtomicDestroy -- destroy an FcAtomic object
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.
FcAtomicCreate
Name
FcAtomicCreate -- create an FcAtomic object
Synopsis
#include <fontconfig.h>
FcAtomic * FcAtomicCreate(const FcChar8 *file);
Description
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.
Version
Fontconfig version 2.8.0
FcAtomicLock
Name
FcAtomicLock -- lock a file
Synopsis
#include <fontconfig.h>
FcBool FcAtomicLock(FcAtomic *atomic);
Description
Attempts to lock the file referenced by atomic. Returns FcFalse
if the file is already locked, else returns FcTrue and leaves
the file locked.
Version
Fontconfig version 2.8.0
FcAtomicNewFile
Name
FcAtomicNewFile -- return new temporary file name
Synopsis
#include <fontconfig.h>
FcChar8 * FcAtomicNewFile(FcAtomic *atomic);
Description
Returns the filename for writing a new version of the file
referenced by atomic.
Version
Fontconfig version 2.8.0
FcAtomicOrigFile
Name
FcAtomicOrigFile -- return original file name
Synopsis
#include <fontconfig.h>
FcChar8 * FcAtomicOrigFile(FcAtomic *atomic);
Description
Returns the file refernced by atomic.
Version
Fontconfig version 2.8.0
FcAtomicReplaceOrig
Name
FcAtomicReplaceOrig -- replace original with new
Synopsis
#include <fontconfig.h>
FcBool FcAtomicReplaceOrig(FcAtomic *atomic);
Description
Replaces the original file referenced by atomic with the new
file. Returns FcFalse if the file cannot be replaced due to
permission issues in the filesystem. Otherwise returns FcTrue.
Version
Fontconfig version 2.8.0
FcAtomicDeleteNew
Name
FcAtomicDeleteNew -- delete new file
Synopsis
#include <fontconfig.h>
void FcAtomicDeleteNew(FcAtomic *atomic);
Description
Deletes the new file. Used in error recovery to back out
changes.
Version
Fontconfig version 2.8.0
FcAtomicUnlock
Name
FcAtomicUnlock -- unlock a file
Synopsis
#include <fontconfig.h>
void FcAtomicUnlock(FcAtomic *atomic);
Description
Unlocks the file.
Version
Fontconfig version 2.8.0
FcAtomicDestroy
Name
FcAtomicDestroy -- destroy an FcAtomic object
Synopsis
#include <fontconfig.h>
void FcAtomicDestroy(FcAtomic *atomic);
Description
Destroys atomic.
Version
Fontconfig version 2.8.0
__________________________________________________________
4.15. File and Directory routines
Table of Contents
FcFileScan -- scan a font file
FcFileIsDir -- check whether a file is a directory
FcDirScan -- scan a font directory without caching it
FcDirSave -- DEPRECATED: formerly used to save a directory
cache
FcDirCacheUnlink -- Remove all caches related to dir
FcDirCacheValid -- check directory cache
FcDirCacheLoad -- load a directory cache
FcDirCacheRead -- read or construct a directory cache
FcDirCacheLoadFile -- load a cache file
FcDirCacheUnload -- unload a cache file
These routines work with font files and directories, including
font directory cache files.
FcFileScan
Name
FcFileScan -- scan a font file
Synopsis
#include <fontconfig.h>
FcBool FcFileScan(FcFontSet *set, FcStrSet *dirs, FcFileCache
*cache, FcBlanks *blanks, const FcChar8 *file, FcBool force);
Description
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. Whether fonts are found depends on fontconfig
policy as well as the current configuration. Internally,
fontconfig will ignore BDF and PCF fonts which are not in
Unicode (or the effectively equivalent ISO Latin-1) encoding as
those are not usable by Unicode-based applications. The
configuration can ignore fonts based on filename or contents of
the font file itself. Returns FcFalse if any of the fonts
cannot be added (due to allocation failure). Otherwise returns
FcTrue.
Version
Fontconfig version 2.8.0
FcFileIsDir
Name
FcFileIsDir -- check whether a file is a directory
Synopsis
#include <fontconfig.h>
FcBool FcFileIsDir(const FcChar8 *file);
Description
Returns FcTrue if file is a directory, otherwise returns
FcFalse.
Version
Fontconfig version 2.8.0
FcDirScan
Name
FcDirScan -- scan a font directory without caching it
Synopsis
#include <fontconfig.h>
FcBool FcDirScan(FcFontSet *set, FcStrSet *dirs, FcFileCache
*cache, FcBlanks *blanks, const FcChar8 *dir, FcBool force);
Description
If cache is not zero or if force is FcFalse, this function
currently returns FcFalse. Otherwise, it scans an entire
directory and adds all fonts found to set. Any subdirectories
found are added to dirs. Calling this function does not create
any cache files. Use FcDirCacheRead() if caching is desired.
Version
Fontconfig version 2.8.0
FcDirSave
Name
FcDirSave -- DEPRECATED: formerly used to save a directory
cache
Synopsis
#include <fontconfig.h>
FcBool FcDirSave(FcFontSet *set, FcStrSet *dirs, const FcChar8
*dir);
Description
This function now does nothing aside from returning FcFalse. It
used to creates the per-directory cache file for dir and
populates it with the fonts in set and subdirectories in dirs.
All of this functionality is now automatically managed by
FcDirCacheLoad and FcDirCacheRead.
Version
Fontconfig version 2.8.0
FcDirCacheUnlink
Name
FcDirCacheUnlink -- Remove all caches related to dir
Synopsis
#include <fontconfig.h>
FcBool FcDirCacheUnlink(const FcChar8 *dir, FcConfig *config);
Description
Scans the cache directories in config, removing any instances
of the cache file for dir. Returns FcFalse when some internal
error occurs (out of memory, etc). Errors actually unlinking
any files are ignored.
Version
Fontconfig version 2.8.0
FcDirCacheValid
Name
FcDirCacheValid -- check directory cache
Synopsis
#include <fontconfig.h>
FcBool FcDirCacheValid(const FcChar8 *dir);
Description
Returns FcTrue if dir has an associated valid cache file, else
returns FcFalse
Version
Fontconfig version 2.8.0
FcDirCacheLoad
Name
FcDirCacheLoad -- load a directory cache
Synopsis
#include <fontconfig.h>
FcCache * FcDirCacheLoad(const FcChar8 *dir, FcConfig *config,
FcChar8 **cache_file);
Description
Loads the cache related to dir. If no cache file exists,
returns NULL. The name of the cache file is returned in
cache_file, unless that is NULL. See also FcDirCacheRead.
Version
Fontconfig version 2.8.0
FcDirCacheRead
Name
FcDirCacheRead -- read or construct a directory cache
Synopsis
#include <fontconfig.h>
FcCache * FcDirCacheRead(const FcChar8 *dir, FcBool force,
FcConfig *config);
Description
This returns a cache for dir. If force is FcFalse, then an
existing, valid cache file will be used. Otherwise, a new cache
will be created by scanning the directory and that returned.
Version
Fontconfig version 2.8.0
FcDirCacheLoadFile
Name
FcDirCacheLoadFile -- load a cache file
Synopsis
#include <fontconfig.h>
FcCache * FcDirCacheLoadFile(const FcChar8 *cache_file, struct
stat *file_stat);
Description
This function loads a directory cache from cache_file. If
file_stat is non-NULL, it will be filled with the results of
stat(2) on the cache file.
Version
Fontconfig version 2.8.0
FcDirCacheUnload
Name
FcDirCacheUnload -- unload a cache file
Synopsis
#include <fontconfig.h>
void FcDirCacheUnload(FcCache *cache);
Description
This function dereferences cache. When no other references to
it remain, all memory associated with the cache will be freed.
Version
Fontconfig version 2.8.0
__________________________________________________________
4.16. FcCache routines
Table of Contents
FcCacheDir -- Return directory of cache
FcCacheCopySet -- Returns a copy of the fontset from cache
FcCacheSubdir -- Return the i'th subdirectory.
FcCacheNumSubdir -- Return the number of subdirectories in
cache.
FcCacheNumFont -- Returns the number of fonts in cache.
These routines work with font directory caches, accessing their
contents in limited ways. It is not expected that normal
applications will need to use these functions.
FcCacheDir
Name
FcCacheDir -- Return directory of cache
Synopsis
#include <fontconfig.h>
const FcChar8 * FcCacheDir(const FcCache *cache);
Description
This function returns the directory from which the cache was
constructed.
Version
Fontconfig version 2.8.0
FcCacheCopySet
Name
FcCacheCopySet -- Returns a copy of the fontset from cache
Synopsis
#include <fontconfig.h>
FcFontSet * FcCacheCopySet(const FcCache *cache);
Description
The returned fontset contains each of the font patterns from
cache. This fontset may be modified, but the patterns from the
cache are read-only.
Version
Fontconfig version 2.8.0
FcCacheSubdir
Name
FcCacheSubdir -- Return the i'th subdirectory.
Synopsis
#include <fontconfig.h>
const FcChar8 * FcCacheSubdir(const FcCache *cache, inti);
Description
The set of subdirectories stored in a cache file are indexed by
this function, i should range from 0 to n-1, where n is the
return value from FcCacheNumSubdir.
Version
Fontconfig version 2.8.0
FcCacheNumSubdir
Name
FcCacheNumSubdir -- Return the number of subdirectories in
cache.
Synopsis
#include <fontconfig.h>
int FcCacheNumSubdir(const FcCache *cache);
Description
This returns the total number of subdirectories in the cache.
Version
Fontconfig version 2.8.0
FcCacheNumFont
Name
FcCacheNumFont -- Returns the number of fonts in cache.
Synopsis
#include <fontconfig.h>
int FcCacheNumFont(const FcCache *cache);
Description
This returns the number of fonts which would be included in the
return from FcCacheCopySet.
Version
Fontconfig version 2.8.0
__________________________________________________________
4.17. FcStrSet and FcStrList
Table of Contents
FcStrSetCreate -- create a string set
FcStrSetMember -- check set for membership
FcStrSetEqual -- check sets for equality
FcStrSetAdd -- add to a string set
FcStrSetAddFilename -- add a filename to a string set
FcStrSetDel -- delete from a string set
FcStrSetDestroy -- destroy a string set
FcStrListCreate -- create a string iterator
FcStrListNext -- get next string in iteration
FcStrListDone -- destroy a string iterator
A data structure for enumerating strings, used to list
directories while scanning the configuration as directories are
added while scanning.
FcStrSetCreate
Name
FcStrSetCreate -- create a string set
Synopsis
#include <fontconfig.h>
FcStrSet * FcStrSetCreate(void);
Description
Create an empty set.
Version
Fontconfig version 2.8.0
FcStrSetMember
Name
FcStrSetMember -- check set for membership
Synopsis
#include <fontconfig.h>
FcBool FcStrSetMember(FcStrSet *set, const FcChar8 *s);
Description
Returns whether s is a member of set.
Version
Fontconfig version 2.8.0
FcStrSetEqual
Name
FcStrSetEqual -- check sets for equality
Synopsis
#include <fontconfig.h>
FcBool FcStrSetEqual(FcStrSet *set_a, FcStrSet *set_b);
Description
Returns whether set_a contains precisely the same strings as
set_b. Ordering of strings within the two sets is not
considered.
Version
Fontconfig version 2.8.0
FcStrSetAdd
Name
FcStrSetAdd -- add to a string set
Synopsis
#include <fontconfig.h>
FcBool FcStrSetAdd(FcStrSet *set, const FcChar8 *s);
Description
Adds a copy of s to set.
Version
Fontconfig version 2.8.0
FcStrSetAddFilename
Name
FcStrSetAddFilename -- add a filename to a string set
Synopsis
#include <fontconfig.h>
FcBool FcStrSetAddFilename(FcStrSet *set, const FcChar8 *s);
Description
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.
Version
Fontconfig version 2.8.0
FcStrSetDel
Name
FcStrSetDel -- delete from a string set
Synopsis
#include <fontconfig.h>
FcBool FcStrSetDel(FcStrSet *set, const FcChar8 *s);
Description
Removes s from set, returning FcTrue if s was a member else
FcFalse.
Version
Fontconfig version 2.8.0
FcStrSetDestroy
Name
FcStrSetDestroy -- destroy a string set
Synopsis
#include <fontconfig.h>
void FcStrSetDestroy(FcStrSet *set);
Description
Destroys set.
Version
Fontconfig version 2.8.0
FcStrListCreate
Name
FcStrListCreate -- create a string iterator
Synopsis
#include <fontconfig.h>
FcStrList * FcStrListCreate(FcStrSet *set);
Description
Creates an iterator to list the strings in set.
Version
Fontconfig version 2.8.0
FcStrListNext
Name
FcStrListNext -- get next string in iteration
Synopsis
#include <fontconfig.h>
FcChar8 * FcStrListNext(FcStrList *list);
Description
Returns the next string in set.
Version
Fontconfig version 2.8.0
FcStrListDone
Name
FcStrListDone -- destroy a string iterator
Synopsis
#include <fontconfig.h>
void FcStrListDone(FcStrList *list);
Description
Destroys the enumerator list.
Version
Fontconfig version 2.8.0
__________________________________________________________
4.18. String utilities
Table of Contents
FcUtf8ToUcs4 -- convert UTF-8 to UCS4
FcUcs4ToUtf8 -- convert UCS4 to UTF-8
FcUtf8Len -- count UTF-8 encoded chars
FcUtf16ToUcs4 -- convert UTF-16 to UCS4
FcUtf16Len -- count UTF-16 encoded chars
FcIsLower -- check for lower case ASCII character
FcIsUpper -- check for upper case ASCII character
FcToLower -- convert upper case ASCII to lower case
FcStrCopy -- duplicate a string
FcStrDowncase -- create a lower case translation of a string
FcStrCopyFilename -- create a complete path from a filename
FcStrCmp -- compare UTF-8 strings
FcStrCmpIgnoreCase -- compare UTF-8 strings ignoring case
FcStrStr -- locate UTF-8 substring
FcStrStrIgnoreCase -- locate UTF-8 substring ignoring ASCII
case
FcStrPlus -- concatenate two strings
FcStrFree -- free a string
FcStrDirname -- directory part of filename
FcStrBasename -- last component of filename
Fontconfig manipulates many UTF-8 strings represented with the
FcChar8 type. These functions are exposed to help applications
deal with these UTF-8 strings in a locale-insensitive manner.
FcUtf8ToUcs4
Name
FcUtf8ToUcs4 -- convert UTF-8 to UCS4
Synopsis
#include <fontconfig.h>
int FcUtf8ToUcs4(FcChar8 *src, FcChar32 *dst, int len);
Description
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.
Version
Fontconfig version 2.8.0
FcUcs4ToUtf8
Name
FcUcs4ToUtf8 -- convert UCS4 to UTF-8
Synopsis
#include <fontconfig.h>
int FcUcs4ToUtf8(FcChar32 src, FcChar8 dst[FC_UTF8_MAX_LEN]);
Description
Converts the Unicode char from src into dst and returns the
number of bytes needed to encode the char.
Version
Fontconfig version 2.8.0
FcUtf8Len
Name
FcUtf8Len -- count UTF-8 encoded chars
Synopsis
#include <fontconfig.h>
FcBool FcUtf8Len(FcChar8 *src, int len, int *nchar, int
*wchar);
Description
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.
Version
Fontconfig version 2.8.0
FcUtf16ToUcs4
Name
FcUtf16ToUcs4 -- convert UTF-16 to UCS4
Synopsis
#include <fontconfig.h>
int FcUtf16ToUcs4(FcChar8 *src, FcEndian endian, FcChar32 *dst,
int len);
Description
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.
Version
Fontconfig version 2.8.0
FcUtf16Len
Name
FcUtf16Len -- count UTF-16 encoded chars
Synopsis
#include <fontconfig.h>
FcBool FcUtf16Len(FcChar8 *src, FcEndian endian, int len, int
*nchar, int *wchar);
Description
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.
Version
Fontconfig version 2.8.0
FcIsLower
Name
FcIsLower -- check for lower case ASCII character
Synopsis
#include <fontconfig.h>
FcBool FcIsLower(FcChar8c);
Description
This macro checks whether c is an lower case ASCII letter.
Version
Fontconfig version 2.8.0
FcIsUpper
Name
FcIsUpper -- check for upper case ASCII character
Synopsis
#include <fontconfig.h>
FcBool FcIsUpper(FcChar8c);
Description
This macro checks whether c is a upper case ASCII letter.
Version
Fontconfig version 2.8.0
FcToLower
Name
FcToLower -- convert upper case ASCII to lower case
Synopsis
#include <fontconfig.h>
FcChar8 FcToLower(FcChar8c);
Description
This macro converts upper case ASCII c to the equivalent lower
case letter.
Version
Fontconfig version 2.8.0
FcStrCopy
Name
FcStrCopy -- duplicate a string
Synopsis
#include <fontconfig.h>
FcChar8 * FcStrCopy(const FcChar8 *s);
Description
Allocates memory, copies s and returns the resulting buffer.
Yes, this is strdup, but that function isn't available on every
platform.
Version
Fontconfig version 2.8.0
FcStrDowncase
Name
FcStrDowncase -- create a lower case translation of a string
Synopsis
#include <fontconfig.h>
FcChar8 * FcStrDowncase(const FcChar8 *s);
Description
Allocates memory, copies s, converting upper case letters to
lower case and returns the allocated buffer.
Version
Fontconfig version 2.8.0
FcStrCopyFilename
Name
FcStrCopyFilename -- create a complete path from a filename
Synopsis
#include <fontconfig.h>
FcChar8 * FcStrCopyFilename(const FcChar8 *s);
Description
FcStrCopyFilename constructs an absolute pathname from s. It
converts any leading '~' characters in to the value of the HOME
environment variable, and any relative paths are converted to
absolute paths using the current working directory. Sequences
of '/' characters are converted to a single '/', and names
containing the current directory '.' or parent directory '..'
are correctly reconstructed. Returns NULL if '~' is the leading
character and HOME is unset or disabled (see
FcConfigEnableHome).
Version
Fontconfig version 2.8.0
FcStrCmp
Name
FcStrCmp -- compare UTF-8 strings
Synopsis
#include <fontconfig.h>
int FcStrCmp(const FcChar8 *s1, const FcChar8 *s2);
Description
Returns the usual <0, 0, >0 result of comparing s1 and s2.
Version
Fontconfig version 2.8.0
FcStrCmpIgnoreCase
Name
FcStrCmpIgnoreCase -- compare UTF-8 strings ignoring case
Synopsis
#include <fontconfig.h>
int FcStrCmpIgnoreCase(const FcChar8 *s1, const FcChar8 *s2);
Description
Returns the usual <0, 0, >0 result of comparing s1 and s2. This
test is case-insensitive for all proper UTF-8 encoded strings.
Version
Fontconfig version 2.8.0
FcStrStr
Name
FcStrStr -- locate UTF-8 substring
Synopsis
#include <fontconfig.h>
FcChar8 * FcStrStr(const FcChar8 *s1, const FcChar8 *s2);
Description
Returns the location of s2 in s1. Returns NULL if s2 is not
present in s1. This test will operate properly with UTF8
encoded strings.
Version
Fontconfig version 2.8.0
FcStrStrIgnoreCase
Name
FcStrStrIgnoreCase -- locate UTF-8 substring ignoring ASCII
case
Synopsis
#include <fontconfig.h>
FcChar8 * FcStrStrIgnoreCase(const FcChar8 *s1, const FcChar8
*s2);
Description
Returns the location of s2 in s1, ignoring case. Returns NULL
if s2 is not present in s1. This test is case-insensitive for
all proper UTF-8 encoded strings.
Version
Fontconfig version 2.8.0
FcStrPlus
Name
FcStrPlus -- concatenate two strings
Synopsis
#include <fontconfig.h>
FcChar8 * FcStrPlus(const FcChar8 *s1, const FcChar8 *s2);
Description
This function allocates new storage and places the
concatenation of s1 and s2 there, returning the new string.
Version
Fontconfig version 2.8.0
FcStrFree
Name
FcStrFree -- free a string
Synopsis
#include <fontconfig.h>
void FcStrFree(FcChar8 *s);
Description
This is just a wrapper around free(3) which helps track memory
usage of strings within the fontconfig library.
Version
Fontconfig version 2.8.0
FcStrDirname
Name
FcStrDirname -- directory part of filename
Synopsis
#include <fontconfig.h>
FcChar8 * FcStrDirname(const FcChar8 *file);
Description
Returns the directory containing file. This is returned in
newly allocated storage which should be freed when no longer
needed.
Version
Fontconfig version 2.8.0
FcStrBasename
Name
FcStrBasename -- last component of filename
Synopsis
#include <fontconfig.h>
FcChar8 * FcStrBasename(const FcChar8 *file);
Description
Returns the filename of file stripped of any leading directory
names. This is returned in newly allocated storage which should
be freed when no longer needed.
Version
Fontconfig version 2.8.0
