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