fcpattern.fncs revision 2c393a42
1/* 2 * $Id: fcpattern.fncs,v 1.1.1.1 2008/07/30 01:24:21 mrg Exp $ 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 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 */ 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@ 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@ FcChar32 81@FUNC@ FcPatternHash 82@TYPE1@ const FcPattern * @ARG1@ p 83@PURPOSE@ Compute a pattern hash value 84@DESC@ 85Returns a 32-bit number which is the same for any two patterns which are 86equal. 87@@ 88 89@RET@ FcBool 90@FUNC@ FcPatternAdd 91@TYPE1@ FcPattern * @ARG1@ p 92@TYPE2@ const char * @ARG2@ object 93@TYPE3@ FcValue% @ARG3@ value 94@TYPE4@ FcBool% @ARG4@ append 95@PURPOSE@ Add a value to a pattern 96@DESC@ 97Adds a single value to the list of values associated with the property named 98`object<parameter>. If `append</parameter> is FcTrue, the value is added at the end of any 99existing list, otherwise it is inserted at the begining. `value' is saved 100(with FcValueSave) when inserted into the pattern so that the library 101retains 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 108@TYPE3@ FcValue% @ARG3@ value 109@TYPE4@ FcBool% @ARG4@ append 110@PURPOSE@ Add a value to a pattern with weak binding 111@DESC@ 112FcPatternAddWeak is essentially the same as FcPatternAdd except that any 113values added to the list have binding <parameter>weak</parameter> instead of <parameter>strong</parameter>. 114@@ 115 116@TITLE@ FcPatternAdd-Type 117@RET@ FcBool 118@FUNC@ FcPatternAddInteger 119@TYPE1@ FcPattern * @ARG1@ p 120@TYPE2@ const char * @ARG2@ object 121@TYPE3@ int% @ARG3@ i 122 123@PROTOTYPE+@ 124@RET+@ FcBool 125@FUNC+@ FcPatternAddDouble 126@TYPE1+@ FcPattern * @ARG1+@ p 127@TYPE2+@ const char * @ARG2+@ object 128@TYPE3+@ double% @ARG3+@ d 129 130@PROTOTYPE++@ 131@RET++@ FcBool 132@FUNC++@ FcPatternAddString 133@TYPE1++@ FcPattern * @ARG1++@ p 134@TYPE2++@ const char * @ARG2++@ object 135@TYPE3++@ const FcChar8 * @ARG3++@ s 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 156@TYPE3+++++@ FcBool% @ARG3+++++@ b 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 172@PURPOSE@ Add a typed value to a pattern 173@DESC@ 174These are all convenience functions that insert objects of the specified 175type into the pattern. Use these in preference to FcPatternAdd as they 176will provide compile-time typechecking. These all append values to 177any existing list of values. 178@@ 179 180@RET@ FcResult 181@FUNC@ FcPatternGet 182@TYPE1@ FcPattern * @ARG1@ p 183@TYPE2@ const char * @ARG2@ object 184@TYPE3@ int% @ARG3@ id 185@TYPE4@ FcValue * @ARG4@ v 186@PURPOSE@ Return a value from a pattern 187@DESC@ 188Returns in <parameter>v</parameter> the <parameter>id</parameter>'th value 189associated with the property <parameter>object</parameter>. 190The value returned is not a copy, but rather refers to the data stored 191within 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 200@TYPE3@ int% @ARG3@ n 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 208@TYPE3+@ int% @ARG3+@ n 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 216@TYPE3++@ int% @ARG3++@ n 217@TYPE4++@ FcChar8 ** @ARG4++@ s 218 219@PROTOTYPE+++@ 220@RET+++@ FcResult 221@FUNC+++@ FcPatternGetMatrix 222@TYPE1+++@ FcPattern * @ARG1+++@ p 223@TYPE2+++@ const char * @ARG2+++@ object 224@TYPE3+++@ int% @ARG3+++@ n 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 232@TYPE3++++@ int% @ARG3++++@ n 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 240@TYPE3+++++@ int% @ARG3+++++@ n 241@TYPE4+++++@ FcBool * @ARG4+++++@ b 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 257@PURPOSE@ Return a typed value from a pattern 258@DESC@ 259These are convenience functions that call FcPatternGet and verify that the 260returned data is of the expected type. They return FcResultTypeMismatch if 261this is not the case. Note that these (like FcPatternGet) do not make a 262copy of any data structure referenced by the return value. Use these 263in 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 275@TYPE2+@ va_list% @ARG2+@ va 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 284@PURPOSE@ Create patterns from arguments 285@DESC@ 286Builds a pattern using a list of objects, types and values. Each 287value to be entered in the pattern is specified with three arguments: 288</para> 289<orderedlist> 290<listitem><para> 291Object name, a string describing the property to be added. 292</para></listitem><listitem><para> 293Object type, one of the FcType enumerated values 294</para></listitem><listitem><para> 295Value, not an FcValue, but the raw type as passed to any of the 296FcPatternAdd<type> functions. Must match the type of the second 297argument. 298</para></listitem> 299</orderedlist> 300<para> 301The argument list is terminated by a null object name, no object type nor 302value 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 304returned. Example 305</para> 306<programlisting> 307pattern = FcPatternBuild (0, FC_FAMILY, FcTypeString, "Times", (char *) 0); 308</programlisting> 309<para> 310FcPatternVaBuild is used when the arguments are already in the form of a 311varargs value. FcPatternVapBuild is a macro version of FcPatternVaBuild 312which returns its result directly in the <parameter>result</parameter> 313variable. 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@ 322Deletes all values associated with the property `object', returning 323whether the property existed or not. 324@@ 325 326@RET@ FcBool 327@FUNC@ FcPatternRemove 328@TYPE1@ FcPattern * @ARG1@ p 329@TYPE2@ const char * @ARG2@ object 330@TYPE3@ int% @ARG3@ id 331@PURPOSE@ Remove one object of the specified type from the pattern 332@DESC@ 333Removes the value associated with the property `object' at position `id', returning 334whether the property existed and had a value at that position or not. 335@@ 336 337@RET@ void 338@FUNC@ FcPatternPrint 339@TYPE1@ const FcPattern * @ARG1@ p 340@PURPOSE@ Print a pattern for debugging 341@DESC@ 342Prints an easily readable version of the pattern to stdout. There is 343no provision for reparsing data in this format, it's just for diagnostics 344and debugging. 345@@ 346 347@RET@ void 348@FUNC@ FcDefaultSubstitute 349@TYPE1@ FcPattern * @ARG1@ pattern 350@PURPOSE@ Perform default substitutions in a pattern 351@DESC@ 352Supplies default values for underspecified font patterns: 353<itemizedlist> 354<listitem><para> 355Patterns without a specified style or weight are set to Medium 356</para></listitem> 357<listitem><para> 358Patterns without a specified style or slant are set to Roman 359</para></listitem> 360<listitem><para> 361Patterns without a specified pixel size are given one computed from any 362specified point size (default 12), dpi (default 75) and scale (default 1). 363</para></listitem> 364</itemizedlist> 365@@ 366 367@RET@ FcPattern * 368@FUNC@ FcNameParse 369@TYPE1@ const FcChar8 * @ARG1@ name 370@PURPOSE@ Parse a pattern string 371@DESC@ 372Converts <parameter>name</parameter> from the standard text format described above into a pattern. 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@ 380Converts the given pattern into the standard text format described above. 381The return value is not static, but instead refers to newly allocated memory 382which should be freed by the caller. 383@@ 384