doc/fcfontset.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@           FcFontSet *
  25 @FUNC@          FcFontSetCreate
  26 @TYPE1@         void
  27 @PURPOSE@       Create a font set
  28 @DESC@
  29 Creates an empty font set.
  30 @@
  31
  32 @RET@           void
  33 @FUNC@          FcFontSetDestroy
  34 @TYPE1@         FcFontSet *                     @ARG1@          s
  35 @PURPOSE@       Destroy a font set
  36 @DESC@
  37 Destroys a font set.  Note that this destroys any referenced patterns as
  38 well.
  39 @@
  40
  41 @RET@           FcBool
  42 @FUNC@          FcFontSetAdd
  43 @TYPE1@         FcFontSet *                     @ARG1@          s
  44 @TYPE2@         FcPattern *                     @ARG2@          font
  45 @PURPOSE@       Add to a font set
  46 @DESC@
  47 Adds a pattern to a font set.  Note that the pattern is not copied before
  48 being inserted into the set.
  49 @@
  50
  51 @RET@           FcFontSet *
  52 @FUNC@          FcFontSetList
  53 @TYPE1@         FcConfig *                      @ARG1@          config
  54 @TYPE2@         FcFontSet **                    @ARG2@          sets
  55 @TYPE3@         int                             @ARG3@          nsets
  56 @TYPE4@         FcPattern *                     @ARG4@          pattern
  57 @TYPE5@         FcObjectSet *                   @ARG5@          object_set
  58 @PURPOSE@       List fonts from a set of font sets
  59 @DESC@
  60 Selects fonts matching <parameter>pattern</parameter> from
  61 <parameter>sets</parameter>, creates patterns from those
  62 fonts containing only the objects in <parameter>object_set</parameter> and returns
  63 the set of unique such patterns.
  64 @@
  65
  66 @RET@           FcPattern *
  67 @FUNC@          FcFontSetMatch
  68 @TYPE1@         FcConfig *                      @ARG1@          config
  69 @TYPE2@         FcFontSet **                    @ARG2@          sets
  70 @TYPE3@         int                             @ARG3@          nsets
  71 @TYPE4@         FcPattern *                     @ARG4@          pattern
  72 @TYPE5@         FcResult *                      @ARG5@          result
  73 @PURPOSE@       Return the best font from a set of font sets
  74 @DESC@
  75 Returns the font in <parameter>sets</parameter> most close matching
  76 <parameter>pattern</parameter>.  This function should be called only after
  77 FcConfigSubstitute and FcDefaultSubstitute have been called for
  78 <parameter>pattern</parameter>; otherwise the results will not be correct.
  79 @@
  80
  81 @RET@           void
  82 @FUNC@          FcFontSetPrint
  83 @TYPE1@         FcFontSet *                     @ARG1@          set
  84 @PURPOSE@       Print a set of patterns to stdout
  85 @DESC@
  86 This function is useful for diagnosing font related issues, printing the
  87 complete contents of every pattern in <parameter>set</parameter>. The format
  88 of the output is designed to be of help to users and developers, and may
  89 change at any time.
  90 @@
  91
  92 @RET@
  93 @FUNC@          FcFontSetSort
  94 @TYPE1@         FcConfig *                      @ARG1@          config
  95 @TYPE2@         FcFontSet **                    @ARG2@          sets
  96 @TYPE3@         int                             @ARG3@          nsets
  97 @TYPE4@         FcPattern *                     @ARG4@          pattern
  98 @TYPE5@         FcBool%                         @ARG5@          trim
  99 @TYPE6@         FcCharSet **                    @ARG6@          csp
 100 @TYPE7@         FcResult *                      @ARG7@          result
 101 @PURPOSE@       Add to a font set
 102 @DESC@
 103 Returns the list of fonts from <parameter>sets</parameter>
 104 sorted by closeness to <parameter>pattern</parameter>.
 105 If <parameter>trim</parameter> is FcTrue,
 106 elements in the list which don't include Unicode coverage not provided by
 107 earlier elements in the list are elided.  The union of Unicode coverage of
 108 all of the fonts is returned in <parameter>csp</parameter>,
 109 if <parameter>csp</parameter> is not NULL.  This function
 110 should be called only after FcConfigSubstitute and FcDefaultSubstitute have
 111 been called for <parameter>p</parameter>;
 112 otherwise the results will not be correct.
 113     </para><para>
 114 The returned FcFontSet references FcPattern structures which may be shared
 115 by the return value from multiple FcFontSort calls, applications cannot
 116 modify these patterns.  Instead, they should be passed, along with
 117 <parameter>pattern</parameter> to
 118 FcFontRenderPrepare which combines them into a complete pattern.
 119     </para><para>
 120 The FcFontSet returned by FcFontSetSort is destroyed by caling FcFontSetDestroy.
 121 @@
 122
 123 @RET@
 124 @FUNC@          FcFontSetSortDestroy
 125 @TYPE1@         FcFontSet *                     @ARG1@          set
 126 @PURPOSE@       DEPRECATED destroy a font set
 127 @DESC@
 128 This function is DEPRECATED. <function>FcFontSetSortDestroy</function>
 129 destroys <parameter>set</parameter> by calling
 130 <function>FcFontSetDestroy</function>. Applications should use
 131 <function>FcFontSetDestroy</function> directly instead.
 132 @@