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