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 Returns the font in <parameter>sets</parameter> most close matching
  77 <parameter>pattern</parameter>.  This function should be called only after
  78 FcConfigSubstitute and FcDefaultSubstitute have been called for
  79 <parameter>pattern</parameter>; otherwise the results will not be correct.
  80 @@
  81
  82 @RET@           void
  83 @FUNC@          FcFontSetPrint
  84 @TYPE1@         FcFontSet *                     @ARG1@          set
  85 @PURPOSE@       Print a set of patterns to stdout
  86 @DESC@
  87 This function is useful for diagnosing font related issues, printing the
  88 complete contents of every pattern in <parameter>set</parameter>. The format
  89 of the output is designed to be of help to users and developers, and may
  90 change at any time.
  91 @@
  92
  93 @RET@
  94 @FUNC@          FcFontSetSort
  95 @TYPE1@         FcConfig *                      @ARG1@          config
  96 @TYPE2@         FcFontSet **                    @ARG2@          sets
  97 @TYPE3@         int                             @ARG3@          nsets
  98 @TYPE4@         FcPattern *                     @ARG4@          pattern
  99 @TYPE5@         FcBool%                         @ARG5@          trim
 100 @TYPE6@         FcCharSet **                    @ARG6@          csp
 101 @TYPE7@         FcResult *                      @ARG7@          result
 102 @PURPOSE@       Add to a font set
 103 @DESC@
 104 Returns the list of fonts from <parameter>sets</parameter>
 105 sorted by closeness to <parameter>pattern</parameter>.
 106 If <parameter>trim</parameter> is FcTrue,
 107 elements in the list which don't include Unicode coverage not provided by
 108 earlier elements in the list are elided.  The union of Unicode coverage of
 109 all of the fonts is returned in <parameter>csp</parameter>,
 110 if <parameter>csp</parameter> is not NULL.  This function
 111 should be called only after FcConfigSubstitute and FcDefaultSubstitute have
 112 been called for <parameter>p</parameter>;
 113 otherwise the results will not be correct.
 114     </para><para>
 115 The returned FcFontSet references FcPattern structures which may be shared
 116 by the return value from multiple FcFontSort calls, applications cannot
 117 modify these patterns.  Instead, they should be passed, along with
 118 <parameter>pattern</parameter> to
 119 FcFontRenderPrepare which combines them into a complete pattern.
 120     </para><para>
 121 The FcFontSet returned by FcFontSetSort is destroyed by caling FcFontSetDestroy.
 122 @@
 123
 124 @RET@
 125 @FUNC@          FcFontSetSortDestroy
 126 @TYPE1@         FcFontSet *                     @ARG1@          set
 127 @PURPOSE@       DEPRECATED destroy a font set
 128 @DESC@
 129 This function is DEPRECATED. <function>FcFontSetSortDestroy</function>
 130 destroys <parameter>set</parameter> by calling
 131 <function>FcFontSetDestroy</function>. Applications should use
 132 <function>FcFontSetDestroy</function> directly instead.
 133 @@