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@           void
  33 @FUNC@          FcPatternDestroy
  34 @TYPE1@         FcPattern *                     @ARG1@           p
  35 @PURPOSE@       Destroy a pattern
  36 @DESC@
  37 Destroys a pattern, in the process destroying all related values.
  38 @@
  39
  40 @RET@           FcBool
  41 @FUNC@          FcPatternEqual
  42 @TYPE1@         const FcPattern *               @ARG1@          pa
  43 @TYPE2@         const FcPattern *               @ARG2@          pb
  44 @PURPOSE@       Compare patterns
  45 @DESC@
  46 Returns whether 'pa' and 'pb' are exactly alike.
  47 @@
  48
  49 @RET@           FcBool
  50 @FUNC@          FcPatternEqualSubset
  51 @TYPE1@         const FcPattern *               @ARG1@          pa
  52 @TYPE2@         const FcPattern *               @ARG2@          pb
  53 @TYPE3@         const FcObjectSet *             @ARG3@          os
  54 @PURPOSE@       Compare portions of patterns
  55 @DESC@
  56 Returns whether 'pa' and 'pb' have exactly the same values for all of the
  57 objects in 'os'.
  58 @@
  59
  60 @RET@           FcChar32
  61 @FUNC@          FcPatternHash
  62 @TYPE1@         const FcPattern *               @ARG1@          p
  63 @PURPOSE@       Compute a pattern hash value
  64 @DESC@
  65 Returns a 32-bit number which is the same for any two patterns which are
  66 equal.
  67 @@
  68
  69 @RET@           FcBool
  70 @FUNC@          FcPatternAdd
  71 @TYPE1@         FcPattern *                     @ARG1@          p
  72 @TYPE2@         const char *                    @ARG2@          object
  73 @TYPE3@         FcValue                         @ARG3@          value
  74 @TYPE4@         FcBool                          @ARG4@          append
  75 @PURPOSE@       Add a value to a pattern
  76 @DESC@
  77 Adds a single value to the list of values associated with the property named
  78 `object'.  If `append' is FcTrue, the value is added at the end of any
  79 existing list, otherwise it is inserted at the begining.  `value' is saved
  80 (with FcValueSave) when inserted into the pattern so that the library
  81 retains no reference to any application-supplied data structure.
  82 @@
  83
  84 @RET@           FcBool
  85 @FUNC@          FcPatternAddWeak
  86 @TYPE1@         FcPattern *                     @ARG1@          p
  87 @TYPE2@         const char *                    @ARG2@          object
  88 @TYPE3@         FcValue                         @ARG3@          value
  89 @TYPE4@         FcBool                          @ARG4@          append
  90 @PURPOSE@       Add a value to a pattern with weak binding
  91 @DESC@
  92 FcPatternAddWeak is essentially the same as FcPatternAdd except that any
  93 values added to the list have binding 'weak' instead of 'strong'.
  94 @@
  95
  96 @TITLE@         FcPatternAdd-Type
  97 @RET@           FcBool
  98 @FUNC@          FcPatternAddInteger
  99 @TYPE1@         FcPattern *                     @ARG1@          p
 100 @TYPE2@         const char *                    @ARG2@          object
 101 @TYPE3@         int                             @ARG3@          i
 102
 103 @PROTOTYPE+@
 104 @RET+@          FcBool
 105 @FUNC+@         FcPatternAddDouble
 106 @TYPE1+@        FcPattern *                     @ARG1+@         p
 107 @TYPE2+@        const char *                    @ARG2+@         object
 108 @TYPE3+@        double                          @ARG3+@         d
 109
 110 @PROTOTYPE++@
 111 @RET++@         FcBool
 112 @FUNC++@        FcPatternAddString
 113 @TYPE1++@       FcPattern *                     @ARG1++@        p
 114 @TYPE2++@       const char *                    @ARG2++@        object
 115 @TYPE3++@       const char *                    @ARG3++@        s
 116
 117 @PROTOTYPE+++@
 118 @RET+++@        FcBool
 119 @FUNC+++@       FcPatternAddMatrix
 120 @TYPE1+++@      FcPattern *                     @ARG1+++@       p
 121 @TYPE2+++@      const char *                    @ARG2+++@       object
 122 @TYPE3+++@      const FcMatrix *                @ARG3+++@       m
 123
 124 @PROTOTYPE++++@
 125 @RET++++@       FcBool
 126 @FUNC++++@      FcPatternAddCharSet
 127 @TYPE1++++@     FcPattern *                     @ARG1++++@      p
 128 @TYPE2++++@     const char *                    @ARG2++++@      object
 129 @TYPE3++++@     const FcCharSet *               @ARG3++++@      c
 130
 131 @PROTOTYPE+++++@
 132 @RET+++++@      FcBool
 133 @FUNC+++++@     FcPatternAddBool
 134 @TYPE1+++++@    FcPattern *                     @ARG1+++++@     p
 135 @TYPE2+++++@    const char *                    @ARG2+++++@     object
 136 @TYPE3+++++@    FcBool                          @ARG3+++++@     b
 137 @PURPOSE@       Add a typed value to a pattern
 138 @DESC@
 139 These are all convenience functions that insert objects of the specified
 140 type into the pattern.  Use these in preference to FcPatternAdd as they
 141 will provide compile-time typechecking.  These all append values to
 142 any existing list of values.
 143 @@
 144
 145 @RET@           FcResult
 146 @FUNC@          FcPatternGet
 147 @TYPE1@         FcPattern *                     @ARG1@          p
 148 @TYPE2@         const char *                    @ARG2@          object
 149 @TYPE3@         int                             @ARG3@          id
 150 @TYPE4@         FcValue *                       @ARG4@          v
 151 @PURPOSE@       Return a value from a pattern
 152 @DESC@
 153 Returns in `v' the `id'th value associated with the property `object'.
 154 The value returned is not a copy, but rather refers to the data stored
 155 within the pattern directly.  Applications must not free this value.
 156 @@
 157
 158 @TITLE@         FcPatternGet-Type
 159 @PROTOTYPE@
 160 @RET@           FcResult
 161 @FUNC@          FcPatternGetInteger
 162 @TYPE1@         FcPattern *                     @ARG1@          p
 163 @TYPE2@         const char *                    @ARG2@          object
 164 @TYPE3@         int                             @ARG3@          n
 165 @TYPE4@         int *                           @ARG4@          i
 166
 167 @PROTOTYPE+@
 168 @RET+@          FcResult
 169 @FUNC+@         FcPatternGetDouble
 170 @TYPE1+@        FcPattern *                     @ARG1+@         p
 171 @TYPE2+@        const char *                    @ARG2+@         object
 172 @TYPE3+@        int                             @ARG3+@         n
 173 @TYPE4+@        double *                        @ARG4+@         d
 174
 175 @PROTOTYPE++@
 176 @RET++@         FcResult
 177 @FUNC++@        FcPatternGetString
 178 @TYPE1++@       FcPattern *                     @ARG1++@        p
 179 @TYPE2++@       const char *                    @ARG2++@        object
 180 @TYPE3++@       int                             @ARG3++@        n
 181 @TYPE4++@       char **const                    @ARG4++@        s
 182
 183 @PROTOTYPE+++@
 184 @RET+++@        FcResult
 185 @FUNC+++@       FcPatternGetMatrix
 186 @TYPE1+++@      FcPattern *                     @ARG1+++@       p
 187 @TYPE2+++@      const char *                    @ARG2+++@       object
 188 @TYPE3+++@      int                             @ARG3+++@       n
 189 @TYPE4+++@      FcMatrix **                     @ARG4+++@       s
 190
 191 @PROTOTYPE++++@
 192 @RET++++@       FcResult
 193 @FUNC++++@      FcPatternGetCharSet
 194 @TYPE1++++@     FcPattern *                     @ARG1++++@      p
 195 @TYPE2++++@     const char *                    @ARG2++++@      object
 196 @TYPE3++++@     int                             @ARG3++++@      n
 197 @TYPE4++++@     FcCharSet **                    @ARG4++++@      c
 198
 199 @PROTOTYPE+++++@
 200 @RET+++++@      FcResult
 201 @FUNC+++++@     FcPatternGetBool
 202 @TYPE1+++++@    FcPattern *                     @ARG1+++++@     p
 203 @TYPE2+++++@    const char *                    @ARG2+++++@     object
 204 @TYPE3+++++@    int                             @ARG3+++++@     n
 205 @TYPE4+++++@    FcBool *                        @ARG4+++++@     b
 206 @PURPOSE@       Return a typed value from a pattern
 207 @DESC@
 208 These are convenience functions that call FcPatternGet and verify that the
 209 returned data is of the expected type. They return FcResultTypeMismatch if
 210 this is not the case.  Note that these (like FcPatternGet) do not make a
 211 copy of any data structure referenced by the return value.  Use these
 212 in preference to FcPatternGet to provide compile-time typechecking.
 213 @@
 214
 215 @RET@           FcPattern *
 216 @FUNC@          FcPatternBuild
 217 @TYPE1@         FcPattern *                     @ARG1@          orig
 218 @TYPE2@         ...
 219
 220 @PROTOTYPE+@
 221 @RET+@          FcPattern *
 222 @FUNC+@         FcPatternVaBuild
 223 @TYPE1+@        FcPattern *                     @ARG1+@         orig
 224 @TYPE2+@        va_list                         @ARG2+@         va
 225 @PURPOSE@       Create patterns from arguments
 226 @DESC@
 227 Builds a pattern using a list of objects, types and values.  Each
 228 value to be entered in the pattern is specified with three arguments:
 229 <orderedlist>
 230 <listitem><para>
 231 Object name, a string describing the property to be added.
 232 </para></listitem><listitem><para>
 233 Object type, one of the FcType enumerated values
 234 </para></listitem><listitem><para>
 235 Value, not an FcValue, but the raw type as passed to any of the
 236 FcPatternAdd&lt;type&gt; functions.  Must match the type of the second
 237 argument.
 238 </para></listitem>
 239 </orderedlist>
 240 <para>
 241 The argument list is terminated by a null object name, no object type nor
 242 value need be passed for this.  The values are added to `pattern', if
 243 `pattern' is null, a new pattern is created.  In either case, the pattern is
 244 returned. Example
 245 </para>
 246 <programlisting>
 247 pattern = FcPatternBuild (0, FC_FAMILY, FtTypeString, "Times", (char *) 0);
 248 </programlisting>
 249 <para>
 250 FcPatternVaBuild is used when the arguments are already in the form of a
 251 varargs value.
 252 @@
 253
 254 @RET@           FcBool
 255 @FUNC@          FcPatternDel
 256 @TYPE1@         FcPattern *                     @ARG1@          p
 257 @TYPE2@         const char *                    @ARG2@          object
 258 @PURPOSE@       Delete a property from a pattern
 259 @DESC@
 260 Deletes all values associated with the property `object', returning
 261 whether the property existed or not.
 262 @@
 263
 264 @RET@           void
 265 @FUNC@          FcPatternPrint
 266 @TYPE1@         const FcPattern *               @ARG1@          p
 267 @PURPOSE@       Print a pattern for debugging
 268 @DESC@
 269 Prints an easily readable version of the pattern to stdout.  There is
 270 no provision for reparsing data in this format, it's just for diagnostics
 271 and debugging.
 272 @@
 273
 274 @RET@           void
 275 @FUNC@          FcDefaultSubstitute
 276 @TYPE1@         FcPattern *                     @ARG1@          pattern
 277 @PURPOSE@       Perform default substitutions in a pattern
 278 @DESC@
 279 Supplies default values for underspecified font patterns:
 280 <itemizedlist>
 281 <listitem><para>
 282 Patterns without a specified style or weight are set to Medium
 283 </para></listitem>
 284 <listitem><para>
 285 Patterns without a specified style or slant are set to Roman
 286 </para></listitem>
 287 <listitem><para>
 288 Patterns without a specified pixel size are given one computed from any
 289 specified point size (default 12), dpi (default 75) and scale (default 1).
 290 </para></listitem>
 291 </itemizedlist>
 292 @@
 293
 294 @RET@           FcPattern *
 295 @FUNC@          FcNameParse
 296 @TYPE1@         const char *                    @ARG1@          name
 297 @PURPOSE@       Parse a pattern string
 298 @DESC@
 299 Converts 'name' from the standard text format described above into a pattern.
 300 @@
 301
 302 @RET@           FcChar8 *
 303 @FUNC@          FcNameUnparse
 304 @TYPE1@         FcPattern *                     @ARG1@          pat
 305 @PURPOSE@       Convert a pattern back into a string that can be parsed
 306 @DESC@
 307 Converts the given pattern into the standard text format described above.
 308 The return value is not static, but instead refers to newly allocated memory
 309 which should be freed by the caller.
 310 @@