2 * fontconfig/doc/fcpattern.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 the author(s) not be used in
11 * advertising or publicity pertaining to distribution of the software without
12 * specific, written prior permission. The authors make no
13 * representations about the suitability of this software for any purpose. It
14 * is provided "as is" without express or implied warranty.
16 * THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
17 * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
18 * EVENT SHALL THE AUTHOR(S) 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@ const 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>.
81 @FUNC@ FcPatternFilter
82 @TYPE1@ FcPattern * @ARG1@ p
83 @TYPE2@ const FcObjectSet * @ARG1@ os
84 @PURPOSE@ Filter the objects of pattern
86 Returns a new pattern that only has those objects from
87 <parameter>p</parameter> that are in <parameter>os</parameter>.
88 If <parameter>os</parameter> is NULL, a duplicate of
89 <parameter>p</parameter> is returned.
94 @TYPE1@ const FcPattern * @ARG1@ p
95 @PURPOSE@ Compute a pattern hash value
97 Returns a 32-bit number which is the same for any two patterns which are
103 @TYPE1@ FcPattern * @ARG1@ p
104 @TYPE2@ const char * @ARG2@ object
105 @TYPE3@ FcValue% @ARG3@ value
106 @TYPE4@ FcBool% @ARG4@ append
107 @PURPOSE@ Add a value to a pattern
109 Adds a single value to the list of values associated with the property named
110 `object<parameter>. If `append</parameter> is FcTrue, the value is added at the end of any
111 existing list, otherwise it is inserted at the beginning. `value' is saved
112 (with FcValueSave) when inserted into the pattern so that the library
113 retains no reference to any application-supplied data structure.
117 @FUNC@ FcPatternAddWeak
118 @TYPE1@ FcPattern * @ARG1@ p
119 @TYPE2@ const char * @ARG2@ object
120 @TYPE3@ FcValue% @ARG3@ value
121 @TYPE4@ FcBool% @ARG4@ append
122 @PURPOSE@ Add a value to a pattern with weak binding
124 FcPatternAddWeak is essentially the same as FcPatternAdd except that any
125 values added to the list have binding <parameter>weak</parameter> instead of <parameter>strong</parameter>.
128 @TITLE@ FcPatternAdd-Type
130 @FUNC@ FcPatternAddInteger
131 @TYPE1@ FcPattern * @ARG1@ p
132 @TYPE2@ const char * @ARG2@ object
133 @TYPE3@ int% @ARG3@ i
137 @FUNC+@ FcPatternAddDouble
138 @TYPE1+@ FcPattern * @ARG1+@ p
139 @TYPE2+@ const char * @ARG2+@ object
140 @TYPE3+@ double% @ARG3+@ d
144 @FUNC++@ FcPatternAddString
145 @TYPE1++@ FcPattern * @ARG1++@ p
146 @TYPE2++@ const char * @ARG2++@ object
147 @TYPE3++@ const FcChar8 * @ARG3++@ s
151 @FUNC+++@ FcPatternAddMatrix
152 @TYPE1+++@ FcPattern * @ARG1+++@ p
153 @TYPE2+++@ const char * @ARG2+++@ object
154 @TYPE3+++@ const FcMatrix * @ARG3+++@ m
158 @FUNC++++@ FcPatternAddCharSet
159 @TYPE1++++@ FcPattern * @ARG1++++@ p
160 @TYPE2++++@ const char * @ARG2++++@ object
161 @TYPE3++++@ const FcCharSet * @ARG3++++@ c
165 @FUNC+++++@ FcPatternAddBool
166 @TYPE1+++++@ FcPattern * @ARG1+++++@ p
167 @TYPE2+++++@ const char * @ARG2+++++@ object
168 @TYPE3+++++@ FcBool% @ARG3+++++@ b
172 @FUNC++++++@ FcPatternAddFTFace
173 @TYPE1++++++@ FcPattern * @ARG1++++++@ p
174 @TYPE2++++++@ const char * @ARG2++++++@ object
175 @TYPE3++++++@ const FT_Face @ARG3++++++@ f
179 @FUNC+++++++@ FcPatternAddLangSet
180 @TYPE1+++++++@ FcPattern * @ARG1+++++++@ p
181 @TYPE2+++++++@ const char * @ARG2+++++++@ object
182 @TYPE3+++++++@ const FcLangSet * @ARG3+++++++@ l
186 @FUNC++++++++@ FcPatternAddRange
187 @TYPE1++++++++@ FcPattern * @ARG1++++++++@ p
188 @TYPE2++++++++@ const char * @ARG2++++++++@ object
189 @TYPE3++++++++@ const FcRange * @ARG3++++++++@ r
191 @PURPOSE@ Add a typed value to a pattern
193 These are all convenience functions that insert objects of the specified
194 type into the pattern. Use these in preference to FcPatternAdd as they
195 will provide compile-time typechecking. These all append values to
196 any existing list of values.
198 <function>FcPatternAddRange</function> are available since 2.11.91.
203 @TYPE1@ FcPattern * @ARG1@ p
204 @TYPE2@ const char * @ARG2@ object
205 @TYPE3@ int% @ARG3@ id
206 @TYPE4@ FcValue * @ARG4@ v
207 @PURPOSE@ Return a value from a pattern
209 Returns in <parameter>v</parameter> the <parameter>id</parameter>'th value
210 associated with the property <parameter>object</parameter>.
211 The value returned is not a copy, but rather refers to the data stored
212 within the pattern directly. Applications must not free this value.
215 @TITLE@ FcPatternGet-Type
218 @FUNC@ FcPatternGetInteger
219 @TYPE1@ FcPattern * @ARG1@ p
220 @TYPE2@ const char * @ARG2@ object
221 @TYPE3@ int% @ARG3@ n
222 @TYPE4@ int * @ARG4@ i
226 @FUNC+@ FcPatternGetDouble
227 @TYPE1+@ FcPattern * @ARG1+@ p
228 @TYPE2+@ const char * @ARG2+@ object
229 @TYPE3+@ int% @ARG3+@ n
230 @TYPE4+@ double * @ARG4+@ d
234 @FUNC++@ FcPatternGetString
235 @TYPE1++@ FcPattern * @ARG1++@ p
236 @TYPE2++@ const char * @ARG2++@ object
237 @TYPE3++@ int% @ARG3++@ n
238 @TYPE4++@ FcChar8 ** @ARG4++@ s
242 @FUNC+++@ FcPatternGetMatrix
243 @TYPE1+++@ FcPattern * @ARG1+++@ p
244 @TYPE2+++@ const char * @ARG2+++@ object
245 @TYPE3+++@ int% @ARG3+++@ n
246 @TYPE4+++@ FcMatrix ** @ARG4+++@ s
250 @FUNC++++@ FcPatternGetCharSet
251 @TYPE1++++@ FcPattern * @ARG1++++@ p
252 @TYPE2++++@ const char * @ARG2++++@ object
253 @TYPE3++++@ int% @ARG3++++@ n
254 @TYPE4++++@ FcCharSet ** @ARG4++++@ c
258 @FUNC+++++@ FcPatternGetBool
259 @TYPE1+++++@ FcPattern * @ARG1+++++@ p
260 @TYPE2+++++@ const char * @ARG2+++++@ object
261 @TYPE3+++++@ int% @ARG3+++++@ n
262 @TYPE4+++++@ FcBool * @ARG4+++++@ b
266 @FUNC++++++@ FcPatternGetFTFace
267 @TYPE1++++++@ FcPattern * @ARG1++++++@ p
268 @TYPE2++++++@ const char * @ARG2++++++@ object
269 @TYPE3++++++@ int% @ARG3++++++@ n
270 @TYPE4++++++@ FT_Face * @ARG4++++++@ f
273 @RET+++++++@ FcResult
274 @FUNC+++++++@ FcPatternGetLangSet
275 @TYPE1+++++++@ FcPattern * @ARG1+++++++@ p
276 @TYPE2+++++++@ const char * @ARG2+++++++@ object
277 @TYPE3+++++++@ int% @ARG3+++++++@ n
278 @TYPE4+++++++@ FcLangSet ** @ARG4+++++++@ l
281 @RET++++++++@ FcResult
282 @FUNC++++++++@ FcPatternGetRange
283 @TYPE1++++++++@ FcPattern * @ARG1++++++++@ p
284 @TYPE2++++++++@ const char * @ARG2++++++++@ object
285 @TYPE3++++++++@ int% @ARG3++++++++@ n
286 @TYPE4++++++++@ FcRange ** @ARG4++++++++@ r
288 @PURPOSE@ Return a typed value from a pattern
290 These are convenience functions that call FcPatternGet and verify that the
291 returned data is of the expected type. They return FcResultTypeMismatch if
292 this is not the case. Note that these (like FcPatternGet) do not make a
293 copy of any data structure referenced by the return value. Use these
294 in preference to FcPatternGet to provide compile-time typechecking.
296 <function>FcPatternGetRange</function> are available since 2.11.91.
300 @FUNC@ FcPatternBuild
301 @TYPE1@ FcPattern * @ARG1@ pattern
306 @FUNC+@ FcPatternVaBuild
307 @TYPE1+@ FcPattern * @ARG1+@ pattern
308 @TYPE2+@ va_list% @ARG2+@ va
312 @FUNC++@ FcPatternVapBuild
313 @TYPE1++@ FcPattern * @ARG1++@ result
314 @TYPE2++@ FcPattern * @ARG2++@ pattern
315 @TYPE3++@ va_list% @ARG3++@ va
317 @PURPOSE@ Create patterns from arguments
319 Builds a pattern using a list of objects, types and values. Each
320 value to be entered in the pattern is specified with three arguments:
324 Object name, a string describing the property to be added.
325 </para></listitem><listitem><para>
326 Object type, one of the FcType enumerated values
327 </para></listitem><listitem><para>
328 Value, not an FcValue, but the raw type as passed to any of the
329 FcPatternAdd<type> functions. Must match the type of the second
334 The argument list is terminated by a null object name, no object type nor
335 value need be passed for this. The values are added to `pattern', if
336 `pattern' is null, a new pattern is created. In either case, the pattern is
340 pattern = FcPatternBuild (0, FC_FAMILY, FcTypeString, "Times", (char *) 0);
343 FcPatternVaBuild is used when the arguments are already in the form of a
344 varargs value. FcPatternVapBuild is a macro version of FcPatternVaBuild
345 which returns its result directly in the <parameter>result</parameter>
351 @TYPE1@ FcPattern * @ARG1@ p
352 @TYPE2@ const char * @ARG2@ object
353 @PURPOSE@ Delete a property from a pattern
355 Deletes all values associated with the property `object', returning
356 whether the property existed or not.
360 @FUNC@ FcPatternRemove
361 @TYPE1@ FcPattern * @ARG1@ p
362 @TYPE2@ const char * @ARG2@ object
363 @TYPE3@ int% @ARG3@ id
364 @PURPOSE@ Remove one object of the specified type from the pattern
366 Removes the value associated with the property `object' at position `id', returning
367 whether the property existed and had a value at that position or not.
371 @FUNC@ FcPatternPrint
372 @TYPE1@ const FcPattern * @ARG1@ p
373 @PURPOSE@ Print a pattern for debugging
375 Prints an easily readable version of the pattern to stdout. There is
376 no provision for reparsing data in this format, it's just for diagnostics
381 @FUNC@ FcDefaultSubstitute
382 @TYPE1@ FcPattern * @ARG1@ pattern
383 @PURPOSE@ Perform default substitutions in a pattern
385 Supplies default values for underspecified font patterns:
388 Patterns without a specified style or weight are set to Medium
391 Patterns without a specified style or slant are set to Roman
394 Patterns without a specified pixel size are given one computed from any
395 specified point size (default 12), dpi (default 75) and scale (default 1).
402 @TYPE1@ const FcChar8 * @ARG1@ name
403 @PURPOSE@ Parse a pattern string
405 Converts <parameter>name</parameter> from the standard text format described above into a pattern.
410 @TYPE1@ FcPattern * @ARG1@ pat
411 @PURPOSE@ Convert a pattern back into a string that can be parsed
413 Converts the given pattern into the standard text format described above.
414 The return value is not static, but instead refers to newly allocated memory
415 which should be freed by the caller using free().