]>
Commit | Line | Data |
---|---|---|
1 | /* | |
2 | * fontconfig/doc/fcpattern.fncs | |
3 | * | |
4 | * Copyright © 2003 Keith Packard | |
5 | * | |
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. | |
15 | * | |
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. | |
23 | */ | |
24 | @RET@ FcPattern * | |
25 | @FUNC@ FcPatternCreate | |
26 | @TYPE1@ void | |
27 | @PURPOSE@ Create a pattern | |
28 | @DESC@ | |
29 | Creates a pattern with no properties; used to build patterns from scratch. | |
30 | @@ | |
31 | ||
32 | @RET@ FcPattern * | |
33 | @FUNC@ FcPatternDuplicate | |
34 | @TYPE1@ const FcPattern * @ARG1@ p | |
35 | @PURPOSE@ Copy a pattern | |
36 | @DESC@ | |
37 | Copy a pattern, returning a new pattern that matches | |
38 | <parameter>p</parameter>. Each pattern may be modified without affecting the | |
39 | other. | |
40 | @@ | |
41 | ||
42 | @RET@ void | |
43 | @FUNC@ FcPatternReference | |
44 | @TYPE1@ FcPattern * @ARG1@ p | |
45 | @PURPOSE@ Increment pattern reference count | |
46 | @DESC@ | |
47 | Add another reference to <parameter>p</parameter>. Patterns are freed only | |
48 | when the reference count reaches zero. | |
49 | @@ | |
50 | ||
51 | @RET@ void | |
52 | @FUNC@ FcPatternDestroy | |
53 | @TYPE1@ FcPattern * @ARG1@ p | |
54 | @PURPOSE@ Destroy a pattern | |
55 | @DESC@ | |
56 | Decrement the pattern reference count. If all references are gone, destroys | |
57 | the pattern, in the process destroying all related values. | |
58 | @@ | |
59 | ||
60 | @RET@ FcBool | |
61 | @FUNC@ FcPatternEqual | |
62 | @TYPE1@ const FcPattern * @ARG1@ pa | |
63 | @TYPE2@ const FcPattern * @ARG2@ pb | |
64 | @PURPOSE@ Compare patterns | |
65 | @DESC@ | |
66 | Returns whether <parameter>pa</parameter> and <parameter>pb</parameter> are exactly alike. | |
67 | @@ | |
68 | ||
69 | @RET@ FcBool | |
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 | |
75 | @DESC@ | |
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>. | |
78 | @@ | |
79 | ||
80 | @RET@ FcPattern * | |
81 | @FUNC@ FcPatternFilter | |
82 | @TYPE1@ FcPattern * @ARG1@ p | |
83 | @TYPE2@ const FcObjectSet * @ARG1@ os | |
84 | @PURPOSE@ Filter the objects of pattern | |
85 | @DESC@ | |
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. | |
90 | @@ | |
91 | ||
92 | @RET@ FcChar32 | |
93 | @FUNC@ FcPatternHash | |
94 | @TYPE1@ const FcPattern * @ARG1@ p | |
95 | @PURPOSE@ Compute a pattern hash value | |
96 | @DESC@ | |
97 | Returns a 32-bit number which is the same for any two patterns which are | |
98 | equal. | |
99 | @@ | |
100 | ||
101 | @RET@ FcBool | |
102 | @FUNC@ FcPatternAdd | |
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 | |
108 | @DESC@ | |
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. | |
114 | @@ | |
115 | ||
116 | @RET@ FcBool | |
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 | |
123 | @DESC@ | |
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>. | |
126 | @@ | |
127 | ||
128 | @TITLE@ FcPatternAdd-Type | |
129 | @RET@ FcBool | |
130 | @FUNC@ FcPatternAddInteger | |
131 | @TYPE1@ FcPattern * @ARG1@ p | |
132 | @TYPE2@ const char * @ARG2@ object | |
133 | @TYPE3@ int% @ARG3@ i | |
134 | ||
135 | @PROTOTYPE+@ | |
136 | @RET+@ FcBool | |
137 | @FUNC+@ FcPatternAddDouble | |
138 | @TYPE1+@ FcPattern * @ARG1+@ p | |
139 | @TYPE2+@ const char * @ARG2+@ object | |
140 | @TYPE3+@ double% @ARG3+@ d | |
141 | ||
142 | @PROTOTYPE++@ | |
143 | @RET++@ FcBool | |
144 | @FUNC++@ FcPatternAddString | |
145 | @TYPE1++@ FcPattern * @ARG1++@ p | |
146 | @TYPE2++@ const char * @ARG2++@ object | |
147 | @TYPE3++@ const FcChar8 * @ARG3++@ s | |
148 | ||
149 | @PROTOTYPE+++@ | |
150 | @RET+++@ FcBool | |
151 | @FUNC+++@ FcPatternAddMatrix | |
152 | @TYPE1+++@ FcPattern * @ARG1+++@ p | |
153 | @TYPE2+++@ const char * @ARG2+++@ object | |
154 | @TYPE3+++@ const FcMatrix * @ARG3+++@ m | |
155 | ||
156 | @PROTOTYPE++++@ | |
157 | @RET++++@ FcBool | |
158 | @FUNC++++@ FcPatternAddCharSet | |
159 | @TYPE1++++@ FcPattern * @ARG1++++@ p | |
160 | @TYPE2++++@ const char * @ARG2++++@ object | |
161 | @TYPE3++++@ const FcCharSet * @ARG3++++@ c | |
162 | ||
163 | @PROTOTYPE+++++@ | |
164 | @RET+++++@ FcBool | |
165 | @FUNC+++++@ FcPatternAddBool | |
166 | @TYPE1+++++@ FcPattern * @ARG1+++++@ p | |
167 | @TYPE2+++++@ const char * @ARG2+++++@ object | |
168 | @TYPE3+++++@ FcBool% @ARG3+++++@ b | |
169 | ||
170 | @PROTOTYPE++++++@ | |
171 | @RET++++++@ FcBool | |
172 | @FUNC++++++@ FcPatternAddFTFace | |
173 | @TYPE1++++++@ FcPattern * @ARG1++++++@ p | |
174 | @TYPE2++++++@ const char * @ARG2++++++@ object | |
175 | @TYPE3++++++@ const FT_Face @ARG3++++++@ f | |
176 | ||
177 | @PROTOTYPE+++++++@ | |
178 | @RET+++++++@ FcBool | |
179 | @FUNC+++++++@ FcPatternAddLangSet | |
180 | @TYPE1+++++++@ FcPattern * @ARG1+++++++@ p | |
181 | @TYPE2+++++++@ const char * @ARG2+++++++@ object | |
182 | @TYPE3+++++++@ const FcLangSet * @ARG3+++++++@ l | |
183 | ||
184 | @PURPOSE@ Add a typed value to a pattern | |
185 | @DESC@ | |
186 | These are all convenience functions that insert objects of the specified | |
187 | type into the pattern. Use these in preference to FcPatternAdd as they | |
188 | will provide compile-time typechecking. These all append values to | |
189 | any existing list of values. | |
190 | @@ | |
191 | ||
192 | @RET@ FcResult | |
193 | @FUNC@ FcPatternGet | |
194 | @TYPE1@ FcPattern * @ARG1@ p | |
195 | @TYPE2@ const char * @ARG2@ object | |
196 | @TYPE3@ int% @ARG3@ id | |
197 | @TYPE4@ FcValue * @ARG4@ v | |
198 | @PURPOSE@ Return a value from a pattern | |
199 | @DESC@ | |
200 | Returns in <parameter>v</parameter> the <parameter>id</parameter>'th value | |
201 | associated with the property <parameter>object</parameter>. | |
202 | The value returned is not a copy, but rather refers to the data stored | |
203 | within the pattern directly. Applications must not free this value. | |
204 | @@ | |
205 | ||
206 | @TITLE@ FcPatternGet-Type | |
207 | @PROTOTYPE@ | |
208 | @RET@ FcResult | |
209 | @FUNC@ FcPatternGetInteger | |
210 | @TYPE1@ FcPattern * @ARG1@ p | |
211 | @TYPE2@ const char * @ARG2@ object | |
212 | @TYPE3@ int% @ARG3@ n | |
213 | @TYPE4@ int * @ARG4@ i | |
214 | ||
215 | @PROTOTYPE+@ | |
216 | @RET+@ FcResult | |
217 | @FUNC+@ FcPatternGetDouble | |
218 | @TYPE1+@ FcPattern * @ARG1+@ p | |
219 | @TYPE2+@ const char * @ARG2+@ object | |
220 | @TYPE3+@ int% @ARG3+@ n | |
221 | @TYPE4+@ double * @ARG4+@ d | |
222 | ||
223 | @PROTOTYPE++@ | |
224 | @RET++@ FcResult | |
225 | @FUNC++@ FcPatternGetString | |
226 | @TYPE1++@ FcPattern * @ARG1++@ p | |
227 | @TYPE2++@ const char * @ARG2++@ object | |
228 | @TYPE3++@ int% @ARG3++@ n | |
229 | @TYPE4++@ FcChar8 ** @ARG4++@ s | |
230 | ||
231 | @PROTOTYPE+++@ | |
232 | @RET+++@ FcResult | |
233 | @FUNC+++@ FcPatternGetMatrix | |
234 | @TYPE1+++@ FcPattern * @ARG1+++@ p | |
235 | @TYPE2+++@ const char * @ARG2+++@ object | |
236 | @TYPE3+++@ int% @ARG3+++@ n | |
237 | @TYPE4+++@ FcMatrix ** @ARG4+++@ s | |
238 | ||
239 | @PROTOTYPE++++@ | |
240 | @RET++++@ FcResult | |
241 | @FUNC++++@ FcPatternGetCharSet | |
242 | @TYPE1++++@ FcPattern * @ARG1++++@ p | |
243 | @TYPE2++++@ const char * @ARG2++++@ object | |
244 | @TYPE3++++@ int% @ARG3++++@ n | |
245 | @TYPE4++++@ FcCharSet ** @ARG4++++@ c | |
246 | ||
247 | @PROTOTYPE+++++@ | |
248 | @RET+++++@ FcResult | |
249 | @FUNC+++++@ FcPatternGetBool | |
250 | @TYPE1+++++@ FcPattern * @ARG1+++++@ p | |
251 | @TYPE2+++++@ const char * @ARG2+++++@ object | |
252 | @TYPE3+++++@ int% @ARG3+++++@ n | |
253 | @TYPE4+++++@ FcBool * @ARG4+++++@ b | |
254 | ||
255 | @PROTOTYPE++++++@ | |
256 | @RET++++++@ FcResult | |
257 | @FUNC++++++@ FcPatternGetFTFace | |
258 | @TYPE1++++++@ FcPattern * @ARG1++++++@ p | |
259 | @TYPE2++++++@ const char * @ARG2++++++@ object | |
260 | @TYPE3+++++@ int% @ARG3+++++@ n | |
261 | @TYPE3++++++@ FT_Face * @ARG3++++++@ f | |
262 | ||
263 | @PROTOTYPE+++++++@ | |
264 | @RET+++++++@ FcResult | |
265 | @FUNC+++++++@ FcPatternGetLangSet | |
266 | @TYPE1+++++++@ FcPattern * @ARG1+++++++@ p | |
267 | @TYPE2+++++++@ const char * @ARG2+++++++@ object | |
268 | @TYPE3+++++@ int% @ARG3+++++@ n | |
269 | @TYPE3+++++++@ FcLangSet ** @ARG3+++++++@ l | |
270 | ||
271 | @PURPOSE@ Return a typed value from a pattern | |
272 | @DESC@ | |
273 | These are convenience functions that call FcPatternGet and verify that the | |
274 | returned data is of the expected type. They return FcResultTypeMismatch if | |
275 | this is not the case. Note that these (like FcPatternGet) do not make a | |
276 | copy of any data structure referenced by the return value. Use these | |
277 | in preference to FcPatternGet to provide compile-time typechecking. | |
278 | @@ | |
279 | ||
280 | @RET@ FcPattern * | |
281 | @FUNC@ FcPatternBuild | |
282 | @TYPE1@ FcPattern * @ARG1@ pattern | |
283 | @TYPE2@ ... | |
284 | ||
285 | @PROTOTYPE+@ | |
286 | @RET+@ FcPattern * | |
287 | @FUNC+@ FcPatternVaBuild | |
288 | @TYPE1+@ FcPattern * @ARG1+@ pattern | |
289 | @TYPE2+@ va_list% @ARG2+@ va | |
290 | ||
291 | @PROTOTYPE++@ | |
292 | @RET++@ void | |
293 | @FUNC++@ FcPatternVapBuild | |
294 | @TYPE1++@ FcPattern * @ARG1++@ result | |
295 | @TYPE2++@ FcPattern * @ARG2++@ pattern | |
296 | @TYPE3++@ va_list% @ARG3++@ va | |
297 | ||
298 | @PURPOSE@ Create patterns from arguments | |
299 | @DESC@ | |
300 | Builds a pattern using a list of objects, types and values. Each | |
301 | value to be entered in the pattern is specified with three arguments: | |
302 | </para> | |
303 | <orderedlist> | |
304 | <listitem><para> | |
305 | Object name, a string describing the property to be added. | |
306 | </para></listitem><listitem><para> | |
307 | Object type, one of the FcType enumerated values | |
308 | </para></listitem><listitem><para> | |
309 | Value, not an FcValue, but the raw type as passed to any of the | |
310 | FcPatternAdd<type> functions. Must match the type of the second | |
311 | argument. | |
312 | </para></listitem> | |
313 | </orderedlist> | |
314 | <para> | |
315 | The argument list is terminated by a null object name, no object type nor | |
316 | value need be passed for this. The values are added to `pattern', if | |
317 | `pattern' is null, a new pattern is created. In either case, the pattern is | |
318 | returned. Example | |
319 | </para> | |
320 | <programlisting> | |
321 | pattern = FcPatternBuild (0, FC_FAMILY, FcTypeString, "Times", (char *) 0); | |
322 | </programlisting> | |
323 | <para> | |
324 | FcPatternVaBuild is used when the arguments are already in the form of a | |
325 | varargs value. FcPatternVapBuild is a macro version of FcPatternVaBuild | |
326 | which returns its result directly in the <parameter>result</parameter> | |
327 | variable. | |
328 | @@ | |
329 | ||
330 | @RET@ FcBool | |
331 | @FUNC@ FcPatternDel | |
332 | @TYPE1@ FcPattern * @ARG1@ p | |
333 | @TYPE2@ const char * @ARG2@ object | |
334 | @PURPOSE@ Delete a property from a pattern | |
335 | @DESC@ | |
336 | Deletes all values associated with the property `object', returning | |
337 | whether the property existed or not. | |
338 | @@ | |
339 | ||
340 | @RET@ FcBool | |
341 | @FUNC@ FcPatternRemove | |
342 | @TYPE1@ FcPattern * @ARG1@ p | |
343 | @TYPE2@ const char * @ARG2@ object | |
344 | @TYPE3@ int% @ARG3@ id | |
345 | @PURPOSE@ Remove one object of the specified type from the pattern | |
346 | @DESC@ | |
347 | Removes the value associated with the property `object' at position `id', returning | |
348 | whether the property existed and had a value at that position or not. | |
349 | @@ | |
350 | ||
351 | @RET@ void | |
352 | @FUNC@ FcPatternPrint | |
353 | @TYPE1@ const FcPattern * @ARG1@ p | |
354 | @PURPOSE@ Print a pattern for debugging | |
355 | @DESC@ | |
356 | Prints an easily readable version of the pattern to stdout. There is | |
357 | no provision for reparsing data in this format, it's just for diagnostics | |
358 | and debugging. | |
359 | @@ | |
360 | ||
361 | @RET@ void | |
362 | @FUNC@ FcDefaultSubstitute | |
363 | @TYPE1@ FcPattern * @ARG1@ pattern | |
364 | @PURPOSE@ Perform default substitutions in a pattern | |
365 | @DESC@ | |
366 | Supplies default values for underspecified font patterns: | |
367 | <itemizedlist> | |
368 | <listitem><para> | |
369 | Patterns without a specified style or weight are set to Medium | |
370 | </para></listitem> | |
371 | <listitem><para> | |
372 | Patterns without a specified style or slant are set to Roman | |
373 | </para></listitem> | |
374 | <listitem><para> | |
375 | Patterns without a specified pixel size are given one computed from any | |
376 | specified point size (default 12), dpi (default 75) and scale (default 1). | |
377 | </para></listitem> | |
378 | </itemizedlist> | |
379 | @@ | |
380 | ||
381 | @RET@ FcPattern * | |
382 | @FUNC@ FcNameParse | |
383 | @TYPE1@ const FcChar8 * @ARG1@ name | |
384 | @PURPOSE@ Parse a pattern string | |
385 | @DESC@ | |
386 | Converts <parameter>name</parameter> from the standard text format described above into a pattern. | |
387 | @@ | |
388 | ||
389 | @RET@ FcChar8 * | |
390 | @FUNC@ FcNameUnparse | |
391 | @TYPE1@ FcPattern * @ARG1@ pat | |
392 | @PURPOSE@ Convert a pattern back into a string that can be parsed | |
393 | @DESC@ | |
394 | Converts the given pattern into the standard text format described above. | |
395 | The return value is not static, but instead refers to newly allocated memory | |
396 | which should be freed by the caller using free(). | |
397 | @@ |