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@ 29Creates 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@ 37Copy a pattern, returning a new pattern that matches 38<parameter>p</parameter>. Each pattern may be modified without affecting the 39other. 40@@ 41 42@RET@ void 43@FUNC@ FcPatternReference 44@TYPE1@ FcPattern * @ARG1@ p 45@PURPOSE@ Increment pattern reference count 46@DESC@ 47Add another reference to <parameter>p</parameter>. Patterns are freed only 48when 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@ 56Decrement the pattern reference count. If all references are gone, destroys 57the 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@ 65Returns 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@ 75Returns 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@ 85Returns whether <parameter>pa</parameter> and <parameter>pb</parameter> have exactly the same values for all of the 86objects 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@ 95Returns a new pattern that only has those objects from 96<parameter>p</parameter> that are in <parameter>os</parameter>. 97If <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@ 106Returns a 32-bit number which is the same for any two patterns which are 107equal. 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@ 118Adds 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 120existing list, otherwise it is inserted at the beginning. `value' is saved 121(with FcValueSave) when inserted into the pattern so that the library 122retains 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@ 133FcPatternAddWeak is essentially the same as FcPatternAdd except that any 134values 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@ 202These are all convenience functions that insert objects of the specified 203type into the pattern. Use these in preference to FcPatternAdd as they 204will provide compile-time typechecking. These all append values to 205any 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@ 219Returns in <parameter>v</parameter> the <parameter>id</parameter>'th value 220and <parameter>b</parameter> binding for that associated with the property 221<parameter>object</parameter>. 222The Value returned is not a copy, but rather refers to the data stored 223within 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@ 235Returns in <parameter>v</parameter> the <parameter>id</parameter>'th value 236associated with the property <parameter>object</parameter>. 237The value returned is not a copy, but rather refers to the data stored 238within 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@ 316These are convenience functions that call FcPatternGet and verify that the 317returned data is of the expected type. They return FcResultTypeMismatch if 318this is not the case. Note that these (like FcPatternGet) do not make a 319copy of any data structure referenced by the return value. Use these 320in 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@ 345Builds a pattern using a list of objects, types and values. Each 346value to be entered in the pattern is specified with three arguments: 347</para> 348<orderedlist> 349<listitem><para> 350Object name, a string describing the property to be added. 351</para></listitem><listitem><para> 352Object type, one of the FcType enumerated values 353</para></listitem><listitem><para> 354Value, not an FcValue, but the raw type as passed to any of the 355FcPatternAdd<type> functions. Must match the type of the second 356argument. 357</para></listitem> 358</orderedlist> 359<para> 360The argument list is terminated by a null object name, no object type nor 361value 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 363returned. Example 364</para> 365<programlisting> 366pattern = FcPatternBuild (0, FC_FAMILY, FcTypeString, "Times", (char *) 0); 367</programlisting> 368<para> 369FcPatternVaBuild is used when the arguments are already in the form of a 370varargs value. FcPatternVapBuild is a macro version of FcPatternVaBuild 371which returns its result directly in the <parameter>result</parameter> 372variable. 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@ 381Deletes all values associated with the property `object', returning 382whether 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@ 392Removes the value associated with the property `object' at position `id', returning 393whether 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@ 402Initialize <parameter>iter</parameter> with the first iterator in <parameter>p</parameter>. 403If there are no objects in <parameter>p</parameter>, <parameter>iter</parameter> 404will 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@ 414Set <parameter>iter</parameter> to point to the next object in <parameter>p</parameter> 415and returns FcTrue if <parameter>iter</parameter> has been changed to the next object. 416returns 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@ 428Return FcTrue if both <parameter>i1</parameter> and <parameter>i2</parameter> 429point 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@ 440Set <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@ 451Returns FcTrue if <parameter>iter</parameter> point to the valid entry 452in <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@ 462Returns 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@ 474Returns the number of the values in the object which <parameter>iter</parameter> 475point 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@ 488Returns in <parameter>v</parameter> the <parameter>id</parameter>'th value 489which <parameter>iter</parameter> point to. also binding to <parameter>b</parameter> 490if given. 491The value returned is not a copy, but rather refers to the data stored 492within 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@ 501Prints an easily readable version of the pattern to stdout. There is 502no provision for reparsing data in this format, it's just for diagnostics 503and debugging. 504@@ 505 506@RET@ void 507@FUNC@ FcDefaultSubstitute 508@TYPE1@ FcPattern * @ARG1@ pattern 509@PURPOSE@ Perform default substitutions in a pattern 510@DESC@ 511Supplies default values for underspecified font patterns: 512<itemizedlist> 513<listitem><para> 514Patterns without a specified style or weight are set to Medium 515</para></listitem> 516<listitem><para> 517Patterns without a specified style or slant are set to Roman 518</para></listitem> 519<listitem><para> 520Patterns without a specified pixel size are given one computed from any 521specified 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@ 531Converts <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@ 539Converts the given pattern into the standard text format described above. 540The return value is not static, but instead refers to newly allocated memory 541which should be freed by the caller using free(). 542@@ 543