[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++++++@	const FT_Face *			@ARG3++++++@	f

@PROTOTYPE+++++++@
@RET+++++++@	FcBool
@FUNC+++++++@	FcPatternGetLangSet
@TYPE1+++++++@ 	FcPattern * 			@ARG1+++++++@ 	p
@TYPE2+++++++@	const char *			@ARG2+++++++@	object
@TYPE3+++++++@	const 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
	248	@TYPE3++++++@ const FT_Face * @ARG3++++++@ f
	249
	250	@PROTOTYPE+++++++@
	251	@RET+++++++@ FcBool
	252	@FUNC+++++++@ FcPatternGetLangSet
	253	@TYPE1+++++++@ FcPattern * @ARG1+++++++@ p
	254	@TYPE2+++++++@ const char * @ARG2+++++++@ object
	255	@TYPE3+++++++@ const FcLangSet ** @ARG3+++++++@ l
	256
22671e25 KP	257	@PURPOSE@ Return a typed value from a pattern
	258	@DESC@
	259	These are convenience functions that call FcPatternGet and verify that the
	260	returned data is of the expected type. They return FcResultTypeMismatch if
	261	this is not the case. Note that these (like FcPatternGet) do not make a
	262	copy of any data structure referenced by the return value. Use these
	263	in preference to FcPatternGet to provide compile-time typechecking.
	264	@@
	265
	266	@RET@ FcPattern *
	267	@FUNC@ FcPatternBuild
	268	@TYPE1@ FcPattern * @ARG1@ orig
	269	@TYPE2@ ...
	270
	271	@PROTOTYPE+@
	272	@RET+@ FcPattern *
	273	@FUNC+@ FcPatternVaBuild
	274	@TYPE1+@ FcPattern * @ARG1+@ orig
61895ed1	275	@TYPE2+@ va_list% @ARG2+@ va
1315db01 KP	276
	277	@PROTOTYPE++@
	278	@RET++@ void
	279	@FUNC++@ FcPatternVapBuild
	280	@TYPE1++@ FcPattern * @ARG1++@ result
	281	@TYPE2++@ FcPattern * @ARG2++@ orig
	282	@TYPE3++@ va_list% @ARG3++@ va
	283
22671e25 KP	284	@PURPOSE@ Create patterns from arguments
	285	@DESC@
	286	Builds a pattern using a list of objects, types and values. Each
	287	value to be entered in the pattern is specified with three arguments:
8c87b429	288	</para>
22671e25 KP	289	<orderedlist>
	290	<listitem><para>
	291	Object name, a string describing the property to be added.
	292	</para></listitem><listitem><para>
	293	Object type, one of the FcType enumerated values
	294	</para></listitem><listitem><para>
	295	Value, not an FcValue, but the raw type as passed to any of the
	296	FcPatternAdd<type> functions. Must match the type of the second
	297	argument.
	298	</para></listitem>
	299	</orderedlist>
	300	<para>
	301	The argument list is terminated by a null object name, no object type nor
	302	value need be passed for this. The values are added to `pattern', if
	303	`pattern' is null, a new pattern is created. In either case, the pattern is
	304	returned. Example
	305	</para>
	306	<programlisting>
af7a965f	307	pattern = FcPatternBuild (0, FC_FAMILY, FcTypeString, "Times", (char *) 0);
22671e25 KP	308	</programlisting>
	309	<para>
	310	FcPatternVaBuild is used when the arguments are already in the form of a
1315db01 KP	311	varargs value. FcPatternVapBuild is a macro version of FcPatternVaBuild
	312	which returns its result directly in the <parameter>result</parameter>
	313	variable.
22671e25 KP	314	@@
	315
	316	@RET@ FcBool
	317	@FUNC@ FcPatternDel
	318	@TYPE1@ FcPattern * @ARG1@ p
	319	@TYPE2@ const char * @ARG2@ object
	320	@PURPOSE@ Delete a property from a pattern
	321	@DESC@
	322	Deletes all values associated with the property `object', returning
	323	whether the property existed or not.
	324	@@
	325
4f27c1c0 KP	326	@RET@ FcBool
	327	@FUNC@ FcPatternRemove
	328	@TYPE1@ FcPattern * @ARG1@ p
	329	@TYPE2@ const char * @ARG2@ object
61895ed1	330	@TYPE3@ int% @ARG3@ id
4f27c1c0 KP	331	@PURPOSE@ Remove one object of the specified type from the pattern
	332	@DESC@
	333	Removes the value associated with the property `object' at position `id', returning
	334	whether the property existed and had a value at that position or not.
	335	@@
	336
22671e25 KP	337	@RET@ void
	338	@FUNC@ FcPatternPrint
	339	@TYPE1@ const FcPattern * @ARG1@ p
	340	@PURPOSE@ Print a pattern for debugging
	341	@DESC@
	342	Prints an easily readable version of the pattern to stdout. There is
	343	no provision for reparsing data in this format, it's just for diagnostics
	344	and debugging.
	345	@@
	346
	347	@RET@ void
	348	@FUNC@ FcDefaultSubstitute
	349	@TYPE1@ FcPattern * @ARG1@ pattern
	350	@PURPOSE@ Perform default substitutions in a pattern
	351	@DESC@
	352	Supplies default values for underspecified font patterns:
	353	<itemizedlist>
	354	<listitem><para>
	355	Patterns without a specified style or weight are set to Medium
	356	</para></listitem>
	357	<listitem><para>
	358	Patterns without a specified style or slant are set to Roman
	359	</para></listitem>
	360	<listitem><para>
	361	Patterns without a specified pixel size are given one computed from any
	362	specified point size (default 12), dpi (default 75) and scale (default 1).
	363	</para></listitem>
	364	</itemizedlist>
	365	@@
	366
	367	@RET@ FcPattern *
	368	@FUNC@ FcNameParse
f2772d6b	369	@TYPE1@ const FcChar8 * @ARG1@ name
22671e25 KP	370	@PURPOSE@ Parse a pattern string
22671e25 KP	371	@DESC@
2df0c662	372	Converts <parameter>name</parameter> from the standard text format described above into a pattern.
22671e25 KP	373	@@
	374
	375	@RET@ FcChar8 *
	376	@FUNC@ FcNameUnparse
	377	@TYPE1@ FcPattern * @ARG1@ pat
	378	@PURPOSE@ Convert a pattern back into a string that can be parsed
	379	@DESC@
	380	Converts the given pattern into the standard text format described above.
	381	The return value is not static, but instead refers to newly allocated memory
	382	which should be freed by the caller.
	383	@@