[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.
             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 existence 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
      */