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 `v<parameter> the `id</parameter>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 </para>
 230 <orderedlist>
 231 <listitem><para>
 232 Object name, a string describing the property to be added.
 233 </para></listitem><listitem><para>
 234 Object type, one of the FcType enumerated values
 235 </para></listitem><listitem><para>
 236 Value, not an FcValue, but the raw type as passed to any of the
 237 FcPatternAdd&lt;type&gt; functions.  Must match the type of the second
 238 argument.
 239 </para></listitem>
 240 </orderedlist>
 241 <para>
 242 The argument list is terminated by a null object name, no object type nor
 243 value need be passed for this.  The values are added to `pattern', if
 244 `pattern' is null, a new pattern is created.  In either case, the pattern is
 245 returned. Example
 246 </para>
 247 <programlisting>
 248 pattern = FcPatternBuild (0, FC_FAMILY, FtTypeString, "Times", (char *) 0);
 249 </programlisting>
 250 <para>
 251 FcPatternVaBuild is used when the arguments are already in the form of a
 252 varargs value.
 253 @@
 254
 255 @RET@           FcBool
 256 @FUNC@          FcPatternDel
 257 @TYPE1@         FcPattern *                     @ARG1@          p
 258 @TYPE2@         const char *                    @ARG2@          object
 259 @PURPOSE@       Delete a property from a pattern
 260 @DESC@
 261 Deletes all values associated with the property `object', returning
 262 whether the property existed or not.
 263 @@
 264
 265 @RET@           FcBool
 266 @FUNC@          FcPatternRemove
 267 @TYPE1@         FcPattern *                     @ARG1@          p
 268 @TYPE2@         const char *                    @ARG2@          object
 269 @TYPE3@         int                             @ARG3@          id
 270 @PURPOSE@       Remove one object of the specified type from the pattern
 271 @DESC@
 272 Removes the value associated with the property `object' at position `id', returning
 273 whether the property existed and had a value at that position or not.
 274 @@
 275
 276 @RET@           void
 277 @FUNC@          FcPatternPrint
 278 @TYPE1@         const FcPattern *               @ARG1@          p
 279 @PURPOSE@       Print a pattern for debugging
 280 @DESC@
 281 Prints an easily readable version of the pattern to stdout.  There is
 282 no provision for reparsing data in this format, it's just for diagnostics
 283 and debugging.
 284 @@
 285
 286 @RET@           void
 287 @FUNC@          FcDefaultSubstitute
 288 @TYPE1@         FcPattern *                     @ARG1@          pattern
 289 @PURPOSE@       Perform default substitutions in a pattern
 290 @DESC@
 291 Supplies default values for underspecified font patterns:
 292 <itemizedlist>
 293 <listitem><para>
 294 Patterns without a specified style or weight are set to Medium
 295 </para></listitem>
 296 <listitem><para>
 297 Patterns without a specified style or slant are set to Roman
 298 </para></listitem>
 299 <listitem><para>
 300 Patterns without a specified pixel size are given one computed from any
 301 specified point size (default 12), dpi (default 75) and scale (default 1).
 302 </para></listitem>
 303 </itemizedlist>
 304 @@
 305
 306 @RET@           FcPattern *
 307 @FUNC@          FcNameParse
 308 @TYPE1@         const char *                    @ARG1@          name
 309 @PURPOSE@       Parse a pattern string
 310 @DESC@
 311 Converts <parameter>name</parameter> from the standard text format described above into a pattern.
 312 @@
 313
 314 @RET@           FcChar8 *
 315 @FUNC@          FcNameUnparse
 316 @TYPE1@         FcPattern *                     @ARG1@          pat
 317 @PURPOSE@       Convert a pattern back into a string that can be parsed
 318 @DESC@
 319 Converts the given pattern into the standard text format described above.
 320 The return value is not static, but instead refers to newly allocated memory
 321 which should be freed by the caller.
 322 @@