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@ int 61 @FUNC@ FcPatternObjectCount 62 @TYPE1@ const FcPattern * @ARG1@ p 63 @PURPOSE@ Returns the number of the object 64 @DESC@ 65 Returns the number of the object <parameter>p</parameter> has. 66 @SINCE@ 2.13.1 67 @@ 68 69 @RET@ FcBool 70 @FUNC@ FcPatternEqual 71 @TYPE1@ const FcPattern * @ARG1@ pa 72 @TYPE2@ const FcPattern * @ARG2@ pb 73 @PURPOSE@ Compare patterns 74 @DESC@ 75 Returns whether <parameter>pa</parameter> and <parameter>pb</parameter> are exactly alike. 76 @@ 77 78 @RET@ FcBool 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 84 @DESC@ 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>. 87 @@ 88 89 @RET@ FcPattern * 90 @FUNC@ FcPatternFilter 91 @TYPE1@ FcPattern * @ARG1@ p 92 @TYPE2@ const FcObjectSet * @ARG2@ os 93 @PURPOSE@ Filter the objects of pattern 94 @DESC@ 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. 99 @@ 100 101 @RET@ FcChar32 102 @FUNC@ FcPatternHash 103 @TYPE1@ const FcPattern * @ARG1@ p 104 @PURPOSE@ Compute a pattern hash value 105 @DESC@ 106 Returns a 32-bit number which is the same for any two patterns which are 107 equal. 108 @@ 109 110 @RET@ FcBool 111 @FUNC@ FcPatternAdd 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 117 @DESC@ 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. 123 @@ 124 125 @RET@ FcBool 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 132 @DESC@ 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>. 135 @@ 136 137 @TITLE@ FcPatternAdd-Type 138 @RET@ FcBool 139 @FUNC@ FcPatternAddInteger 140 @TYPE1@ FcPattern * @ARG1@ p 141 @TYPE2@ const char * @ARG2@ object 142 @TYPE3@ int% @ARG3@ i 143 144 @PROTOTYPE+@ 145 @RET+@ FcBool 146 @FUNC+@ FcPatternAddDouble 147 @TYPE1+@ FcPattern * @ARG1+@ p 148 @TYPE2+@ const char * @ARG2+@ object 149 @TYPE3+@ double% @ARG3+@ d 150 151 @PROTOTYPE++@ 152 @RET++@ FcBool 153 @FUNC++@ FcPatternAddString 154 @TYPE1++@ FcPattern * @ARG1++@ p 155 @TYPE2++@ const char * @ARG2++@ object 156 @TYPE3++@ const FcChar8 * @ARG3++@ s 157 158 @PROTOTYPE+++@ 159 @RET+++@ FcBool 160 @FUNC+++@ FcPatternAddMatrix 161 @TYPE1+++@ FcPattern * @ARG1+++@ p 162 @TYPE2+++@ const char * @ARG2+++@ object 163 @TYPE3+++@ const FcMatrix * @ARG3+++@ m 164 165 @PROTOTYPE++++@ 166 @RET++++@ FcBool 167 @FUNC++++@ FcPatternAddCharSet 168 @TYPE1++++@ FcPattern * @ARG1++++@ p 169 @TYPE2++++@ const char * @ARG2++++@ object 170 @TYPE3++++@ const FcCharSet * @ARG3++++@ c 171 172 @PROTOTYPE+++++@ 173 @RET+++++@ FcBool 174 @FUNC+++++@ FcPatternAddBool 175 @TYPE1+++++@ FcPattern * @ARG1+++++@ p 176 @TYPE2+++++@ const char * @ARG2+++++@ object 177 @TYPE3+++++@ FcBool% @ARG3+++++@ b 178 179 @PROTOTYPE++++++@ 180 @RET++++++@ FcBool 181 @FUNC++++++@ FcPatternAddFTFace 182 @TYPE1++++++@ FcPattern * @ARG1++++++@ p 183 @TYPE2++++++@ const char * @ARG2++++++@ object 184 @TYPE3++++++@ const FT_Face @ARG3++++++@ f 185 186 @PROTOTYPE+++++++@ 187 @RET+++++++@ FcBool 188 @FUNC+++++++@ FcPatternAddLangSet 189 @TYPE1+++++++@ FcPattern * @ARG1+++++++@ p 190 @TYPE2+++++++@ const char * @ARG2+++++++@ object 191 @TYPE3+++++++@ const FcLangSet * @ARG3+++++++@ l 192 193 @PROTOTYPE++++++++@ 194 @RET++++++++@ FcBool 195 @FUNC++++++++@ FcPatternAddRange 196 @TYPE1++++++++@ FcPattern * @ARG1++++++++@ p 197 @TYPE2++++++++@ const char * @ARG2++++++++@ object 198 @TYPE3++++++++@ const FcRange * @ARG3++++++++@ r 199 200 @PURPOSE@ Add a typed value to a pattern 201 @DESC@ 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. 206 207 <function>FcPatternAddRange</function> are available since 2.11.91. 208 @@ 209 210 @RET@ FcResult 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 218 @DESC@ 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. 224 @SINCE@ 2.12.5 225 @@ 226 227 @RET@ FcResult 228 @FUNC@ FcPatternGet 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 234 @DESC@ 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. 239 @@ 240 241 @TITLE@ FcPatternGet-Type 242 @PROTOTYPE@ 243 @RET@ FcResult 244 @FUNC@ FcPatternGetInteger 245 @TYPE1@ FcPattern * @ARG1@ p 246 @TYPE2@ const char * @ARG2@ object 247 @TYPE3@ int% @ARG3@ n 248 @TYPE4@ int * @ARG4@ i 249 250 @PROTOTYPE+@ 251 @RET+@ FcResult 252 @FUNC+@ FcPatternGetDouble 253 @TYPE1+@ FcPattern * @ARG1+@ p 254 @TYPE2+@ const char * @ARG2+@ object 255 @TYPE3+@ int% @ARG3+@ n 256 @TYPE4+@ double * @ARG4+@ d 257 258 @PROTOTYPE++@ 259 @RET++@ FcResult 260 @FUNC++@ FcPatternGetString 261 @TYPE1++@ FcPattern * @ARG1++@ p 262 @TYPE2++@ const char * @ARG2++@ object 263 @TYPE3++@ int% @ARG3++@ n 264 @TYPE4++@ FcChar8 ** @ARG4++@ s 265 266 @PROTOTYPE+++@ 267 @RET+++@ FcResult 268 @FUNC+++@ FcPatternGetMatrix 269 @TYPE1+++@ FcPattern * @ARG1+++@ p 270 @TYPE2+++@ const char * @ARG2+++@ object 271 @TYPE3+++@ int% @ARG3+++@ n 272 @TYPE4+++@ FcMatrix ** @ARG4+++@ s 273 274 @PROTOTYPE++++@ 275 @RET++++@ FcResult 276 @FUNC++++@ FcPatternGetCharSet 277 @TYPE1++++@ FcPattern * @ARG1++++@ p 278 @TYPE2++++@ const char * @ARG2++++@ object 279 @TYPE3++++@ int% @ARG3++++@ n 280 @TYPE4++++@ FcCharSet ** @ARG4++++@ c 281 282 @PROTOTYPE+++++@ 283 @RET+++++@ FcResult 284 @FUNC+++++@ FcPatternGetBool 285 @TYPE1+++++@ FcPattern * @ARG1+++++@ p 286 @TYPE2+++++@ const char * @ARG2+++++@ object 287 @TYPE3+++++@ int% @ARG3+++++@ n 288 @TYPE4+++++@ FcBool * @ARG4+++++@ b 289 290 @PROTOTYPE++++++@ 291 @RET++++++@ FcResult 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 297 298 @PROTOTYPE+++++++@ 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 305 306 @PROTOTYPE++++++++@ 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 313 314 @PURPOSE@ Return a typed value from a pattern 315 @DESC@ 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. 321 322 <function>FcPatternGetRange</function> are available since 2.11.91. 323 @@ 324 325 @RET@ FcPattern * 326 @FUNC@ FcPatternBuild 327 @TYPE1@ FcPattern * @ARG1@ pattern 328 @TYPE2@ ... 329 330 @PROTOTYPE+@ 331 @RET+@ FcPattern * 332 @FUNC+@ FcPatternVaBuild 333 @TYPE1+@ FcPattern * @ARG1+@ pattern 334 @TYPE2+@ va_list% @ARG2+@ va 335 336 @PROTOTYPE++@ 337 @RET++@ void 338 @FUNC++@ FcPatternVapBuild 339 @TYPE1++@ FcPattern * @ARG1++@ result 340 @TYPE2++@ FcPattern * @ARG2++@ pattern 341 @TYPE3++@ va_list% @ARG3++@ va 342 343 @PURPOSE@ Create patterns from arguments 344 @DESC@ 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: 347 </para> 348 <orderedlist> 349 <listitem><para> 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 356 argument. 357 </para></listitem> 358 </orderedlist> 359 <para> 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 363 returned. Example 364 </para> 365 <programlisting> 366 pattern = FcPatternBuild (0, FC_FAMILY, FcTypeString, "Times", (char *) 0); 367 </programlisting> 368 <para> 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> 372 variable. 373 @@ 374 375 @RET@ FcBool 376 @FUNC@ FcPatternDel 377 @TYPE1@ FcPattern * @ARG1@ p 378 @TYPE2@ const char * @ARG2@ object 379 @PURPOSE@ Delete a property from a pattern 380 @DESC@ 381 Deletes all values associated with the property `object', returning 382 whether the property existed or not. 383 @@ 384 385 @RET@ FcBool 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 391 @DESC@ 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. 394 @@ 395 396 @RET@ void 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 401 @DESC@ 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. 405 @SINCE@ 2.13.1 406 @@ 407 408 @RET@ FcBool 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 413 @DESC@ 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. 417 @SINCE@ 2.13.1 418 @@ 419 420 @RET@ FcBool 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 427 @DESC@ 428 Return FcTrue if both <parameter>i1</parameter> and <parameter>i2</parameter> 429 point to same object and contains same values. return FcFalse otherwise. 430 @SINCE@ 2.13.1 431 @@ 432 433 @RET@ FcBool 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 439 @DESC@ 440 Set <parameter>iter</parameter> to point to <parameter>object</parameter> in 441 <parameter>p</parameter> if any and returns FcTrue. returns FcFalse otherwise. 442 @SINCE@ 2.13.1 443 @@ 444 445 @RET@ FcBool 446 @FUNC@ FcPatternIterIsValid 447 @TYPE1@ const FcPattern * @ARG1@ p 448 @TYPE2@ FcPatternIter : @ARG2@ iter 449 @PURPOSE@ Check whether the iterator is valid or not 450 @DESC@ 451 Returns FcTrue if <parameter>iter</parameter> point to the valid entry 452 in <parameter>p</parameter>. returns FcFalse otherwise. 453 @SINCE@ 2.13.1 454 @@ 455 456 @RET@ const char * 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 461 @DESC@ 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. 465 @SINCE@ 2.13.1 466 @@ 467 468 @RET@ int 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 473 @DESC@ 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. 476 @SINCE@ 2.13.1 477 @@ 478 479 @RET@ FcResult 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 487 @DESC@ 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> 490 if given. 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. 493 @SINCE@ 2.13.1 494 @@ 495 496 @RET@ void 497 @FUNC@ FcPatternPrint 498 @TYPE1@ const FcPattern * @ARG1@ p 499 @PURPOSE@ Print a pattern for debugging 500 @DESC@ 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 503 and debugging. 504 @@ 505 506 @RET@ void 507 @FUNC@ FcDefaultSubstitute 508 @TYPE1@ FcPattern * @ARG1@ pattern 509 @PURPOSE@ Perform default substitutions in a pattern 510 @DESC@ 511 Supplies default values for underspecified font patterns: 512 <itemizedlist> 513 <listitem><para> 514 Patterns without a specified style or weight are set to Medium 515 </para></listitem> 516 <listitem><para> 517 Patterns without a specified style or slant are set to Roman 518 </para></listitem> 519 <listitem><para> 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). 522 </para></listitem> 523 </itemizedlist> 524 @@ 525 526 @RET@ FcPattern * 527 @FUNC@ FcNameParse 528 @TYPE1@ const FcChar8 * @ARG1@ name 529 @PURPOSE@ Parse a pattern string 530 @DESC@ 531 Converts <parameter>name</parameter> from the standard text format described above into a pattern. 532 @@ 533 534 @RET@ FcChar8 * 535 @FUNC@ FcNameUnparse 536 @TYPE1@ FcPattern * @ARG1@ pat 537 @PURPOSE@ Convert a pattern back into a string that can be parsed 538 @DESC@ 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(). 542 @@ 543
Indexes created Fri Oct 16 00:26:10 UTC 2026