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@ 29Creates 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@ 37Destroys a font set. Note that this destroys any referenced patterns as 38well. 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@ 47Adds a pattern to a font set. Note that the pattern is not copied before 48being inserted into the set. Returns FcFalse if the pattern cannot be 49inserted 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@ 61Selects fonts matching <parameter>pattern</parameter> from 62<parameter>sets</parameter>, creates patterns from those 63fonts containing only the objects in <parameter>object_set</parameter> and returns 64the set of unique such patterns. 65If <parameter>config</parameter> is NULL, the default configuration is checked 66to 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@ 78Finds 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 81pattern. 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. 85If <parameter>config</parameter> is NULL, the current configuration is used. 86Returns 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@ 94This function is useful for diagnosing font related issues, printing the 95complete contents of every pattern in <parameter>set</parameter>. The format 96of the output is designed to be of help to users and developers, and may 97change 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@ 111Returns the list of fonts from <parameter>sets</parameter> 112sorted by closeness to <parameter>pattern</parameter>. 113If <parameter>trim</parameter> is FcTrue, 114elements in the list which don't include Unicode coverage not provided by 115earlier elements in the list are elided. The union of Unicode coverage of 116all of the fonts is returned in <parameter>csp</parameter>, 117if <parameter>csp</parameter> is not NULL. This function 118should be called only after FcConfigSubstitute and FcDefaultSubstitute have 119been called for <parameter>p</parameter>; 120otherwise the results will not be correct. 121 </para><para> 122The returned FcFontSet references FcPattern structures which may be shared 123by the return value from multiple FcFontSort calls, applications cannot 124modify 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> 128The 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@ 136This function is DEPRECATED. <function>FcFontSetSortDestroy</function> 137destroys <parameter>set</parameter> by calling 138<function>FcFontSetDestroy</function>. Applications should use 139<function>FcFontSetDestroy</function> directly instead. 140@@ 141