doc/fcfontset.fncs

   1 /*
   2  * fontconfig/doc/fcfontset.fncs
   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 the author(s) not be used in
  11  * advertising or publicity pertaining to distribution of the software without
  12  * specific, written prior permission.  The authors make 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  * THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
  17  * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
  18  * EVENT SHALL THE AUTHOR(S) 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 If <parameter>config</parameter> is NULL, the default configuration is checked
  66 to be up to date, and used.
  67 @@
  68
  69 @RET@           FcPattern *
  70 @FUNC@          FcFontSetMatch
  71 @TYPE1@         FcConfig *                      @ARG1@          config
  72 @TYPE2@         FcFontSet **                    @ARG2@          sets
  73 @TYPE3@         int                             @ARG3@          nsets
  74 @TYPE4@         FcPattern *                     @ARG4@          pattern
  75 @TYPE5@         FcResult *                      @ARG5@          result
  76 @PURPOSE@       Return the best font from a set of font sets
  77 @DESC@
  78 Finds the font in <parameter>sets</parameter> most closely matching
  79 <parameter>pattern</parameter> and returns the result of
  80 <function>FcFontRenderPrepare</function> for that font and the provided
  81 pattern. This function should be called only after
  82 <function>FcConfigSubstitute</function> and
  83 <function>FcDefaultSubstitute</function> have been called for
  84 <parameter>pattern</parameter>; otherwise the results will not be correct.
  85 If <parameter>config</parameter> is NULL, the current configuration is used.
  86 Returns NULL if an error occurs during this process.
  87 @@
  88
  89 @RET@           void
  90 @FUNC@          FcFontSetPrint
  91 @TYPE1@         FcFontSet *                     @ARG1@          set
  92 @PURPOSE@       Print a set of patterns to stdout
  93 @DESC@
  94 This function is useful for diagnosing font related issues, printing the
  95 complete contents of every pattern in <parameter>set</parameter>. The format
  96 of the output is designed to be of help to users and developers, and may
  97 change at any time.
  98 @@
  99
 100 @RET@
 101 @FUNC@          FcFontSetSort
 102 @TYPE1@         FcConfig *                      @ARG1@          config
 103 @TYPE2@         FcFontSet **                    @ARG2@          sets
 104 @TYPE3@         int                             @ARG3@          nsets
 105 @TYPE4@         FcPattern *                     @ARG4@          pattern
 106 @TYPE5@         FcBool%                         @ARG5@          trim
 107 @TYPE6@         FcCharSet **                    @ARG6@          csp
 108 @TYPE7@         FcResult *                      @ARG7@          result
 109 @PURPOSE@       Add to a font set
 110 @DESC@
 111 Returns the list of fonts from <parameter>sets</parameter>
 112 sorted by closeness to <parameter>pattern</parameter>.
 113 If <parameter>trim</parameter> is FcTrue,
 114 elements in the list which don't include Unicode coverage not provided by
 115 earlier elements in the list are elided.  The union of Unicode coverage of
 116 all of the fonts is returned in <parameter>csp</parameter>,
 117 if <parameter>csp</parameter> is not NULL.  This function
 118 should be called only after FcConfigSubstitute and FcDefaultSubstitute have
 119 been called for <parameter>p</parameter>;
 120 otherwise the results will not be correct.
 121     </para><para>
 122 The returned FcFontSet references FcPattern structures which may be shared
 123 by the return value from multiple FcFontSort calls, applications cannot
 124 modify these patterns.  Instead, they should be passed, along with
 125 <parameter>pattern</parameter> to
 126 <function>FcFontRenderPrepare</function> which combines them into a complete pattern.
 127     </para><para>
 128 The FcFontSet returned by FcFontSetSort is destroyed by calling FcFontSetDestroy.
 129 @@
 130
 131 @RET@
 132 @FUNC@          FcFontSetSortDestroy
 133 @TYPE1@         FcFontSet *                     @ARG1@          set
 134 @PURPOSE@       DEPRECATED destroy a font set
 135 @DESC@
 136 This function is DEPRECATED. <function>FcFontSetSortDestroy</function>
 137 destroys <parameter>set</parameter> by calling
 138 <function>FcFontSetDestroy</function>. Applications should use
 139 <function>FcFontSetDestroy</function> directly instead.
 140 @@