aboutsummaryrefslogtreecommitdiff
path: root/fontconfig/doc/fcpattern.fncs
diff options
context:
space:
mode:
Diffstat (limited to 'fontconfig/doc/fcpattern.fncs')
-rw-r--r--fontconfig/doc/fcpattern.fncs397
1 files changed, 397 insertions, 0 deletions
diff --git a/fontconfig/doc/fcpattern.fncs b/fontconfig/doc/fcpattern.fncs
new file mode 100644
index 000000000..e2c2953df
--- /dev/null
+++ b/fontconfig/doc/fcpattern.fncs
@@ -0,0 +1,397 @@
+/*
+ * fontconfig/doc/fcpattern.fncs
+ *
+ * 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.
+ *
+ * THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
+ * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
+ * 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
+ * PERFORMANCE OF THIS SOFTWARE.
+ */
+@RET@ FcPattern *
+@FUNC@ FcPatternCreate
+@TYPE1@ void
+@PURPOSE@ Create a pattern
+@DESC@
+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
+<parameter>p</parameter>. 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 <parameter>p</parameter>. Patterns are freed only
+when the reference count reaches zero.
+@@
+
+@RET@ void
+@FUNC@ FcPatternDestroy
+@TYPE1@ FcPattern * @ARG1@ p
+@PURPOSE@ Destroy a pattern
+@DESC@
+Decrement the pattern reference count. If all references are gone, destroys
+the pattern, in the process destroying all related values.
+@@
+
+@RET@ FcBool
+@FUNC@ FcPatternEqual
+@TYPE1@ const FcPattern * @ARG1@ pa
+@TYPE2@ const FcPattern * @ARG2@ pb
+@PURPOSE@ Compare patterns
+@DESC@
+Returns whether <parameter>pa</parameter> and <parameter>pb</parameter> are exactly alike.
+@@
+
+@RET@ FcBool
+@FUNC@ FcPatternEqualSubset
+@TYPE1@ const FcPattern * @ARG1@ pa
+@TYPE2@ const FcPattern * @ARG2@ pb
+@TYPE3@ const FcObjectSet * @ARG3@ os
+@PURPOSE@ Compare portions of patterns
+@DESC@
+Returns whether <parameter>pa</parameter> and <parameter>pb</parameter> have exactly the same values for all of the
+objects in <parameter>os</parameter>.
+@@
+
+@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
+<parameter>p</parameter> that are in <parameter>os</parameter>.
+If <parameter>os</parameter> is NULL, a duplicate of
+<parameter>p</parameter> is returned.
+@@
+
+@RET@ FcChar32
+@FUNC@ FcPatternHash
+@TYPE1@ const FcPattern * @ARG1@ p
+@PURPOSE@ Compute a pattern hash value
+@DESC@
+Returns a 32-bit number which is the same for any two patterns which are
+equal.
+@@
+
+@RET@ FcBool
+@FUNC@ FcPatternAdd
+@TYPE1@ FcPattern * @ARG1@ p
+@TYPE2@ const char * @ARG2@ object
+@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<parameter>. If `append</parameter> 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.
+@@
+
+@RET@ FcBool
+@FUNC@ FcPatternAddWeak
+@TYPE1@ FcPattern * @ARG1@ p
+@TYPE2@ const char * @ARG2@ object
+@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 <parameter>weak</parameter> instead of <parameter>strong</parameter>.
+@@
+
+@TITLE@ FcPatternAdd-Type
+@RET@ FcBool
+@FUNC@ FcPatternAddInteger
+@TYPE1@ FcPattern * @ARG1@ p
+@TYPE2@ const char * @ARG2@ object
+@TYPE3@ int% @ARG3@ i
+
+@PROTOTYPE+@
+@RET+@ FcBool
+@FUNC+@ FcPatternAddDouble
+@TYPE1+@ FcPattern * @ARG1+@ p
+@TYPE2+@ const char * @ARG2+@ object
+@TYPE3+@ double% @ARG3+@ d
+
+@PROTOTYPE++@
+@RET++@ FcBool
+@FUNC++@ FcPatternAddString
+@TYPE1++@ FcPattern * @ARG1++@ p
+@TYPE2++@ const char * @ARG2++@ object
+@TYPE3++@ const FcChar8 * @ARG3++@ s
+
+@PROTOTYPE+++@
+@RET+++@ FcBool
+@FUNC+++@ FcPatternAddMatrix
+@TYPE1+++@ FcPattern * @ARG1+++@ p
+@TYPE2+++@ const char * @ARG2+++@ object
+@TYPE3+++@ const FcMatrix * @ARG3+++@ m
+
+@PROTOTYPE++++@
+@RET++++@ FcBool
+@FUNC++++@ FcPatternAddCharSet
+@TYPE1++++@ FcPattern * @ARG1++++@ p
+@TYPE2++++@ const char * @ARG2++++@ object
+@TYPE3++++@ const FcCharSet * @ARG3++++@ c
+
+@PROTOTYPE+++++@
+@RET+++++@ FcBool
+@FUNC+++++@ FcPatternAddBool
+@TYPE1+++++@ FcPattern * @ARG1+++++@ p
+@TYPE2+++++@ const char * @ARG2+++++@ object
+@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
+type into the pattern. Use these in preference to FcPatternAdd as they
+will provide compile-time typechecking. These all append values to
+any existing list of values.
+@@
+
+@RET@ FcResult
+@FUNC@ FcPatternGet
+@TYPE1@ FcPattern * @ARG1@ p
+@TYPE2@ const char * @ARG2@ object
+@TYPE3@ int% @ARG3@ id
+@TYPE4@ FcValue * @ARG4@ v
+@PURPOSE@ Return a value from a pattern
+@DESC@
+Returns in <parameter>v</parameter> the <parameter>id</parameter>'th value
+associated with the property <parameter>object</parameter>.
+The value returned is not a copy, but rather refers to the data stored
+within the pattern directly. Applications must not free this value.
+@@
+
+@TITLE@ FcPatternGet-Type
+@PROTOTYPE@
+@RET@ FcResult
+@FUNC@ FcPatternGetInteger
+@TYPE1@ FcPattern * @ARG1@ p
+@TYPE2@ const char * @ARG2@ object
+@TYPE3@ int% @ARG3@ n
+@TYPE4@ int * @ARG4@ i
+
+@PROTOTYPE+@
+@RET+@ FcResult
+@FUNC+@ FcPatternGetDouble
+@TYPE1+@ FcPattern * @ARG1+@ p
+@TYPE2+@ const char * @ARG2+@ object
+@TYPE3+@ int% @ARG3+@ n
+@TYPE4+@ double * @ARG4+@ d
+
+@PROTOTYPE++@
+@RET++@ FcResult
+@FUNC++@ FcPatternGetString
+@TYPE1++@ FcPattern * @ARG1++@ p
+@TYPE2++@ const char * @ARG2++@ object
+@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
+@TYPE4+++@ FcMatrix ** @ARG4+++@ s
+
+@PROTOTYPE++++@
+@RET++++@ FcResult
+@FUNC++++@ FcPatternGetCharSet
+@TYPE1++++@ FcPattern * @ARG1++++@ p
+@TYPE2++++@ const char * @ARG2++++@ object
+@TYPE3++++@ int% @ARG3++++@ n
+@TYPE4++++@ FcCharSet ** @ARG4++++@ c
+
+@PROTOTYPE+++++@
+@RET+++++@ FcResult
+@FUNC+++++@ FcPatternGetBool
+@TYPE1+++++@ FcPattern * @ARG1+++++@ p
+@TYPE2+++++@ const char * @ARG2+++++@ object
+@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
+returned data is of the expected type. They return FcResultTypeMismatch if
+this is not the case. Note that these (like FcPatternGet) do not make a
+copy of any data structure referenced by the return value. Use these
+in preference to FcPatternGet to provide compile-time typechecking.
+@@
+
+@RET@ FcPattern *
+@FUNC@ FcPatternBuild
+@TYPE1@ FcPattern * @ARG1@ pattern
+@TYPE2@ ...
+
+@PROTOTYPE+@
+@RET+@ FcPattern *
+@FUNC+@ FcPatternVaBuild
+@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:
+</para>
+<orderedlist>
+<listitem><para>
+Object name, a string describing the property to be added.
+</para></listitem><listitem><para>
+Object type, one of the FcType enumerated values
+</para></listitem><listitem><para>
+Value, not an FcValue, but the raw type as passed to any of the
+FcPatternAdd&lt;type&gt; functions. Must match the type of the second
+argument.
+</para></listitem>
+</orderedlist>
+<para>
+The argument list is terminated by a null object name, no object type nor
+value need be passed for this. The values are added to `pattern', if
+`pattern' is null, a new pattern is created. In either case, the pattern is
+returned. Example
+</para>
+<programlisting>
+pattern = FcPatternBuild (0, FC_FAMILY, FcTypeString, "Times", (char *) 0);
+</programlisting>
+<para>
+FcPatternVaBuild is used when the arguments are already in the form of a
+varargs value. FcPatternVapBuild is a macro version of FcPatternVaBuild
+which returns its result directly in the <parameter>result</parameter>
+variable.
+@@
+
+@RET@ FcBool
+@FUNC@ FcPatternDel
+@TYPE1@ FcPattern * @ARG1@ p
+@TYPE2@ const char * @ARG2@ object
+@PURPOSE@ Delete a property from a pattern
+@DESC@
+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
+@PURPOSE@ Print a pattern for debugging
+@DESC@
+Prints an easily readable version of the pattern to stdout. There is
+no provision for reparsing data in this format, it's just for diagnostics
+and debugging.
+@@
+
+@RET@ void
+@FUNC@ FcDefaultSubstitute
+@TYPE1@ FcPattern * @ARG1@ pattern
+@PURPOSE@ Perform default substitutions in a pattern
+@DESC@
+Supplies default values for underspecified font patterns:
+<itemizedlist>
+<listitem><para>
+Patterns without a specified style or weight are set to Medium
+</para></listitem>
+<listitem><para>
+Patterns without a specified style or slant are set to Roman
+</para></listitem>
+<listitem><para>
+Patterns without a specified pixel size are given one computed from any
+specified point size (default 12), dpi (default 75) and scale (default 1).
+</para></listitem>
+</itemizedlist>
+@@
+
+@RET@ FcPattern *
+@FUNC@ FcNameParse
+@TYPE1@ const FcChar8 * @ARG1@ name
+@PURPOSE@ Parse a pattern string
+@DESC@
+Converts <parameter>name</parameter> from the standard text format described above into a pattern.
+@@
+
+@RET@ FcChar8 *
+@FUNC@ FcNameUnparse
+@TYPE1@ FcPattern * @ARG1@ pat
+@PURPOSE@ Convert a pattern back into a string that can be parsed
+@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 using free().
+@@