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@ FcPatternCreate
27 @PURPOSE@ Create a pattern
29 Creates a pattern with no properties; used to build patterns from scratch.
33 @FUNC@ FcPatternDuplicate
34 @TYPE1@ FcPattern * @ARG1@ p
35 @PURPOSE@ Copy a pattern
37 Copy a pattern, returning a new pattern that matches
38 <parameter>p</parameter>. Each pattern may be modified without affecting the
43 @FUNC@ FcPatternReference
44 @TYPE1@ FcPattern * @ARG1@ p
45 @PURPOSE@ Increment pattern reference count
47 Add another reference to <parameter>p</parameter>. Patterns are freed only
48 when the reference count reaches zero.
52 @FUNC@ FcPatternDestroy
53 @TYPE1@ FcPattern * @ARG1@ p
54 @PURPOSE@ Destroy a pattern
56 Decrement the pattern reference count. If all references are gone, destroys
57 the pattern, in the process destroying all related values.
62 @TYPE1@ const FcPattern * @ARG1@ pa
63 @TYPE2@ const FcPattern * @ARG2@ pb
64 @PURPOSE@ Compare patterns
66 Returns whether <parameter>pa</parameter> and <parameter>pb</parameter> are exactly alike.
70 @FUNC@ FcPatternEqualSubset
71 @TYPE1@ const FcPattern * @ARG1@ pa
72 @TYPE2@ const FcPattern * @ARG2@ pb
73 @TYPE3@ const FcObjectSet * @ARG3@ os
74 @PURPOSE@ Compare portions of patterns
76 Returns whether <parameter>pa</parameter> and <parameter>pb</parameter> have exactly the same values for all of the
77 objects in <parameter>os</parameter>.
82 @TYPE1@ const FcPattern * @ARG1@ p
83 @PURPOSE@ Compute a pattern hash value
85 Returns a 32-bit number which is the same for any two patterns which are
91 @TYPE1@ FcPattern * @ARG1@ p
92 @TYPE2@ const char * @ARG2@ object
93 @TYPE3@ FcValue% @ARG3@ value
94 @TYPE4@ FcBool% @ARG4@ append
95 @PURPOSE@ Add a value to a pattern
97 Adds a single value to the list of values associated with the property named
98 `object<parameter>. If `append</parameter> is FcTrue, the value is added at the end of any
99 existing list, otherwise it is inserted at the begining. `value' is saved
100 (with FcValueSave) when inserted into the pattern so that the library
101 retains no reference to any application-supplied data structure.
105 @FUNC@ FcPatternAddWeak
106 @TYPE1@ FcPattern * @ARG1@ p
107 @TYPE2@ const char * @ARG2@ object
108 @TYPE3@ FcValue% @ARG3@ value
109 @TYPE4@ FcBool% @ARG4@ append
110 @PURPOSE@ Add a value to a pattern with weak binding
112 FcPatternAddWeak is essentially the same as FcPatternAdd except that any
113 values added to the list have binding <parameter>weak</parameter> instead of <parameter>strong</parameter>.
116 @TITLE@ FcPatternAdd-Type
118 @FUNC@ FcPatternAddInteger
119 @TYPE1@ FcPattern * @ARG1@ p
120 @TYPE2@ const char * @ARG2@ object
121 @TYPE3@ int% @ARG3@ i
125 @FUNC+@ FcPatternAddDouble
126 @TYPE1+@ FcPattern * @ARG1+@ p
127 @TYPE2+@ const char * @ARG2+@ object
128 @TYPE3+@ double% @ARG3+@ d
132 @FUNC++@ FcPatternAddString
133 @TYPE1++@ FcPattern * @ARG1++@ p
134 @TYPE2++@ const char * @ARG2++@ object
135 @TYPE3++@ const FcChar8 * @ARG3++@ s
139 @FUNC+++@ FcPatternAddMatrix
140 @TYPE1+++@ FcPattern * @ARG1+++@ p
141 @TYPE2+++@ const char * @ARG2+++@ object
142 @TYPE3+++@ const FcMatrix * @ARG3+++@ m
146 @FUNC++++@ FcPatternAddCharSet
147 @TYPE1++++@ FcPattern * @ARG1++++@ p
148 @TYPE2++++@ const char * @ARG2++++@ object
149 @TYPE3++++@ const FcCharSet * @ARG3++++@ c
153 @FUNC+++++@ FcPatternAddBool
154 @TYPE1+++++@ FcPattern * @ARG1+++++@ p
155 @TYPE2+++++@ const char * @ARG2+++++@ object
156 @TYPE3+++++@ FcBool% @ARG3+++++@ b
160 @FUNC++++++@ FcPatternAddFTFace
161 @TYPE1++++++@ FcPattern * @ARG1++++++@ p
162 @TYPE2++++++@ const char * @ARG2++++++@ object
163 @TYPE3++++++@ const FT_Face @ARG3++++++@ f
167 @FUNC+++++++@ FcPatternAddLangSet
168 @TYPE1+++++++@ FcPattern * @ARG1+++++++@ p
169 @TYPE2+++++++@ const char * @ARG2+++++++@ object
170 @TYPE3+++++++@ const FcLangSet * @ARG3+++++++@ l
172 @PURPOSE@ Add a typed value to a pattern
174 These are all convenience functions that insert objects of the specified
175 type into the pattern. Use these in preference to FcPatternAdd as they
176 will provide compile-time typechecking. These all append values to
177 any existing list of values.
182 @TYPE1@ FcPattern * @ARG1@ p
183 @TYPE2@ const char * @ARG2@ object
184 @TYPE3@ int% @ARG3@ id
185 @TYPE4@ FcValue * @ARG4@ v
186 @PURPOSE@ Return a value from a pattern
188 Returns in <parameter>v</parameter> the <parameter>id</parameter>'th value
189 associated with the property <parameter>object</parameter>.
190 The value returned is not a copy, but rather refers to the data stored
191 within the pattern directly. Applications must not free this value.
194 @TITLE@ FcPatternGet-Type
197 @FUNC@ FcPatternGetInteger
198 @TYPE1@ FcPattern * @ARG1@ p
199 @TYPE2@ const char * @ARG2@ object
200 @TYPE3@ int% @ARG3@ n
201 @TYPE4@ int * @ARG4@ i
205 @FUNC+@ FcPatternGetDouble
206 @TYPE1+@ FcPattern * @ARG1+@ p
207 @TYPE2+@ const char * @ARG2+@ object
208 @TYPE3+@ int% @ARG3+@ n
209 @TYPE4+@ double * @ARG4+@ d
213 @FUNC++@ FcPatternGetString
214 @TYPE1++@ FcPattern * @ARG1++@ p
215 @TYPE2++@ const char * @ARG2++@ object
216 @TYPE3++@ int% @ARG3++@ n
217 @TYPE4++@ FcChar8 ** @ARG4++@ s
221 @FUNC+++@ FcPatternGetMatrix
222 @TYPE1+++@ FcPattern * @ARG1+++@ p
223 @TYPE2+++@ const char * @ARG2+++@ object
224 @TYPE3+++@ int% @ARG3+++@ n
225 @TYPE4+++@ FcMatrix ** @ARG4+++@ s
229 @FUNC++++@ FcPatternGetCharSet
230 @TYPE1++++@ FcPattern * @ARG1++++@ p
231 @TYPE2++++@ const char * @ARG2++++@ object
232 @TYPE3++++@ int% @ARG3++++@ n
233 @TYPE4++++@ FcCharSet ** @ARG4++++@ c
237 @FUNC+++++@ FcPatternGetBool
238 @TYPE1+++++@ FcPattern * @ARG1+++++@ p
239 @TYPE2+++++@ const char * @ARG2+++++@ object
240 @TYPE3+++++@ int% @ARG3+++++@ n
241 @TYPE4+++++@ FcBool * @ARG4+++++@ b
245 @FUNC++++++@ FcPatternGetFTFace
246 @TYPE1++++++@ FcPattern * @ARG1++++++@ p
247 @TYPE2++++++@ const char * @ARG2++++++@ object
248 @TYPE3++++++@ const FT_Face * @ARG3++++++@ f
252 @FUNC+++++++@ FcPatternGetLangSet
253 @TYPE1+++++++@ FcPattern * @ARG1+++++++@ p
254 @TYPE2+++++++@ const char * @ARG2+++++++@ object
255 @TYPE3+++++++@ const FcLangSet ** @ARG3+++++++@ l
257 @PURPOSE@ Return a typed value from a pattern
259 These are convenience functions that call FcPatternGet and verify that the
260 returned data is of the expected type. They return FcResultTypeMismatch if
261 this is not the case. Note that these (like FcPatternGet) do not make a
262 copy of any data structure referenced by the return value. Use these
263 in preference to FcPatternGet to provide compile-time typechecking.
267 @FUNC@ FcPatternBuild
268 @TYPE1@ FcPattern * @ARG1@ orig
273 @FUNC+@ FcPatternVaBuild
274 @TYPE1+@ FcPattern * @ARG1+@ orig
275 @TYPE2+@ va_list% @ARG2+@ va
279 @FUNC++@ FcPatternVapBuild
280 @TYPE1++@ FcPattern * @ARG1++@ result
281 @TYPE2++@ FcPattern * @ARG2++@ orig
282 @TYPE3++@ va_list% @ARG3++@ va
284 @PURPOSE@ Create patterns from arguments
286 Builds a pattern using a list of objects, types and values. Each
287 value to be entered in the pattern is specified with three arguments:
291 Object name, a string describing the property to be added.
292 </para></listitem><listitem><para>
293 Object type, one of the FcType enumerated values
294 </para></listitem><listitem><para>
295 Value, not an FcValue, but the raw type as passed to any of the
296 FcPatternAdd<type> functions. Must match the type of the second
301 The argument list is terminated by a null object name, no object type nor
302 value need be passed for this. The values are added to `pattern', if
303 `pattern' is null, a new pattern is created. In either case, the pattern is
307 pattern = FcPatternBuild (0, FC_FAMILY, FcTypeString, "Times", (char *) 0);
310 FcPatternVaBuild is used when the arguments are already in the form of a
311 varargs value. FcPatternVapBuild is a macro version of FcPatternVaBuild
312 which returns its result directly in the <parameter>result</parameter>
318 @TYPE1@ FcPattern * @ARG1@ p
319 @TYPE2@ const char * @ARG2@ object
320 @PURPOSE@ Delete a property from a pattern
322 Deletes all values associated with the property `object', returning
323 whether the property existed or not.
327 @FUNC@ FcPatternRemove
328 @TYPE1@ FcPattern * @ARG1@ p
329 @TYPE2@ const char * @ARG2@ object
330 @TYPE3@ int% @ARG3@ id
331 @PURPOSE@ Remove one object of the specified type from the pattern
333 Removes the value associated with the property `object' at position `id', returning
334 whether the property existed and had a value at that position or not.
338 @FUNC@ FcPatternPrint
339 @TYPE1@ const FcPattern * @ARG1@ p
340 @PURPOSE@ Print a pattern for debugging
342 Prints an easily readable version of the pattern to stdout. There is
343 no provision for reparsing data in this format, it's just for diagnostics
348 @FUNC@ FcDefaultSubstitute
349 @TYPE1@ FcPattern * @ARG1@ pattern
350 @PURPOSE@ Perform default substitutions in a pattern
352 Supplies default values for underspecified font patterns:
355 Patterns without a specified style or weight are set to Medium
358 Patterns without a specified style or slant are set to Roman
361 Patterns without a specified pixel size are given one computed from any
362 specified point size (default 12), dpi (default 75) and scale (default 1).
369 @TYPE1@ const FcChar8 * @ARG1@ name
370 @PURPOSE@ Parse a pattern string
372 Converts <parameter>name</parameter> from the standard text format described above into a pattern.
377 @TYPE1@ FcPattern * @ARG1@ pat
378 @PURPOSE@ Convert a pattern back into a string that can be parsed
380 Converts the given pattern into the standard text format described above.
381 The return value is not static, but instead refers to newly allocated memory
382 which should be freed by the caller.