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.
61 @FUNC@ FcPatternObjectCount
62 @TYPE1@ const FcPattern * @ARG1@ p
63 @PURPOSE@ Returns the number of the object
65 Returns the number of the object <parameter>p</parameter> has.
71 @TYPE1@ const FcPattern * @ARG1@ pa
72 @TYPE2@ const FcPattern * @ARG2@ pb
73 @PURPOSE@ Compare patterns
75 Returns whether <parameter>pa</parameter> and <parameter>pb</parameter> are exactly alike.
79 @FUNC@ FcPatternEqualSubset
80 @TYPE1@ const FcPattern * @ARG1@ pa
81 @TYPE2@ const FcPattern * @ARG2@ pb
82 @TYPE3@ const FcObjectSet * @ARG3@ os
83 @PURPOSE@ Compare portions of patterns
85 Returns whether <parameter>pa</parameter> and <parameter>pb</parameter> have exactly the same values for all of the
86 objects in <parameter>os</parameter>.
90 @FUNC@ FcPatternFilter
91 @TYPE1@ FcPattern * @ARG1@ p
92 @TYPE2@ const FcObjectSet * @ARG2@ os
93 @PURPOSE@ Filter the objects of pattern
95 Returns a new pattern that only has those objects from
96 <parameter>p</parameter> that are in <parameter>os</parameter>.
97 If <parameter>os</parameter> is NULL, a duplicate of
98 <parameter>p</parameter> is returned.
103 @TYPE1@ const FcPattern * @ARG1@ p
104 @PURPOSE@ Compute a pattern hash value
106 Returns a 32-bit number which is the same for any two patterns which are
112 @TYPE1@ FcPattern * @ARG1@ p
113 @TYPE2@ const char * @ARG2@ object
114 @TYPE3@ FcValue% @ARG3@ value
115 @TYPE4@ FcBool% @ARG4@ append
116 @PURPOSE@ Add a value to a pattern
118 Adds a single value to the list of values associated with the property named
119 `object<parameter>. If `append</parameter> is FcTrue, the value is added at the end of any
120 existing list, otherwise it is inserted at the beginning. `value' is saved
121 (with FcValueSave) when inserted into the pattern so that the library
122 retains no reference to any application-supplied data structure.
126 @FUNC@ FcPatternAddWeak
127 @TYPE1@ FcPattern * @ARG1@ p
128 @TYPE2@ const char * @ARG2@ object
129 @TYPE3@ FcValue% @ARG3@ value
130 @TYPE4@ FcBool% @ARG4@ append
131 @PURPOSE@ Add a value to a pattern with weak binding
133 FcPatternAddWeak is essentially the same as FcPatternAdd except that any
134 values added to the list have binding <parameter>weak</parameter> instead of <parameter>strong</parameter>.
137 @TITLE@ FcPatternAdd-Type
139 @FUNC@ FcPatternAddInteger
140 @TYPE1@ FcPattern * @ARG1@ p
141 @TYPE2@ const char * @ARG2@ object
142 @TYPE3@ int% @ARG3@ i
146 @FUNC+@ FcPatternAddDouble
147 @TYPE1+@ FcPattern * @ARG1+@ p
148 @TYPE2+@ const char * @ARG2+@ object
149 @TYPE3+@ double% @ARG3+@ d
153 @FUNC++@ FcPatternAddString
154 @TYPE1++@ FcPattern * @ARG1++@ p
155 @TYPE2++@ const char * @ARG2++@ object
156 @TYPE3++@ const FcChar8 * @ARG3++@ s
160 @FUNC+++@ FcPatternAddMatrix
161 @TYPE1+++@ FcPattern * @ARG1+++@ p
162 @TYPE2+++@ const char * @ARG2+++@ object
163 @TYPE3+++@ const FcMatrix * @ARG3+++@ m
167 @FUNC++++@ FcPatternAddCharSet
168 @TYPE1++++@ FcPattern * @ARG1++++@ p
169 @TYPE2++++@ const char * @ARG2++++@ object
170 @TYPE3++++@ const FcCharSet * @ARG3++++@ c
174 @FUNC+++++@ FcPatternAddBool
175 @TYPE1+++++@ FcPattern * @ARG1+++++@ p
176 @TYPE2+++++@ const char * @ARG2+++++@ object
177 @TYPE3+++++@ FcBool% @ARG3+++++@ b
181 @FUNC++++++@ FcPatternAddFTFace
182 @TYPE1++++++@ FcPattern * @ARG1++++++@ p
183 @TYPE2++++++@ const char * @ARG2++++++@ object
184 @TYPE3++++++@ const FT_Face @ARG3++++++@ f
188 @FUNC+++++++@ FcPatternAddLangSet
189 @TYPE1+++++++@ FcPattern * @ARG1+++++++@ p
190 @TYPE2+++++++@ const char * @ARG2+++++++@ object
191 @TYPE3+++++++@ const FcLangSet * @ARG3+++++++@ l
195 @FUNC++++++++@ FcPatternAddRange
196 @TYPE1++++++++@ FcPattern * @ARG1++++++++@ p
197 @TYPE2++++++++@ const char * @ARG2++++++++@ object
198 @TYPE3++++++++@ const FcRange * @ARG3++++++++@ r
200 @PURPOSE@ Add a typed value to a pattern
202 These are all convenience functions that insert objects of the specified
203 type into the pattern. Use these in preference to FcPatternAdd as they
204 will provide compile-time typechecking. These all append values to
205 any existing list of values.
207 <function>FcPatternAddRange</function> are available since 2.11.91.
211 @FUNC@ FcPatternGetWithBinding
212 @TYPE1@ FcPattern * @ARG1@ p
213 @TYPE2@ const char * @ARG2@ object
214 @TYPE3@ int% @ARG3@ id
215 @TYPE4@ FcValue * @ARG4@ v
216 @TYPE5@ FcValueBinding * @ARG5@ b
217 @PURPOSE@ Return a value with binding from a pattern
219 Returns in <parameter>v</parameter> the <parameter>id</parameter>'th value
220 and <parameter>b</parameter> binding for that associated with the property
221 <parameter>object</parameter>.
222 The Value returned is not a copy, but rather refers to the data stored
223 within the pattern directly. Applications must not free this value.
229 @TYPE1@ FcPattern * @ARG1@ p
230 @TYPE2@ const char * @ARG2@ object
231 @TYPE3@ int% @ARG3@ id
232 @TYPE4@ FcValue * @ARG4@ v
233 @PURPOSE@ Return a value from a pattern
235 Returns in <parameter>v</parameter> the <parameter>id</parameter>'th value
236 associated with the property <parameter>object</parameter>.
237 The value returned is not a copy, but rather refers to the data stored
238 within the pattern directly. Applications must not free this value.
241 @TITLE@ FcPatternGet-Type
244 @FUNC@ FcPatternGetInteger
245 @TYPE1@ FcPattern * @ARG1@ p
246 @TYPE2@ const char * @ARG2@ object
247 @TYPE3@ int% @ARG3@ n
248 @TYPE4@ int * @ARG4@ i
252 @FUNC+@ FcPatternGetDouble
253 @TYPE1+@ FcPattern * @ARG1+@ p
254 @TYPE2+@ const char * @ARG2+@ object
255 @TYPE3+@ int% @ARG3+@ n
256 @TYPE4+@ double * @ARG4+@ d
260 @FUNC++@ FcPatternGetString
261 @TYPE1++@ FcPattern * @ARG1++@ p
262 @TYPE2++@ const char * @ARG2++@ object
263 @TYPE3++@ int% @ARG3++@ n
264 @TYPE4++@ FcChar8 ** @ARG4++@ s
268 @FUNC+++@ FcPatternGetMatrix
269 @TYPE1+++@ FcPattern * @ARG1+++@ p
270 @TYPE2+++@ const char * @ARG2+++@ object
271 @TYPE3+++@ int% @ARG3+++@ n
272 @TYPE4+++@ FcMatrix ** @ARG4+++@ s
276 @FUNC++++@ FcPatternGetCharSet
277 @TYPE1++++@ FcPattern * @ARG1++++@ p
278 @TYPE2++++@ const char * @ARG2++++@ object
279 @TYPE3++++@ int% @ARG3++++@ n
280 @TYPE4++++@ FcCharSet ** @ARG4++++@ c
284 @FUNC+++++@ FcPatternGetBool
285 @TYPE1+++++@ FcPattern * @ARG1+++++@ p
286 @TYPE2+++++@ const char * @ARG2+++++@ object
287 @TYPE3+++++@ int% @ARG3+++++@ n
288 @TYPE4+++++@ FcBool * @ARG4+++++@ b
292 @FUNC++++++@ FcPatternGetFTFace
293 @TYPE1++++++@ FcPattern * @ARG1++++++@ p
294 @TYPE2++++++@ const char * @ARG2++++++@ object
295 @TYPE3++++++@ int% @ARG3++++++@ n
296 @TYPE4++++++@ FT_Face * @ARG4++++++@ f
299 @RET+++++++@ FcResult
300 @FUNC+++++++@ FcPatternGetLangSet
301 @TYPE1+++++++@ FcPattern * @ARG1+++++++@ p
302 @TYPE2+++++++@ const char * @ARG2+++++++@ object
303 @TYPE3+++++++@ int% @ARG3+++++++@ n
304 @TYPE4+++++++@ FcLangSet ** @ARG4+++++++@ l
307 @RET++++++++@ FcResult
308 @FUNC++++++++@ FcPatternGetRange
309 @TYPE1++++++++@ FcPattern * @ARG1++++++++@ p
310 @TYPE2++++++++@ const char * @ARG2++++++++@ object
311 @TYPE3++++++++@ int% @ARG3++++++++@ n
312 @TYPE4++++++++@ FcRange ** @ARG4++++++++@ r
314 @PURPOSE@ Return a typed value from a pattern
316 These are convenience functions that call FcPatternGet and verify that the
317 returned data is of the expected type. They return FcResultTypeMismatch if
318 this is not the case. Note that these (like FcPatternGet) do not make a
319 copy of any data structure referenced by the return value. Use these
320 in preference to FcPatternGet to provide compile-time typechecking.
322 <function>FcPatternGetRange</function> are available since 2.11.91.
326 @FUNC@ FcPatternBuild
327 @TYPE1@ FcPattern * @ARG1@ pattern
332 @FUNC+@ FcPatternVaBuild
333 @TYPE1+@ FcPattern * @ARG1+@ pattern
334 @TYPE2+@ va_list% @ARG2+@ va
338 @FUNC++@ FcPatternVapBuild
339 @TYPE1++@ FcPattern * @ARG1++@ result
340 @TYPE2++@ FcPattern * @ARG2++@ pattern
341 @TYPE3++@ va_list% @ARG3++@ va
343 @PURPOSE@ Create patterns from arguments
345 Builds a pattern using a list of objects, types and values. Each
346 value to be entered in the pattern is specified with three arguments:
350 Object name, a string describing the property to be added.
351 </para></listitem><listitem><para>
352 Object type, one of the FcType enumerated values
353 </para></listitem><listitem><para>
354 Value, not an FcValue, but the raw type as passed to any of the
355 FcPatternAdd<type> functions. Must match the type of the second
360 The argument list is terminated by a null object name, no object type nor
361 value need be passed for this. The values are added to `pattern', if
362 `pattern' is null, a new pattern is created. In either case, the pattern is
366 pattern = FcPatternBuild (0, FC_FAMILY, FcTypeString, "Times", (char *) 0);
369 FcPatternVaBuild is used when the arguments are already in the form of a
370 varargs value. FcPatternVapBuild is a macro version of FcPatternVaBuild
371 which returns its result directly in the <parameter>result</parameter>
377 @TYPE1@ FcPattern * @ARG1@ p
378 @TYPE2@ const char * @ARG2@ object
379 @PURPOSE@ Delete a property from a pattern
381 Deletes all values associated with the property `object', returning
382 whether the property existed or not.
386 @FUNC@ FcPatternRemove
387 @TYPE1@ FcPattern * @ARG1@ p
388 @TYPE2@ const char * @ARG2@ object
389 @TYPE3@ int% @ARG3@ id
390 @PURPOSE@ Remove one object of the specified type from the pattern
392 Removes the value associated with the property `object' at position `id', returning
393 whether the property existed and had a value at that position or not.
397 @FUNC@ FcPatternIterStart
398 @TYPE1@ const FcPattern * @ARG1@ p
399 @TYPE2@ FcPatternIter * @ARG2@ iter
400 @PURPOSE@ Initialize the iterator with the first iterator in the pattern
402 Initialize <parameter>iter</parameter> with the first iterator in <parameter>p</parameter>.
403 If there are no objects in <parameter>p</parameter>, <parameter>iter</parameter>
404 will not have any valid data.
409 @FUNC@ FcPatternIterNext
410 @TYPE1@ const FcPattern * @ARG1@ p
411 @TYPE2@ FcPatternIter * @ARG2@ iter
412 @PURPUSE@ Set the iterator to point to the next object in the pattern
414 Set <parameter>iter</parameter> to point to the next object in <parameter>p</parameter>
415 and returns FcTrue if <parameter>iter</parameter> has been changed to the next object.
416 returns FcFalse otherwise.
421 @FUNC@ FcPatternIterEqual
422 @TYPE1@ const FcPattern * @ARG1@ p1
423 @TYPE2@ FcPatternIter * @ARG2@ i1
424 @TYPE3@ const FcPattern * @ARG3@ p2
425 @TYPE4@ FcPatternIter * @ARG4@ i2
426 @PURPOSE@ Compare iterators
428 Return FcTrue if both <parameter>i1</parameter> and <parameter>i2</parameter>
429 point to same object and contains same values. return FcFalse otherwise.
434 @FUNC@ FcPatternFindIter
435 @TYPE1@ const FcPattern * @ARG1@ p
436 @TYPE2@ FcPatternIter * @ARG2@ iter
437 @TYPE3@ const char * @ARG3@ object
438 @PURPOSE@ Set the iterator to point to the object in the pattern
440 Set <parameter>iter</parameter> to point to <parameter>object</parameter> in
441 <parameter>p</parameter> if any and returns FcTrue. returns FcFalse otherwise.
446 @FUNC@ FcPatternIterIsValid
447 @TYPE1@ const FcPattern * @ARG1@ p
448 @TYPE2@ FcPatternIter : @ARG2@ iter
449 @PURPOSE@ Check whether the iterator is valid or not
451 Returns FcTrue if <parameter>iter</parameter> point to the valid entry
452 in <parameter>p</parameter>. returns FcFalse otherwise.
457 @FUNC@ FcPatternIterGetObject
458 @TYPE1@ const FcPattern * @ARG1@ p
459 @TYPE2@ FcPatternIter * @ARG2@ iter
460 @PURPOSE@ Returns an object name which the iterator point to
462 Returns an object name in <parameter>p</parameter> which
463 <parameter>iter</parameter> point to. returns NULL if
464 <parameter>iter</parameter> isn't valid.
469 @FUNC@ FcPatternIterValueCount
470 @TYPE1@ const FcPattern * @ARG1@ p
471 @TYPE2@ FcPatternIter * @ARG2@ iter
472 @PURPOSE@ Returns the number of the values which the iterator point to
474 Returns the number of the values in the object which <parameter>iter</parameter>
475 point to. if <parameter>iter</parameter> isn't valid, returns 0.
480 @FUNC@ FcPatternIterGetValue
481 @TYPE1@ const FcPattern * @ARG1@ p
482 @TYPE2@ FcPatternIter * @ARG2@ iter
483 @TYPE3@ int @ARG3@ id
484 @TYPE4@ FcValue * @ARG4@ v
485 @TYPE5@ FcValueBinding * @ARG5@ b
486 @PURPOSE@ Returns a value which the iterator point to
488 Returns in <parameter>v</parameter> the <parameter>id</parameter>'th value
489 which <parameter>iter</parameter> point to. also binding to <parameter>b</parameter>
491 The value returned is not a copy, but rather refers to the data stored
492 within the pattern directly. Applications must not free this value.
497 @FUNC@ FcPatternPrint
498 @TYPE1@ const FcPattern * @ARG1@ p
499 @PURPOSE@ Print a pattern for debugging
501 Prints an easily readable version of the pattern to stdout. There is
502 no provision for reparsing data in this format, it's just for diagnostics
507 @FUNC@ FcDefaultSubstitute
508 @TYPE1@ FcPattern * @ARG1@ pattern
509 @PURPOSE@ Perform default substitutions in a pattern
511 Supplies default values for underspecified font patterns:
514 Patterns without a specified style or weight are set to Medium
517 Patterns without a specified style or slant are set to Roman
520 Patterns without a specified pixel size are given one computed from any
521 specified point size (default 12), dpi (default 75) and scale (default 1).
528 @TYPE1@ const FcChar8 * @ARG1@ name
529 @PURPOSE@ Parse a pattern string
531 Converts <parameter>name</parameter> from the standard text format described above into a pattern.
536 @TYPE1@ FcPattern * @ARG1@ pat
537 @PURPOSE@ Convert a pattern back into a string that can be parsed
539 Converts the given pattern into the standard text format described above.
540 The return value is not static, but instead refers to newly allocated memory
541 which should be freed by the caller using free().