[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@		void
@FUNC@		FcPatternDestroy
@TYPE1@		FcPattern * 			@ARG1@		 p
@PURPOSE@	Destroy a pattern
@DESC@
Destroys a 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 char *			@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
@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++@	char **const			@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 
@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
@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.
@@

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