From a190678e3c4497870679808dde418191407be91d Mon Sep 17 00:00:00 2001 From: Keith Packard Date: Sat, 3 Nov 2007 22:23:28 -0700 Subject: [PATCH] Document previously undocumented functions. (bug 12963) --- doc/Makefile.am | 3 + doc/check-missing-doc | 4 +- doc/fccache.fncs | 68 +++++++++++++++++++++ doc/fccharset.fncs | 24 ++++++++ doc/fcconfig.fncs | 31 ++++++++++ doc/fcdircache.fncs | 88 +++++++++++++++++++++++++++ doc/fcfile.fncs | 29 +++++---- doc/fcfontset.fncs | 83 +++++++++++++++++++++++++ doc/fcfreetype.fncs | 22 +++++++ doc/fclangset.fncs | 124 ++++++++++++++++++++++++++++++++++++++ doc/fcmatrix.fncs | 2 + doc/fcpattern.fncs | 52 +++++++++++++++- doc/fcstring.fncs | 80 +++++++++++++++++++----- doc/fcstrset.fncs | 11 ++++ doc/fcvalue.fncs | 21 +++++++ doc/fontconfig-devel.sgml | 26 +++++++- 16 files changed, 638 insertions(+), 30 deletions(-) create mode 100644 doc/fccache.fncs create mode 100644 doc/fcdircache.fncs create mode 100644 doc/fclangset.fncs diff --git a/doc/Makefile.am b/doc/Makefile.am index 7b40eb4..e5c922b 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -42,13 +42,16 @@ FNCS_TMPL = ${DOC_SRC}/func.sgml DOC_FUNCS_FNCS=\ fcatomic.fncs \ fcblanks.fncs \ + fccache.fncs \ fccharset.fncs \ fcconfig.fncs \ fcconstant.fncs \ + fcdircache.fncs \ fcfile.fncs \ fcfontset.fncs \ fcfreetype.fncs \ fcinit.fncs \ + fclangset.fncs \ fcmatrix.fncs \ fcobjectset.fncs \ fcobjecttype.fncs \ diff --git a/doc/check-missing-doc b/doc/check-missing-doc index 13d1eb9..3eef93a 100644 --- a/doc/check-missing-doc +++ b/doc/check-missing-doc @@ -1,7 +1,7 @@ #!/bin/sh header=fontconfig-header doc=fontconfig-doc -#trap "rm $header $doc" 0 1 15 +trap "rm $header $doc" 0 1 15 top_srcdir=${top_srcdir-".."} ( cat $top_srcdir/fontconfig/*.h | grep '^Fc' | @@ -10,7 +10,7 @@ cat $top_srcdir/fontconfig/*.h | grep '^Fc' | sed -n 's/#define \(Fc[a-zA-Z]*\)(.*$/\1/p') | sort -u > $header -grep '@FUNC@' $top_srcdir/doc/*.fncs | +grep '@FUNC[+]*@' $top_srcdir/doc/*.fncs | awk '{print $2}' | sort -u > $doc diff --git a/doc/fccache.fncs b/doc/fccache.fncs new file mode 100644 index 0000000..0a08632 --- /dev/null +++ b/doc/fccache.fncs @@ -0,0 +1,68 @@ +/* + * Copyright © 2007 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@ const FcChar8 * +@FUNC@ FcCacheDir +@TYPE1@ const FcCache * @ARG1@ cache +@PURPOSE@ Return directory of cache +@DESC@ +This function returns the directory from which the cache was constructed. +@@ + +@RET@ FcFontSet * +@FUNC@ FcCacheCopySet +@TYPE1@ const FcCache * @ARG1@ cache +@PURPOSE@ Returns a copy of the fontset from cache +@DESC +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. +@@ + +@RET@ const FcChar8 * +@FUNC@ FcCacheSubdir +@TYPE1@ const FcCache * @ARG1@ cache +@TYPE2@ int @ARG2@ i +@PURPOSE@ Return the i'th subdirectory. +@DESC +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. +@@ + +@RET@ int +@FUNC@ FcCacheNumSubdir +@TYPE1@ const FcCache * @ARG1@ cache +@PURPOSE@ Return the number of subdirectories in cache. +@DESC +This returns the total number of subdirectories in the cache. +@@ + +@RET@ int +@FUNC@ FcCacheNumFont +@TYPE1@ const FcCache * @ARG1@ cache +@PURPOSE@ Returns the number of fonts in cache. +@DESC +This returns the number of fonts which would be included in the return from +FcCacheCopySet. +@@ diff --git a/doc/fccharset.fncs b/doc/fccharset.fncs index cb07680..f4e81a7 100644 --- a/doc/fccharset.fncs +++ b/doc/fccharset.fncs @@ -165,3 +165,27 @@ Builds an array of bits marking the Unicode coverage of a *next. Returns the base of the array. next contains the next page in the font. @@ + +@RET@ FcChar32 +@FUNC@ FcCharSetCoverage +@TYPE1@ const FcCharSet * @ARG1@ a +@TYPE2@ FcChar32 @ARG2@ page +@TYPE3@ FcChar32[8] @ARG3@ result +@PURPOSE@ DEPRECATED return coverage for a Unicode page +@DESC@ +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. +@@ + +@RET@ FcCharSet * +@FUNC@ FcCharSetNew +@TYPE1@ void +@PURPOSE@ DEPRECATED alias for FcCharSetCreate +@DESC@ +FcCharSetNew is a DEPRECATED alias for FcCharSetCreate. +@@ + diff --git a/doc/fcconfig.fncs b/doc/fcconfig.fncs index d252d60..998974f 100644 --- a/doc/fcconfig.fncs +++ b/doc/fcconfig.fncs @@ -65,6 +65,27 @@ Checks all of the files related to config and returns whether any of them has been modified since the configuration was created. @@ +@RET@ FcBool +@FUNC@ FcConfigHome +@TYPE1@ void +@PURPOSE@ return the current home directory. +@DESC@ +Return the current user's home directory, if it is available, and if using it +is enabled. See also FcConfigEnableHome). +@@ + +@RET@ FcBol +@FUNC@ FcConfigEnableHome +@TYPE1@ FcBool% @ARG1@ enable +@PURPOSE@ controls use of the home directory. +@DESC@ +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. +@@ + @RET@ FcBool @FUNC@ FcConfigBuildFonts @TYPE1@ FcConfig * @ARG1@ config @@ -111,6 +132,16 @@ Note that this will not include any configuration done with FcConfigParse. Returns the name of the file used to store per-user font information. @@ +@RET@ FcStrList * +@FUNC@ FcConfigGetCacheDirs +@TYPE1@ FcConfig * @ARG1@ config +@PURPOSE@ return the list of directories searched for cache files +@DESC@ +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. +@@ + @RET@ FcFontSet * @FUNC@ FcConfigGetFonts @TYPE1@ FcConfig * @ARG1@ config diff --git a/doc/fcdircache.fncs b/doc/fcdircache.fncs new file mode 100644 index 0000000..24dea8b --- /dev/null +++ b/doc/fcdircache.fncs @@ -0,0 +1,88 @@ +/* + * Copyright © 2007 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 the copyright holders not be used in advertising or + * publicity pertaining to distribution of the software without specific, + * written prior permission. The copyright holders make no representations + * about the suitability of this software for any purpose. It is provided "as + * is" without express or implied warranty. + * + * THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, + * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO + * EVENT SHALL THE COPYRIGHT HOLDERS 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@ FcDirCacheUnlink +@TYPE1@ const FcChar8 * @ARG1@ dir +@TYPE2@ FcConfig * @ARG2@ config +@PURPOSE@ Remove all caches related to dir +@DESC@ +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. +@@ + +@RET@ FcBool +@FUNC@ FcDirCacheValid +@TYPE1@ const FcChar8 * @ARG1@ dir +@PURPOSE@ check directory cache +@DESC@ +Returns FcTrue if dir has an associated valid cache +file, else returns FcFalse +@@ + +@RET@ FcCache * +@FUNC@ FcDirCacheLoad +@TYPE1@ const FcChar8 * @ARG1@ dir +@TYPE2@ FcConfig * @ARG2@ config +@TYPE3@ FcChar8 ** @ARG3@ cache_file +@PURPOSE@ load a directory cache +@DESC@ +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. +@@ + +@RET@ FcCache * +@FUNC@ FcDirCacheRead +@TYPE1@ const FcChar8 * @ARG1@ dir +@TYPE2@ FcBool% @ARG2@ force +@TYPE3@ FcConfig * @ARG3@ config +@PURPOSE@ read or construct a directory cache +@DESC@ +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. +@@ + +@RET@ FcCache * +@FUNC@ FcDirCacheLoadFile +@TYPE1@ const FcChar8 * @ARG1@ cache_file +@TYPE2@ struct stat * @ARG2@ file_stat +@PURPOSE@ load a cache file +@DESC@ +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. +@@ + +@RET@ void +@FUNC@ FcDirCacheUnload +@TYPE1@ FcCache * @ARG1@ cache +@PURPOSE@ unload a cache file +@DESC@ +This function dereferences cache. When no other +references to it remain, all memory associated with the cache will be freed. +@@ diff --git a/doc/fcfile.fncs b/doc/fcfile.fncs index df7400b..98b8f81 100644 --- a/doc/fcfile.fncs +++ b/doc/fcfile.fncs @@ -37,7 +37,20 @@ 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 -poliy as well as the current configuration. +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. +@@ + +@RET@ FcBool +@FUNC@ FcFileIsDir +@TYPE1@ const FcChar8 * @ARG1@ file +@PURPOSE@ check whether a file is a directory +@DESC@ +Returns FcTrue if file is a directory, otherwise +returns FcFalse. @@ @RET@ FcBool @@ -54,9 +67,9 @@ 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. Whether fonts -or directories are found depends on fontconfig -policy as well as the current configuration. +subdirectories found are added to dirs. See the +manual for FcFileScan for a description of how +fontconfig selects which fonts to include. @@ @RET@ FcBool @@ -71,11 +84,3 @@ populates it with the fonts in set and subdirectories in dirs. @@ -@RET@ FcBool -@FUNC@ FcDirCacheValid -@TYPE1@ const FcChar8 * @ARG1@ cache_file -@PURPOSE@ check directory cache timestamp -@DESC@ -Returns FcTrue if cache_file is no older than the -directory containing it, else FcFalse. -@@ diff --git a/doc/fcfontset.fncs b/doc/fcfontset.fncs index 9c739c6..bcf4bd3 100644 --- a/doc/fcfontset.fncs +++ b/doc/fcfontset.fncs @@ -47,3 +47,86 @@ well. Adds a pattern to a font set. Note that the pattern is not copied before being inserted into the set. @@ + +@RET@ FcFontSet * +@FUNC@ FcFontSetList +@TYPE1@ FcConfig * @ARG1@ config +@TYPE2@ FcFontSet ** @ARG2@ sets +@TYPE3@ int @ARG3@ nsets +@TYPE4@ FcPattern * @ARG4@ pattern +@TYPE5@ FcObjectSet * @ARG5@ object_set +@PURPOSE@ List fonts from a set of font sets +@DESC@ +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. +@@ + +@RET@ FcPattern * +@FUNC@ FcFontSetMatch +@TYPE1@ FcConfig * @ARG1@ config +@TYPE2@ FcFontSet ** @ARG2@ sets +@TYPE3@ int @ARG3@ nsets +@TYPE4@ FcPattern * @ARG4@ pattern +@TYPE5@ FcResult * @ARG5@ result +@PURPOSE@ Return the best font from a set of font sets +@DESC@ +Returns the font in sets most close matching +pattern. This function should be called only after +FcConfigSubstitute and FcDefaultSubstitute have been called for +pattern; otherwise the results will not be correct. +@@ + +@RET@ void +@FUNC@ FcFontSetPrint +@TYPE1@ FcFontSet * @ARG1@ set +@PURPOSE@ Print a set of patterns to stdout +@DESC@ +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. +@@ + +@RET@ +@FUNC@ FcFontSetSort +@TYPE1@ FcConfig * @ARG1@ config +@TYPE2@ FcFontSet ** @ARG2@ sets +@TYPE3@ int @ARG3@ nsets +@TYPE4@ FcPattern * @ARG4@ pattern +@TYPE5@ FcBool% @ARG5@ trim +@TYPE6@ FcCharSet ** @ARG6@ csp +@TYPE7@ FcResult * @ARG7@ result +@PURPOSE@ Add to a font set +@DESC@ +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. +@@ + +@RET@ +@FUNC@ FcFontSetSortDestroy +@TYPE1@ FcFontSet * @ARG1@ set +@PURPOSE@ DEPRECATED destroy a font set +@DESC@ +This function is DEPRECATED. FcFontSetSortDestroy +destroys set by calling +FcFontSetDestroy. Applications should use +FcFontSetDestroy directly instead. +@@ diff --git a/doc/fcfreetype.fncs b/doc/fcfreetype.fncs index 6ecedda..935eacf 100644 --- a/doc/fcfreetype.fncs +++ b/doc/fcfreetype.fncs @@ -53,6 +53,28 @@ 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 <fontconfig.h> +#include <fcfreetype.h> +@RET@ FcCharSet * +@FUNC@ FcFreeTypeCharSetAndSpacing +@TYPE1@ FT_Face% @ARG1@ face +@TYPE2@ FcBlanks * @ARG2@ blanks +@TYPE3@ int * @ARG3@ spacing +@PURPOSE@ compute unicode coverage and spacing type +@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. +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. +@@ + @SYNOPSIS@ #include <fontconfig.h> #include <fcfreetype.h> diff --git a/doc/fclangset.fncs b/doc/fclangset.fncs new file mode 100644 index 0000000..eb4a937 --- /dev/null +++ b/doc/fclangset.fncs @@ -0,0 +1,124 @@ +/* + * Copyright © 2007 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 the copyright holders not be used in advertising or + * publicity pertaining to distribution of the software without specific, + * written prior permission. The copyright holders make no representations + * about the suitability of this software for any purpose. It is provided "as + * is" without express or implied warranty. + * + * THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, + * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO + * EVENT SHALL THE COPYRIGHT HOLDERS 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@ FcLangSet * +@FUNC@ FcLangSetCreate +@TYPE1@ void +@PURPOSE@ create a langset object +@DESC@ +FcLangSetCreate creates a new FcLangSet object. +@@ + +@RET@ void +@FUNC@ FcLangSetDestroy +@TYPE1@ FcLangSet * @ARG1@ ls +@PURPOSE@ destroy a langset object +@DESC@ +FcLangSetDestroy destroys a FcLangSet object, freeing +all memory associated with it. +@@ + +@RET@ FcLangSet * +@FUNC@ FcLangSetCopy +@TYPE1@ const FcLangSet * @ARG1@ ls +@PURPOSE@ copy a langset object +@DESC@ +FcLangSetCopy creates a new FcLangSet object and +populates it with the contents of ls. +@@ + +@RET@ FcBool +@FUNC@ FcLangSetAdd +@TYPE1@ FcLangSet * @ARG1@ ls +@TYPE2@ const FcChar8 * @ARG2@ lang +@PURPOSE@ add a language to a langset +@DESC@ +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. +@@ + +@RET@ FcLangResult +@FUNC@ FcLangSetCompare +@TYPE1@ const FcLangSet * @ARG1@ ls_a +@TYPE2@ const FcLangSet * @ARG2@ ls_b +@PURPOSE@ compare language sets +@DESC@ +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. +@@ + +@RET@ FcBool +@FUNC@ FcLangSetContains +@TYPE1@ const FcLangSet * @ARG1@ ls_a +@TYPE2@ const FcLangSet * @ARG2@ ls_b +@PURPOSE@ check langset subset relation +@DESC@ +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. +@@ + +@RET@ FcBool +@FUNC@ FcLangSetEqual +@TYPE1@ const FcLangSet * @ARG1@ ls_a +@TYPE2@ const FcLangSet * @ARG2@ ls_b +@PURPOSE@ test for matching langsets +@DESC@ +Returns FcTrue if and only if ls_a supports precisely +the same language and territory combinations as ls_b. +@@ + +@RET@ FcChar32 +@FUNC@ FcLangSetHash +@TYPE1@ const FcLangSet * @ARG1@ ls +@PURPOSE@ return a hash value for a langset +@DESC@ +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. +@@ + +@RET@ FcLangResult +@FUNC@ FcLangSetHasLang +@TYPE1@ const FcLangSet * @ARG1@ ls +@TYPE2@ const FcChar8 * @ARG2@ lang +@PURPOSE@ test langset for language support +@DESC@ +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. +@@ diff --git a/doc/fcmatrix.fncs b/doc/fcmatrix.fncs index 2d48b1e..0159555 100644 --- a/doc/fcmatrix.fncs +++ b/doc/fcmatrix.fncs @@ -21,6 +21,8 @@ * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR * PERFORMANCE OF THIS SOFTWARE. */ + +@RET@ void @FUNC@ FcMatrixInit @PURPOSE@ initialize an FcMatrix structure @TYPE1@ FcMatrix * diff --git a/doc/fcpattern.fncs b/doc/fcpattern.fncs index c04d9b3..74f3675 100644 --- a/doc/fcpattern.fncs +++ b/doc/fcpattern.fncs @@ -29,12 +29,32 @@ Creates a pattern with no properties; used to build patterns from scratch. @@ +@RET@ FcPattern * +@FUNC@ FcPatternDuplicate +@TYPE1@ FcPattern * @ARG1@ p +@PURPOSE@ Copy a pattern +@DESC@ +Copy a pattern, returning a new pattern that matches +p. Each pattern may be modified without affecting the +other. +@@ + +@RET@ void +@FUNC@ FcPatternReference +@TYPE1@ FcPattern * @ARG1@ p +@PURPOSE@ Increment pattern reference count +@DESC@ +Add another reference to p. Patterns are freed only +when the reference count reaches zero. +@@ + @RET@ void @FUNC@ FcPatternDestroy @TYPE1@ FcPattern * @ARG1@ p @PURPOSE@ Destroy a pattern @DESC@ -Destroys a pattern, in the process destroying all related values. +Decrement the pattern reference count. If all references are gone, destroys +the pattern, in the process destroying all related values. @@ @RET@ FcBool @@ -134,6 +154,21 @@ values added to the list have binding weak instead of string is a well-formed UTF16 string. @@ +@RET@ FcBool +@FUNC@ FcIsLower +@TYPE1@ FcChar8 @ARG1@ c +@PURPOSE@ check for lower case ASCII character +@DESC@ +This macro checks whether c is an lower case ASCII +letter. +@@ + +@RET@ FcBool +@FUNC@ FcIsUpper +@TYPE1@ FcChar8 @ARG1@ c +@PURPOSE@ check for upper case ASCII character +@DESC@ +This macro checks whether c is a upper case ASCII +letter. +@@ + +@RET@ FcChar8 +@FUNC@ FcToLower +@TYPE1@ FcChar8 @ARG1@ c +@PURPOSE@ convert upper case ASCII to lower case +@DESC@ +This macro converts upper case ASCII c to the +equivalent lower case letter. +@@ + @RET@ FcChar8 * @FUNC@ FcStrCopy @TYPE1@ const FcChar8 * @ARG1@ s @@ -126,45 +153,70 @@ Just like FcStrCopy except that it converts any leading '~' characters in Returns NULL if '~' is present in s and HOME is unset. @@ +@RET@ int +@FUNC@ FcStrCmp +@TYPE1@ const FcChar8 * @ARG1@ s1 +@TYPE2@ const FcChar8 * @ARG2@ s2 +@PURPOSE@ compare UTF-8 strings +@DESC@ +Returns the usual <0, 0, >0 result of comparing +s1 and s2. +@@ + @RET@ int @FUNC@ FcStrCmpIgnoreCase @TYPE1@ const FcChar8 * @ARG1@ s1 @TYPE2@ const FcChar8 * @ARG2@ s2 -@PURPOSE@ compare UTF-8 strings ignoring ASCII case +@PURPOSE@ compare UTF-8 strings ignoring case @DESC@ Returns the usual <0, 0, >0 result of comparing -s1 and s2. This test is -case-insensitive in the ASCII range and will operate properly with UTF8 -encoded strings, although it does not check for well formed strings. +s1 and s2. This test is +case-insensitive for all proper UTF-8 encoded strings. @@ @RET@ FcChar8 * @FUNC@ FcStrStr -@TYPE1@ const char * @ARG1@ s1 -@TYPE2@ const char * @ARG2@ s2 +@TYPE1@ const FcChar8 * @ARG1@ s1 +@TYPE2@ const FcChar8 * @ARG2@ s2 @PURPOSE@ locate UTF-8 substring @DESC@ 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, although it does not check for well formed -strings. +with UTF8 encoded strings. @@ @RET@ FcChar8 * @FUNC@ FcStrStrIgnoreCase -@TYPE1@ const char * @ARG1@ s1 -@TYPE2@ const char * @ARG2@ s2 +@TYPE1@ const FcChar8 * @ARG1@ s1 +@TYPE2@ const FcChar8 * @ARG2@ s2 @PURPOSE@ locate UTF-8 substring ignoring ASCII case @DESC@ Returns the location of s2 in -s1, ignoring ASCII case. Returns NULL if +s1, ignoring case. Returns NULL if s2 is not present in s1. -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. +This test is case-insensitive for all proper UTF-8 encoded strings. @@ +@RET@ FcChar8 * +@FUNC@ FcStrPlus +@TYPE1@ const FcChar8 * @ARG1@ s1 +@TYPE2@ const FcChar8 * @ARG2@ s2 +@PURPOSE@ concatenate two strings +@DESC@ +This function allocates new storage and places the concatenation of +s1 and s2 there, returning the +new string. +@@ + +@RET@ void +@FUNC@ FcStrFree +@TYPE1@ FcChar8 * @ARG1@ s +@PURPOSE@ free a string +@DESC@ +This is just a wrapper around free(3) which helps track memory usage of +strings within the fontconfig library. + @RET@ FcChar8 * @FUNC@ FcStrDirname @TYPE1@ const FcChar8 * @ARG1@ file diff --git a/doc/fcstrset.fncs b/doc/fcstrset.fncs index c6dd819..d6b0520 100644 --- a/doc/fcstrset.fncs +++ b/doc/fcstrset.fncs @@ -41,6 +41,17 @@ Returns whether s is a member of set. @@ +@RET@ FcBool +@FUNC@ FcStrSetEqual +@TYPE1@ FcStrSet * @ARG1@ set_a +@TYPE2@ FcStrSet * @ARG2@ set_b +@PURPOSE@ check sets for equality +@DESC@ +Returns whether set_a contains precisely the same +strings as set_b. Ordering of strings within the two +sets is not considered. +@@ + @RET@ FcBool @FUNC@ FcStrSetAdd @TYPE1@ FcStrSet * @ARG1@ set diff --git a/doc/fcvalue.fncs b/doc/fcvalue.fncs index 88ccaf3..14d043b 100644 --- a/doc/fcvalue.fncs +++ b/doc/fcvalue.fncs @@ -38,3 +38,24 @@ FcTypeMatrix and FcTypeCharSet reference memory, the other types do not. Returns a copy of v duplicating any object referenced by it so that v may be safely destroyed without harming the new value. @@ + +@RET@ void +@FUNC@ FcValuePrint +@TYPE1@ FcValue% @ARG1@ v +@PURPOSE@ Print a value to stdout +@DESC@ +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. +@@ + +@RET@ FcBool +@FUNC@ FcValueEqual +@TYPE1@ FcValue% @ARG1@ v_a +@TYPE2@ FcValue% @ARG2@ v_b +@PURPOSE@ Test two values for equality +@DESC@ +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. +@@ diff --git a/doc/fontconfig-devel.sgml b/doc/fontconfig-devel.sgml index 5bad9a5..d448524 100644 --- a/doc/fontconfig-devel.sgml +++ b/doc/fontconfig-devel.sgml @@ -178,7 +178,7 @@ convenience for the applications rendering mechanism. spacing charset FC_CHARSET CharSet Unicode chars encoded by the font - lang FC_LANG String List of RFC-3066-style + lang FC_LANG LangSet Set of RFC-3066-style languages this font supports fontversion FC_FONTVERSION Int Version number of the font capability FC_CAPABILITY String List of layout capabilities in @@ -217,6 +217,26 @@ 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. + 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. + + + 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. + + FcType Tags the kind of data stored in an FcValue. @@ -236,6 +256,8 @@ types. The 'type' tag indicates which member is valid. double d; const FcMatrix *m; const FcCharSet *c; + void *f; + const FcLangSet *l; } u; } FcValue; @@ -251,6 +273,8 @@ types. The 'type' tag indicates which member is valid. FcTypeBool b b FcTypeMatrix m FcMatrix * FcTypeCharSet c FcCharSet * + FcTypeFTFace f void * (FT_Face) + FcTypeLangSet l FcLangSet * -- 2.39.5