walkero
/
fontconfig
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Finish reformatting developer documentation

This commit is contained in:
Keith Packard 2003-03-07 19:01:41 +00:00
parent 90bdcf6051
commit 39381776a4
10 changed files with 794 additions and 437 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
doc/Makefile.am
View File

@ -17,7 +17,13 @@ DOC_FUNCS_FNCS=\
fcobjecttype.fncs \
fcconstant.fncs \
fcblanks.fncs \
fcconfig.fncs
fcconfig.fncs \
fcinit.fncs \
fcatomic.fncs \
fcfreetype.fncs \
fcfile.fncs \
fcstrset.fncs \
fcstring.fncs
DOC_FUNCS_SGML=\
fcmatrix.sgml \
@ -29,7 +35,13 @@ DOC_FUNCS_SGML=\
fcobjecttype.sgml \
fcconstant.sgml \
fcblanks.sgml \
fcconfig.sgml
fcconfig.sgml \
fcinit.sgml \
fcatomic.sgml \
fcfreetype.sgml \
fcfile.sgml \
fcstrset.sgml \
fcstring.sgml
man3_MANS= \
FcCharSetAddChar.3 \

17
doc/edit-sgml.c
View File

@ -145,6 +145,15 @@ ReplaceDispose (Replace *r)
Dispose (r);
}
void
Bail (char *format, char *arg)
{
fprintf (stderr, "fatal: ");
fprintf (stderr, format, arg);
fprintf (stderr, "\n");
exit (1);
}
Replace *
ReplaceRead (FILE *f)
{
@ -164,6 +173,8 @@ ReplaceRead (FILE *f)
ReplaceDispose (r);
return 0;
}
if (isspace (c))
Bail ("invalid character after tag %s", r->tag->buf);
StringAdd (r->tag, c);
}
if (r->tag->buf[0] == '\0')
@ -408,10 +419,12 @@ main (int argc, char **argv)
FILE *f;
ReplaceSet *s;
if (!argv[1])
Bail ("usage: %s <template.sgml>", argv[0]);
f = fopen (argv[1], "r");
if (!f)
{
perror (argv[1]);
Bail ("can't open file %s", argv[1]);
exit (1);
}
while ((s = ReplaceSetRead (stdin)))
@ -421,6 +434,6 @@ main (int argc, char **argv)
rewind (f);
}
if (ferror (stdout))
exit (1);
Bail ("%s", "error writing output");
exit (0);
}

93
doc/fcatomic.fncs Normal file
View File

@ -0,0 +1,93 @@
/*
* $Id$
*
* Copyright © 2003 Keith Packard
*
* Permission to use, copy, modify, distribute, and sell this software and its
* documentation for any purpose is hereby granted without fee, provided that
* the above copyright notice appear in all copies and that both that
* copyright notice and this permission notice appear in supporting
* documentation, and that the name of Keith Packard not be used in
* advertising or publicity pertaining to distribution of the software without
* specific, written prior permission. Keith Packard makes no
* representations about the suitability of this software for any purpose. It
* is provided "as is" without express or implied warranty.
*
* KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
* INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
* EVENT SHALL KEITH PACKARD BE LIABLE FOR ANY SPECIAL, INDIRECT OR
* CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
* DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
* TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
* PERFORMANCE OF THIS SOFTWARE.
*/
@RET@ FcAtomic *
@FUNC@ FcAtomicCreate
@TYPE1@ const FcChar8 * @ARG1@ file
@PURPOSE@ create an FcAtomic object
@DESC@
Creates a data structure containing data needed to control access to <parameter>file</parameter>.
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.
@@
@RET@ FcBool
@FUNC@ FcAtomicLock
@TYPE1@ FcAtomic * @ARG1@ atomic
@PURPOSE@ lock a file
@DESC@
Attempts to lock the file referenced by <parameter>atomic</parameter>. Returns FcFalse if the
file is locked by another process, else returns FcTrue and leaves the file
locked.
@@
@RET@ FcChar8 *
@FUNC@ FcAtomicNewFile
@TYPE1@ FcAtomic * @ARG1@ atomic
@PURPOSE@ return new temporary file name
@DESC@
Returns the filename for writing a new version of the file referenced
by <parameter>atomic</parameter>.
@@
@RET@ FcChar8 *
@FUNC@ FcAtomicOrigFile
@TYPE1@ FcAtomic * @ARG1@ atomic
@PURPOSE@ return original file name
@DESC@
Returns the file refernced by <parameter>atomic</parameter>.
@@
@RET@ FcBool
@FUNC@ FcAtomicReplaceOrig
@TYPE1@ FcAtomic * @ARG1@ atomic
@PURPOSE@ replace original with new
@DESC@
Replaces the original file referenced by <parameter>atomic</parameter> with the new file.
@@
@RET@ void
@FUNC@ FcAtomicDeleteNew
@TYPE1@ FcAtomic * @ARG1@ atomic
@PURPOSE@ delete new file
@DESC@
Deletes the new file. Used in error recovery to back out changes.
@@
@RET@ void
@FUNC@ FcAtomicUnlock
@TYPE1@ FcAtomic * @ARG1@ atomic
@PURPOSE@ unlock a file
@DESC@
Unlocks the file.
@@
@RET@ void
@FUNC@ FcAtomicDestroy
@TYPE1@ FcAtomic * @ARG1@ atomic
@PURPOSE@ destroy an FcAtomic object
@DESC@
Destroys <parameter>atomic</parameter>.
@@

153
doc/fcconfig.fncs
View File

@ -21,7 +21,7 @@
* TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
* PERFORMANCE OF THIS SOFTWARE.
*/
@RET@ FcConfig *
@RET@ FcConfig *
@FUNC@ FcConfigCreate
@TYPE1@ void
@PURPOSE@ Create a configuration
@ -29,9 +29,9 @@
Creates an empty configuration.
@@
@RET@ void
@FUNC@ FcConfigDestroy
@TYPE1@ FcConfig * @ARG1@ config
@RET@ void
@FUNC@ FcConfigDestroy
@TYPE1@ FcConfig * @ARG1@ config
@PURPOSE@ Destroy a configuration
@DESC@
Destroys a configuration and any data associated with it. Note that calling
@ -39,16 +39,16 @@ this function with the return from FcConfigGetCurrent will place the library
in an indeterminate state.
@@
@RET@ FcBool
@FUNC@ FcConfigSetCurrent
@TYPE1@ FcConfig * @ARG1@ config
@RET@ FcBool
@FUNC@ FcConfigSetCurrent
@TYPE1@ FcConfig * @ARG1@ config
@PURPOSE@ Set configuration as default
@DESC@
Sets the current default configuration to <parameter>config</parameter>. Implicitly calls
FcConfigBuildFonts if necessary, returning FcFalse if that call fails.
@@
@RET@ FcConfig *
@RET@ FcConfig *
@FUNC@ FcConfigGetCurrent
@TYPE1@ void
@PURPOSE@ Return current configuration
@ -56,18 +56,18 @@ FcConfigBuildFonts if necessary, returning FcFalse if that call fails.
Returns the current default configuration.
@@
@RET@ FcBool
@FUNC@ FcConfigUptoDate
@TYPE1@ FcConfig * @ARG1@ config
@RET@ FcBool
@FUNC@ FcConfigUptoDate
@TYPE1@ FcConfig * @ARG1@ config
@PURPOSE@ Check timestamps on config files
@DESC@
Checks all of the files related to <parameter>config</parameter> and returns whether the
in-memory version is in sync with the disk version.
@@
@RET@ FcBool
@FUNC@ FcConfigBuildFonts
@TYPE1@ FcConfig * @ARG1@ config
@RET@ FcBool
@FUNC@ FcConfigBuildFonts
@TYPE1@ FcConfig * @ARG1@ config
@PURPOSE@ Build font database
@DESC@
Builds the set of available fonts for the given configuration. Note that
@ -75,18 +75,18 @@ any changes to the configuration after this call have indeterminate effects.
Returns FcFalse if this operation runs out of memory.
@@
@RET@ FcStrList *
@FUNC@ FcConfigGetConfigDirs
@TYPE1@ FcConfig * @ARG1@ config
@RET@ FcStrList *
@FUNC@ FcConfigGetConfigDirs
@TYPE1@ FcConfig * @ARG1@ config
@PURPOSE@ Get config directories
@DESC@
Returns the list of font directories specified in the configuration files
for <parameter>config</parameter>. Does not include any subdirectories.
@@
@RET@ FcStrList *
@FUNC@ FcConfigGetFontDirs
@TYPE1@ FcConfig * @ARG1@ config
@RET@ FcStrList *
@FUNC@ FcConfigGetFontDirs
@TYPE1@ FcConfig * @ARG1@ config
@PURPOSE@ Get font directories
@DESC@
Returns the list of font directories in <parameter>config</parameter>. This includes the
@ -94,45 +94,45 @@ configured font directories along with any directories below those in the
filesystem.
@@
@RET@ FcStrList *
@FUNC@ FcConfigGetConfigFiles
@TYPE1@ FcConfig * @ARG1@ config
@RET@ FcStrList *
@FUNC@ FcConfigGetConfigFiles
@TYPE1@ FcConfig * @ARG1@ config
@PURPOSE@ Get config files
@DESC@
Returns the list of known configuration files used to generate <parameter>config</parameter>.
Note that this will not include any configuration done with FcConfigParse.
@@
@RET@ char *
@FUNC@ FcConfigGetCache
@TYPE1@ FcConfig * @ARG1@ config
@RET@ char *
@FUNC@ FcConfigGetCache
@TYPE1@ FcConfig * @ARG1@ config
@PURPOSE@ Get cache filename
@DESC@
Returns the name of the file used to store per-user font information.
@@
@RET@ FcFontSet *
@FUNC@ FcConfigGetFonts
@RET@ FcFontSet *
@FUNC@ FcConfigGetFonts
@TYPE1@ FcConfig * @ARG1@ config
@TYPE2@ FcSetName @ARG2@ set
@TYPE2@ FcSetName @ARG2@ set
@PURPOSE@ Get config font set
@DESC@
Returns one of the two sets of fonts from the configuration as specified
Returns one of the two sets of fonts from the configuration as specified
by <parameter>set</parameter>.
@@
@RET@ FcBlanks *
@FUNC@ FcConfigGetBlanks
@TYPE1@ FcConfig * @ARG1@ config
@RET@ FcBlanks *
@FUNC@ FcConfigGetBlanks
@TYPE1@ FcConfig * @ARG1@ config
@PURPOSE@ Get config blanks
@DESC@
Returns the FcBlanks object associated with the given configuration, if no
blanks were present in the configuration, this function will return 0.
@@
@RET@ int
@FUNC@ FcConfigGetRescanInverval
@TYPE1@ FcConfig * @ARG1@ config
@RET@ int
@FUNC@ FcConfigGetRescanInverval
@TYPE1@ FcConfig * @ARG1@ config
@PURPOSE@ Get config rescan interval
@DESC@
Returns the interval between automatic checks of the configuration (in
@ -140,8 +140,8 @@ seconds) specified in <parameter>config</parameter>. The configuration is check
a call to FcFontList when this interval has passed since the last check.
@@
@RET@ FcBool
@FUNC@ FcConfigSetRescanInverval
@RET@ FcBool
@FUNC@ FcConfigSetRescanInverval
@TYPE1@ FcConfig * @ARG1@ config
@TYPE2@ int @ARG2@ rescanInterval
@PURPOSE@ Set config rescan interval
@ -149,62 +149,62 @@ a call to FcFontList when this interval has passed since the last check.
Sets the rescan interval; returns FcFalse if an error occurred.
@@
@RET@ FcBool
@FUNC@ FcConfigAppFontAddFile
@RET@ FcBool
@FUNC@ FcConfigAppFontAddFile
@TYPE1@ FcConfig * @ARG1@ config
@TYPE2@ const char * @ARG2@ file
@TYPE2@ const char * @ARG2@ file
@PURPOSE@ Add font file to font database
@DESC@
Adds an application-specific font to the configuration.
@@
@RET@ FcBool
@FUNC@ FcConfigAppFontAddDir
@RET@ FcBool
@FUNC@ FcConfigAppFontAddDir
@TYPE1@ FcConfig * @ARG1@ config
@TYPE2@ const char * @ARG1@ dir
@TYPE2@ const char * @ARG1@ dir
@PURPOSE@ Add fonts from directory to font database
@DESC@
Scans the specified directory for fonts, adding each one found to the
application-specific set of fonts.
@@
@RET@ void
@FUNC@ FcConfigAppFontClear
@TYPE1@ FcConfig * @ARG1@ config
@RET@ void
@FUNC@ FcConfigAppFontClear
@TYPE1@ FcConfig * @ARG1@ config
@PURPOSE@ Remove all app fonts from font database
@DESC@
Clears the set of application-specific fonts.
@@
@RET@ FcBool
@FUNC@ FcConfigSubstituteWithPat
@RET@ FcBool
@FUNC@ FcConfigSubstituteWithPat
@TYPE1@ FcConfig * @ARG1@ config
@TYPE2@ FcPattern * @ARG2@ p
@TYPE3@ FcPattern * @ARG3@ p_pat
@TYPE4@ FcMatchKind @ARG4@ kind
@TYPE4@ FcMatchKind @ARG4@ kind
@PURPOSE@ Execute substitutions
@DESC@
Performs the sequence of pattern modification operations, if <parameter>kind</parameter> is
FcMatchPattern, then those tagged as pattern operations are applied, else
FcMatchPattern, then those tagged as pattern operations are applied, else
if <parameter>kind</parameter> is FcMatchFont, those tagged as font operations are applied and
p_pat is used for &lt;test&gt; elements with target=pattern.
@@
@RET@ FcBool
@FUNC@ FcConfigSubstitute
@RET@ FcBool
@FUNC@ FcConfigSubstitute
@TYPE1@ FcConfig * @ARG1@ config
@TYPE2@ FcPattern * @ARG2@ p
@TYPE3@ FcMatchKind @ARG3@ kind
@TYPE3@ FcMatchKind @ARG3@ kind
@PURPOSE@ Execute substitutions
@DESC@
Calls FcConfigSubstituteWithPat setting p_pat to NULL.
@@
@RET@ FcPattern *
@FUNC@ FcFontMatch
@RET@ FcPattern *
@FUNC@ FcFontMatch
@TYPE1@ FcConfig * @ARG1@ config
@TYPE2@ FcPattern * @ARG2@ p
@TYPE3@ FcResult * @ARG3@ result
@TYPE3@ FcResult * @ARG3@ result
@PURPOSE@ Return best font
@DESC@
Returns the font in <parameter>config</parameter> most close matching <parameter>p</parameter>. This function
@ -212,13 +212,13 @@ should be called only after FcConfigSubstitute and FcDefaultSubstitute have
been called for <parameter>p</parameter>; otherwise the results will not be correct.
@@
@RET@ FcFontSet *
@FUNC@ FcFontSort
@RET@ FcFontSet *
@FUNC@ FcFontSort
@TYPE1@ FcConfig * @ARG1@ config
@TYPE2@ FcPattern * @ARG2@ p
@TYPE3@ FcBool @ARG3@ trim
@TYPE4@ FcCharSet ** @ARG4@ csp
@TYPE5@ FcResult * @ARG5@ result
@TYPE5@ FcResult * @ARG5@ result
@PURPOSE@ Return list of matching fonts
@DESC@
Returns the list of fonts sorted by closeness to <parameter>p</parameter>. If <parameter>trim</parameter> is FcTrue,
@ -236,11 +236,11 @@ FcFontRenderPrepare which combines them into a complete pattern.
The FcFontSet returned by FcFontSort is destroyed by caling FcFontSetDestroy.
@@
@RET@ FcPattern *
@FUNC@ FcFontRenderPrepare
@RET@ FcPattern *
@FUNC@ FcFontRenderPrepare
@TYPE1@ FcConfig * @ARG1@ config
@TYPE2@ FcPattern * @ARG2@ pat
@TYPE3@ FcPattern * @ARG3@ font
@TYPE3@ FcPattern * @ARG3@ font
@PURPOSE@ Prepare pattern for loading font file
@DESC@
Creates a new pattern consisting of elements of <parameter>font</parameter> not appearing
@ -249,25 +249,25 @@ value from <parameter>pat</parameter> for elements appearing in both. The resul
FcConfigSubstitute with <parameter>kind</parameter> FcMatchFont and then returned.
@@
@RET@ FcFontSet *
@FUNC@ FcFontList
@RET@ FcFontSet *
@FUNC@ FcFontList
@TYPE1@ FcConfig * @ARG1@ config
@TYPE2@ FcPattern * @ARG2@ p
@TYPE3@ FcObjectSet * @ARG3@ os
@TYPE3@ FcObjectSet * @ARG3@ os
@PURPOSE@ List fonts
@DESC@
Selects fonts matching <parameter>p</parameter>, creates patterns from those fonts containing
only the objects in <parameter>os</parameter> and returns the set of unique such patterns.
@@
@RET@ char *
@FUNC@ FcConfigFilename
@TYPE1@ const char * @ARG1@ name
@RET@ char *
@FUNC@ FcConfigFilename
@TYPE1@ const char * @ARG1@ name
@PURPOSE@ Find a config file
@DESC@
Given the specified external entity name, return the associated filename.
This provides applications a way to convert various configuration file
references into filename form.
references into filename form.
</para><para>
A null or empty <parameter>name</parameter> indicates that the default configuration file should
be used; which file this references can be overridden with the
@ -277,3 +277,16 @@ 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.
@@
@RET@ FcBool
@FUNC@ FcConfigParseAndLoad
@TYPE1@ FcConfig * @ARG1@ config
@TYPE2@ const FcChar8 * @ARG2@ file
@TYPE2@ FcBool @ARG3@ complain
@PURPOSE@ load a configuration file
@DESC@
Walks the configuration in 'file' and constructs the internal representation
in 'config'. Any include files referenced from within 'file' will be loaded
with FcConfigLoad and also parsed. If 'complain' is FcFalse, no warning
will be displayed if 'file' does not exist.
@@

78
doc/fcfile.fncs Normal file
View File

@ -0,0 +1,78 @@
/*
* $Id$
*
* Copyright © 2003 Keith Packard
*
* Permission to use, copy, modify, distribute, and sell this software and its
* documentation for any purpose is hereby granted without fee, provided that
* the above copyright notice appear in all copies and that both that
* copyright notice and this permission notice appear in supporting
* documentation, and that the name of Keith Packard not be used in
* advertising or publicity pertaining to distribution of the software without
* specific, written prior permission. Keith Packard makes no
* representations about the suitability of this software for any purpose. It
* is provided "as is" without express or implied warranty.
*
* KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
* INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
* EVENT SHALL KEITH PACKARD BE LIABLE FOR ANY SPECIAL, INDIRECT OR
* CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
* DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
* TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
* PERFORMANCE OF THIS SOFTWARE.
*/
@RET@ FcBool
@FUNC@ FcFileScan
@TYPE1@ FcFontSet * @ARG1@ set
@TYPE2@ FcStrSet * @ARG2@ dirs
@TYPE3@ FcFileCache * @ARG3@ cache
@TYPE4@ FcBlanks * @ARG4@ blanks
@TYPE5@ const char * @ARG5@ file
@TYPE6@ FcBool @ARG6@ force
@PURPOSE@ scan a font file
@DESC@
Scans a single file and adds all fonts found to <parameter>set</parameter>.
If <parameter>force</parameter> is FcTrue, then the file is scanned even if
associated information is found in <parameter>cache</parameter>. If
<parameter>file</parameter> is a directory, it is added to
<parameter>dirs</parameter>.
@@
@RET@ FcBool
@FUNC@ FcDirScan
@TYPE1@ FcFontSet * @ARG1@ set
@TYPE2@ FcStrSet * @ARG2@ dirs
@TYPE3@ FcFileCache * @ARG3@ cache
@TYPE4@ FcBlanks * @ARG4@ blanks
@TYPE5@ const char * @ARG5@ dir
@TYPE6@ FcBool @ARG6@ force
@PURPOSE@ scan a font directory
@DESC@
Scans an entire directory and adds all fonts found to
<parameter>set</parameter>. If <parameter>force</parameter> is FcTrue, then
the directory and all files within it are scanned even if information is
present in the per-directory cache file or <parameter>cache</parameter>. Any
subdirectories found are added to <parameter>dirs</parameter>.
@@
@RET@ FcBool
@FUNC@ FcDirSave
@TYPE1@ FcFontSet * @ARG1@ set
@TYPE2@ FcStrSet * @ARG2@ dirs
@TYPE3@ const char * @ARG3@ dir
@PURPOSE@ save a directory cache
@DESC@
Creates the per-directory cache file for <parameter>dir</parameter> and
populates it with the fonts in <parameter>set</parameter> and subdirectories
in <parameter>dirs</parameter>.
@@
@RET@ FcBool
@FUNC@ FcDirCacheValid
@TYPE1@ const FcChar8 * @ARG1@ cache_file
@PURPOSE@ check directory cache timestamp
@DESC@
Returns FcTrue if <parameter>cache_file</parameter> is no older than the
directory containing it, else FcFalse.
@@

69
doc/fcfreetype.fncs Normal file
View File

@ -0,0 +1,69 @@
/*
* $Id$
*
* Copyright © 2003 Keith Packard
*
* Permission to use, copy, modify, distribute, and sell this software and its
* documentation for any purpose is hereby granted without fee, provided that
* the above copyright notice appear in all copies and that both that
* copyright notice and this permission notice appear in supporting
* documentation, and that the name of Keith Packard not be used in
* advertising or publicity pertaining to distribution of the software without
* specific, written prior permission. Keith Packard makes no
* representations about the suitability of this software for any purpose. It
* is provided "as is" without express or implied warranty.
*
* KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
* INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
* EVENT SHALL KEITH PACKARD BE LIABLE FOR ANY SPECIAL, INDIRECT OR
* CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
* DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
* TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
* PERFORMANCE OF THIS SOFTWARE.
*/
@SYNOPSIS@
#include &lt;fontconfig.h&gt;
#include &lt;fcfreetype.h&gt;
@RET@ FT_UInt
@FUNC@ FcFreeTypeCharIndex
@TYPE1@ FT_Face @ARG1@ face
@TYPE2@ FcChar32 @ARG2@ ucs4
@PURPOSE@ map Unicode to glyph id
@DESC@
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.
@@
@SYNOPSIS@
#include &lt;fontconfig.h&gt;
#include &lt;fcfreetype.h&gt;
@RET@ FcCharSet *
@FUNC@ FcFreeTypeCharSet
@TYPE1@ FT_Face @ARG1@ face
@TYPE2@ FcBlanks * @ARG2@ blanks
@PURPOSE@ compute unicode coverage
@DESC@
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.
@@
@SYNOPSIS@
#include &lt;fontconfig.h&gt;
#include &lt;fcfreetype.h&gt;
@RET@ FcPattern *
@FUNC@ FcFreeTypeQuery
@TYPE1@ const char * @ARG1@ file
@TYPE2@ int @ARG2@ id
@TYPE3@ FcBlanks * @ARG3@ blanks
@TYPE4@ int * @ARG4@ count
@PURPOSE@ compute font file pattern
@DESC@
Constructs a pattern representing the 'id'th font in 'file'. The number
of fonts in 'file' is returned in 'count'.
@@

78
doc/fcinit.fncs Normal file
View File

@ -0,0 +1,78 @@
/*
* $Id$
*
* Copyright © 2003 Keith Packard
*
* Permission to use, copy, modify, distribute, and sell this software and its
* documentation for any purpose is hereby granted without fee, provided that
* the above copyright notice appear in all copies and that both that
* copyright notice and this permission notice appear in supporting
* documentation, and that the name of Keith Packard not be used in
* advertising or publicity pertaining to distribution of the software without
* specific, written prior permission. Keith Packard makes no
* representations about the suitability of this software for any purpose. It
* is provided "as is" without express or implied warranty.
*
* KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
* INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
* EVENT SHALL KEITH PACKARD BE LIABLE FOR ANY SPECIAL, INDIRECT OR
* CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
* DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
* TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
* PERFORMANCE OF THIS SOFTWARE.
*/
@RET@ FcConfig *
@FUNC@ FcInitLoadConfig
@TYPE1@ void
@PURPOSE@ load configuration
@DESC@
Loads the default configuration file and returns the resulting configuration.
Does not load any font information.
@@
@RET@ FcConfig *
@FUNC@ FcInitLoadConfigAndFonts
@TYPE1@ void
@PURPOSE@ load configuration and font data
@DESC@
Loads the default configuration file and builds information about the
available fonts. Returns the resulting configuration.
@@
@RET@ FcBool
@FUNC@ FcInit
@TYPE1@ void
@PURPOSE@ initialize fontconfig library
@DESC@
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.
@@
@RET@ int
@FUNC@ FcGetVersion
@TYPE1@ void
@PURPOSE@ library version number
@DESC@
Returns the version number of the library.
@@
@RET@ FcBool
@FUNC@ FcInitReinitialize
@TYPE1@ void
@PURPOSE@ re-initialize library
@DESC@
Forces the default configuration file to be reloaded and resets the default
configuration.
@@
@RET@ FcBool
@FUNC@ FcInitBringUptoDate
@TYPE1@ void
@PURPOSE@ reload configuration files if needed
@DESC@
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.
@@

150
doc/fcstring.fncs Normal file
View File

@ -0,0 +1,150 @@
/*
* $Id$
*
* Copyright © 2003 Keith Packard
*
* Permission to use, copy, modify, distribute, and sell this software and its
* documentation for any purpose is hereby granted without fee, provided that
* the above copyright notice appear in all copies and that both that
* copyright notice and this permission notice appear in supporting
* documentation, and that the name of Keith Packard not be used in
* advertising or publicity pertaining to distribution of the software without
* specific, written prior permission. Keith Packard makes no
* representations about the suitability of this software for any purpose. It
* is provided "as is" without express or implied warranty.
*
* KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
* INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
* EVENT SHALL KEITH PACKARD BE LIABLE FOR ANY SPECIAL, INDIRECT OR
* CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
* DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
* TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
* PERFORMANCE OF THIS SOFTWARE.
*/
<variablelist>
@RET@ int
@FUNC@ FcUtf8ToUcs4
@TYPE1@ FcChar8 * @ARG1@ src
@TYPE2@ FcChar32 * @ARG2@ dst
@TYPE3@ int @ARG3@ len
@PURPOSE@ convert UTF-8 to UCS4
@DESC@
Converts the next Unicode char from <parameter>src</parameter> into
<parameter>dst</parameter> and returns the number of bytes containing the
char. <parameter>src</parameter> nust be at least
<parameter>len</parameter> bytes long.
@@
@RET@ int
@FUNC@ FcUcs4ToUtf8
@TYPE1@ FcChar32 @ARG1@ src
@TYPE2@ FcChar8 @ARG2@ dst[FC_UTF8_MAX_LEN]
@PURPOSE@ convert UCS4 to UTF-8
@DESC@
Converts the Unicode char from <parameter>src</parameter> into
<parameter>dst</parameter> and returns the number of bytes needed to encode
the char.
@@
@RET@ FcBool
@FUNC@ FcUtf8Len
@TYPE1@ FcChar8 * @ARG1@ src
@TYPE2@ int @ARG2@ len
@TYPE3@ int * @ARG3@ nchar
@TYPE4@ int * @ARG4@ wchar
@PURPOSE@ count UTF-8 encoded chars
@DESC@
Counts the number of Unicode chars in <parameter>len</parameter> bytes of
<parameter>src</parameter>. Places that count in
<parameter>nchar</parameter>. <parameter>wchar</parameter> contains 1, 2 or
4 depending on the number of bytes needed to hold the largest unicode char
counted. The return value indicates whether <parameter>src</parameter> is a
well-formed UTF8 string.
@@
@RET@ int
@FUNC@ FcUtf16ToUcs4
@TYPE1@ FcChar8 * @ARG1@ src
@TYPE2@ FcEndian @ARG2@ endian
@TYPE3@ FcChar32 * @ARG3@ dst
@TYPE4@ int @ARG4@ len
@PURPOSE@ convert UTF-16 to UCS4
@DESC@
Converts the next Unicode char from <parameter>src</parameter> into
<parameter>dst</parameter> and returns the number of bytes containing the
char. <parameter>src</parameter> must be at least <parameter>len</parameter>
bytes long. Bytes of <parameter>src</parameter> are combined into 16-bit
units according to <parameter>endian</parameter>.
@@
@RET@ FcBool
@FUNC@ FcUtf16Len
@TYPE1@ FcChar8 * @ARG1@ src
@TYPE2@ FcEndian @ARG2@ endian
@TYPE3@ int @ARG3@ len
@TYPE4@ int * @ARG4@ nchar
@TYPE5@ int * @ARG5@ wchar
@PURPOSE@ count UTF-16 encoded chars
@DESC@
Counts the number of Unicode chars in <parameter>len</parameter> bytes of
<parameter>src</parameter>. Bytes of <parameter>src</parameter> are
combined into 16-bit units according to <parameter>endian</parameter>.
Places that count in <parameter>nchar</parameter>.
<parameter>wchar</parameter> contains 1, 2 or 4 depending on the number of
bytes needed to hold the largest unicode char counted. The return value
indicates whether <parameter>string</parameter> is a well-formed UTF16
string.
@@
@RET@ FcChar8 *
@FUNC@ FcStrCopy
@TYPE1@ const FcChar8 * @ARG1@ s
@PURPOSE@ duplicate a string
@DESC@
Allocates memory, copies <parameter>s</parameter> and returns the resulting
buffer. Yes, this is <function>strdup</function>, but that function isn't
available on every platform.
@@
@RET@ FcChar8 *
@FUNC@ FcStrCopyFilename
@TYPE1@ const FcChar8 * @ARG1@ s
@PURPOSE@ copy a string, expanding '~'
@DESC@
Just like FcStrCopy except that it converts any leading '~' characters in
<parameter>s</parameter> to the value of the HOME environment variable.
Returns NULL if '~' is present in <parameter>s</parameter> and HOME is unset.
@@
@RET@ int
@FUNC@ FcStrCmpIgnoreCase
@TYPE1@ const char * @ARG1@ s1
@TYPE2@ const char * @ARG2@ s2
@PURPOSE@ compare UTF-8 strings ignoring ASCII case
@DESC@
Returns the usual &lt;0, 0, &gt;0 result of comparing
<parameter>s1</parameter> and <parameter>s2</parameter>. This test is
case-insensitive in the ASCII range and will operate properly with UTF8
encoded strings, although it does not check for well formed strings.
@@
@RET@ FcChar8 *
@FUNC@ FcStrDirname
@TYPE1@ const FcChar8 * @ARG1@ file
@PURPOSE@ directory part of filename
@DESC@
Returns the directory containing <parameter>file</parameter>. This
is returned in newly allocated storage which should be freed when no longer
needed.
@@
@RET@ FcChar8 *
@FUNC@ FcStrBasename
@TYPE1@ const FcChar8 * @ARG1@ file
@PURPOSE@ last component of filename
@DESC@
Returns the filename of <parameter>file</parameter> stripped of any leading
directory names. This is returned in newly allocated storage which should
be freed when no longer needed.
@@

104
doc/fcstrset.fncs Normal file
View File

@ -0,0 +1,104 @@
/*
* $Id$
*
* Copyright © 2003 Keith Packard
*
* Permission to use, copy, modify, distribute, and sell this software and its
* documentation for any purpose is hereby granted without fee, provided that
* the above copyright notice appear in all copies and that both that
* copyright notice and this permission notice appear in supporting
* documentation, and that the name of Keith Packard not be used in
* advertising or publicity pertaining to distribution of the software without
* specific, written prior permission. Keith Packard makes no
* representations about the suitability of this software for any purpose. It
* is provided "as is" without express or implied warranty.
*
* KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
* INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
* EVENT SHALL KEITH PACKARD BE LIABLE FOR ANY SPECIAL, INDIRECT OR
* CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
* DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
* TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
* PERFORMANCE OF THIS SOFTWARE.
*/
<variablelist>
@RET@ FcStrSet *
@FUNC@ FcStrSetCreate
@TYPE1@ void
@PURPOSE@ create a string set
@DESC@
Create an empty set.
@@
@RET@ FcBool
@FUNC@ FcStrSetMember
@TYPE1@ FcStrSet * @ARG1@ set
@TYPE2@ const FcChar8 * @ARG2@ s
@PURPOSE@ check set for membership
@DESC@
Returns whether <parameter>s</parameter> is a member of
<parameter>set</parameter>.
@@
@RET@ FcBool
@FUNC@ FcStrSetAdd
@TYPE1@ FcStrSet * @ARG1@ set
@TYPE2@ const FcChar8 * @ARG2@ s
@PURPOSE@ add to a string set
@DESC@
Adds a copy of <parameter>s</parameter> to <parameter>set</parameter>.
@@
@RET@ FcBool
@FUNC@ FcStrSetAddFilename
@TYPE1@ FcStrSet * @ARG1@ set
@TYPE2@ const FcChar8 * @ARG2@ s
@PURPOSE@ add a filename to a string set
@DESC@
Adds a copy <parameter>s</parameter> to <parameter>set</parameter>, The copy
is created with FcStrCopyFilename so that leading '~' values are replaced
with the value of the HOME environment variable.
@@
@RET@ FcBool
@FUNC@ FcStrSetDel
@TYPE1@ FcStrSet * @ARG1@ set
@TYPE2@ const FcChar8 * @ARG2@ s
@PURPOSE@ delete from a string set
@DESC@
Removes <parameter>s</parameter> from <parameter>set</parameter>, returning
FcTrue if <parameter>s</parameter> was a member else FcFalse.
@@
@RET@ void
@FUNC@ FcStrSetDestroy
@TYPE1@ FcStrSet * @ARG1@ set
@PURPOSE@ destroy a string set
@DESC@
Destroys <parameter>set</parameter>.
@@
@RET@ FcStrList *
@FUNC@ FcStrListCreate
@TYPE1@ FcStrSet * @ARG1@ set
@PURPOSE@ create a string iterator
@DESC@
Creates an iterator to list the strings in <parameter>set</parameter>.
@@
@RET@ FcChar8 *
@FUNC@ FcStrListNext
@TYPE1@ FcStrList * @ARG1@ list
@PURPOSE@ get next string in iteration
@DESC@
Returns the next string in <parameter>set</parameter>.
@@
@RET@ void
@FUNC@ FcStrListDone
@TYPE1@ FcStrList * @ARG1@ list
@PURPOSE@ destroy a string iterator
@DESC@
Destroys the enumerator <parameter>list</parameter>.
@@

473
doc/fontconfig-devel.sgml
View File

@ -1,19 +1,25 @@
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
<!ENTITY fcmatrix SYSTEM "fcmatrix.sgml">
<!ENTITY fcatomic SYSTEM "fcatomic.sgml">
<!ENTITY fcblanks SYSTEM "fcblanks.sgml">
<!ENTITY fccharset SYSTEM "fccharset.sgml">
<!ENTITY fcvalue SYSTEM "fcvalue.sgml">
<!ENTITY fcpattern SYSTEM "fcpattern.sgml">
<!ENTITY fcconfig SYSTEM "fcconfig.sgml">
<!ENTITY fcconstant SYSTEM "fcconstant.sgml">
<!ENTITY fcfile SYSTEM "fcfile.sgml">
<!ENTITY fcfontset SYSTEM "fcfontset.sgml">
<!ENTITY fcfreetype SYSTEM "fcfreetype.sgml">
<!ENTITY fcinit SYSTEM "fcinit.sgml">
<!ENTITY fcmatrix SYSTEM "fcmatrix.sgml">
<!ENTITY fcobjectset SYSTEM "fcobjectset.sgml">
<!ENTITY fcobjecttype SYSTEM "fcobjecttype.sgml">
<!ENTITY fcconstant SYSTEM "fcconstant.sgml">
<!ENTITY fcblanks SYSTEM "fcblanks.sgml">
<!ENTITY fcconfig SYSTEM "fcconfig.sgml">
<!ENTITY fcpattern SYSTEM "fcpattern.sgml">
<!ENTITY fcstring SYSTEM "fcstring.sgml">
<!ENTITY fcstrset SYSTEM "fcstrset.sgml">
<!ENTITY fcvalue SYSTEM "fcvalue.sgml">
]>
<!--
$Id$
Copyright © 2002 Keith Packard
Copyright © 2003 Keith Packard
Permission to use, copy, modify, distribute, and sell this software and its
documentation for any purpose is hereby granted without fee, provided that
@ -173,25 +179,19 @@ convenience for the applications rendering mechanism.
</programlisting>
</sect2>
</sect1>
<sect1><title>DATATYPES</title>
<sect1><title>Datatypes</title>
<para>
Fontconfig uses abstract datatypes to hide internal implementation details
for most data structures. A few structures are exposed where appropriate.
</para>
<variablelist>
<varlistentry>
<term>FcChar8<term>
<term>FcChar16<term>
<term>FcChar32<term>
<term>FcBool</term>
<listitem>
<sect2><title>FcChar8, FcChar16, FcChar32, FcBool</title>
<para>
These are primitive datatypes; the FcChar* types hold precisely the number
of bits stated (if supported by the C implementation). FcBool holds
one of two CPP symbols: FcFalse or FcTrue.
</para>
</listitem></varlistentry>
<varlistentry><term>FcMatrix</term><listitem>
</sect2>
<sect2><title>FcMatrix</title>
<para>
An FcMatrix holds an affine transformation, usually used to reshape glyphs.
A small set of matrix operations are provided to manipulate these.
@ -201,19 +201,19 @@ A small set of matrix operations are provided to manipulate these.
} FcMatrix;
</programlisting>
</para>
</listitem></varlistentry>
<varlistentry><term>FcCharSet</term><listitem>
</sect2>
<sect2><title>FcCharSet</title>
<para>
An FcCharSet is an abstract type that holds the set of encoded unicode chars
in a font. Operations to build and compare these sets are provided.
</para>
</listitem></varlistentry>
<varlistentry><term>FcType</term><listitem>
</sect2>
<sect2><title>FcType</title>
<para>
Tags the kind of data stored in an FcValue.
</para>
</listitem></varlistentry>
<varlistentry><term>FcValue</term><listitem>
</sect2>
<sect2><title>FcValue</title>
<para>
An FcValue object holds a single value with one of a number of different
types. The 'type' tag indicates which member is valid.
@ -244,8 +244,8 @@ types. The 'type' tag indicates which member is valid.
FcTypeCharSet c FcCharSet *
</programlisting>
</para>
</listitem></varlistentry>
<varlistentry><term>FcPattern</term><listitem>
</sect2>
<sect2><title>FcPattern</title>
<para>
holds a set of names with associated value lists; each name refers to a
property of a font. FcPatterns are used as inputs to the matching code as
@ -253,8 +253,8 @@ well as holding information about specific fonts. Each property can hold
one or more values; conventionally all of the same type, although the
interface doesn't demand that.
</para>
</listitem></varlistentry>
<varlistentry><term>FcFontSet</term><listitem>
</sect2>
<sect2><title>FcFontSet</title>
<para>
<programlisting>
typedef struct _FcFontSet {
@ -269,8 +269,8 @@ results of listing fonts in this format. 'nfont' holds the number of
patterns in the 'fonts' array; 'sfont' is used to indicate the size of that
array.
</para>
</listitem></varlistentry>
<varlistentry><term>FcStrSet</term><term>FcStrList</term><listitem>
</sect2>
<sect2><title>FcStrSet, FcStrList</title>
<para>
FcStrSet holds a list of strings that can be appended to and enumerated.
Its unique characteristic is that the enumeration works even while strings
@ -278,8 +278,8 @@ are appended during enumeration. FcStrList is used during enumeration to
safely and correctly walk the list of strings even while that list is edited
in the middle of enumeration.
</para>
</listitem></varlistentry>
<varlistentry><term>FcObjectSet</term><listitem>
</sect2>
<sect2><title>FcObjectSet</title>
<para>
<programlisting>
typedef struct _FcObjectSet {
@ -291,8 +291,8 @@ in the middle of enumeration.
holds a set of names and is used to specify which fields from fonts are
placed in the the list of returned patterns when listing fonts.
</para>
</listitem></varlistentry>
<varlistentry><term>FcObjectType</term><listitem>
</sect2>
<sect2><title>FcObjectType</title>
<para>
<programlisting>
typedef struct _FcObjectType {
@ -304,8 +304,8 @@ marks the type of a pattern element generated when parsing font names.
Applications can add new object types so that font names may contain the new
elements.
</para>
</listitem></varlistentry>
<varlistentry><term>FcConstant</term><listitem>
</sect2>
<sect2><title>FcConstant</title>
<para>
<programlisting>
typedef struct _FcConstant {
@ -317,22 +317,22 @@ elements.
Provides for symbolic constants for new pattern elements. When 'name' is
seen in a font name, an 'object' element is created with value 'value'.
</para>
</listitem></varlistentry>
<varlistentry><term>FcBlanks</term><listitem>
</sect2>
<sect2><title>FcBlanks</title>
<para>
holds a list of Unicode chars which are expected to be blank; unexpectedly
blank chars are assumed to be invalid and are elided from the charset
associated with the font.
</para>
</listitem></varlistentry>
<varlistentry><term>FcFileCache</term><listitem>
</sect2>
<sect2><title>FcFileCache</title>
<para>
holds the per-user cache information for use while loading the font
database. This is built automatically for the current configuration when
that is loaded. Applications must always pass '0' when one is requested.
</para>
</listitem></varlistentry>
<varlistentry><term>FcConfig</term><listitem>
</sect2>
<sect2><title>FcConfig</title>
<para>
holds a complete configuration of the library; there is one default
configuration, other can be constructed from XML data structures. All
@ -343,15 +343,15 @@ second set holds those added by the application at run-time. Interfaces
that need to reference a particulat set use one of the FcSetName enumerated
values.
</para>
</listitem></varlistentry>
<varlistentry><term>FcSetName</term><listitem>
</sect2>
<sect2><title>FcSetName</title>
<para>
Specifies one of the two sets of fonts available in a configuration;
FcSetSystem for those fonts specified in the configuration and
FcSetApplication which holds fonts provided by the application.
</para>
</listitem></varlistentry>
<varlistentry><term>FcResult</term><listitem>
</sect2>
<sect2><title>FcResult</title>
<para>
Used as a return type for functions manipulating FcPattern objects.
<programlisting>
@ -365,44 +365,24 @@ Used as a return type for functions manipulating FcPattern objects.
than specified
</programlisting>
</para>
</listitem></varlistentry>
<varlistentry><term>FcAtomic</term><listitem>
</sect2>
<sect2><title>FcAtomic</title>
<para>
Used for locking access to config files. Provides a safe way to update
configuration files.
</para>
</listitem></varlistentry>
</variablelist>
</sect2>
</sect1>
<sect1><title>FUNCTIONS</title>
<para>
Functions are grouped by the main datatype involved
These are grouped by functionality, often using the main datatype being
manipulated.
</para>
<sect2><title>FcMatrix</title>
<sect2><title>Initialization</title>
<para>
FcMatrix structures hold an affine transformation in matrix form.
These functions provide some control over how the library is initialized.
</para>
&fcmatrix;
</sect2>
<sect2><title>FcCharSet</title>
<para>
An FcCharSet is a boolean array indicating a set of unicode chars. Those
associated with a font are marked constant and cannot be edited.
FcCharSets may be reference counted internally to reduce memory consumption;
this may be visible to applications as the result of FcCharSetCopy may
return it's argument, and that CharSet may remain unmodifiable.
</para>
&fccharset;
</sect2>
<sect2><title>FcValue</title>
<para>
FcValue is a structure containing a type tag and a union of all possible
datatypes. The tag is an enum of type
<emphasis>FcType</emphasis>
and is intended to provide a measure of run-time
typechecking, although that depends on careful programming.
</para>
&fcvalue;
&fcinit;
</sect2>
<sect2><title>FcPattern</title>
<para>
@ -426,6 +406,48 @@ FcFontList.
</para>
&fcobjectset;
</sect2>
<sect2><title>FreeType specific functions</title>
<para>
While the fontconfig library doesn't insist that FreeType be used as the
rasterization mechanism for fonts, it does provide some convenience
functions.
</para>
&fcfreetype;
</sect2>
<sect2><title>FcValue</title>
<para>
FcValue is a structure containing a type tag and a union of all possible
datatypes. The tag is an enum of type
<emphasis>FcType</emphasis>
and is intended to provide a measure of run-time
typechecking, although that depends on careful programming.
</para>
&fcvalue;
</sect2>
<sect2><title>FcCharSet</title>
<para>
An FcCharSet is a boolean array indicating a set of unicode chars. Those
associated with a font are marked constant and cannot be edited.
FcCharSets may be reference counted internally to reduce memory consumption;
this may be visible to applications as the result of FcCharSetCopy may
return it's argument, and that CharSet may remain unmodifiable.
</para>
&fccharset;
</sect2>
<sect2><title>FcMatrix</title>
<para>
FcMatrix structures hold an affine transformation in matrix form.
</para>
&fcmatrix;
</sect2>
<sect2><title>FcConfig</title>
<para>
An FcConfig object holds the internal representation of a configuration.
There is a default configuration which applications may use by passing 0 to
any function using the data within an FcConfig.
</para>
&fcconfig;
</sect2>
<sect2><title>FcObjectType</title>
<para>
Provides for applcation-specified font name object types so that new
@ -449,309 +471,34 @@ accurate CharSet for applications.
</para>
&fcblanks;
</sect2>
<sect2><title>FcConfig</title>
<para>
An FcConfig object holds the internal representation of a configuration.
There is a default configuration which applications may use by passing 0 to
any function using the data within an FcConfig.
</para>
&fcconfig;
</sect2>
<sect2><title>Initialization</title>
<para>
These functions provide some control over how the library is initialized.
</para>
<variablelist>
<varlistentry><term>
FcConfig *FcInitLoadConfig (void);
</term><listitem><para>
Loads the default configuration file and returns the resulting configuration.
Does not load any font information.
</para></listitem></varlistentry>
<varlistentry><term>
FcConfig *FcInitLoadConfigAndFonts (void);
</term><listitem><para>
Loads the default configuration file and builds information about the
available fonts. Returns the resulting configuration.
</para></listitem></varlistentry>
<varlistentry><term>
FcBool FcInit (void);
</term><listitem><para>
Loads the default configuration file and the fonts referenced therein and
sets the default configuration to that result. Returns whether this
process succeeded or not. If the default configuration has already
been loaded, this routine does nothing and returns FcTrue.
</para></listitem></varlistentry>
<varlistentry><term>
int FcGetVersion (void);
</term><listitem><para>
Returns the version number of the library.
</para></listitem></varlistentry>
<varlistentry><term>
FcBool FcInitReinitialize (void);
</term><listitem><para>
Forces the default configuration file to be reloaded and resets the default
configuration.
</para></listitem></varlistentry>
<varlistentry><term>
FcBool FcInitBringUptoDate (void);
</term><listitem><para>
Checks the rescan interval in the default configuration, checking the
configuration if the interval has passed and reloading the configuration if
when any changes are detected.
</para></listitem></varlistentry>
</variablelist></sect2>
<sect2><title>FcAtomic</title>
<para>
These functions provide a safe way to update config files, allowing ongoing
reading of the old config file while locked for writing and ensuring that a
consistent and complete version of the config file is always available.
</para>
<variablelist>
<varlistentry><term>
FcAtomic * FcAtomicCreate (const FcChar8 *file);
</term><listitem><para>
Creates a data structure containing data needed to control access to 'file'.
Writing is done to a separate file. Once that file is complete, the original
configuration file is atomically replaced so that reading process always see
a consistent and complete file without the need to lock for reading.
</para></listitem></varlistentry>
<varlistentry><term>
FcBool FcAtomicLock (FcAtomic *atomic);
</term><listitem><para>
Attempts to lock the file referenced by 'atomic'. Returns FcFalse if the
file is locked by another process, else returns FcTrue and leaves the file
locked.
</para></listitem></varlistentry>
<varlistentry><term>
FcChar8 *FcAtomicNewFile (FcAtomic *atomic);
</term><listitem><para>
Returns the filename for writing a new version of the file referenced
by 'atomic'.
</para></listitem></varlistentry>
<varlistentry><term>
FcChar8 *FcAtomicOrigFile (FcAtomic *atomic);
</term><listitem><para>
Returns the file refernced by 'atomic'.
</para></listitem></varlistentry>
<varlistentry><term>
FcBool FcAtomicReplaceOrig (FcAtomic *atomic);
</term><listitem><para>
Replaces the original file referenced by 'atomic' with the new file.
</para></listitem></varlistentry>
<varlistentry><term>
void FcAtomicDeleteNew (FcAtomic *atomic);
</term><listitem><para>
Deletes the new file.
</para></listitem></varlistentry>
<varlistentry><term>
void FcAtomicUnlock (FcAtomic *atomic);
</term><listitem><para>
Unlocks the file.
</para></listitem></varlistentry>
<varlistentry><term>
void FcAtomicDestroy (FcAtomic *atomic);
</term><listitem><para>
Destroys 'atomic'.
</para></listitem></varlistentry>
</variablelist></sect2>
<sect2><title>FreeType specific functions</title>
<para>
<programlisting>
#include &lt;fontconfig/fcfreetype.h&gt;
</programlisting>
While the fontconfig library doesn't insist that FreeType be used as the
rasterization mechanism for fonts, it does provide some convenience
functions.
</para>
<variablelist>
<varlistentry><term>
FT_UInt FcFreeTypeCharIndex (FT_Face face, FcChar32 ucs4);
</term><listitem><para>
Maps a Unicode char to a glyph index. This function uses information from
several possible underlying encoding tables to work around broken fonts.
As a result, this function isn't designed to be used in performance
sensitive areas; results from this function are intended to be cached by
higher level functions.
</para></listitem></varlistentry>
<varlistentry><term>
FcCharSet *FcFreeTypeCharSet (FT_Face face, FcBlanks *blanks) Scans a
</term><listitem><para>
FreeType face and returns the set of encoded Unicode chars. This scans
several encoding tables to build as complete a list as possible.
If 'blanks' is not 0, the glyphs in the font are examined and any blank glyphs
not in 'blanks' are not placed in the returned FcCharSet.
</para></listitem></varlistentry>
<varlistentry><term>
FcPattern *FcFreeTypeQuery (const char *file, int id, FcBlanks *blanks, int *count);
</term><listitem><para>
Constructs a pattern representing the 'id'th font in 'file'. The number
of fonts in 'file' is returned in 'count'.
</para></listitem></varlistentry>
</variablelist></sect2>
<sect2><title>XML specific functions</title>
<variablelist>
<varlistentry><term>
FcBool FcConfigParseAndLoad (FcConfig *config, const FcChar8 *file, FcBool complain);
</term><listitem><para>
Walks the configuration in 'file' and constructs the internal representation
in 'config'. Any include files referenced from within 'file' will be loaded
with FcConfigLoad and also parsed. If 'complain' is FcFalse, no warning
will be displayed if 'file' does not exist.
</para></listitem></varlistentry>
</variablelist></sect2>
&fcatomic;
</sect2>
<sect2><title>File and Directory routines</title>
<variablelist>
<varlistentry><term>
FcBool FcFileScan (FcFontSet *set, FcStrSet *dirs, FcFileCache *cache, FcBlanks *blanks, const char *file, FcBool force);
</term><listitem><para>
Scans a single file and adds all fonts found to 'set'. If 'force' is FcTrue,
then the file is scanned even if associated information is found in 'cache'.
If 'file' is a directory, it is added to 'dirs'.
</para></listitem></varlistentry>
<varlistentry><term>
FcBool FcDirScan (FcFontSet *set, FcStrSet *dirs, FcFileCache *cache, FcBlanks *blanks, const char *dir, FcBool force);
</term><listitem><para>
Scans an entire directory and adds all fonts found to 'set'. If 'force' is
FcTrue, then the directory and all files within it are scanned even if
information is present in the per-directory cache file or 'cache'. Any
subdirectories found are added to 'dirs'.
</para></listitem></varlistentry>
<varlistentry><term>
FcBool FcDirSave (FcFontSet *set, FcStrSet *dirs, const char *dir);
</term><listitem><para>
Creates the per-directory cache file for 'dir' and populates it with the
fonts in 'set' and subdirectories in 'dirs'.
</para></listitem></varlistentry>
<varlistentry><term>
FcBool FcDirCacheValid (const FcChar8 *cache_file);
</term><listitem><para>
Returns FcTrue if 'cache_file' is no older than the directory containing it,
else FcFalse.
</para></listitem></varlistentry>
</variablelist></sect2>
<para>
These routines work with font files and directories, including font
directory cache files.
&fcfile;
</sect2>
<sect2><title>FcStrSet and FcStrList</title>
<para>
A data structure for enumerating strings, used to list directories while
scanning the configuration as directories are added while scanning.
</para>
<variablelist>
<varlistentry><term>
FcStrSet *FcStrSetCreate (void);
</term><listitem><para>
Create an empty set.
</para></listitem></varlistentry>
<varlistentry><term>
FcBool FcStrSetMember (FcStrSet *set, const FcChar8 *s);
</term><listitem><para>
Returns whether 's' is a member of 'set'.
</para></listitem></varlistentry>
<varlistentry><term>
FcBool FcStrSetAdd (FcStrSet *set, const FcChar8 *s);
</term><listitem><para>
Adds a copy of 's' to 'set'.
</para></listitem></varlistentry>
<varlistentry><term>
FcBool FcStrSetAddFilename (FcStrSet *set, const FcChar8 *s);
</term><listitem><para>
Adds a copy 's' to 'set', The copy is created with FcStrCopyFilename
so that leading '~' values are replaced with the value of the HOME
environment variable.
</para></listitem></varlistentry>
<varlistentry><term>
FcBool FcStrSetDel (FcStrSet *set, const FcChar8 *s);
</term><listitem><para>
Removes 's' from 'set', returning FcTrue if 's' was a member else FcFalse.
</para></listitem></varlistentry>
<varlistentry><term>
void FcStrSetDestroy (FcStrSet *set);
</term><listitem><para>
Destroys 'set'.
</para></listitem></varlistentry>
<varlistentry><term>
FcStrList *FcStrListCreate (FcStrSet *set);
</term><listitem><para>
Creates an enumerator to list the strings in 'set'.
</para></listitem></varlistentry>
<varlistentry><term>
FcChar8 *FcStrListNext (FcStrList *list);
</term><listitem><para>
Returns the next string in 'set'.
</para></listitem></varlistentry>
<varlistentry><term>
void FcStrListDone (FcStrList *list);
</term><listitem><para>
Destroys the enumerator 'list'.
</para></listitem></varlistentry>
</variablelist></sect2>
&fcstrset;
</sect2>
<sect2><title>String utilities</title>
<variablelist>
<varlistentry><term>
int FcUtf8ToUcs4 (FcChar8 *src, FcChar32 *dst, int len);
</term><listitem>
<para>
Converts the next Unicode char from 'src' into 'dst' and returns the number
of bytes containing the char. 'src' nust be at least 'len' bytes long.
</para></listitem></varlistentry>
<varlistentry><term>
int FcUcs4ToUtf8 (FcChar32 src, FcChar8 dst[FC_UTF8_MAX_LEN]);
</term><listitem><para>
Converts the Unicode char from 'src' into 'dst' and returns the
number of bytes needed to encode the char.
</para></listitem></varlistentry>
<varlistentry><term>
FcBool FcUtf8Len (FcChar8 *src, int len, int *nchar, int *wchar);
</term><listitem><para>
Counts the number of Unicode chars in 'len' bytes of 'src'. Places that
count in 'nchar'. 'wchar' contains 1, 2 or 4 depending on the number of
bytes needed to hold the largest unicode char counted. The return value
indicates whether 'src' is a well-formed UTF8 string.
</para></listitem></varlistentry>
<varlistentry><term>
int FcUtf16ToUcs4 (FcChar8 *src, FcEndian endian, FcChar32 *dst, int len);
</term><listitem><para>
Converts the next Unicode char from 'src' into 'dst' and returns the
number of bytes containing the char. 'src' must be at least 'len' bytes
long. Bytes of 'src' are combined into 16-bit units according to 'endian'.
</para></listitem></varlistentry>
<varlistentry><term>
FcBool FcUtf16Len (FcChar8 *src, FcEndian endian, int len, int *nchar, int *wchar);
</term><listitem><para>
Counts the number of Unicode chars in 'len' bytes of 'src'. Bytes of 'src'
are combined into 16-bit units according to 'endian'. Places that
count in 'nchar'. 'wchar' contains 1, 2 or 4 depending on the number of
bytes needed to hold the largest unicode char counted. The return value
indicates whether 'string' is a well-formed UTF16 string.
</para></listitem></varlistentry>
<varlistentry><term>
FcChar8 *FcStrCopy (const FcChar8 *s);
</term><listitem><para>
Allocates memory, copies 's' and returns the resulting buffer. Yes, this
is 'strdup', but that function isn't available on every platform.
</para></listitem></varlistentry>
<varlistentry><term>
FcChar8 *FcStrCopyFilename (const FcChar8 *s);
</term><listitem><para>
Just like FcStrCopy except that it converts any leading '~' characters
in 's' to the value of the HOME environment variable.
</para></listitem></varlistentry>
<varlistentry><term>
int FcStrCmpIgnoreCase (const char *s1, const char *s2);
</term><listitem><para>
Returns the usual &lt;0, 0, &gt;0 result of comparing 's1' and 's2'. This test
is case-insensitive in the ASCII range and will operate properly with UTF8
encoded strings, although it does not check for well formed strings.
</para></listitem></varlistentry>
<varlistentry><term>
FcChar8 *FcStrDirname (const FcChar8 *file);
</term><listitem><para>
Returns the directory containing 'file'.
</para></listitem></varlistentry>
<varlistentry><term>
FcChar8 *FcStrBasename (const FcChar8 *file);
</term><listitem><para>
Returns the filename of 'file' stripped of any leading directory names.
</para></listitem></varlistentry>
</variablelist></sect2>
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.
</para>
&fcstring;
</sect2>
</sect1>
</article>