doc/fcpattern.fncs

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