X-Git-Url: https://git.wh0rd.org/?a=blobdiff_plain;f=doc%2Ffcpattern.fncs;h=8948e88a3a7d98ea48e90377207dcf3c44444743;hb=3074a73b418b40135d4a4f4e0713fcf987d34795;hp=4dbbed7b1c7429d99c193529d5066e572c524fa1;hpb=bfc2dc3ac4b1eb5f0f9f0dfae7abac7e77e28061;p=fontconfig.git
diff --git a/doc/fcpattern.fncs b/doc/fcpattern.fncs
index 4dbbed7..8948e88 100644
--- a/doc/fcpattern.fncs
+++ b/doc/fcpattern.fncs
@@ -1,7 +1,7 @@
/*
- * $Id$
+ * fontconfig/doc/fcpattern.fncs
*
- * Copyright © 2003 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
@@ -13,9 +13,9 @@
* 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,
+ * THE AUTHOR(S) 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
+ * EVENT SHALL THE AUTHOR(S) 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
@@ -29,12 +29,32 @@
Creates a pattern with no properties; used to build patterns from scratch.
@@
+@RET@ FcPattern *
+@FUNC@ FcPatternDuplicate
+@TYPE1@ const 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
@@ -43,7 +63,7 @@ Destroys a pattern, in the process destroying all related values.
@TYPE2@ const FcPattern * @ARG2@ pb
@PURPOSE@ Compare patterns
@DESC@
-Returns whether 'pa' and 'pb' are exactly alike.
+Returns whether pa and pb are exactly alike.
@@
@RET@ FcBool
@@ -53,8 +73,20 @@ Returns whether 'pa' and 'pb' are exactly alike.
@TYPE3@ const FcObjectSet * @ARG3@ os
@PURPOSE@ Compare portions of patterns
@DESC@
-Returns whether 'pa' and 'pb' have exactly the same values for all of the
-objects in 'os'.
+Returns whether pa and pb have exactly the same values for all of the
+objects in os.
+@@
+
+@RET@ FcPattern *
+@FUNC@ FcPatternFilter
+@TYPE1@ FcPattern * @ARG1@ p
+@TYPE2@ const FcObjectSet * @ARG1@ os
+@PURPOSE@ Filter the objects of pattern
+@DESC@
+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.
@@
@RET@ FcChar32
@@ -70,12 +102,12 @@ equal.
@FUNC@ FcPatternAdd
@TYPE1@ FcPattern * @ARG1@ p
@TYPE2@ const char * @ARG2@ object
-@TYPE3@ FcValue @ARG3@ value
-@TYPE4@ FcBool @ARG4@ append
+@TYPE3@ FcValue% @ARG3@ value
+@TYPE4@ FcBool% @ARG4@ append
@PURPOSE@ Add a value to a pattern
@DESC@
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
+`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.
@@ -85,12 +117,12 @@ retains no reference to any application-supplied data structure.
@FUNC@ FcPatternAddWeak
@TYPE1@ FcPattern * @ARG1@ p
@TYPE2@ const char * @ARG2@ object
-@TYPE3@ FcValue @ARG3@ value
-@TYPE4@ FcBool @ARG4@ append
+@TYPE3@ FcValue% @ARG3@ value
+@TYPE4@ FcBool% @ARG4@ append
@PURPOSE@ Add a value to a pattern with weak binding
@DESC@
FcPatternAddWeak is essentially the same as FcPatternAdd except that any
-values added to the list have binding 'weak' instead of 'strong'.
+values added to the list have binding weak instead of strong.
@@
@TITLE@ FcPatternAdd-Type
@@ -98,21 +130,21 @@ values added to the list have binding 'weak' instead of 'strong'.
@FUNC@ FcPatternAddInteger
@TYPE1@ FcPattern * @ARG1@ p
@TYPE2@ const char * @ARG2@ object
-@TYPE3@ int @ARG3@ i
+@TYPE3@ int% @ARG3@ i
@PROTOTYPE+@
@RET+@ FcBool
@FUNC+@ FcPatternAddDouble
@TYPE1+@ FcPattern * @ARG1+@ p
@TYPE2+@ const char * @ARG2+@ object
-@TYPE3+@ double @ARG3+@ d
+@TYPE3+@ double% @ARG3+@ d
@PROTOTYPE++@
@RET++@ FcBool
@FUNC++@ FcPatternAddString
@TYPE1++@ FcPattern * @ARG1++@ p
@TYPE2++@ const char * @ARG2++@ object
-@TYPE3++@ const char * @ARG3++@ s
+@TYPE3++@ const FcChar8 * @ARG3++@ s
@PROTOTYPE+++@
@RET+++@ FcBool
@@ -133,7 +165,22 @@ values added to the list have binding 'weak' instead of 'strong'.
@FUNC+++++@ FcPatternAddBool
@TYPE1+++++@ FcPattern * @ARG1+++++@ p
@TYPE2+++++@ const char * @ARG2+++++@ object
-@TYPE3+++++@ FcBool @ARG3+++++@ b
+@TYPE3+++++@ FcBool% @ARG3+++++@ b
+
+@PROTOTYPE++++++@
+@RET++++++@ FcBool
+@FUNC++++++@ FcPatternAddFTFace
+@TYPE1++++++@ FcPattern * @ARG1++++++@ p
+@TYPE2++++++@ const char * @ARG2++++++@ object
+@TYPE3++++++@ const FT_Face @ARG3++++++@ f
+
+@PROTOTYPE+++++++@
+@RET+++++++@ FcBool
+@FUNC+++++++@ FcPatternAddLangSet
+@TYPE1+++++++@ FcPattern * @ARG1+++++++@ p
+@TYPE2+++++++@ const char * @ARG2+++++++@ object
+@TYPE3+++++++@ const FcLangSet * @ARG3+++++++@ l
+
@PURPOSE@ Add a typed value to a pattern
@DESC@
These are all convenience functions that insert objects of the specified
@@ -146,11 +193,12 @@ any existing list of values.
@FUNC@ FcPatternGet
@TYPE1@ FcPattern * @ARG1@ p
@TYPE2@ const char * @ARG2@ object
-@TYPE3@ int @ARG3@ id
+@TYPE3@ int% @ARG3@ id
@TYPE4@ FcValue * @ARG4@ v
@PURPOSE@ Return a value from a pattern
@DESC@
-Returns in `v' the `id'th value associated with the property `object'.
+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.
@@
@@ -161,7 +209,7 @@ within the pattern directly. Applications must not free this value.
@FUNC@ FcPatternGetInteger
@TYPE1@ FcPattern * @ARG1@ p
@TYPE2@ const char * @ARG2@ object
-@TYPE3@ int @ARG3@ n
+@TYPE3@ int% @ARG3@ n
@TYPE4@ int * @ARG4@ i
@PROTOTYPE+@
@@ -169,7 +217,7 @@ within the pattern directly. Applications must not free this value.
@FUNC+@ FcPatternGetDouble
@TYPE1+@ FcPattern * @ARG1+@ p
@TYPE2+@ const char * @ARG2+@ object
-@TYPE3+@ int @ARG3+@ n
+@TYPE3+@ int% @ARG3+@ n
@TYPE4+@ double * @ARG4+@ d
@PROTOTYPE++@
@@ -177,15 +225,15 @@ within the pattern directly. Applications must not free this value.
@FUNC++@ FcPatternGetString
@TYPE1++@ FcPattern * @ARG1++@ p
@TYPE2++@ const char * @ARG2++@ object
-@TYPE3++@ int @ARG3++@ n
-@TYPE4++@ char **const @ARG4++@ s
+@TYPE3++@ int% @ARG3++@ n
+@TYPE4++@ FcChar8 ** @ARG4++@ s
@PROTOTYPE+++@
@RET+++@ FcResult
@FUNC+++@ FcPatternGetMatrix
@TYPE1+++@ FcPattern * @ARG1+++@ p
@TYPE2+++@ const char * @ARG2+++@ object
-@TYPE3+++@ int @ARG3+++@ n
+@TYPE3+++@ int% @ARG3+++@ n
@TYPE4+++@ FcMatrix ** @ARG4+++@ s
@PROTOTYPE++++@
@@ -193,7 +241,7 @@ within the pattern directly. Applications must not free this value.
@FUNC++++@ FcPatternGetCharSet
@TYPE1++++@ FcPattern * @ARG1++++@ p
@TYPE2++++@ const char * @ARG2++++@ object
-@TYPE3++++@ int @ARG3++++@ n
+@TYPE3++++@ int% @ARG3++++@ n
@TYPE4++++@ FcCharSet ** @ARG4++++@ c
@PROTOTYPE+++++@
@@ -201,8 +249,25 @@ within the pattern directly. Applications must not free this value.
@FUNC+++++@ FcPatternGetBool
@TYPE1+++++@ FcPattern * @ARG1+++++@ p
@TYPE2+++++@ const char * @ARG2+++++@ object
-@TYPE3+++++@ int @ARG3+++++@ n
+@TYPE3+++++@ int% @ARG3+++++@ n
@TYPE4+++++@ FcBool * @ARG4+++++@ b
+
+@PROTOTYPE++++++@
+@RET++++++@ FcResult
+@FUNC++++++@ FcPatternGetFTFace
+@TYPE1++++++@ FcPattern * @ARG1++++++@ p
+@TYPE2++++++@ const char * @ARG2++++++@ object
+@TYPE3+++++@ int% @ARG3+++++@ n
+@TYPE3++++++@ FT_Face * @ARG3++++++@ f
+
+@PROTOTYPE+++++++@
+@RET+++++++@ FcResult
+@FUNC+++++++@ FcPatternGetLangSet
+@TYPE1+++++++@ FcPattern * @ARG1+++++++@ p
+@TYPE2+++++++@ const char * @ARG2+++++++@ object
+@TYPE3+++++@ int% @ARG3+++++@ n
+@TYPE3+++++++@ FcLangSet ** @ARG3+++++++@ l
+
@PURPOSE@ Return a typed value from a pattern
@DESC@
These are convenience functions that call FcPatternGet and verify that the
@@ -214,18 +279,27 @@ in preference to FcPatternGet to provide compile-time typechecking.
@RET@ FcPattern *
@FUNC@ FcPatternBuild
-@TYPE1@ FcPattern * @ARG1@ orig
+@TYPE1@ FcPattern * @ARG1@ pattern
@TYPE2@ ...
@PROTOTYPE+@
@RET+@ FcPattern *
@FUNC+@ FcPatternVaBuild
-@TYPE1+@ FcPattern * @ARG1+@ orig
-@TYPE2+@ va_list @ARG2+@ va
+@TYPE1+@ FcPattern * @ARG1+@ pattern
+@TYPE2+@ va_list% @ARG2+@ va
+
+@PROTOTYPE++@
+@RET++@ void
+@FUNC++@ FcPatternVapBuild
+@TYPE1++@ FcPattern * @ARG1++@ result
+@TYPE2++@ FcPattern * @ARG2++@ pattern
+@TYPE3++@ va_list% @ARG3++@ va
+
@PURPOSE@ Create patterns from arguments
@DESC@
Builds a pattern using a list of objects, types and values. Each
value to be entered in the pattern is specified with three arguments:
+
Object name, a string describing the property to be added.
@@ -244,11 +318,13 @@ value need be passed for this. The values are added to `pattern', if
returned. Example
-pattern = FcPatternBuild (0, FC_FAMILY, FtTypeString, "Times", (char *) 0);
+pattern = FcPatternBuild (0, FC_FAMILY, FcTypeString, "Times", (char *) 0);
FcPatternVaBuild is used when the arguments are already in the form of a
-varargs value.
+varargs value. FcPatternVapBuild is a macro version of FcPatternVaBuild
+which returns its result directly in the result
+variable.
@@
@RET@ FcBool
@@ -261,6 +337,17 @@ Deletes all values associated with the property `object', returning
whether the property existed or not.
@@
+@RET@ FcBool
+@FUNC@ FcPatternRemove
+@TYPE1@ FcPattern * @ARG1@ p
+@TYPE2@ const char * @ARG2@ object
+@TYPE3@ int% @ARG3@ id
+@PURPOSE@ Remove one object of the specified type from the pattern
+@DESC@
+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.
+@@
+
@RET@ void
@FUNC@ FcPatternPrint
@TYPE1@ const FcPattern * @ARG1@ p
@@ -293,10 +380,10 @@ specified point size (default 12), dpi (default 75) and scale (default 1).
@RET@ FcPattern *
@FUNC@ FcNameParse
-@TYPE1@ const char * @ARG1@ name
+@TYPE1@ const FcChar8 * @ARG1@ name
@PURPOSE@ Parse a pattern string
@DESC@
-Converts 'name' from the standard text format described above into a pattern.
+Converts name from the standard text format described above into a pattern.
@@
@RET@ FcChar8 *
@@ -306,5 +393,25 @@ Converts 'name' from the standard text format described above into a pattern.
@DESC@
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.
+which should be freed by the caller using free().
+@@
+
+@RET@ FcChar8 *
+@FUNC@ FcPatternFormat
+@TYPE1@ FcPattern * @ARG1@ pat
+@TYPE2@ const FcChar8 * @ARG2@ format
+@PURPOSE@ Format a pattern into a string according to a format specifier
+@DESC@
+
+Converts the given pattern into text format described by the format specifier.
+The format specifier is similar to a C style printf string, which the
+printf(2) man page provides a good introduction to. However, as fontconfig
+already knows the type of data that is being printed, you must omit the type
+specifier. In its place put the element name you wish to print enclosed in
+curly braces ({}). For example, to print the family name and style the
+pattern, use the format "%{family} %{style}\n".
+There can be an option width specifier after the percent sign and before
+the opening brace. The width modifier acts similar to those in printf.
+The return value refers to newly allocated memory which should be freed by the
+caller using free(), or NULL if format is invalid.
@@