[fontconfig.git] / doc / fcfile.fncs

/*
 * fontconfig/doc/fcfile.fncs
 *
 * 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@		FcBool 	
@FUNC@		FcFileScan 
@TYPE1@		FcFontSet *			@ARG1@		set	
@TYPE2@		FcStrSet *			@ARG2@		dirs	
@TYPE3@		FcFileCache *			@ARG3@		cache	
@TYPE4@		FcBlanks *			@ARG4@		blanks	
@TYPE5@		const FcChar8 *			@ARG5@		file	
@TYPE6@		FcBool% 				@ARG6@		force	
@PURPOSE@	scan a font file
@DESC@
Scans a single file and adds all fonts found to <parameter>set</parameter>.
If <parameter>force</parameter> is FcTrue, then the file is scanned even if
associated information is found in <parameter>cache</parameter>.  If
<parameter>file</parameter> is a directory, it is added to
<parameter>dirs</parameter>. Whether fonts are found depends on fontconfig
policy as well as the current configuration. Internally, fontconfig will
ignore BDF and PCF fonts which are not in Unicode (or the effectively
equivalent ISO Latin-1) encoding as those are not usable by Unicode-based
applications. The configuration can ignore fonts based on filename or
contents of the font file itself. Returns FcFalse if any of the fonts cannot be
added (due to allocation failure). Otherwise returns FcTrue.
@@

@RET@		FcBool
@FUNC@		FcFileIsDir
@TYPE1@		const FcChar8 *			@ARG1@		file
@PURPOSE@	check whether a file is a directory
@DESC@
Returns FcTrue if <parameter>file</parameter> is a directory, otherwise
returns FcFalse.
@@

@RET@		FcBool 	
@FUNC@		FcDirScan 
@TYPE1@		FcFontSet *			@ARG1@		set	
@TYPE2@		FcStrSet *			@ARG2@		dirs	
@TYPE3@		FcFileCache *			@ARG3@		cache	
@TYPE4@		FcBlanks *			@ARG4@		blanks	
@TYPE5@		const FcChar8 *			@ARG5@		dir	
@TYPE6@		FcBool% 				@ARG6@		force	
@PURPOSE@	DEPRECATED: formerly used to scan a font directory
@DESC@
This function does nothing aside from returning FcFalse. It used to scan an
entire directory and add all fonts found to
<parameter>set</parameter>.  If <parameter>force</parameter> was FcTrue, then
the directory and all files within it were scanned even if information was
present in the per-directory cache file or <parameter>cache</parameter>. Any
subdirectories found were added to <parameter>dirs</parameter>.
@@

@RET@		FcBool 	
@FUNC@		FcDirSave 
@TYPE1@		FcFontSet *			@ARG1@		set	
@TYPE2@		FcStrSet *			@ARG2@		dirs	
@TYPE3@		const FcChar8 *			@ARG3@		dir	
@PURPOSE@	DEPRECATED: formerly used to save a directory cache
@DESC@
This function now does nothing aside from returning FcFalse. It used to creates the
per-directory cache file for <parameter>dir</parameter> and populates it
with the fonts in <parameter>set</parameter> and subdirectories in
<parameter>dirs</parameter>. All of this functionality is now automatically
managed by FcDirCacheLoad and FcDirCacheRead.
@@
Commit	Line	Data
39381776	1	/*
e690fbb2	2	* fontconfig/doc/fcfile.fncs
39381776	3	*
46b51147	4	* Copyright © 2003 Keith Packard
39381776 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	*/
	24
	25	@RET@ FcBool
	26	@FUNC@ FcFileScan
	27	@TYPE1@ FcFontSet * @ARG1@ set
	28	@TYPE2@ FcStrSet * @ARG2@ dirs
	29	@TYPE3@ FcFileCache * @ARG3@ cache
	30	@TYPE4@ FcBlanks * @ARG4@ blanks
f2772d6b	31	@TYPE5@ const FcChar8 * @ARG5@ file
61895ed1	32	@TYPE6@ FcBool% @ARG6@ force
39381776 KP	33	@PURPOSE@ scan a font file
	34	@DESC@
	35	Scans a single file and adds all fonts found to <parameter>set</parameter>.
	36	If <parameter>force</parameter> is FcTrue, then the file is scanned even if
	37	associated information is found in <parameter>cache</parameter>. If
	38	<parameter>file</parameter> is a directory, it is added to
2ddce88c	39	<parameter>dirs</parameter>. Whether fonts are found depends on fontconfig
a190678e KP	40	policy as well as the current configuration. Internally, fontconfig will
	41	ignore BDF and PCF fonts which are not in Unicode (or the effectively
	42	equivalent ISO Latin-1) encoding as those are not usable by Unicode-based
	43	applications. The configuration can ignore fonts based on filename or
fab44f3c KP	44	contents of the font file itself. Returns FcFalse if any of the fonts cannot be
fab44f3c KP	45	added (due to allocation failure). Otherwise returns FcTrue.
a190678e KP	46	@@
	47
	48	@RET@ FcBool
	49	@FUNC@ FcFileIsDir
	50	@TYPE1@ const FcChar8 * @ARG1@ file
	51	@PURPOSE@ check whether a file is a directory
	52	@DESC@
	53	Returns FcTrue if <parameter>file</parameter> is a directory, otherwise
	54	returns FcFalse.
39381776 KP	55	@@
	56
	57	@RET@ FcBool
	58	@FUNC@ FcDirScan
	59	@TYPE1@ FcFontSet * @ARG1@ set
	60	@TYPE2@ FcStrSet * @ARG2@ dirs
	61	@TYPE3@ FcFileCache * @ARG3@ cache
	62	@TYPE4@ FcBlanks * @ARG4@ blanks
f2772d6b	63	@TYPE5@ const FcChar8 * @ARG5@ dir
61895ed1	64	@TYPE6@ FcBool% @ARG6@ force
fab44f3c	65	@PURPOSE@ DEPRECATED: formerly used to scan a font directory
39381776	66	@DESC@
fab44f3c KP	67	This function does nothing aside from returning FcFalse. It used to scan an
	68	entire directory and add all fonts found to
	69	<parameter>set</parameter>. If <parameter>force</parameter> was FcTrue, then
	70	the directory and all files within it were scanned even if information was
	71	present in the per-directory cache file or <parameter>cache</parameter>. Any
	72	subdirectories found were added to <parameter>dirs</parameter>.
39381776 KP	73	@@
	74
	75	@RET@ FcBool
	76	@FUNC@ FcDirSave
	77	@TYPE1@ FcFontSet * @ARG1@ set
	78	@TYPE2@ FcStrSet * @ARG2@ dirs
f2772d6b	79	@TYPE3@ const FcChar8 * @ARG3@ dir
fab44f3c	80	@PURPOSE@ DEPRECATED: formerly used to save a directory cache
39381776	81	@DESC@
fab44f3c KP	82	This function now does nothing aside from returning FcFalse. It used to creates the
	83	per-directory cache file for <parameter>dir</parameter> and populates it
	84	with the fonts in <parameter>set</parameter> and subdirectories in
	85	<parameter>dirs</parameter>. All of this functionality is now automatically
	86	managed by FcDirCacheLoad and FcDirCacheRead.
39381776 KP	87	@@
39381776 KP	88