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 <parameter>pa</parameter> and <parameter>pb</parameter> 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 <parameter>pa</parameter> and <parameter>pb</parameter> have exactly the same values for all of the
  57 objects in <parameter>os</parameter>.
  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<parameter>.  If `append</parameter> 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 <parameter>weak</parameter> instead of <parameter>strong</parameter>.
  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 <parameter>v</parameter> the <parameter>id</parameter>'th value
 154 associated with the property <parameter>object</parameter>.
 155 The value returned is not a copy, but rather refers to the data stored
 156 within the pattern directly.  Applications must not free this value.
 157 @@
 158
 159 @TITLE@         FcPatternGet-Type
 160 @PROTOTYPE@
 161 @RET@           FcResult
 162 @FUNC@          FcPatternGetInteger
 163 @TYPE1@         FcPattern *                     @ARG1@          p
 164 @TYPE2@         const char *                    @ARG2@          object
 165 @TYPE3@         int                             @ARG3@          n
 166 @TYPE4@         int *                           @ARG4@          i
 167
 168 @PROTOTYPE+@
 169 @RET+@          FcResult
 170 @FUNC+@         FcPatternGetDouble
 171 @TYPE1+@        FcPattern *                     @ARG1+@         p
 172 @TYPE2+@        const char *                    @ARG2+@         object
 173 @TYPE3+@        int                             @ARG3+@         n
 174 @TYPE4+@        double *                        @ARG4+@         d
 175
 176 @PROTOTYPE++@
 177 @RET++@         FcResult
 178 @FUNC++@        FcPatternGetString
 179 @TYPE1++@       FcPattern *                     @ARG1++@        p
 180 @TYPE2++@       const char *                    @ARG2++@        object
 181 @TYPE3++@       int                             @ARG3++@        n
 182 @TYPE4++@       char **const                    @ARG4++@        s
 183
 184 @PROTOTYPE+++@
 185 @RET+++@        FcResult
 186 @FUNC+++@       FcPatternGetMatrix
 187 @TYPE1+++@      FcPattern *                     @ARG1+++@       p
 188 @TYPE2+++@      const char *                    @ARG2+++@       object
 189 @TYPE3+++@      int                             @ARG3+++@       n
 190 @TYPE4+++@      FcMatrix **                     @ARG4+++@       s
 191
 192 @PROTOTYPE++++@
 193 @RET++++@       FcResult
 194 @FUNC++++@      FcPatternGetCharSet
 195 @TYPE1++++@     FcPattern *                     @ARG1++++@      p
 196 @TYPE2++++@     const char *                    @ARG2++++@      object
 197 @TYPE3++++@     int                             @ARG3++++@      n
 198 @TYPE4++++@     FcCharSet **                    @ARG4++++@      c
 199
 200 @PROTOTYPE+++++@
 201 @RET+++++@      FcResult
 202 @FUNC+++++@     FcPatternGetBool
 203 @TYPE1+++++@    FcPattern *                     @ARG1+++++@     p
 204 @TYPE2+++++@    const char *                    @ARG2+++++@     object
 205 @TYPE3+++++@    int                             @ARG3+++++@     n
 206 @TYPE4+++++@    FcBool *                        @ARG4+++++@     b
 207 @PURPOSE@       Return a typed value from a pattern
 208 @DESC@
 209 These are convenience functions that call FcPatternGet and verify that the
 210 returned data is of the expected type. They return FcResultTypeMismatch if
 211 this is not the case.  Note that these (like FcPatternGet) do not make a
 212 copy of any data structure referenced by the return value.  Use these
 213 in preference to FcPatternGet to provide compile-time typechecking.
 214 @@
 215
 216 @RET@           FcPattern *
 217 @FUNC@          FcPatternBuild
 218 @TYPE1@         FcPattern *                     @ARG1@          orig
 219 @TYPE2@         ...
 220
 221 @PROTOTYPE+@
 222 @RET+@          FcPattern *
 223 @FUNC+@         FcPatternVaBuild
 224 @TYPE1+@        FcPattern *                     @ARG1+@         orig
 225 @TYPE2+@        va_list                         @ARG2+@         va
 226 @PURPOSE@       Create patterns from arguments
 227 @DESC@
 228 Builds a pattern using a list of objects, types and values.  Each
 229 value to be entered in the pattern is specified with three arguments:
 230 </para>
 231 <orderedlist>
 232 <listitem><para>
 233 Object name, a string describing the property to be added.
 234 </para></listitem><listitem><para>
 235 Object type, one of the FcType enumerated values
 236 </para></listitem><listitem><para>
 237 Value, not an FcValue, but the raw type as passed to any of the
 238 FcPatternAdd&lt;type&gt; functions.  Must match the type of the second
 239 argument.
 240 </para></listitem>
 241 </orderedlist>
 242 <para>
 243 The argument list is terminated by a null object name, no object type nor
 244 value need be passed for this.  The values are added to `pattern', if
 245 `pattern' is null, a new pattern is created.  In either case, the pattern is
 246 returned. Example
 247 </para>
 248 <programlisting>
 249 pattern = FcPatternBuild (0, FC_FAMILY, FcTypeString, "Times", (char *) 0);
 250 </programlisting>
 251 <para>
 252 FcPatternVaBuild is used when the arguments are already in the form of a
 253 varargs value.
 254 @@
 255
 256 @RET@           FcBool
 257 @FUNC@          FcPatternDel
 258 @TYPE1@         FcPattern *                     @ARG1@          p
 259 @TYPE2@         const char *                    @ARG2@          object
 260 @PURPOSE@       Delete a property from a pattern
 261 @DESC@
 262 Deletes all values associated with the property `object', returning
 263 whether the property existed or not.
 264 @@
 265
 266 @RET@           FcBool
 267 @FUNC@          FcPatternRemove
 268 @TYPE1@         FcPattern *                     @ARG1@          p
 269 @TYPE2@         const char *                    @ARG2@          object
 270 @TYPE3@         int                             @ARG3@          id
 271 @PURPOSE@       Remove one object of the specified type from the pattern
 272 @DESC@
 273 Removes the value associated with the property `object' at position `id', returning
 274 whether the property existed and had a value at that position or not.
 275 @@
 276
 277 @RET@           void
 278 @FUNC@          FcPatternPrint
 279 @TYPE1@         const FcPattern *               @ARG1@          p
 280 @PURPOSE@       Print a pattern for debugging
 281 @DESC@
 282 Prints an easily readable version of the pattern to stdout.  There is
 283 no provision for reparsing data in this format, it's just for diagnostics
 284 and debugging.
 285 @@
 286
 287 @RET@           void
 288 @FUNC@          FcDefaultSubstitute
 289 @TYPE1@         FcPattern *                     @ARG1@          pattern
 290 @PURPOSE@       Perform default substitutions in a pattern
 291 @DESC@
 292 Supplies default values for underspecified font patterns:
 293 <itemizedlist>
 294 <listitem><para>
 295 Patterns without a specified style or weight are set to Medium
 296 </para></listitem>
 297 <listitem><para>
 298 Patterns without a specified style or slant are set to Roman
 299 </para></listitem>
 300 <listitem><para>
 301 Patterns without a specified pixel size are given one computed from any
 302 specified point size (default 12), dpi (default 75) and scale (default 1).
 303 </para></listitem>
 304 </itemizedlist>
 305 @@
 306
 307 @RET@           FcPattern *
 308 @FUNC@          FcNameParse
 309 @TYPE1@         const char *                    @ARG1@          name
 310 @PURPOSE@       Parse a pattern string
 311 @DESC@
 312 Converts <parameter>name</parameter> from the standard text format described above into a pattern.
 313 @@
 314
 315 @RET@           FcChar8 *
 316 @FUNC@          FcNameUnparse
 317 @TYPE1@         FcPattern *                     @ARG1@          pat
 318 @PURPOSE@       Convert a pattern back into a string that can be parsed
 319 @DESC@
 320 Converts the given pattern into the standard text format described above.
 321 The return value is not static, but instead refers to newly allocated memory
 322 which should be freed by the caller.
 323 @@