]>
Commit | Line | Data |
---|---|---|
bfc2dc3a KP |
1 | /* |
2 | * $Id$ | |
3 | * | |
46b51147 | 4 | * Copyright © 2003 Keith Packard |
bfc2dc3a KP |
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 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. | |
15 | * | |
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. | |
23 | */ | |
22671e25 KP |
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 | ||
a190678e KP |
32 | @RET@ FcPattern * |
33 | @FUNC@ FcPatternDuplicate | |
34 | @TYPE1@ 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 | ||
22671e25 KP |
51 | @RET@ void |
52 | @FUNC@ FcPatternDestroy | |
53 | @TYPE1@ FcPattern * @ARG1@ p | |
54 | @PURPOSE@ Destroy a pattern | |
55 | @DESC@ | |
a190678e KP |
56 | Decrement the pattern reference count. If all references are gone, destroys |
57 | the pattern, in the process destroying all related values. | |
22671e25 KP |
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@ | |
2df0c662 | 66 | Returns whether <parameter>pa</parameter> and <parameter>pb</parameter> are exactly alike. |
22671e25 KP |
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@ | |
2df0c662 KP |
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>. | |
22671e25 KP |
78 | @@ |
79 | ||
80 | @RET@ FcChar32 | |
81 | @FUNC@ FcPatternHash | |
82 | @TYPE1@ const FcPattern * @ARG1@ p | |
83 | @PURPOSE@ Compute a pattern hash value | |
84 | @DESC@ | |
85 | Returns a 32-bit number which is the same for any two patterns which are | |
86 | equal. | |
87 | @@ | |
88 | ||
89 | @RET@ FcBool | |
90 | @FUNC@ FcPatternAdd | |
91 | @TYPE1@ FcPattern * @ARG1@ p | |
92 | @TYPE2@ const char * @ARG2@ object | |
61895ed1 KP |
93 | @TYPE3@ FcValue% @ARG3@ value |
94 | @TYPE4@ FcBool% @ARG4@ append | |
22671e25 KP |
95 | @PURPOSE@ Add a value to a pattern |
96 | @DESC@ | |
97 | Adds a single value to the list of values associated with the property named | |
2df0c662 | 98 | `object<parameter>. If `append</parameter> is FcTrue, the value is added at the end of any |
22671e25 KP |
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. | |
102 | @@ | |
103 | ||
104 | @RET@ FcBool | |
105 | @FUNC@ FcPatternAddWeak | |
106 | @TYPE1@ FcPattern * @ARG1@ p | |
107 | @TYPE2@ const char * @ARG2@ object | |
61895ed1 KP |
108 | @TYPE3@ FcValue% @ARG3@ value |
109 | @TYPE4@ FcBool% @ARG4@ append | |
22671e25 KP |
110 | @PURPOSE@ Add a value to a pattern with weak binding |
111 | @DESC@ | |
112 | FcPatternAddWeak is essentially the same as FcPatternAdd except that any | |
2df0c662 | 113 | values added to the list have binding <parameter>weak</parameter> instead of <parameter>strong</parameter>. |
22671e25 KP |
114 | @@ |
115 | ||
116 | @TITLE@ FcPatternAdd-Type | |
117 | @RET@ FcBool | |
118 | @FUNC@ FcPatternAddInteger | |
119 | @TYPE1@ FcPattern * @ARG1@ p | |
120 | @TYPE2@ const char * @ARG2@ object | |
61895ed1 | 121 | @TYPE3@ int% @ARG3@ i |
22671e25 KP |
122 | |
123 | @PROTOTYPE+@ | |
124 | @RET+@ FcBool | |
125 | @FUNC+@ FcPatternAddDouble | |
126 | @TYPE1+@ FcPattern * @ARG1+@ p | |
127 | @TYPE2+@ const char * @ARG2+@ object | |
61895ed1 | 128 | @TYPE3+@ double% @ARG3+@ d |
22671e25 KP |
129 | |
130 | @PROTOTYPE++@ | |
131 | @RET++@ FcBool | |
132 | @FUNC++@ FcPatternAddString | |
133 | @TYPE1++@ FcPattern * @ARG1++@ p | |
134 | @TYPE2++@ const char * @ARG2++@ object | |
f2772d6b | 135 | @TYPE3++@ const FcChar8 * @ARG3++@ s |
22671e25 KP |
136 | |
137 | @PROTOTYPE+++@ | |
138 | @RET+++@ FcBool | |
139 | @FUNC+++@ FcPatternAddMatrix | |
140 | @TYPE1+++@ FcPattern * @ARG1+++@ p | |
141 | @TYPE2+++@ const char * @ARG2+++@ object | |
142 | @TYPE3+++@ const FcMatrix * @ARG3+++@ m | |
143 | ||
144 | @PROTOTYPE++++@ | |
145 | @RET++++@ FcBool | |
146 | @FUNC++++@ FcPatternAddCharSet | |
147 | @TYPE1++++@ FcPattern * @ARG1++++@ p | |
148 | @TYPE2++++@ const char * @ARG2++++@ object | |
149 | @TYPE3++++@ const FcCharSet * @ARG3++++@ c | |
150 | ||
151 | @PROTOTYPE+++++@ | |
152 | @RET+++++@ FcBool | |
153 | @FUNC+++++@ FcPatternAddBool | |
154 | @TYPE1+++++@ FcPattern * @ARG1+++++@ p | |
155 | @TYPE2+++++@ const char * @ARG2+++++@ object | |
61895ed1 | 156 | @TYPE3+++++@ FcBool% @ARG3+++++@ b |
a190678e KP |
157 | |
158 | @PROTOTYPE++++++@ | |
159 | @RET++++++@ FcBool | |
160 | @FUNC++++++@ FcPatternAddFTFace | |
161 | @TYPE1++++++@ FcPattern * @ARG1++++++@ p | |
162 | @TYPE2++++++@ const char * @ARG2++++++@ object | |
163 | @TYPE3++++++@ const FT_Face @ARG3++++++@ f | |
164 | ||
165 | @PROTOTYPE+++++++@ | |
166 | @RET+++++++@ FcBool | |
167 | @FUNC+++++++@ FcPatternAddLangSet | |
168 | @TYPE1+++++++@ FcPattern * @ARG1+++++++@ p | |
169 | @TYPE2+++++++@ const char * @ARG2+++++++@ object | |
170 | @TYPE3+++++++@ const FcLangSet * @ARG3+++++++@ l | |
171 | ||
22671e25 KP |
172 | @PURPOSE@ Add a typed value to a pattern |
173 | @DESC@ | |
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. | |
178 | @@ | |
179 | ||
180 | @RET@ FcResult | |
181 | @FUNC@ FcPatternGet | |
182 | @TYPE1@ FcPattern * @ARG1@ p | |
183 | @TYPE2@ const char * @ARG2@ object | |
61895ed1 | 184 | @TYPE3@ int% @ARG3@ id |
22671e25 KP |
185 | @TYPE4@ FcValue * @ARG4@ v |
186 | @PURPOSE@ Return a value from a pattern | |
187 | @DESC@ | |
0c009d2b KP |
188 | Returns in <parameter>v</parameter> the <parameter>id</parameter>'th value |
189 | associated with the property <parameter>object</parameter>. | |
22671e25 KP |
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. | |
192 | @@ | |
193 | ||
194 | @TITLE@ FcPatternGet-Type | |
195 | @PROTOTYPE@ | |
196 | @RET@ FcResult | |
197 | @FUNC@ FcPatternGetInteger | |
198 | @TYPE1@ FcPattern * @ARG1@ p | |
199 | @TYPE2@ const char * @ARG2@ object | |
61895ed1 | 200 | @TYPE3@ int% @ARG3@ n |
22671e25 KP |
201 | @TYPE4@ int * @ARG4@ i |
202 | ||
203 | @PROTOTYPE+@ | |
204 | @RET+@ FcResult | |
205 | @FUNC+@ FcPatternGetDouble | |
206 | @TYPE1+@ FcPattern * @ARG1+@ p | |
207 | @TYPE2+@ const char * @ARG2+@ object | |
61895ed1 | 208 | @TYPE3+@ int% @ARG3+@ n |
22671e25 KP |
209 | @TYPE4+@ double * @ARG4+@ d |
210 | ||
211 | @PROTOTYPE++@ | |
212 | @RET++@ FcResult | |
213 | @FUNC++@ FcPatternGetString | |
214 | @TYPE1++@ FcPattern * @ARG1++@ p | |
215 | @TYPE2++@ const char * @ARG2++@ object | |
61895ed1 | 216 | @TYPE3++@ int% @ARG3++@ n |
f2772d6b | 217 | @TYPE4++@ FcChar8 ** @ARG4++@ s |
22671e25 KP |
218 | |
219 | @PROTOTYPE+++@ | |
220 | @RET+++@ FcResult | |
221 | @FUNC+++@ FcPatternGetMatrix | |
222 | @TYPE1+++@ FcPattern * @ARG1+++@ p | |
223 | @TYPE2+++@ const char * @ARG2+++@ object | |
61895ed1 | 224 | @TYPE3+++@ int% @ARG3+++@ n |
22671e25 KP |
225 | @TYPE4+++@ FcMatrix ** @ARG4+++@ s |
226 | ||
227 | @PROTOTYPE++++@ | |
228 | @RET++++@ FcResult | |
229 | @FUNC++++@ FcPatternGetCharSet | |
230 | @TYPE1++++@ FcPattern * @ARG1++++@ p | |
231 | @TYPE2++++@ const char * @ARG2++++@ object | |
61895ed1 | 232 | @TYPE3++++@ int% @ARG3++++@ n |
22671e25 KP |
233 | @TYPE4++++@ FcCharSet ** @ARG4++++@ c |
234 | ||
235 | @PROTOTYPE+++++@ | |
236 | @RET+++++@ FcResult | |
237 | @FUNC+++++@ FcPatternGetBool | |
238 | @TYPE1+++++@ FcPattern * @ARG1+++++@ p | |
239 | @TYPE2+++++@ const char * @ARG2+++++@ object | |
61895ed1 | 240 | @TYPE3+++++@ int% @ARG3+++++@ n |
22671e25 | 241 | @TYPE4+++++@ FcBool * @ARG4+++++@ b |
a190678e KP |
242 | |
243 | @PROTOTYPE++++++@ | |
244 | @RET++++++@ FcBool | |
245 | @FUNC++++++@ FcPatternGetFTFace | |
246 | @TYPE1++++++@ FcPattern * @ARG1++++++@ p | |
247 | @TYPE2++++++@ const char * @ARG2++++++@ object | |
248 | @TYPE3++++++@ const FT_Face * @ARG3++++++@ f | |
249 | ||
250 | @PROTOTYPE+++++++@ | |
251 | @RET+++++++@ FcBool | |
252 | @FUNC+++++++@ FcPatternGetLangSet | |
253 | @TYPE1+++++++@ FcPattern * @ARG1+++++++@ p | |
254 | @TYPE2+++++++@ const char * @ARG2+++++++@ object | |
255 | @TYPE3+++++++@ const FcLangSet ** @ARG3+++++++@ l | |
256 | ||
22671e25 KP |
257 | @PURPOSE@ Return a typed value from a pattern |
258 | @DESC@ | |
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. | |
264 | @@ | |
265 | ||
266 | @RET@ FcPattern * | |
267 | @FUNC@ FcPatternBuild | |
268 | @TYPE1@ FcPattern * @ARG1@ orig | |
269 | @TYPE2@ ... | |
270 | ||
271 | @PROTOTYPE+@ | |
272 | @RET+@ FcPattern * | |
273 | @FUNC+@ FcPatternVaBuild | |
274 | @TYPE1+@ FcPattern * @ARG1+@ orig | |
61895ed1 | 275 | @TYPE2+@ va_list% @ARG2+@ va |
1315db01 KP |
276 | |
277 | @PROTOTYPE++@ | |
278 | @RET++@ void | |
279 | @FUNC++@ FcPatternVapBuild | |
280 | @TYPE1++@ FcPattern * @ARG1++@ result | |
281 | @TYPE2++@ FcPattern * @ARG2++@ orig | |
282 | @TYPE3++@ va_list% @ARG3++@ va | |
283 | ||
22671e25 KP |
284 | @PURPOSE@ Create patterns from arguments |
285 | @DESC@ | |
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: | |
8c87b429 | 288 | </para> |
22671e25 KP |
289 | <orderedlist> |
290 | <listitem><para> | |
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 | |
297 | argument. | |
298 | </para></listitem> | |
299 | </orderedlist> | |
300 | <para> | |
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 | |
304 | returned. Example | |
305 | </para> | |
306 | <programlisting> | |
af7a965f | 307 | pattern = FcPatternBuild (0, FC_FAMILY, FcTypeString, "Times", (char *) 0); |
22671e25 KP |
308 | </programlisting> |
309 | <para> | |
310 | FcPatternVaBuild is used when the arguments are already in the form of a | |
1315db01 KP |
311 | varargs value. FcPatternVapBuild is a macro version of FcPatternVaBuild |
312 | which returns its result directly in the <parameter>result</parameter> | |
313 | variable. | |
22671e25 KP |
314 | @@ |
315 | ||
316 | @RET@ FcBool | |
317 | @FUNC@ FcPatternDel | |
318 | @TYPE1@ FcPattern * @ARG1@ p | |
319 | @TYPE2@ const char * @ARG2@ object | |
320 | @PURPOSE@ Delete a property from a pattern | |
321 | @DESC@ | |
322 | Deletes all values associated with the property `object', returning | |
323 | whether the property existed or not. | |
324 | @@ | |
325 | ||
4f27c1c0 KP |
326 | @RET@ FcBool |
327 | @FUNC@ FcPatternRemove | |
328 | @TYPE1@ FcPattern * @ARG1@ p | |
329 | @TYPE2@ const char * @ARG2@ object | |
61895ed1 | 330 | @TYPE3@ int% @ARG3@ id |
4f27c1c0 KP |
331 | @PURPOSE@ Remove one object of the specified type from the pattern |
332 | @DESC@ | |
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. | |
335 | @@ | |
336 | ||
22671e25 KP |
337 | @RET@ void |
338 | @FUNC@ FcPatternPrint | |
339 | @TYPE1@ const FcPattern * @ARG1@ p | |
340 | @PURPOSE@ Print a pattern for debugging | |
341 | @DESC@ | |
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 | |
344 | and debugging. | |
345 | @@ | |
346 | ||
347 | @RET@ void | |
348 | @FUNC@ FcDefaultSubstitute | |
349 | @TYPE1@ FcPattern * @ARG1@ pattern | |
350 | @PURPOSE@ Perform default substitutions in a pattern | |
351 | @DESC@ | |
352 | Supplies default values for underspecified font patterns: | |
353 | <itemizedlist> | |
354 | <listitem><para> | |
355 | Patterns without a specified style or weight are set to Medium | |
356 | </para></listitem> | |
357 | <listitem><para> | |
358 | Patterns without a specified style or slant are set to Roman | |
359 | </para></listitem> | |
360 | <listitem><para> | |
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). | |
363 | </para></listitem> | |
364 | </itemizedlist> | |
365 | @@ | |
366 | ||
367 | @RET@ FcPattern * | |
368 | @FUNC@ FcNameParse | |
f2772d6b | 369 | @TYPE1@ const FcChar8 * @ARG1@ name |
22671e25 KP |
370 | @PURPOSE@ Parse a pattern string |
371 | @DESC@ | |
2df0c662 | 372 | Converts <parameter>name</parameter> from the standard text format described above into a pattern. |
22671e25 KP |
373 | @@ |
374 | ||
375 | @RET@ FcChar8 * | |
376 | @FUNC@ FcNameUnparse | |
377 | @TYPE1@ FcPattern * @ARG1@ pat | |
378 | @PURPOSE@ Convert a pattern back into a string that can be parsed | |
379 | @DESC@ | |
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. | |
383 | @@ |