doc/fcfontset.sgml

   1 <!--
   2    fontconfig/doc/func.sgml
   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     <refentry id="FcFontSetCreate">
  25         <refmeta>
  26             <refentrytitle>FcFontSetCreate</refentrytitle>
  27             <manvolnum>3</manvolnum>
  28             <refmiscinfo class="software">Fontconfig &version;</refmiscinfo>
  29         </refmeta>
  30         <refnamediv>
  31             <refname>FcFontSetCreate</refname>
  32             <refpurpose>Create a font set</refpurpose>
  33         </refnamediv>
  34         <refsynopsisdiv>
  35         <funcsynopsis>
  36         <funcsynopsisinfo>
  37 #include &lt;fontconfig/fontconfig.h&gt;
  38         </funcsynopsisinfo>
  39         <funcprototype>
  40             <funcdef>FcFontSet * <function>FcFontSetCreate</function></funcdef>
  41                 <paramdef>void<parameter></parameter></paramdef>
  42         </funcprototype>
  43         </funcsynopsis>
  44         </refsynopsisdiv>
  45         <refsect1><title>Description</title>
  46             <para>
  47 Creates an empty font set.
  48             </para>
  49         </refsect1>
  50     </refentry>
  51 <!--
  52    fontconfig/doc/func.sgml
  53
  54    Copyright © 2003 Keith Packard
  55
  56    Permission to use, copy, modify, distribute, and sell this software and its
  57    documentation for any purpose is hereby granted without fee, provided that
  58    the above copyright notice appear in all copies and that both that
  59    copyright notice and this permission notice appear in supporting
  60    documentation, and that the name of the author(s) not be used in
  61    advertising or publicity pertaining to distribution of the software without
  62    specific, written prior permission.  The authors make no
  63    representations about the suitability of this software for any purpose.  It
  64    is provided "as is" without express or implied warranty.
  65
  66    THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
  67    INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
  68    EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY SPECIAL, INDIRECT OR
  69    CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
  70    DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
  71    TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  72    PERFORMANCE OF THIS SOFTWARE.
  73  -->
  74     <refentry id="FcFontSetDestroy">
  75         <refmeta>
  76             <refentrytitle>FcFontSetDestroy</refentrytitle>
  77             <manvolnum>3</manvolnum>
  78             <refmiscinfo class="software">Fontconfig &version;</refmiscinfo>
  79         </refmeta>
  80         <refnamediv>
  81             <refname>FcFontSetDestroy</refname>
  82             <refpurpose>Destroy a font set</refpurpose>
  83         </refnamediv>
  84         <refsynopsisdiv>
  85         <funcsynopsis>
  86         <funcsynopsisinfo>
  87 #include &lt;fontconfig/fontconfig.h&gt;
  88         </funcsynopsisinfo>
  89         <funcprototype>
  90             <funcdef>void <function>FcFontSetDestroy</function></funcdef>
  91                 <paramdef>FcFontSet *<parameter>s</parameter></paramdef>
  92         </funcprototype>
  93         </funcsynopsis>
  94         </refsynopsisdiv>
  95         <refsect1><title>Description</title>
  96             <para>
  97 Destroys a font set.  Note that this destroys any referenced patterns as
  98 well.
  99             </para>
 100         </refsect1>
 101     </refentry>
 102 <!--
 103    fontconfig/doc/func.sgml
 104
 105    Copyright © 2003 Keith Packard
 106
 107    Permission to use, copy, modify, distribute, and sell this software and its
 108    documentation for any purpose is hereby granted without fee, provided that
 109    the above copyright notice appear in all copies and that both that
 110    copyright notice and this permission notice appear in supporting
 111    documentation, and that the name of the author(s) not be used in
 112    advertising or publicity pertaining to distribution of the software without
 113    specific, written prior permission.  The authors make no
 114    representations about the suitability of this software for any purpose.  It
 115    is provided "as is" without express or implied warranty.
 116
 117    THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
 118    INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
 119    EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY SPECIAL, INDIRECT OR
 120    CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
 121    DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
 122    TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 123    PERFORMANCE OF THIS SOFTWARE.
 124  -->
 125     <refentry id="FcFontSetAdd">
 126         <refmeta>
 127             <refentrytitle>FcFontSetAdd</refentrytitle>
 128             <manvolnum>3</manvolnum>
 129             <refmiscinfo class="software">Fontconfig &version;</refmiscinfo>
 130         </refmeta>
 131         <refnamediv>
 132             <refname>FcFontSetAdd</refname>
 133             <refpurpose>Add to a font set</refpurpose>
 134         </refnamediv>
 135         <refsynopsisdiv>
 136         <funcsynopsis>
 137         <funcsynopsisinfo>
 138 #include &lt;fontconfig/fontconfig.h&gt;
 139         </funcsynopsisinfo>
 140         <funcprototype>
 141             <funcdef>FcBool <function>FcFontSetAdd</function></funcdef>
 142                 <paramdef>FcFontSet *<parameter>s</parameter></paramdef>
 143                 <paramdef>FcPattern *<parameter>font</parameter></paramdef>
 144         </funcprototype>
 145         </funcsynopsis>
 146         </refsynopsisdiv>
 147         <refsect1><title>Description</title>
 148             <para>
 149 Adds a pattern to a font set.  Note that the pattern is not copied before
 150 being inserted into the set. Returns FcFalse if the pattern cannot be
 151 inserted into the set (due to allocation failure). Otherwise returns FcTrue.
 152             </para>
 153         </refsect1>
 154     </refentry>
 155 <!--
 156    fontconfig/doc/func.sgml
 157
 158    Copyright © 2003 Keith Packard
 159
 160    Permission to use, copy, modify, distribute, and sell this software and its
 161    documentation for any purpose is hereby granted without fee, provided that
 162    the above copyright notice appear in all copies and that both that
 163    copyright notice and this permission notice appear in supporting
 164    documentation, and that the name of the author(s) not be used in
 165    advertising or publicity pertaining to distribution of the software without
 166    specific, written prior permission.  The authors make no
 167    representations about the suitability of this software for any purpose.  It
 168    is provided "as is" without express or implied warranty.
 169
 170    THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
 171    INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
 172    EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY SPECIAL, INDIRECT OR
 173    CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
 174    DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
 175    TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 176    PERFORMANCE OF THIS SOFTWARE.
 177  -->
 178     <refentry id="FcFontSetList">
 179         <refmeta>
 180             <refentrytitle>FcFontSetList</refentrytitle>
 181             <manvolnum>3</manvolnum>
 182             <refmiscinfo class="software">Fontconfig &version;</refmiscinfo>
 183         </refmeta>
 184         <refnamediv>
 185             <refname>FcFontSetList</refname>
 186             <refpurpose>List fonts from a set of font sets</refpurpose>
 187         </refnamediv>
 188         <refsynopsisdiv>
 189         <funcsynopsis>
 190         <funcsynopsisinfo>
 191 #include &lt;fontconfig/fontconfig.h&gt;
 192         </funcsynopsisinfo>
 193         <funcprototype>
 194             <funcdef>FcFontSet * <function>FcFontSetList</function></funcdef>
 195                 <paramdef>FcConfig *<parameter>config</parameter></paramdef>
 196                 <paramdef>FcFontSet **<parameter>sets</parameter></paramdef>
 197                 <paramdef>int<parameter>nsets</parameter></paramdef>
 198                 <paramdef>FcPattern *<parameter>pattern</parameter></paramdef>
 199                 <paramdef>FcObjectSet *<parameter>object_set</parameter></paramdef>
 200         </funcprototype>
 201         </funcsynopsis>
 202         </refsynopsisdiv>
 203         <refsect1><title>Description</title>
 204             <para>
 205 Selects fonts matching <parameter>pattern</parameter> from
 206 <parameter>sets</parameter>, creates patterns from those
 207 fonts containing only the objects in <parameter>object_set</parameter> and returns
 208 the set of unique such patterns.
 209 If <parameter>config</parameter> is NULL, the default configuration is checked
 210 to be up to date, and used.
 211             </para>
 212         </refsect1>
 213     </refentry>
 214 <!--
 215    fontconfig/doc/func.sgml
 216
 217    Copyright © 2003 Keith Packard
 218
 219    Permission to use, copy, modify, distribute, and sell this software and its
 220    documentation for any purpose is hereby granted without fee, provided that
 221    the above copyright notice appear in all copies and that both that
 222    copyright notice and this permission notice appear in supporting
 223    documentation, and that the name of the author(s) not be used in
 224    advertising or publicity pertaining to distribution of the software without
 225    specific, written prior permission.  The authors make no
 226    representations about the suitability of this software for any purpose.  It
 227    is provided "as is" without express or implied warranty.
 228
 229    THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
 230    INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
 231    EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY SPECIAL, INDIRECT OR
 232    CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
 233    DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
 234    TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 235    PERFORMANCE OF THIS SOFTWARE.
 236  -->
 237     <refentry id="FcFontSetMatch">
 238         <refmeta>
 239             <refentrytitle>FcFontSetMatch</refentrytitle>
 240             <manvolnum>3</manvolnum>
 241             <refmiscinfo class="software">Fontconfig &version;</refmiscinfo>
 242         </refmeta>
 243         <refnamediv>
 244             <refname>FcFontSetMatch</refname>
 245             <refpurpose>Return the best font from a set of font sets</refpurpose>
 246         </refnamediv>
 247         <refsynopsisdiv>
 248         <funcsynopsis>
 249         <funcsynopsisinfo>
 250 #include &lt;fontconfig/fontconfig.h&gt;
 251         </funcsynopsisinfo>
 252         <funcprototype>
 253             <funcdef>FcPattern * <function>FcFontSetMatch</function></funcdef>
 254                 <paramdef>FcConfig *<parameter>config</parameter></paramdef>
 255                 <paramdef>FcFontSet **<parameter>sets</parameter></paramdef>
 256                 <paramdef>int<parameter>nsets</parameter></paramdef>
 257                 <paramdef>FcPattern *<parameter>pattern</parameter></paramdef>
 258                 <paramdef>FcResult *<parameter>result</parameter></paramdef>
 259         </funcprototype>
 260         </funcsynopsis>
 261         </refsynopsisdiv>
 262         <refsect1><title>Description</title>
 263             <para>
 264 Finds the font in <parameter>sets</parameter> most closely matching
 265 <parameter>pattern</parameter> and returns the result of
 266 <function>FcFontRenderPrepare</function> for that font and the provided
 267 pattern. This function should be called only after
 268 <function>FcConfigSubstitute</function> and
 269 <function>FcDefaultSubstitute</function> have been called for
 270 <parameter>pattern</parameter>; otherwise the results will not be correct.
 271 If <parameter>config</parameter> is NULL, the current configuration is used.
 272 Returns NULL if an error occurs during this process.
 273             </para>
 274         </refsect1>
 275     </refentry>
 276 <!--
 277    fontconfig/doc/func.sgml
 278
 279    Copyright © 2003 Keith Packard
 280
 281    Permission to use, copy, modify, distribute, and sell this software and its
 282    documentation for any purpose is hereby granted without fee, provided that
 283    the above copyright notice appear in all copies and that both that
 284    copyright notice and this permission notice appear in supporting
 285    documentation, and that the name of the author(s) not be used in
 286    advertising or publicity pertaining to distribution of the software without
 287    specific, written prior permission.  The authors make no
 288    representations about the suitability of this software for any purpose.  It
 289    is provided "as is" without express or implied warranty.
 290
 291    THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
 292    INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
 293    EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY SPECIAL, INDIRECT OR
 294    CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
 295    DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
 296    TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 297    PERFORMANCE OF THIS SOFTWARE.
 298  -->
 299     <refentry id="FcFontSetPrint">
 300         <refmeta>
 301             <refentrytitle>FcFontSetPrint</refentrytitle>
 302             <manvolnum>3</manvolnum>
 303             <refmiscinfo class="software">Fontconfig &version;</refmiscinfo>
 304         </refmeta>
 305         <refnamediv>
 306             <refname>FcFontSetPrint</refname>
 307             <refpurpose>Print a set of patterns to stdout</refpurpose>
 308         </refnamediv>
 309         <refsynopsisdiv>
 310         <funcsynopsis>
 311         <funcsynopsisinfo>
 312 #include &lt;fontconfig/fontconfig.h&gt;
 313         </funcsynopsisinfo>
 314         <funcprototype>
 315             <funcdef>void <function>FcFontSetPrint</function></funcdef>
 316                 <paramdef>FcFontSet *<parameter>set</parameter></paramdef>
 317         </funcprototype>
 318         </funcsynopsis>
 319         </refsynopsisdiv>
 320         <refsect1><title>Description</title>
 321             <para>
 322 This function is useful for diagnosing font related issues, printing the
 323 complete contents of every pattern in <parameter>set</parameter>. The format
 324 of the output is designed to be of help to users and developers, and may
 325 change at any time.
 326             </para>
 327         </refsect1>
 328     </refentry>
 329 <!--
 330    fontconfig/doc/func.sgml
 331
 332    Copyright © 2003 Keith Packard
 333
 334    Permission to use, copy, modify, distribute, and sell this software and its
 335    documentation for any purpose is hereby granted without fee, provided that
 336    the above copyright notice appear in all copies and that both that
 337    copyright notice and this permission notice appear in supporting
 338    documentation, and that the name of the author(s) not be used in
 339    advertising or publicity pertaining to distribution of the software without
 340    specific, written prior permission.  The authors make no
 341    representations about the suitability of this software for any purpose.  It
 342    is provided "as is" without express or implied warranty.
 343
 344    THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
 345    INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
 346    EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY SPECIAL, INDIRECT OR
 347    CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
 348    DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
 349    TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 350    PERFORMANCE OF THIS SOFTWARE.
 351  -->
 352     <refentry id="FcFontSetSort">
 353         <refmeta>
 354             <refentrytitle>FcFontSetSort</refentrytitle>
 355             <manvolnum>3</manvolnum>
 356             <refmiscinfo class="software">Fontconfig &version;</refmiscinfo>
 357         </refmeta>
 358         <refnamediv>
 359             <refname>FcFontSetSort</refname>
 360             <refpurpose>Add to a font set</refpurpose>
 361         </refnamediv>
 362         <refsynopsisdiv>
 363         <funcsynopsis>
 364         <funcsynopsisinfo>
 365 #include &lt;fontconfig/fontconfig.h&gt;
 366         </funcsynopsisinfo>
 367         <funcprototype>
 368             <funcdef> <function>FcFontSetSort</function></funcdef>
 369                 <paramdef>FcConfig *<parameter>config</parameter></paramdef>
 370                 <paramdef>FcFontSet **<parameter>sets</parameter></paramdef>
 371                 <paramdef>int<parameter>nsets</parameter></paramdef>
 372                 <paramdef>FcPattern *<parameter>pattern</parameter></paramdef>
 373                 <paramdef>FcBool <parameter>trim</parameter></paramdef>
 374                 <paramdef>FcCharSet **<parameter>csp</parameter></paramdef>
 375                 <paramdef>FcResult *<parameter>result</parameter></paramdef>
 376         </funcprototype>
 377         </funcsynopsis>
 378         </refsynopsisdiv>
 379         <refsect1><title>Description</title>
 380             <para>
 381 Returns the list of fonts from <parameter>sets</parameter>
 382 sorted by closeness to <parameter>pattern</parameter>.
 383 If <parameter>trim</parameter> is FcTrue,
 384 elements in the list which don't include Unicode coverage not provided by
 385 earlier elements in the list are elided.  The union of Unicode coverage of
 386 all of the fonts is returned in <parameter>csp</parameter>,
 387 if <parameter>csp</parameter> is not NULL.  This function
 388 should be called only after FcConfigSubstitute and FcDefaultSubstitute have
 389 been called for <parameter>p</parameter>;
 390 otherwise the results will not be correct.
 391     </para><para>
 392 The returned FcFontSet references FcPattern structures which may be shared
 393 by the return value from multiple FcFontSort calls, applications cannot
 394 modify these patterns.  Instead, they should be passed, along with
 395 <parameter>pattern</parameter> to
 396 <function>FcFontRenderPrepare</function> which combines them into a complete pattern.
 397     </para><para>
 398 The FcFontSet returned by FcFontSetSort is destroyed by calling FcFontSetDestroy.
 399             </para>
 400         </refsect1>
 401     </refentry>
 402 <!--
 403    fontconfig/doc/func.sgml
 404
 405    Copyright © 2003 Keith Packard
 406
 407    Permission to use, copy, modify, distribute, and sell this software and its
 408    documentation for any purpose is hereby granted without fee, provided that
 409    the above copyright notice appear in all copies and that both that
 410    copyright notice and this permission notice appear in supporting
 411    documentation, and that the name of the author(s) not be used in
 412    advertising or publicity pertaining to distribution of the software without
 413    specific, written prior permission.  The authors make no
 414    representations about the suitability of this software for any purpose.  It
 415    is provided "as is" without express or implied warranty.
 416
 417    THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
 418    INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
 419    EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY SPECIAL, INDIRECT OR
 420    CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
 421    DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
 422    TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 423    PERFORMANCE OF THIS SOFTWARE.
 424  -->
 425     <refentry id="FcFontSetSortDestroy">
 426         <refmeta>
 427             <refentrytitle>FcFontSetSortDestroy</refentrytitle>
 428             <manvolnum>3</manvolnum>
 429             <refmiscinfo class="software">Fontconfig &version;</refmiscinfo>
 430         </refmeta>
 431         <refnamediv>
 432             <refname>FcFontSetSortDestroy</refname>
 433             <refpurpose>DEPRECATED destroy a font set</refpurpose>
 434         </refnamediv>
 435         <refsynopsisdiv>
 436         <funcsynopsis>
 437         <funcsynopsisinfo>
 438 #include &lt;fontconfig/fontconfig.h&gt;
 439         </funcsynopsisinfo>
 440         <funcprototype>
 441             <funcdef> <function>FcFontSetSortDestroy</function></funcdef>
 442                 <paramdef>FcFontSet *<parameter>set</parameter></paramdef>
 443         </funcprototype>
 444         </funcsynopsis>
 445         </refsynopsisdiv>
 446         <refsect1><title>Description</title>
 447             <para>
 448 This function is DEPRECATED. <function>FcFontSetSortDestroy</function>
 449 destroys <parameter>set</parameter> by calling
 450 <function>FcFontSetDestroy</function>. Applications should use
 451 <function>FcFontSetDestroy</function> directly instead.
 452             </para>
 453         </refsect1>
 454     </refentry>