/*
- * $Id$
+ * fontconfig/doc/fcfontset.fncs
*
* Copyright © 2003 Keith Packard
*
* representations about the suitability of this software for any purpose. It
* is provided "as is" without express or implied warranty.
*
- * KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
+ * THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
* INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
- * EVENT SHALL KEITH PACKARD BE LIABLE FOR ANY SPECIAL, INDIRECT OR
+ * EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY SPECIAL, INDIRECT OR
* CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
* DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
* TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
@PURPOSE@ Add to a font set
@DESC@
Adds a pattern to a font set. Note that the pattern is not copied before
-being inserted into the set.
+being inserted into the set. Returns FcFalse if the pattern cannot be
+inserted into the set (due to allocation failure). Otherwise returns FcTrue.
@@
@RET@ FcFontSet *
<parameter>sets</parameter>, creates patterns from those
fonts containing only the objects in <parameter>object_set</parameter> and returns
the set of unique such patterns.
+If <parameter>config</parameter> is NULL, the default configuration is checked
+to be up to date, and used.
@@
@RET@ FcPattern *
@TYPE5@ FcResult * @ARG5@ result
@PURPOSE@ Return the best font from a set of font sets
@DESC@
-Returns the font in <parameter>sets</parameter> most close matching
-<parameter>pattern</parameter>. This function should be called only after
-FcConfigSubstitute and FcDefaultSubstitute have been called for
+Finds the font in <parameter>sets</parameter> most closely matching
+<parameter>pattern</parameter> and returns the result of
+<function>FcFontRenderPrepare</function> for that font and the provided
+pattern. This function should be called only after
+<function>FcConfigSubstitute</function> and
+<function>FcDefaultSubstitute</function> have been called for
<parameter>pattern</parameter>; otherwise the results will not be correct.
+If <parameter>config</parameter> is NULL, the current configuration is used.
+Returns NULL if an error occurs during this process.
@@
@RET@ void
by the return value from multiple FcFontSort calls, applications cannot
modify these patterns. Instead, they should be passed, along with
<parameter>pattern</parameter> to
-FcFontRenderPrepare which combines them into a complete pattern.
+<function>FcFontRenderPrepare</function> which combines them into a complete pattern.
</para><para>
The FcFontSet returned by FcFontSetSort is destroyed by caling FcFontSetDestroy.
@@