2 * fontconfig/doc/fcfontset.fncs
4 * Copyright © 2003 Keith Packard
6 * Permission to use, copy, modify, distribute, and sell this software and its
7 * documentation for any purpose is hereby granted without fee, provided that
8 * the above copyright notice appear in all copies and that both that
9 * copyright notice and this permission notice appear in supporting
10 * documentation, and that the name of Keith Packard not be used in
11 * advertising or publicity pertaining to distribution of the software without
12 * specific, written prior permission. Keith Packard makes no
13 * representations about the suitability of this software for any purpose. It
14 * is provided "as is" without express or implied warranty.
16 * KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
17 * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
18 * EVENT SHALL KEITH PACKARD BE LIABLE FOR ANY SPECIAL, INDIRECT OR
19 * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
20 * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
21 * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
22 * PERFORMANCE OF THIS SOFTWARE.
25 @FUNC@ FcFontSetCreate
27 @PURPOSE@ Create a font set
29 Creates an empty font set.
33 @FUNC@ FcFontSetDestroy
34 @TYPE1@ FcFontSet * @ARG1@ s
35 @PURPOSE@ Destroy a font set
37 Destroys a font set. Note that this destroys any referenced patterns as
43 @TYPE1@ FcFontSet * @ARG1@ s
44 @TYPE2@ FcPattern * @ARG2@ font
45 @PURPOSE@ Add to a font set
47 Adds a pattern to a font set. Note that the pattern is not copied before
48 being inserted into the set. Returns FcFalse if the pattern cannot be
49 inserted into the set (due to allocation failure). Otherwise returns FcTrue.
54 @TYPE1@ FcConfig * @ARG1@ config
55 @TYPE2@ FcFontSet ** @ARG2@ sets
56 @TYPE3@ int @ARG3@ nsets
57 @TYPE4@ FcPattern * @ARG4@ pattern
58 @TYPE5@ FcObjectSet * @ARG5@ object_set
59 @PURPOSE@ List fonts from a set of font sets
61 Selects fonts matching <parameter>pattern</parameter> from
62 <parameter>sets</parameter>, creates patterns from those
63 fonts containing only the objects in <parameter>object_set</parameter> and returns
64 the set of unique such patterns.
65 If <parameter>config</parameter> is NULL, the default configuration is checked
66 to be up to date, and used.
71 @TYPE1@ FcConfig * @ARG1@ config
72 @TYPE2@ FcFontSet ** @ARG2@ sets
73 @TYPE3@ int @ARG3@ nsets
74 @TYPE4@ FcPattern * @ARG4@ pattern
75 @TYPE5@ FcResult * @ARG5@ result
76 @PURPOSE@ Return the best font from a set of font sets
78 Finds the font in <parameter>sets</parameter> most closely matching
79 <parameter>pattern</parameter> and returns the result of
80 <function>FcFontRenderPrepare</function> for that font and the provided
81 pattern. This function should be called only after
82 <function>FcConfigSubstitute</function> and
83 <function>FcDefaultSubstitute</function> have been called for
84 <parameter>pattern</parameter>; otherwise the results will not be correct.
85 If <parameter>config</parameter> is NULL, the current configuration is used.
86 Returns NULL if an error occurs during this process.
91 @TYPE1@ FcFontSet * @ARG1@ set
92 @PURPOSE@ Print a set of patterns to stdout
94 This function is useful for diagnosing font related issues, printing the
95 complete contents of every pattern in <parameter>set</parameter>. The format
96 of the output is designed to be of help to users and developers, and may
102 @TYPE1@ FcConfig * @ARG1@ config
103 @TYPE2@ FcFontSet ** @ARG2@ sets
104 @TYPE3@ int @ARG3@ nsets
105 @TYPE4@ FcPattern * @ARG4@ pattern
106 @TYPE5@ FcBool% @ARG5@ trim
107 @TYPE6@ FcCharSet ** @ARG6@ csp
108 @TYPE7@ FcResult * @ARG7@ result
109 @PURPOSE@ Add to a font set
111 Returns the list of fonts from <parameter>sets</parameter>
112 sorted by closeness to <parameter>pattern</parameter>.
113 If <parameter>trim</parameter> is FcTrue,
114 elements in the list which don't include Unicode coverage not provided by
115 earlier elements in the list are elided. The union of Unicode coverage of
116 all of the fonts is returned in <parameter>csp</parameter>,
117 if <parameter>csp</parameter> is not NULL. This function
118 should be called only after FcConfigSubstitute and FcDefaultSubstitute have
119 been called for <parameter>p</parameter>;
120 otherwise the results will not be correct.
122 The returned FcFontSet references FcPattern structures which may be shared
123 by the return value from multiple FcFontSort calls, applications cannot
124 modify these patterns. Instead, they should be passed, along with
125 <parameter>pattern</parameter> to
126 <function>FcFontRenderPrepare</function> which combines them into a complete pattern.
128 The FcFontSet returned by FcFontSetSort is destroyed by caling FcFontSetDestroy.
132 @FUNC@ FcFontSetSortDestroy
133 @TYPE1@ FcFontSet * @ARG1@ set
134 @PURPOSE@ DEPRECATED destroy a font set
136 This function is DEPRECATED. <function>FcFontSetSortDestroy</function>
137 destroys <parameter>set</parameter> by calling
138 <function>FcFontSetDestroy</function>. Applications should use
139 <function>FcFontSetDestroy</function> directly instead.