doc/fcpattern.fncs

   1 /*
   2  * $Id$
   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@
  29 Creates 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@
  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@           FcBool
  61 @FUNC@          FcPatternEqual
  62 @TYPE1@         const FcPattern *               @ARG1@          pa
  63 @TYPE2@         const FcPattern *               @ARG2@          pb
  64 @PURPOSE@       Compare patterns
  65 @DESC@
  66 Returns 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@
  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>.
  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
  93 @TYPE3@         FcValue%                        @ARG3@          value
  94 @TYPE4@         FcBool%                         @ARG4@          append
  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
  98 `object<parameter>.  If `append</parameter> is FcTrue, the value is added at the end of any
  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
 108 @TYPE3@         FcValue%                        @ARG3@          value
 109 @TYPE4@         FcBool%                         @ARG4@          append
 110 @PURPOSE@       Add a value to a pattern with weak binding
 111 @DESC@
 112 FcPatternAddWeak is essentially the same as FcPatternAdd except that any
 113 values 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 char *                    @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@
 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
 184 @TYPE3@         int%                            @ARG3@          id
 185 @TYPE4@         FcValue *                       @ARG4@          v
 186 @PURPOSE@       Return a value from a pattern
 187 @DESC@
 188 Returns in <parameter>v</parameter> the <parameter>id</parameter>'th value
 189 associated with the property <parameter>object</parameter>.
 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
 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++@       char **const                    @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@
 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
 275 @TYPE2+@        va_list%                        @ARG2+@         va
 276 @PURPOSE@       Create patterns from arguments
 277 @DESC@
 278 Builds a pattern using a list of objects, types and values.  Each
 279 value to be entered in the pattern is specified with three arguments:
 280 </para>
 281 <orderedlist>
 282 <listitem><para>
 283 Object name, a string describing the property to be added.
 284 </para></listitem><listitem><para>
 285 Object type, one of the FcType enumerated values
 286 </para></listitem><listitem><para>
 287 Value, not an FcValue, but the raw type as passed to any of the
 288 FcPatternAdd&lt;type&gt; functions.  Must match the type of the second
 289 argument.
 290 </para></listitem>
 291 </orderedlist>
 292 <para>
 293 The argument list is terminated by a null object name, no object type nor
 294 value need be passed for this.  The values are added to `pattern', if
 295 `pattern' is null, a new pattern is created.  In either case, the pattern is
 296 returned. Example
 297 </para>
 298 <programlisting>
 299 pattern = FcPatternBuild (0, FC_FAMILY, FcTypeString, "Times", (char *) 0);
 300 </programlisting>
 301 <para>
 302 FcPatternVaBuild is used when the arguments are already in the form of a
 303 varargs value.
 304 @@
 305
 306 @RET@           FcBool
 307 @FUNC@          FcPatternDel
 308 @TYPE1@         FcPattern *                     @ARG1@          p
 309 @TYPE2@         const char *                    @ARG2@          object
 310 @PURPOSE@       Delete a property from a pattern
 311 @DESC@
 312 Deletes all values associated with the property `object', returning
 313 whether the property existed or not.
 314 @@
 315
 316 @RET@           FcBool
 317 @FUNC@          FcPatternRemove
 318 @TYPE1@         FcPattern *                     @ARG1@          p
 319 @TYPE2@         const char *                    @ARG2@          object
 320 @TYPE3@         int%                            @ARG3@          id
 321 @PURPOSE@       Remove one object of the specified type from the pattern
 322 @DESC@
 323 Removes the value associated with the property `object' at position `id', returning
 324 whether the property existed and had a value at that position or not.
 325 @@
 326
 327 @RET@           void
 328 @FUNC@          FcPatternPrint
 329 @TYPE1@         const FcPattern *               @ARG1@          p
 330 @PURPOSE@       Print a pattern for debugging
 331 @DESC@
 332 Prints an easily readable version of the pattern to stdout.  There is
 333 no provision for reparsing data in this format, it's just for diagnostics
 334 and debugging.
 335 @@
 336
 337 @RET@           void
 338 @FUNC@          FcDefaultSubstitute
 339 @TYPE1@         FcPattern *                     @ARG1@          pattern
 340 @PURPOSE@       Perform default substitutions in a pattern
 341 @DESC@
 342 Supplies default values for underspecified font patterns:
 343 <itemizedlist>
 344 <listitem><para>
 345 Patterns without a specified style or weight are set to Medium
 346 </para></listitem>
 347 <listitem><para>
 348 Patterns without a specified style or slant are set to Roman
 349 </para></listitem>
 350 <listitem><para>
 351 Patterns without a specified pixel size are given one computed from any
 352 specified point size (default 12), dpi (default 75) and scale (default 1).
 353 </para></listitem>
 354 </itemizedlist>
 355 @@
 356
 357 @RET@           FcPattern *
 358 @FUNC@          FcNameParse
 359 @TYPE1@         const char *                    @ARG1@          name
 360 @PURPOSE@       Parse a pattern string
 361 @DESC@
 362 Converts <parameter>name</parameter> from the standard text format described above into a pattern.
 363 @@
 364
 365 @RET@           FcChar8 *
 366 @FUNC@          FcNameUnparse
 367 @TYPE1@         FcPattern *                     @ARG1@          pat
 368 @PURPOSE@       Convert a pattern back into a string that can be parsed
 369 @DESC@
 370 Converts the given pattern into the standard text format described above.
 371 The return value is not static, but instead refers to newly allocated memory
 372 which should be freed by the caller.
 373 @@