@database "diskfont"
@master "ADCD_v1.2:IncludesD/Inc&AD1.3/doc/diskfont.doc"

@Node Main "diskfont.doc"
@TOC 1.3Includes_Autodocs/Autodocs

@{" AvailFonts() " Link "AvailFonts()"}             @{" NewFontContents() " Link "NewFontContents()"}
@{" DisposeFontContents() " Link "DisposeFontContents()"}    @{" OpenDiskFont() " Link "OpenDiskFont()"}

@EndNode

@Node "AvailFonts()" "diskfont.library/AvailFonts"

NAME
    @{"AvailFonts" Link "ADCD_v1.2:Inc&AD1.3/Includes/libraries/diskfont.h/Main" 64} - build an array of all fonts in memory / on disk

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

FUNCTION
    @{"AvailFonts" Link "ADCD_v1.2:Inc&AD1.3/Includes/libraries/diskfont.h/Main" 64} 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" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/diskfont/OpenDiskFont()"}, those already in memory are accessed via
    @{"OpenFont" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/graphics/OpenFont()"}.  The @{"TextAttr" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/text.h/Main" 46} structure required by the open calls
    is part of the information @{"AvailFonts" Link "ADCD_v1.2:Inc&AD1.3/Includes/libraries/diskfont.h/Main" 64} supplies.

    When @{"AvailFonts" Link "ADCD_v1.2:Inc&AD1.3/Includes/libraries/diskfont.h/Main" 64} 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.
    If the second @{"AvailFonts" Link "ADCD_v1.2:Inc&AD1.3/Includes/libraries/diskfont.h/Main" 64} call fails, abort the operation.

INPUTS
    buffer - memory to be filled with struct @{"AvailFontsHeader" Link "ADCD_v1.2:Inc&AD1.3/Includes/libraries/diskfont.h/Main" 69}
            followed by an array of @{"AvailFonts" Link "ADCD_v1.2:Inc&AD1.3/Includes/libraries/diskfont.h/Main" 64} elements, which
            contains entries for the available fonts and their
            names.
    bufBytes - the number of bytes in the buffer
    types - 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.  Both can be specified.

RESULTS
    buffer - filled with struct @{"AvailFontsHeader" Link "ADCD_v1.2:Inc&AD1.3/Includes/libraries/diskfont.h/Main" 69} followed by the
            @{"AvailFonts" Link "ADCD_v1.2:Inc&AD1.3/Includes/libraries/diskfont.h/Main" 64} 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" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/diskfont/OpenDiskFont()"} of it may
            fail.
    error - if non-zero, this indicates the number of bytes needed
            for @{"AvailFonts" Link "ADCD_v1.2:Inc&AD1.3/Includes/libraries/diskfont.h/Main" 64} in addition to those supplied.  Thus
            structure elements were not returned because of
            insufficient bufBytes.

@EndNode

@Node "DisposeFontContents()" "diskfont.library/DisposeFontContents"

NAME
    DisposeFontContents - free the result from @{"NewFontContents" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/diskfont/NewFontContents()"}

SYNOPSIS
    DisposeFontContents(fontContentsHeader)
                        A1

FUNCTION
    This function frees the array of FontContents entries
    returned by @{"NewFontContents" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/diskfont/NewFontContents()"}.

INPUTS
    fontContentsHeader - a struct @{"FontContentsHeader" Link "ADCD_v1.2:Inc&AD1.3/Includes/libraries/diskfont.h/Main" 33} pointer
        returned by @{"NewFontContents" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/diskfont/NewFontContents()"}.

EXCEPTIONS
    This command was first made available as of version 34.

    A fontContentsHeader other than one acquired by a call
    @{"NewFontContents" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/diskfont/NewFontContents()"} will crash.

SEE ALSO
    @{"NewFontContents" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/diskfont/NewFontContents()"} to get structure freed here.

@EndNode

@Node "NewFontContents()" "diskfont.library/NewFontContents"

NAME
    NewFontContents - create a FontContents structs for a font

SYNOPSIS
    fontContentsHeader = NewFontContents(fontsLock,fontName)
    D0                                   A0        A1

FUNCTION
    This function creates a new array of FontContents entries
    that describe all the fonts associated with the fontName,
    specifically, all those in the font directory whose name
    is that of the font sans the ".font" suffix.

INPUTS
    fontsLock - a DOS lock on the FONTS: directory (or other
        directory where the font contents file and associated
        font directory resides).
    fontName - the font name, with the ".font" suffix, which
        is also the name of the font contents file.

RESULT
    fontContentsHeader - a struct @{"FontContentsHeader" Link "ADCD_v1.2:Inc&AD1.3/Includes/libraries/diskfont.h/Main" 33} pointer.

EXCEPTIONS
    This command was first made available as of version 34.

    D0 is zero if the fontName is does not have a ".font" suffix,
    or a DOS error occurred, or memory could not be allocated for
    the fontContentsHeader.

SEE ALSO
    @{"DisposeFontContents" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/diskfont/DisposeFontContents()"} to free the structure acquired here.

@EndNode

@Node "OpenDiskFont()" "diskfont.library/OpenDiskFont"

NAME
    OpenDiskFont - load and get a pointer to a disk font.

SYNOPSIS
    font = OpenDiskFont(textAttr)
    D0                  A0

FUNCTION
    This function finds the font with the specified textAttr on
    disk, loads it into memory, and returns a pointer to the font
    that can be used in subsequent @{"SetFont" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/graphics/SetFont()"} and @{"CloseFont" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/graphics/CloseFont()"} calls.
    It is important to match this call with a corresponding
    @{"CloseFont" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/graphics/CloseFont()"} call for effective management of font memory.

    If the font is already in memory, the copy in memory is used.
    The disk copy is not reloaded.

INPUTS
    textAttr - a @{"TextAttr" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/text.h/Main" 46} structure that describes the text font
           attributes desired.

RESULTS
    D0 is zero if the desired font cannot be found.

BUGS
    This routine will not work well with font names whose file
    name components are longer than the maximum allowed
    (30 characters).

@EndNode

