fcpattern.fncs revision 953daeba
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@ FcBool 61@FUNC@ FcPatternEqual 62@TYPE1@ const FcPattern * @ARG1@ pa 63@TYPE2@ const FcPattern * @ARG2@ pb 64@PURPOSE@ Compare patterns 65@DESC@ 66Returns 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@ 76Returns whether <parameter>pa</parameter> and <parameter>pb</parameter> have exactly the same values for all of the 77objects 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@ 86Returns a new pattern that only has those objects from 87<parameter>p</parameter> that are in <parameter>os</parameter>. 88If <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@ 97Returns a 32-bit number which is the same for any two patterns which are 98equal. 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@ 109Adds 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 111existing list, otherwise it is inserted at the beginning. `value' is saved 112(with FcValueSave) when inserted into the pattern so that the library 113retains 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@ 124FcPatternAddWeak is essentially the same as FcPatternAdd except that any 125values 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@PROTOTYPE++++++++@ 185@RET++++++++@ FcBool 186@FUNC++++++++@ FcPatternAddRange 187@TYPE1++++++++@ FcPattern * @ARG1++++++++@ p 188@TYPE2++++++++@ const char * @ARG2++++++++@ object 189@TYPE3++++++++@ const FcRange * @ARG3++++++++@ r 190 191@PURPOSE@ Add a typed value to a pattern 192@DESC@ 193These are all convenience functions that insert objects of the specified 194type into the pattern. Use these in preference to FcPatternAdd as they 195will provide compile-time typechecking. These all append values to 196any existing list of values. 197 198<function>FcPatternAddRange</function> are available since 2.11.91. 199@@ 200 201@RET@ FcResult 202@FUNC@ FcPatternGet 203@TYPE1@ FcPattern * @ARG1@ p 204@TYPE2@ const char * @ARG2@ object 205@TYPE3@ int% @ARG3@ id 206@TYPE4@ FcValue * @ARG4@ v 207@PURPOSE@ Return a value from a pattern 208@DESC@ 209Returns in <parameter>v</parameter> the <parameter>id</parameter>'th value 210associated with the property <parameter>object</parameter>. 211The value returned is not a copy, but rather refers to the data stored 212within the pattern directly. Applications must not free this value. 213@@ 214 215@TITLE@ FcPatternGet-Type 216@PROTOTYPE@ 217@RET@ FcResult 218@FUNC@ FcPatternGetInteger 219@TYPE1@ FcPattern * @ARG1@ p 220@TYPE2@ const char * @ARG2@ object 221@TYPE3@ int% @ARG3@ n 222@TYPE4@ int * @ARG4@ i 223 224@PROTOTYPE+@ 225@RET+@ FcResult 226@FUNC+@ FcPatternGetDouble 227@TYPE1+@ FcPattern * @ARG1+@ p 228@TYPE2+@ const char * @ARG2+@ object 229@TYPE3+@ int% @ARG3+@ n 230@TYPE4+@ double * @ARG4+@ d 231 232@PROTOTYPE++@ 233@RET++@ FcResult 234@FUNC++@ FcPatternGetString 235@TYPE1++@ FcPattern * @ARG1++@ p 236@TYPE2++@ const char * @ARG2++@ object 237@TYPE3++@ int% @ARG3++@ n 238@TYPE4++@ FcChar8 ** @ARG4++@ s 239 240@PROTOTYPE+++@ 241@RET+++@ FcResult 242@FUNC+++@ FcPatternGetMatrix 243@TYPE1+++@ FcPattern * @ARG1+++@ p 244@TYPE2+++@ const char * @ARG2+++@ object 245@TYPE3+++@ int% @ARG3+++@ n 246@TYPE4+++@ FcMatrix ** @ARG4+++@ s 247 248@PROTOTYPE++++@ 249@RET++++@ FcResult 250@FUNC++++@ FcPatternGetCharSet 251@TYPE1++++@ FcPattern * @ARG1++++@ p 252@TYPE2++++@ const char * @ARG2++++@ object 253@TYPE3++++@ int% @ARG3++++@ n 254@TYPE4++++@ FcCharSet ** @ARG4++++@ c 255 256@PROTOTYPE+++++@ 257@RET+++++@ FcResult 258@FUNC+++++@ FcPatternGetBool 259@TYPE1+++++@ FcPattern * @ARG1+++++@ p 260@TYPE2+++++@ const char * @ARG2+++++@ object 261@TYPE3+++++@ int% @ARG3+++++@ n 262@TYPE4+++++@ FcBool * @ARG4+++++@ b 263 264@PROTOTYPE++++++@ 265@RET++++++@ FcResult 266@FUNC++++++@ FcPatternGetFTFace 267@TYPE1++++++@ FcPattern * @ARG1++++++@ p 268@TYPE2++++++@ const char * @ARG2++++++@ object 269@TYPE3++++++@ int% @ARG3++++++@ n 270@TYPE4++++++@ FT_Face * @ARG4++++++@ f 271 272@PROTOTYPE+++++++@ 273@RET+++++++@ FcResult 274@FUNC+++++++@ FcPatternGetLangSet 275@TYPE1+++++++@ FcPattern * @ARG1+++++++@ p 276@TYPE2+++++++@ const char * @ARG2+++++++@ object 277@TYPE3+++++++@ int% @ARG3+++++++@ n 278@TYPE4+++++++@ FcLangSet ** @ARG4+++++++@ l 279 280@PROTOTYPE++++++++@ 281@RET++++++++@ FcResult 282@FUNC++++++++@ FcPatternGetRange 283@TYPE1++++++++@ FcPattern * @ARG1++++++++@ p 284@TYPE2++++++++@ const char * @ARG2++++++++@ object 285@TYPE3++++++++@ int% @ARG3++++++++@ n 286@TYPE4++++++++@ FcRange ** @ARG4++++++++@ r 287 288@PURPOSE@ Return a typed value from a pattern 289@DESC@ 290These are convenience functions that call FcPatternGet and verify that the 291returned data is of the expected type. They return FcResultTypeMismatch if 292this is not the case. Note that these (like FcPatternGet) do not make a 293copy of any data structure referenced by the return value. Use these 294in preference to FcPatternGet to provide compile-time typechecking. 295 296<function>FcPatternGetRange</function> are available since 2.11.91. 297@@ 298 299@RET@ FcPattern * 300@FUNC@ FcPatternBuild 301@TYPE1@ FcPattern * @ARG1@ pattern 302@TYPE2@ ... 303 304@PROTOTYPE+@ 305@RET+@ FcPattern * 306@FUNC+@ FcPatternVaBuild 307@TYPE1+@ FcPattern * @ARG1+@ pattern 308@TYPE2+@ va_list% @ARG2+@ va 309 310@PROTOTYPE++@ 311@RET++@ void 312@FUNC++@ FcPatternVapBuild 313@TYPE1++@ FcPattern * @ARG1++@ result 314@TYPE2++@ FcPattern * @ARG2++@ pattern 315@TYPE3++@ va_list% @ARG3++@ va 316 317@PURPOSE@ Create patterns from arguments 318@DESC@ 319Builds a pattern using a list of objects, types and values. Each 320value to be entered in the pattern is specified with three arguments: 321</para> 322<orderedlist> 323<listitem><para> 324Object name, a string describing the property to be added. 325</para></listitem><listitem><para> 326Object type, one of the FcType enumerated values 327</para></listitem><listitem><para> 328Value, not an FcValue, but the raw type as passed to any of the 329FcPatternAdd<type> functions. Must match the type of the second 330argument. 331</para></listitem> 332</orderedlist> 333<para> 334The argument list is terminated by a null object name, no object type nor 335value need be passed for this. The values are added to `pattern', if 336`pattern' is null, a new pattern is created. In either case, the pattern is 337returned. Example 338</para> 339<programlisting> 340pattern = FcPatternBuild (0, FC_FAMILY, FcTypeString, "Times", (char *) 0); 341</programlisting> 342<para> 343FcPatternVaBuild is used when the arguments are already in the form of a 344varargs value. FcPatternVapBuild is a macro version of FcPatternVaBuild 345which returns its result directly in the <parameter>result</parameter> 346variable. 347@@ 348 349@RET@ FcBool 350@FUNC@ FcPatternDel 351@TYPE1@ FcPattern * @ARG1@ p 352@TYPE2@ const char * @ARG2@ object 353@PURPOSE@ Delete a property from a pattern 354@DESC@ 355Deletes all values associated with the property `object', returning 356whether the property existed or not. 357@@ 358 359@RET@ FcBool 360@FUNC@ FcPatternRemove 361@TYPE1@ FcPattern * @ARG1@ p 362@TYPE2@ const char * @ARG2@ object 363@TYPE3@ int% @ARG3@ id 364@PURPOSE@ Remove one object of the specified type from the pattern 365@DESC@ 366Removes the value associated with the property `object' at position `id', returning 367whether the property existed and had a value at that position or not. 368@@ 369 370@RET@ void 371@FUNC@ FcPatternPrint 372@TYPE1@ const FcPattern * @ARG1@ p 373@PURPOSE@ Print a pattern for debugging 374@DESC@ 375Prints an easily readable version of the pattern to stdout. There is 376no provision for reparsing data in this format, it's just for diagnostics 377and debugging. 378@@ 379 380@RET@ void 381@FUNC@ FcDefaultSubstitute 382@TYPE1@ FcPattern * @ARG1@ pattern 383@PURPOSE@ Perform default substitutions in a pattern 384@DESC@ 385Supplies default values for underspecified font patterns: 386<itemizedlist> 387<listitem><para> 388Patterns without a specified style or weight are set to Medium 389</para></listitem> 390<listitem><para> 391Patterns without a specified style or slant are set to Roman 392</para></listitem> 393<listitem><para> 394Patterns without a specified pixel size are given one computed from any 395specified point size (default 12), dpi (default 75) and scale (default 1). 396</para></listitem> 397</itemizedlist> 398@@ 399 400@RET@ FcPattern * 401@FUNC@ FcNameParse 402@TYPE1@ const FcChar8 * @ARG1@ name 403@PURPOSE@ Parse a pattern string 404@DESC@ 405Converts <parameter>name</parameter> from the standard text format described above into a pattern. 406@@ 407 408@RET@ FcChar8 * 409@FUNC@ FcNameUnparse 410@TYPE1@ FcPattern * @ARG1@ pat 411@PURPOSE@ Convert a pattern back into a string that can be parsed 412@DESC@ 413Converts the given pattern into the standard text format described above. 414The return value is not static, but instead refers to newly allocated memory 415which should be freed by the caller using free(). 416@@ 417