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