[fontconfig.git] / doc / fcpattern.fncs

/*
 * $Id$
 *
 * Copyright © 2003 Keith Packard
 *
 * Permission to use, copy, modify, distribute, and sell this software and its
 * documentation for any purpose is hereby granted without fee, provided that
 * the above copyright notice appear in all copies and that both that
 * copyright notice and this permission notice appear in supporting
 * documentation, and that the name of Keith Packard not be used in
 * advertising or publicity pertaining to distribution of the software without
 * specific, written prior permission.  Keith Packard makes no
 * 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,
 * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
 * EVENT SHALL KEITH PACKARD 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
 * PERFORMANCE OF THIS SOFTWARE.
 */
@RET@		FcPattern *	
@FUNC@		FcPatternCreate
@TYPE1@ 	void
@PURPOSE@	Create a pattern
@DESC@
Creates a pattern with no properties; used to build patterns from scratch.
@@

@RET@		FcPattern *	
@FUNC@		FcPatternDuplicate
@TYPE1@		FcPattern * 			@ARG1@		 p
@PURPOSE@	Copy a pattern
@DESC@
Copy a pattern, returning a new pattern that matches
<parameter>p</parameter>. Each pattern may be modified without affecting the
other.
@@

@RET@		void
@FUNC@		FcPatternReference
@TYPE1@		FcPattern * 			@ARG1@		 p
@PURPOSE@	Increment pattern reference count
@DESC@
Add another reference to <parameter>p</parameter>. Patterns are freed only
when the reference count reaches zero.
@@

@RET@		void
@FUNC@		FcPatternDestroy
@TYPE1@		FcPattern * 			@ARG1@		 p
@PURPOSE@	Destroy a pattern
@DESC@
Decrement the pattern reference count. If all references are gone, destroys
the pattern, in the process destroying all related values.
@@

@RET@		FcBool
@FUNC@		FcPatternEqual
@TYPE1@ 	const FcPattern *		@ARG1@ 		pa
@TYPE2@		const FcPattern * 		@ARG2@		pb 
@PURPOSE@	Compare patterns
@DESC@
Returns whether <parameter>pa</parameter> and <parameter>pb</parameter> are exactly alike.
@@

@RET@		FcBool
@FUNC@		FcPatternEqualSubset
@TYPE1@		const FcPattern * 		@ARG1@ 		pa
@TYPE2@		const FcPattern *		@ARG2@ 		pb
@TYPE3@ 	const FcObjectSet * 		@ARG3@ 		os 
@PURPOSE@	Compare portions of patterns
@DESC@
Returns whether <parameter>pa</parameter> and <parameter>pb</parameter> have exactly the same values for all of the
objects in <parameter>os</parameter>.
@@

@RET@		FcChar32
@FUNC@		FcPatternHash
@TYPE1@		const FcPattern *		@ARG1@		p
@PURPOSE@	Compute a pattern hash value
@DESC@
Returns a 32-bit number which is the same for any two patterns which are
equal.
@@

@RET@		FcBool
@FUNC@		FcPatternAdd
@TYPE1@		FcPattern * 			@ARG1@ 		p
@TYPE2@ 	const char *			@ARG2@ 		object
@TYPE3@		FcValue%			@ARG3@		value
@TYPE4@		FcBool%				@ARG4@		append 
@PURPOSE@	Add a value to a pattern
@DESC@
Adds a single value to the list of values associated with the property named
`object<parameter>.  If `append</parameter> is FcTrue, the value is added at the end of any
existing list, otherwise it is inserted at the begining.  `value' is saved
(with FcValueSave) when inserted into the pattern so that the library
retains no reference to any application-supplied data structure.
@@

@RET@		FcBool
@FUNC@		FcPatternAddWeak
@TYPE1@ 	FcPattern * 			@ARG1@ 		p
@TYPE2@ 	const char * 			@ARG2@ 		object
@TYPE3@ 	FcValue%  			@ARG3@ 		value
@TYPE4@ 	FcBool%  			@ARG4@		append 
@PURPOSE@	Add a value to a pattern with weak binding
@DESC@
FcPatternAddWeak is essentially the same as FcPatternAdd except that any
values added to the list have binding <parameter>weak</parameter> instead of <parameter>strong</parameter>.
@@

@TITLE@		FcPatternAdd-Type
@RET@		FcBool
@FUNC@		FcPatternAddInteger
@TYPE1@ 	FcPattern * 			@ARG1@ 		p
@TYPE2@		const char *			@ARG2@		object
@TYPE3@		int%				@ARG3@		i

@PROTOTYPE+@
@RET+@		FcBool
@FUNC+@		FcPatternAddDouble
@TYPE1+@ 	FcPattern * 			@ARG1+@ 	p
@TYPE2+@	const char *			@ARG2+@		object
@TYPE3+@	double%				@ARG3+@		d

@PROTOTYPE++@
@RET++@		FcBool
@FUNC++@	FcPatternAddString
@TYPE1++@ 	FcPattern * 			@ARG1++@ 	p
@TYPE2++@	const char *			@ARG2++@	object
@TYPE3++@	const FcChar8 *			@ARG3++@	s

@PROTOTYPE+++@
@RET+++@	FcBool
@FUNC+++@	FcPatternAddMatrix
@TYPE1+++@ 	FcPattern * 			@ARG1+++@ 	p
@TYPE2+++@	const char *			@ARG2+++@	object
@TYPE3+++@	const FcMatrix *		@ARG3+++@	m

@PROTOTYPE++++@
@RET++++@	FcBool
@FUNC++++@	FcPatternAddCharSet
@TYPE1++++@ 	FcPattern * 			@ARG1++++@ 	p
@TYPE2++++@	const char *			@ARG2++++@	object
@TYPE3++++@	const FcCharSet *		@ARG3++++@	c

@PROTOTYPE+++++@
@RET+++++@	FcBool
@FUNC+++++@	FcPatternAddBool
@TYPE1+++++@ 	FcPattern * 			@ARG1+++++@ 	p
@TYPE2+++++@	const char *			@ARG2+++++@	object
@TYPE3+++++@	FcBool%				@ARG3+++++@	b

@PROTOTYPE++++++@
@RET++++++@	FcBool
@FUNC++++++@	FcPatternAddFTFace
@TYPE1++++++@ 	FcPattern * 			@ARG1++++++@ 	p
@TYPE2++++++@	const char *			@ARG2++++++@	object
@TYPE3++++++@	const FT_Face 			@ARG3++++++@	f

@PROTOTYPE+++++++@
@RET+++++++@	FcBool
@FUNC+++++++@	FcPatternAddLangSet
@TYPE1+++++++@ 	FcPattern * 			@ARG1+++++++@ 	p
@TYPE2+++++++@	const char *			@ARG2+++++++@	object
@TYPE3+++++++@	const FcLangSet *		@ARG3+++++++@	l

@PURPOSE@	Add a typed value to a pattern
@DESC@
These are all convenience functions that insert objects of the specified
type into the pattern.  Use these in preference to FcPatternAdd as they
will provide compile-time typechecking.  These all append values to
any existing list of values.
@@

@RET@		FcResult
@FUNC@		FcPatternGet
@TYPE1@		FcPattern *			@ARG1@		p
@TYPE2@		const char *			@ARG2@		object
@TYPE3@		int%  				@ARG3@ 		id
@TYPE4@		FcValue *			@ARG4@		v 
@PURPOSE@	Return a value from a pattern
@DESC@
Returns in <parameter>v</parameter> the <parameter>id</parameter>'th value
associated with the property <parameter>object</parameter>.
The value returned is not a copy, but rather refers to the data stored
within the pattern directly.  Applications must not free this value.
@@

@TITLE@		FcPatternGet-Type
@PROTOTYPE@
@RET@ 		FcResult
@FUNC@		FcPatternGetInteger
@TYPE1@		FcPattern *			@ARG1@		p
@TYPE2@		const char *			@ARG2@		object
@TYPE3@		int%				@ARG3@		n
@TYPE4@		int *				@ARG4@		i

@PROTOTYPE+@
@RET+@		FcResult
@FUNC+@ 	FcPatternGetDouble
@TYPE1+@	FcPattern *			@ARG1+@		p
@TYPE2+@	const char *			@ARG2+@		object
@TYPE3+@	int%				@ARG3+@		n
@TYPE4+@	double *			@ARG4+@		d 

@PROTOTYPE++@
@RET++@ 	FcResult
@FUNC++@	FcPatternGetString
@TYPE1++@	FcPattern *			@ARG1++@	p
@TYPE2++@	const char *			@ARG2++@	object
@TYPE3++@	int%				@ARG3++@	n
@TYPE4++@	FcChar8 **			@ARG4++@	s

@PROTOTYPE+++@
@RET+++@	FcResult
@FUNC+++@	FcPatternGetMatrix 
@TYPE1+++@ 	FcPattern * 			@ARG1+++@ 	p 
@TYPE2+++@ 	const char * 			@ARG2+++@ 	object 
@TYPE3+++@ 	int%  				@ARG3+++@ 	n 
@TYPE4+++@ 	FcMatrix ** 			@ARG4+++@ 	s 

@PROTOTYPE++++@
@RET++++@ 	FcResult 
@FUNC++++@ 	FcPatternGetCharSet 
@TYPE1++++@ 	FcPattern * 			@ARG1++++@ 	p 
@TYPE2++++@ 	const char * 			@ARG2++++@ 	object 
@TYPE3++++@ 	int%  				@ARG3++++@ 	n 
@TYPE4++++@ 	FcCharSet ** 			@ARG4++++@ 	c 

@PROTOTYPE+++++@
@RET+++++@ 	FcResult 
@FUNC+++++@ 	FcPatternGetBool 		
@TYPE1+++++@ 	FcPattern * 			@ARG1+++++@ 	p
@TYPE2+++++@ 	const char * 			@ARG2+++++@ 	object 
@TYPE3+++++@ 	int%  				@ARG3+++++@ 	n 
@TYPE4+++++@ 	FcBool * 			@ARG4+++++@ 	b 

@PROTOTYPE++++++@
@RET++++++@	FcBool
@FUNC++++++@	FcPatternGetFTFace
@TYPE1++++++@ 	FcPattern * 			@ARG1++++++@ 	p
@TYPE2++++++@	const char *			@ARG2++++++@	object
@TYPE3+++++@ 	int%  				@ARG3+++++@ 	n
@TYPE3++++++@	FT_Face *			@ARG3++++++@	f

@PROTOTYPE+++++++@
@RET+++++++@	FcBool
@FUNC+++++++@	FcPatternGetLangSet
@TYPE1+++++++@ 	FcPattern * 			@ARG1+++++++@ 	p
@TYPE2+++++++@	const char *			@ARG2+++++++@	object
@TYPE3+++++@ 	int%  				@ARG3+++++@ 	n
@TYPE3+++++++@	FcLangSet **			@ARG3+++++++@	l

@PURPOSE@	Return a typed value from a pattern
@DESC@
These are convenience functions that call FcPatternGet and verify that the
returned data is of the expected type. They return FcResultTypeMismatch if
this is not the case.  Note that these (like FcPatternGet) do not make a
copy of any data structure referenced by the return value.  Use these
in preference to FcPatternGet to provide compile-time typechecking.
@@

@RET@		FcPattern *
@FUNC@		FcPatternBuild
@TYPE1@		FcPattern *			@ARG1@		orig
@TYPE2@ 	...

@PROTOTYPE+@
@RET+@		FcPattern *
@FUNC+@		FcPatternVaBuild
@TYPE1+@	FcPattern *			@ARG1+@		orig
@TYPE2+@	va_list% 			@ARG2+@		va

@PROTOTYPE++@
@RET++@		void
@FUNC++@	FcPatternVapBuild
@TYPE1++@	FcPattern *			@ARG1++@	result
@TYPE2++@	FcPattern *			@ARG2++@	orig
@TYPE3++@	va_list%			@ARG3++@	va

@PURPOSE@	Create patterns from arguments
@DESC@
Builds a pattern using a list of objects, types and values.  Each
value to be entered in the pattern is specified with three arguments:
</para>
<orderedlist>
<listitem><para>
Object name, a string describing the property to be added.
</para></listitem><listitem><para>
Object type, one of the FcType enumerated values
</para></listitem><listitem><para>
Value, not an FcValue, but the raw type as passed to any of the
FcPatternAdd&lt;type&gt; functions.  Must match the type of the second
argument.
</para></listitem>
</orderedlist>
<para>
The argument list is terminated by a null object name, no object type nor
value need be passed for this.  The values are added to `pattern', if
`pattern' is null, a new pattern is created.  In either case, the pattern is
returned. Example
</para>
<programlisting>
pattern = FcPatternBuild (0, FC_FAMILY, FcTypeString, "Times", (char *) 0);
</programlisting>
<para>
FcPatternVaBuild is used when the arguments are already in the form of a
varargs value. FcPatternVapBuild is a macro version of FcPatternVaBuild
which returns its result directly in the <parameter>result</parameter>
variable.
@@

@RET@		FcBool
@FUNC@		FcPatternDel
@TYPE1@		FcPattern *			@ARG1@		p
@TYPE2@		const char *			@ARG2@		object 
@PURPOSE@	Delete a property from a pattern
@DESC@
Deletes all values associated with the property `object', returning 
whether the property existed or not.
@@

@RET@		FcBool
@FUNC@		FcPatternRemove
@TYPE1@		FcPattern *			@ARG1@		p
@TYPE2@		const char *			@ARG2@		object 
@TYPE3@		int%				@ARG3@		id
@PURPOSE@	Remove one object of the specified type from the pattern
@DESC@
Removes the value associated with the property `object' at position `id', returning 
whether the property existed and had a value at that position or not.
@@
		
@RET@		void
@FUNC@		FcPatternPrint
@TYPE1@		const FcPattern *		@ARG1@		p 
@PURPOSE@	Print a pattern for debugging
@DESC@
Prints an easily readable version of the pattern to stdout.  There is
no provision for reparsing data in this format, it's just for diagnostics
and debugging.
@@

@RET@		void 	
@FUNC@		FcDefaultSubstitute
@TYPE1@		FcPattern *			@ARG1@		pattern 
@PURPOSE@	Perform default substitutions in a pattern
@DESC@
Supplies default values for underspecified font patterns:
<itemizedlist>
<listitem><para>
Patterns without a specified style or weight are set to Medium
</para></listitem>
<listitem><para>
Patterns without a specified style or slant are set to Roman
</para></listitem>
<listitem><para>
Patterns without a specified pixel size are given one computed from any
specified point size (default 12), dpi (default 75) and scale (default 1).
</para></listitem>
</itemizedlist>
@@

@RET@		FcPattern *
@FUNC@		FcNameParse
@TYPE1@		const FcChar8 *			@ARG1@		name 
@PURPOSE@	Parse a pattern string
@DESC@
Converts <parameter>name</parameter> from the standard text format described above into a pattern.
@@

@RET@		FcChar8 *
@FUNC@		FcNameUnparse
@TYPE1@		FcPattern *			@ARG1@		pat 
@PURPOSE@	Convert a pattern back into a string that can be parsed
@DESC@
Converts the given pattern into the standard text format described above.
The return value is not static, but instead refers to newly allocated memory
which should be freed by the caller.
@@
Commit	Line	Data
bfc2dc3a KP	1	/*
	2	* $Id$
	3	*
46b51147	4	* Copyright © 2003 Keith Packard
bfc2dc3a KP	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	*/
22671e25 KP	24	@RET@ FcPattern *
	25	@FUNC@ FcPatternCreate
	26	@TYPE1@ void
	27	@PURPOSE@ Create a pattern
	28	@DESC@
	29	Creates a pattern with no properties; used to build patterns from scratch.
	30	@@
	31
a190678e KP	32	@RET@ FcPattern *
	33	@FUNC@ FcPatternDuplicate
	34	@TYPE1@ FcPattern * @ARG1@ p
	35	@PURPOSE@ Copy a pattern
	36	@DESC@
	37	Copy a pattern, returning a new pattern that matches
	38	<parameter>p</parameter>. Each pattern may be modified without affecting the
	39	other.
	40	@@
	41
	42	@RET@ void
	43	@FUNC@ FcPatternReference
	44	@TYPE1@ FcPattern * @ARG1@ p
	45	@PURPOSE@ Increment pattern reference count
	46	@DESC@
	47	Add another reference to <parameter>p</parameter>. Patterns are freed only
	48	when the reference count reaches zero.
	49	@@
	50
22671e25 KP	51	@RET@ void
	52	@FUNC@ FcPatternDestroy
	53	@TYPE1@ FcPattern * @ARG1@ p
	54	@PURPOSE@ Destroy a pattern
	55	@DESC@
a190678e KP	56	Decrement the pattern reference count. If all references are gone, destroys
a190678e KP	57	the pattern, in the process destroying all related values.
22671e25 KP	58	@@
	59
	60	@RET@ FcBool
	61	@FUNC@ FcPatternEqual
	62	@TYPE1@ const FcPattern * @ARG1@ pa
	63	@TYPE2@ const FcPattern * @ARG2@ pb
	64	@PURPOSE@ Compare patterns
	65	@DESC@
2df0c662	66	Returns whether <parameter>pa</parameter> and <parameter>pb</parameter> are exactly alike.
22671e25 KP	67	@@
	68
	69	@RET@ FcBool
	70	@FUNC@ FcPatternEqualSubset
	71	@TYPE1@ const FcPattern * @ARG1@ pa
	72	@TYPE2@ const FcPattern * @ARG2@ pb
	73	@TYPE3@ const FcObjectSet * @ARG3@ os
	74	@PURPOSE@ Compare portions of patterns
	75	@DESC@
2df0c662 KP	76	Returns whether <parameter>pa</parameter> and <parameter>pb</parameter> have exactly the same values for all of the
2df0c662 KP	77	objects in <parameter>os</parameter>.
22671e25 KP	78	@@
	79
	80	@RET@ FcChar32
	81	@FUNC@ FcPatternHash
	82	@TYPE1@ const FcPattern * @ARG1@ p
	83	@PURPOSE@ Compute a pattern hash value
	84	@DESC@
	85	Returns a 32-bit number which is the same for any two patterns which are
	86	equal.
	87	@@
	88
	89	@RET@ FcBool
	90	@FUNC@ FcPatternAdd
	91	@TYPE1@ FcPattern * @ARG1@ p
	92	@TYPE2@ const char * @ARG2@ object
61895ed1 KP	93	@TYPE3@ FcValue% @ARG3@ value
61895ed1 KP	94	@TYPE4@ FcBool% @ARG4@ append
22671e25 KP	95	@PURPOSE@ Add a value to a pattern
	96	@DESC@
	97	Adds a single value to the list of values associated with the property named
2df0c662	98	`object<parameter>. If `append</parameter> is FcTrue, the value is added at the end of any
22671e25 KP	99	existing list, otherwise it is inserted at the begining. `value' is saved
	100	(with FcValueSave) when inserted into the pattern so that the library
	101	retains no reference to any application-supplied data structure.
	102	@@
	103
	104	@RET@ FcBool
	105	@FUNC@ FcPatternAddWeak
	106	@TYPE1@ FcPattern * @ARG1@ p
	107	@TYPE2@ const char * @ARG2@ object
61895ed1 KP	108	@TYPE3@ FcValue% @ARG3@ value
61895ed1 KP	109	@TYPE4@ FcBool% @ARG4@ append
22671e25 KP	110	@PURPOSE@ Add a value to a pattern with weak binding
	111	@DESC@
	112	FcPatternAddWeak is essentially the same as FcPatternAdd except that any
2df0c662	113	values added to the list have binding <parameter>weak</parameter> instead of <parameter>strong</parameter>.
22671e25 KP	114	@@
	115
	116	@TITLE@ FcPatternAdd-Type
	117	@RET@ FcBool
	118	@FUNC@ FcPatternAddInteger
	119	@TYPE1@ FcPattern * @ARG1@ p
	120	@TYPE2@ const char * @ARG2@ object
61895ed1	121	@TYPE3@ int% @ARG3@ i
22671e25 KP	122
	123	@PROTOTYPE+@
	124	@RET+@ FcBool
	125	@FUNC+@ FcPatternAddDouble
	126	@TYPE1+@ FcPattern * @ARG1+@ p
	127	@TYPE2+@ const char * @ARG2+@ object
61895ed1	128	@TYPE3+@ double% @ARG3+@ d
22671e25 KP	129
	130	@PROTOTYPE++@
	131	@RET++@ FcBool
	132	@FUNC++@ FcPatternAddString
	133	@TYPE1++@ FcPattern * @ARG1++@ p
	134	@TYPE2++@ const char * @ARG2++@ object
f2772d6b	135	@TYPE3++@ const FcChar8 * @ARG3++@ s
22671e25 KP	136
	137	@PROTOTYPE+++@
	138	@RET+++@ FcBool
	139	@FUNC+++@ FcPatternAddMatrix
	140	@TYPE1+++@ FcPattern * @ARG1+++@ p
	141	@TYPE2+++@ const char * @ARG2+++@ object
	142	@TYPE3+++@ const FcMatrix * @ARG3+++@ m
	143
	144	@PROTOTYPE++++@
	145	@RET++++@ FcBool
	146	@FUNC++++@ FcPatternAddCharSet
	147	@TYPE1++++@ FcPattern * @ARG1++++@ p
	148	@TYPE2++++@ const char * @ARG2++++@ object
	149	@TYPE3++++@ const FcCharSet * @ARG3++++@ c
	150
	151	@PROTOTYPE+++++@
	152	@RET+++++@ FcBool
	153	@FUNC+++++@ FcPatternAddBool
	154	@TYPE1+++++@ FcPattern * @ARG1+++++@ p
	155	@TYPE2+++++@ const char * @ARG2+++++@ object
61895ed1	156	@TYPE3+++++@ FcBool% @ARG3+++++@ b
a190678e KP	157
	158	@PROTOTYPE++++++@
	159	@RET++++++@ FcBool
	160	@FUNC++++++@ FcPatternAddFTFace
	161	@TYPE1++++++@ FcPattern * @ARG1++++++@ p
	162	@TYPE2++++++@ const char * @ARG2++++++@ object
	163	@TYPE3++++++@ const FT_Face @ARG3++++++@ f
	164
	165	@PROTOTYPE+++++++@
	166	@RET+++++++@ FcBool
	167	@FUNC+++++++@ FcPatternAddLangSet
	168	@TYPE1+++++++@ FcPattern * @ARG1+++++++@ p
	169	@TYPE2+++++++@ const char * @ARG2+++++++@ object
	170	@TYPE3+++++++@ const FcLangSet * @ARG3+++++++@ l
	171
22671e25 KP	172	@PURPOSE@ Add a typed value to a pattern
	173	@DESC@
	174	These are all convenience functions that insert objects of the specified
	175	type into the pattern. Use these in preference to FcPatternAdd as they
	176	will provide compile-time typechecking. These all append values to
	177	any existing list of values.
	178	@@
	179
	180	@RET@ FcResult
	181	@FUNC@ FcPatternGet
	182	@TYPE1@ FcPattern * @ARG1@ p
	183	@TYPE2@ const char * @ARG2@ object
61895ed1	184	@TYPE3@ int% @ARG3@ id
22671e25 KP	185	@TYPE4@ FcValue * @ARG4@ v
	186	@PURPOSE@ Return a value from a pattern
	187	@DESC@
0c009d2b KP	188	Returns in <parameter>v</parameter> the <parameter>id</parameter>'th value
0c009d2b KP	189	associated with the property <parameter>object</parameter>.
22671e25 KP	190	The value returned is not a copy, but rather refers to the data stored
	191	within the pattern directly. Applications must not free this value.
	192	@@
	193
	194	@TITLE@ FcPatternGet-Type
	195	@PROTOTYPE@
	196	@RET@ FcResult
	197	@FUNC@ FcPatternGetInteger
	198	@TYPE1@ FcPattern * @ARG1@ p
	199	@TYPE2@ const char * @ARG2@ object
61895ed1	200	@TYPE3@ int% @ARG3@ n
22671e25 KP	201	@TYPE4@ int * @ARG4@ i
	202
	203	@PROTOTYPE+@
	204	@RET+@ FcResult
	205	@FUNC+@ FcPatternGetDouble
	206	@TYPE1+@ FcPattern * @ARG1+@ p
	207	@TYPE2+@ const char * @ARG2+@ object
61895ed1	208	@TYPE3+@ int% @ARG3+@ n
22671e25 KP	209	@TYPE4+@ double * @ARG4+@ d
	210
	211	@PROTOTYPE++@
	212	@RET++@ FcResult
	213	@FUNC++@ FcPatternGetString
	214	@TYPE1++@ FcPattern * @ARG1++@ p
	215	@TYPE2++@ const char * @ARG2++@ object
61895ed1	216	@TYPE3++@ int% @ARG3++@ n
f2772d6b	217	@TYPE4++@ FcChar8 ** @ARG4++@ s
22671e25 KP	218
	219	@PROTOTYPE+++@
	220	@RET+++@ FcResult
	221	@FUNC+++@ FcPatternGetMatrix
	222	@TYPE1+++@ FcPattern * @ARG1+++@ p
	223	@TYPE2+++@ const char * @ARG2+++@ object
61895ed1	224	@TYPE3+++@ int% @ARG3+++@ n
22671e25 KP	225	@TYPE4+++@ FcMatrix ** @ARG4+++@ s
	226
	227	@PROTOTYPE++++@
	228	@RET++++@ FcResult
	229	@FUNC++++@ FcPatternGetCharSet
	230	@TYPE1++++@ FcPattern * @ARG1++++@ p
	231	@TYPE2++++@ const char * @ARG2++++@ object
61895ed1	232	@TYPE3++++@ int% @ARG3++++@ n
22671e25 KP	233	@TYPE4++++@ FcCharSet ** @ARG4++++@ c
	234
	235	@PROTOTYPE+++++@
	236	@RET+++++@ FcResult
	237	@FUNC+++++@ FcPatternGetBool
	238	@TYPE1+++++@ FcPattern * @ARG1+++++@ p
	239	@TYPE2+++++@ const char * @ARG2+++++@ object
61895ed1	240	@TYPE3+++++@ int% @ARG3+++++@ n
22671e25	241	@TYPE4+++++@ FcBool * @ARG4+++++@ b
a190678e KP	242
	243	@PROTOTYPE++++++@
	244	@RET++++++@ FcBool
	245	@FUNC++++++@ FcPatternGetFTFace
	246	@TYPE1++++++@ FcPattern * @ARG1++++++@ p
	247	@TYPE2++++++@ const char * @ARG2++++++@ object
2e08e0f2 BE	248	@TYPE3+++++@ int% @ARG3+++++@ n
2e08e0f2 BE	249	@TYPE3++++++@ FT_Face * @ARG3++++++@ f
a190678e KP	250
	251	@PROTOTYPE+++++++@
	252	@RET+++++++@ FcBool
	253	@FUNC+++++++@ FcPatternGetLangSet
	254	@TYPE1+++++++@ FcPattern * @ARG1+++++++@ p
	255	@TYPE2+++++++@ const char * @ARG2+++++++@ object
2e08e0f2 BE	256	@TYPE3+++++@ int% @ARG3+++++@ n
2e08e0f2 BE	257	@TYPE3+++++++@ FcLangSet ** @ARG3+++++++@ l
a190678e	258
22671e25 KP	259	@PURPOSE@ Return a typed value from a pattern
	260	@DESC@
	261	These are convenience functions that call FcPatternGet and verify that the
	262	returned data is of the expected type. They return FcResultTypeMismatch if
	263	this is not the case. Note that these (like FcPatternGet) do not make a
	264	copy of any data structure referenced by the return value. Use these
	265	in preference to FcPatternGet to provide compile-time typechecking.
	266	@@
	267
	268	@RET@ FcPattern *
	269	@FUNC@ FcPatternBuild
	270	@TYPE1@ FcPattern * @ARG1@ orig
	271	@TYPE2@ ...
	272
	273	@PROTOTYPE+@
	274	@RET+@ FcPattern *
	275	@FUNC+@ FcPatternVaBuild
	276	@TYPE1+@ FcPattern * @ARG1+@ orig
61895ed1	277	@TYPE2+@ va_list% @ARG2+@ va
1315db01 KP	278
	279	@PROTOTYPE++@
	280	@RET++@ void
	281	@FUNC++@ FcPatternVapBuild
	282	@TYPE1++@ FcPattern * @ARG1++@ result
	283	@TYPE2++@ FcPattern * @ARG2++@ orig
	284	@TYPE3++@ va_list% @ARG3++@ va
	285
22671e25 KP	286	@PURPOSE@ Create patterns from arguments
	287	@DESC@
	288	Builds a pattern using a list of objects, types and values. Each
	289	value to be entered in the pattern is specified with three arguments:
8c87b429	290	</para>
22671e25 KP	291	<orderedlist>
	292	<listitem><para>
	293	Object name, a string describing the property to be added.
	294	</para></listitem><listitem><para>
	295	Object type, one of the FcType enumerated values
	296	</para></listitem><listitem><para>
	297	Value, not an FcValue, but the raw type as passed to any of the
	298	FcPatternAdd<type> functions. Must match the type of the second
	299	argument.
	300	</para></listitem>
	301	</orderedlist>
	302	<para>
	303	The argument list is terminated by a null object name, no object type nor
	304	value need be passed for this. The values are added to `pattern', if
	305	`pattern' is null, a new pattern is created. In either case, the pattern is
	306	returned. Example
	307	</para>
	308	<programlisting>
af7a965f	309	pattern = FcPatternBuild (0, FC_FAMILY, FcTypeString, "Times", (char *) 0);
22671e25 KP	310	</programlisting>
	311	<para>
	312	FcPatternVaBuild is used when the arguments are already in the form of a
1315db01 KP	313	varargs value. FcPatternVapBuild is a macro version of FcPatternVaBuild
	314	which returns its result directly in the <parameter>result</parameter>
	315	variable.
22671e25 KP	316	@@
	317
	318	@RET@ FcBool
	319	@FUNC@ FcPatternDel
	320	@TYPE1@ FcPattern * @ARG1@ p
	321	@TYPE2@ const char * @ARG2@ object
	322	@PURPOSE@ Delete a property from a pattern
	323	@DESC@
	324	Deletes all values associated with the property `object', returning
	325	whether the property existed or not.
	326	@@
	327
4f27c1c0 KP	328	@RET@ FcBool
	329	@FUNC@ FcPatternRemove
	330	@TYPE1@ FcPattern * @ARG1@ p
	331	@TYPE2@ const char * @ARG2@ object
61895ed1	332	@TYPE3@ int% @ARG3@ id
4f27c1c0 KP	333	@PURPOSE@ Remove one object of the specified type from the pattern
	334	@DESC@
	335	Removes the value associated with the property `object' at position `id', returning
	336	whether the property existed and had a value at that position or not.
	337	@@
	338
22671e25 KP	339	@RET@ void
	340	@FUNC@ FcPatternPrint
	341	@TYPE1@ const FcPattern * @ARG1@ p
	342	@PURPOSE@ Print a pattern for debugging
	343	@DESC@
	344	Prints an easily readable version of the pattern to stdout. There is
	345	no provision for reparsing data in this format, it's just for diagnostics
	346	and debugging.
	347	@@
	348
	349	@RET@ void
	350	@FUNC@ FcDefaultSubstitute
	351	@TYPE1@ FcPattern * @ARG1@ pattern
	352	@PURPOSE@ Perform default substitutions in a pattern
	353	@DESC@
	354	Supplies default values for underspecified font patterns:
	355	<itemizedlist>
	356	<listitem><para>
	357	Patterns without a specified style or weight are set to Medium
	358	</para></listitem>
	359	<listitem><para>
	360	Patterns without a specified style or slant are set to Roman
	361	</para></listitem>
	362	<listitem><para>
	363	Patterns without a specified pixel size are given one computed from any
	364	specified point size (default 12), dpi (default 75) and scale (default 1).
	365	</para></listitem>
	366	</itemizedlist>
	367	@@
	368
	369	@RET@ FcPattern *
	370	@FUNC@ FcNameParse
f2772d6b	371	@TYPE1@ const FcChar8 * @ARG1@ name
22671e25 KP	372	@PURPOSE@ Parse a pattern string
22671e25 KP	373	@DESC@
2df0c662	374	Converts <parameter>name</parameter> from the standard text format described above into a pattern.
22671e25 KP	375	@@
	376
	377	@RET@ FcChar8 *
	378	@FUNC@ FcNameUnparse
	379	@TYPE1@ FcPattern * @ARG1@ pat
	380	@PURPOSE@ Convert a pattern back into a string that can be parsed
	381	@DESC@
	382	Converts the given pattern into the standard text format described above.
	383	The return value is not static, but instead refers to newly allocated memory
	384	which should be freed by the caller.
	385	@@