home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Programming / Misc / TRSICAT.LZX / CATS_CD2_TRSI / Inc&AD2.1 / Text_Autodocs / diskfont.doc < prev    next >
Encoding:
Text File  |  1992-09-11  |  8.2 KB  |  250 lines
  1. TABLE OF CONTENTS
  2.  
  3. diskfont.library/AvailFonts
  4. diskfont.library/DisposeFontContents
  5. diskfont.library/NewFontContents
  6. diskfont.library/NewScaledDiskFont
  7. diskfont.library/OpenDiskFont
  8. diskfont.library/AvailFonts                       diskfont.library/AvailFonts
  9.  
  10.    NAME
  11.     AvailFonts -- Inquire available memory & disk fonts.
  12.  
  13.    SYNOPSIS
  14.     error = AvailFonts(buffer, bufBytes, flags);
  15.                        A0      D0        D1
  16.  
  17.     LONG AvailFonts( struct AvailFontsHeader *buffer, LONG bufBytes
  18.         ULONG flags );
  19.  
  20.    FUNCTION
  21.     AvailFonts fills a user supplied buffer with the structure,
  22.     described below, that contains information about all the
  23.     fonts available in memory and/or on disk.  Those fonts
  24.     available on disk need to be loaded into memory and opened
  25.     via OpenDiskFont, those already in memory are accessed via
  26.     OpenFont.  The TextAttr structure required by the open calls
  27.     is part of the information AvailFonts supplies.
  28.  
  29.     When AvailFonts fails, it returns the number of extra bytes
  30.     it needed to complete the command.  Add this number to your
  31.     current buffer size, allocate a new buffer, and try again.
  32.  
  33.    INPUTS
  34.     buffer - memory to be filled with struct AvailFontsHeader
  35.         followed by an array of AvailFonts elements, which
  36.         contains entries for the available fonts and their
  37.         names.
  38.  
  39.     bufBytes - the number of bytes in the buffer
  40.     flags - AFF_MEMORY is set to search memory for fonts to fill
  41.         the structure, AFF_DISK is set to search the disk for
  42.         fonts to fill the structure.  AFF_SCALED is set to
  43.         not filter out memory fonts that are not designed.
  44.         AFF_BITMAP is set to filter out fonts that are not
  45.         stored in Amiga font format, i.e. to filter out
  46.         outline fonts.  Any combination may be specified.
  47.         AFF_TAGGED is set to fill the buffer with TAvailFonts
  48.         elements instead of AvailFonts elements.
  49.  
  50.    RESULTS
  51.     buffer - filled with struct AvailFontsHeader followed by the
  52.         [T]AvailFonts elements, There will be duplicate entries
  53.         for fonts found both in memory and on disk, differing
  54.         only by type.  The existance of a disk font in the
  55.         buffer indicates that it exists as an entry in a font
  56.         contents file -- the underlying font file has not been
  57.         checked for validity, thus an OpenDiskFont of it may
  58.         fail.
  59.     error - if non-zero, this indicates the number of bytes needed
  60.         for AvailFonts in addition to those supplied.  Thus
  61.         structure elements were not returned because of
  62.         insufficient bufBytes.
  63.  
  64.    EXAMPLE
  65.     int afShortage, afSize;
  66.     struct AvailFontsHeader *afh;
  67.  
  68.     ...
  69.  
  70.     afSize = 400;
  71.     do {
  72.         afh = (struct AvailFontsHeader *) AllocMem(afSize, 0);
  73.         if (afh) {
  74.             afShortage = AvailFonts(afh, afSize, AFF_MEMORY|AFF_DISK);
  75.             if (afShortage) {
  76.                 FreeMem(afh, afSize);
  77.                 afSize += afShortage;
  78.             }
  79.         }
  80.         else {
  81.             fail("AllocMem of AvailFonts buffer afh failed\n");
  82.             break;
  83.         }
  84.     }
  85.         while (afShortage);
  86.  
  87.     /*
  88.      * if (afh) non-zero here, then:
  89.      * 1. it points to a valid AvailFontsHeader
  90.      * 2. it must have FreeMem(afh, afSize) called for it after use
  91.      */
  92.  
  93. diskfont.library/DisposeFontContents     diskfont.library/DisposeFontContents
  94.  
  95.    NAME
  96.     DisposeFontContents -- Free the result from NewFontContents. (V34)
  97.  
  98.    SYNOPSIS
  99.     DisposeFontContents(fontContentsHeader)
  100.                 A1
  101.  
  102.     VOID DisposeFontContents( struct FontContentsHeader * );
  103.  
  104.    FUNCTION
  105.     This function frees the array of FontContents entries
  106.     returned by NewFontContents.
  107.  
  108.    INPUTS
  109.     fontContentsHeader - a struct FontContentsHeader pointer
  110.         returned by NewFontContents.
  111.  
  112.    EXCEPTIONS
  113.      This command was first made available as of version 34.
  114.  
  115.     A fontContentsHeader other than one acquired by a call
  116.     NewFontContents will crash.
  117.  
  118.    SEE ALSO
  119.     NewFontContents to get structure freed here.
  120.  
  121. diskfont.library/NewFontContents             diskfont.library/NewFontContents
  122.  
  123.    NAME
  124.     NewFontContents -- Create a FontContents image for a font. (V34)
  125.  
  126.    SYNOPSIS
  127.     fontContentsHeader = NewFontContents(fontsLock,fontName)
  128.        D0                                   A0        A1
  129.  
  130.     struct FontContentsHeader *NewFontContents( BPTR, char * );
  131.  
  132.    FUNCTION
  133.     This function creates a new array of FontContents entries
  134.     that describe all the fonts associated with the fontName,
  135.     specifically, all those in the font directory whose name
  136.     is that of the font sans the ".font" suffix.
  137.  
  138.    INPUTS
  139.     fontsLock - a DOS lock on the FONTS: directory (or other
  140.         directory where the font contents file and associated
  141.         font directory resides).
  142.     fontName - the font name, with the ".font" suffix, which
  143.         is also the name of the font contents file.
  144.  
  145.    RESULT
  146.     fontContentsHeader - a struct FontContentsHeader pointer.
  147.  
  148.    EXCEPTIONS
  149.     This command was first made available as of version 34.
  150.  
  151.     D0 is zero if the fontName is does not have a ".font" suffix,
  152.     if the fontName is too long, if a DOS error occurred, or if
  153.     memory could not be allocated for the fontContentsHeader.
  154.  
  155.    SEE ALSO
  156.     DisposeFontContents to free the structure acquired here.
  157.  
  158. diskfont.library/NewScaledDiskFont         diskfont.library/NewScaledDiskFont
  159.  
  160.    NAME
  161.     NewScaledDiskFont -- Create a DiskFont scaled from another. (V36)
  162.  
  163.    SYNOPSIS
  164.     header = NewScaledDiskFont(srcFont, destTextAttr)
  165.     D0                         A0       A1
  166.  
  167.     struct DiskFontHeader *NewScaledDiskFont( struct TextFont *,
  168.         struct TTextAttr * );
  169.  
  170.    INPUTS
  171.     srcFont - the font from which the scaled font is to be
  172.         constructed.
  173.     destTextAttr - the desired attributes for the new scaled
  174.         font.  This may be a structure of type TextAttr or
  175.         TTextAttr.
  176.  
  177.    RESULT
  178.     header - a pointer to a DiskFontHeader structure.  This is not
  179.         being managed by the diskfont.library, however.
  180.  
  181.    NOTES
  182.     o   This function may use the blitter.
  183.     o   Fonts containing characters that render wholly outside
  184.         the character advance cell are currently not scalable.
  185.     o   The font, and memory allocated for the scaled font can
  186.         can be freed by calling StripFont() on the font,
  187.         and then calling UnLoadSeg() on the segment created
  188.         by this function.
  189.  
  190.         Both the TextFont structure, and segment pointer are contained
  191.         within the DiskFontHeader struct.  The DiskFontHeader structure
  192.         will also be freed as part of the UnLoadSeg() call.
  193.         StripFont() is a new graphics.library call as of V36.
  194.  
  195. diskfont.library/OpenDiskFont                   diskfont.library/OpenDiskFont
  196.  
  197.    NAME
  198.        OpenDiskFont - load and get a pointer to a disk font.
  199.  
  200.    SYNOPSIS
  201.        font = OpenDiskFont(textAttr)
  202.        D0                  A0
  203.  
  204.    FUNCTION
  205.        This function finds the font with the specified textAttr on
  206.        disk, loads it into memory, and returns a pointer to the font
  207.        that can be used in subsequent SetFont and CloseFont calls.
  208.        It is important to match this call with a corresponding
  209.        CloseFont call for effective management of font memory.
  210.  
  211.        If the font is already in memory, the copy in memory is used.
  212.        The disk copy is not reloaded.
  213.  
  214.    INPUTS
  215.        textAttr - a TextAttr structure that describes the text font
  216.                attributes desired.
  217.  
  218.    RESULTS
  219.        D0 is zero if the desired font cannot be found.
  220.  
  221.    NOTES
  222.        As of V36, OpenDiskFont() will automatically attempt to
  223.        construct a font for you if:
  224.  
  225.                You have requested a font size which does not exist
  226.                as a designed font, and
  227.  
  228.                You have not set the DESIGNED bit in the ta_Flags
  229.                field of the TextAttr, or TTextAttr struct.
  230.  
  231.        Constructed fonts are created by scaling a designed font.
  232.        A designed font is one which typically resides on disk,
  233.        or in ROM (e.g., a font which has been designed by hand
  234.        using a drawing tool).  Designed fonts generally look better
  235.        than fonts constructed by the font scaler, but designed
  236.        fonts also require disk space for each font size.
  237.  
  238.        Always set the DESIGNED bit if you do not want constructed fonts,
  239.        or use AvailFonts() to find out which font sizes already exist.
  240.        
  241.        As of V37 the diskfont.library supported built-in outline
  242.        fonts.  Then in V38 the outline font engine was moved to
  243.        a new library, "bullet.library."
  244.  
  245.    BUGS
  246.        This routine will not work well with font names whose file
  247.        name components are longer than the maximum allowed
  248.        (30 characters).
  249.  
  250.