[Contents] [Index] [Help] [Retrace] [Browse <] [Browse >]


   NAME
	AvailFonts -- Inquire available memory & disk fonts.

   SYNOPSIS
	error = AvailFonts(buffer, bufBytes, flags);
	                   A0      D0        D1

	LONG AvailFonts( struct AvailFontsHeader *buffer, LONG bufBytes
		ULONG flags );

   FUNCTION
	AvailFonts fills a user supplied buffer with the structure,
	described below, that contains information about all the
	fonts available in memory and/or on disk.  Those fonts
	available on disk need to be loaded into memory and opened
	via OpenDiskFont, those already in memory are accessed via
	OpenFont.  The TextAttr structure required by the open calls
	is part of the information AvailFonts supplies.

	When AvailFonts fails, it returns the number of extra bytes
	it needed to complete the command.  Add this number to your
	current buffer size, allocate a new buffer, and try again.

   INPUTS
	buffer - memory to be filled with struct AvailFontsHeader
		followed by an array of AvailFonts elements, which
		contains entries for the available fonts and their
		names.

	bufBytes - the number of bytes in the buffer
	flags - AFF_MEMORY is set to search memory for fonts to fill
		the structure, AFF_DISK is set to search the disk for
		fonts to fill the structure.  AFF_SCALED is set to
		not filter out memory fonts that are not designed.
		AFF_BITMAP is set to filter out fonts that are not
		stored in Amiga font format, i.e. to filter out
		outline fonts.  Any combination may be specified.
		AFF_TAGGED is set to fill the buffer with TAvailFonts
		elements instead of AvailFonts elements.

   RESULTS
	buffer - filled with struct AvailFontsHeader followed by the
		[T]AvailFonts elements, There will be duplicate entries
		for fonts found both in memory and on disk, differing
		only by type.  The existance of a disk font in the
		buffer indicates that it exists as an entry in a font
		contents file -- the underlying font file has not been
		checked for validity, thus an OpenDiskFont of it may
		fail.
	error - if non-zero, this indicates the number of bytes needed
		for AvailFonts in addition to those supplied.  Thus
		structure elements were not returned because of
		insufficient bufBytes.

   EXAMPLE
	int afShortage, afSize;
	struct AvailFontsHeader *afh;

	...

	afSize = 400;
	do {
	    afh = (struct AvailFontsHeader *) AllocMem(afSize, 0);
	    if (afh) {
	        afShortage = AvailFonts(afh, afSize, AFF_MEMORY|AFF_DISK);
	        if (afShortage) {
	            FreeMem(afh, afSize);
	            afSize += afShortage;
	        }
	    }
	    else {
	        fail("AllocMem of AvailFonts buffer afh failedn");
	        break;
	    }
	}
	    while (afShortage);

	/*
	 * if (afh) non-zero here, then:
	 * 1. it points to a valid AvailFontsHeader
	 * 2. it must have FreeMem(afh, afSize) called for it after use
	 */