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.
202 @FUNC@ FcPatternGetWithBinding
203 @TYPE1@ FcPattern * @ARG1@ p
204 @TYPE2@ const char * @ARG2@ object
205 @TYPE3@ int% @ARG3@ id
206 @TYPE4@ FcValue * @ARG4@ v
207 @TYPE5@ FcValueBinding * @ARG5@ b
208 @PURPOSE@ Return a value with binding from a pattern
210 Returns in <parameter>v</parameter> the <parameter>id</parameter>'th value
211 and <parameter>b</parameter> binding for that associated with the property
212 <parameter>object</parameter>.
213 The Value returned is not a copy, but rather refers to the data stored
214 within the pattern directly. Applications must not free this value.
220 @TYPE1@ FcPattern * @ARG1@ p
221 @TYPE2@ const char * @ARG2@ object
222 @TYPE3@ int% @ARG3@ id
223 @TYPE4@ FcValue * @ARG4@ v
224 @PURPOSE@ Return a value from a pattern
226 Returns in <parameter>v</parameter> the <parameter>id</parameter>'th value
227 associated with the property <parameter>object</parameter>.
228 The value returned is not a copy, but rather refers to the data stored
229 within the pattern directly. Applications must not free this value.
232 @TITLE@ FcPatternGet-Type
235 @FUNC@ FcPatternGetInteger
236 @TYPE1@ FcPattern * @ARG1@ p
237 @TYPE2@ const char * @ARG2@ object
238 @TYPE3@ int% @ARG3@ n
239 @TYPE4@ int * @ARG4@ i
243 @FUNC+@ FcPatternGetDouble
244 @TYPE1+@ FcPattern * @ARG1+@ p
245 @TYPE2+@ const char * @ARG2+@ object
246 @TYPE3+@ int% @ARG3+@ n
247 @TYPE4+@ double * @ARG4+@ d
251 @FUNC++@ FcPatternGetString
252 @TYPE1++@ FcPattern * @ARG1++@ p
253 @TYPE2++@ const char * @ARG2++@ object
254 @TYPE3++@ int% @ARG3++@ n
255 @TYPE4++@ FcChar8 ** @ARG4++@ s
259 @FUNC+++@ FcPatternGetMatrix
260 @TYPE1+++@ FcPattern * @ARG1+++@ p
261 @TYPE2+++@ const char * @ARG2+++@ object
262 @TYPE3+++@ int% @ARG3+++@ n
263 @TYPE4+++@ FcMatrix ** @ARG4+++@ s
267 @FUNC++++@ FcPatternGetCharSet
268 @TYPE1++++@ FcPattern * @ARG1++++@ p
269 @TYPE2++++@ const char * @ARG2++++@ object
270 @TYPE3++++@ int% @ARG3++++@ n
271 @TYPE4++++@ FcCharSet ** @ARG4++++@ c
275 @FUNC+++++@ FcPatternGetBool
276 @TYPE1+++++@ FcPattern * @ARG1+++++@ p
277 @TYPE2+++++@ const char * @ARG2+++++@ object
278 @TYPE3+++++@ int% @ARG3+++++@ n
279 @TYPE4+++++@ FcBool * @ARG4+++++@ b
283 @FUNC++++++@ FcPatternGetFTFace
284 @TYPE1++++++@ FcPattern * @ARG1++++++@ p
285 @TYPE2++++++@ const char * @ARG2++++++@ object
286 @TYPE3++++++@ int% @ARG3++++++@ n
287 @TYPE4++++++@ FT_Face * @ARG4++++++@ f
290 @RET+++++++@ FcResult
291 @FUNC+++++++@ FcPatternGetLangSet
292 @TYPE1+++++++@ FcPattern * @ARG1+++++++@ p
293 @TYPE2+++++++@ const char * @ARG2+++++++@ object
294 @TYPE3+++++++@ int% @ARG3+++++++@ n
295 @TYPE4+++++++@ FcLangSet ** @ARG4+++++++@ l
298 @RET++++++++@ FcResult
299 @FUNC++++++++@ FcPatternGetRange
300 @TYPE1++++++++@ FcPattern * @ARG1++++++++@ p
301 @TYPE2++++++++@ const char * @ARG2++++++++@ object
302 @TYPE3++++++++@ int% @ARG3++++++++@ n
303 @TYPE4++++++++@ FcRange ** @ARG4++++++++@ r
305 @PURPOSE@ Return a typed value from a pattern
307 These are convenience functions that call FcPatternGet and verify that the
308 returned data is of the expected type. They return FcResultTypeMismatch if
309 this is not the case. Note that these (like FcPatternGet) do not make a
310 copy of any data structure referenced by the return value. Use these
311 in preference to FcPatternGet to provide compile-time typechecking.
313 <function>FcPatternGetRange</function> are available since 2.11.91.
317 @FUNC@ FcPatternBuild
318 @TYPE1@ FcPattern * @ARG1@ pattern
323 @FUNC+@ FcPatternVaBuild
324 @TYPE1+@ FcPattern * @ARG1+@ pattern
325 @TYPE2+@ va_list% @ARG2+@ va
329 @FUNC++@ FcPatternVapBuild
330 @TYPE1++@ FcPattern * @ARG1++@ result
331 @TYPE2++@ FcPattern * @ARG2++@ pattern
332 @TYPE3++@ va_list% @ARG3++@ va
334 @PURPOSE@ Create patterns from arguments
336 Builds a pattern using a list of objects, types and values. Each
337 value to be entered in the pattern is specified with three arguments:
341 Object name, a string describing the property to be added.
342 </para></listitem><listitem><para>
343 Object type, one of the FcType enumerated values
344 </para></listitem><listitem><para>
345 Value, not an FcValue, but the raw type as passed to any of the
346 FcPatternAdd<type> functions. Must match the type of the second
351 The argument list is terminated by a null object name, no object type nor
352 value need be passed for this. The values are added to `pattern', if
353 `pattern' is null, a new pattern is created. In either case, the pattern is
357 pattern = FcPatternBuild (0, FC_FAMILY, FcTypeString, "Times", (char *) 0);
360 FcPatternVaBuild is used when the arguments are already in the form of a
361 varargs value. FcPatternVapBuild is a macro version of FcPatternVaBuild
362 which returns its result directly in the <parameter>result</parameter>
368 @TYPE1@ FcPattern * @ARG1@ p
369 @TYPE2@ const char * @ARG2@ object
370 @PURPOSE@ Delete a property from a pattern
372 Deletes all values associated with the property `object', returning
373 whether the property existed or not.
377 @FUNC@ FcPatternRemove
378 @TYPE1@ FcPattern * @ARG1@ p
379 @TYPE2@ const char * @ARG2@ object
380 @TYPE3@ int% @ARG3@ id
381 @PURPOSE@ Remove one object of the specified type from the pattern
383 Removes the value associated with the property `object' at position `id', returning
384 whether the property existed and had a value at that position or not.
388 @FUNC@ FcPatternPrint
389 @TYPE1@ const FcPattern * @ARG1@ p
390 @PURPOSE@ Print a pattern for debugging
392 Prints an easily readable version of the pattern to stdout. There is
393 no provision for reparsing data in this format, it's just for diagnostics
398 @FUNC@ FcDefaultSubstitute
399 @TYPE1@ FcPattern * @ARG1@ pattern
400 @PURPOSE@ Perform default substitutions in a pattern
402 Supplies default values for underspecified font patterns:
405 Patterns without a specified style or weight are set to Medium
408 Patterns without a specified style or slant are set to Roman
411 Patterns without a specified pixel size are given one computed from any
412 specified point size (default 12), dpi (default 75) and scale (default 1).
419 @TYPE1@ const FcChar8 * @ARG1@ name
420 @PURPOSE@ Parse a pattern string
422 Converts <parameter>name</parameter> from the standard text format described above into a pattern.
427 @TYPE1@ FcPattern * @ARG1@ pat
428 @PURPOSE@ Convert a pattern back into a string that can be parsed
430 Converts the given pattern into the standard text format described above.
431 The return value is not static, but instead refers to newly allocated memory
432 which should be freed by the caller using free().