FONTLOAD()
 Loads EGA/VGA fonts from another file
------------------------------------------------------------------------------
 Syntax

     FONTLOAD(<cFileName>, <nFontArea>, [<nOffset>],
        [<nCounter>]) --> nErrorCode

     or

     FONTLOAD (<cFileName>, <nFontArea>,
        [<lOtherPixelHeight>])--> nErrorCode

 Arguments

     <cFileName>  Designates the name and path of the font file.

     <nFontArea>  Designates the number of the specified font area.  For
     EGA, the values 1 to 4 are allowed, or whatever values MAXFONT()
     permits.  For VGA, the values 1 to 8 are allowed, or whatever MAXFONT()
     permits.

     <nOffset>  Designates from what character position the screen
     adapter font table is overwritten.  The default value is 0.

     <nCounter>  Designates how many characters to load from the new
     font.  The default value is 256.

     <lOtherPixelHeight>  Designates .T. to allow the function to modify
     the pixel height.  This leads to a mode change and character count.
     Please note that you must designate both <nOffset> and <nCounter> to
     implement this parameter.

 Returns

     The function returns an error code which corresponds to the explanation
     below:

     Table 6-1: Values returned for FONTLOAD()
     ------------------------------------------------------------------------
     Error Code   Explanation
     ------------------------------------------------------------------------
      0           Font loaded successfully
     -2           Impossible in current video mode
     -3           Font file not found
     -4           The <lOtherPixelHeight> mode is not possible (the Extended
                  Drivers are not linked in)
     ------------------------------------------------------------------------

 Description

     FONTLOAD() allows you to load the font definitions from a file into the
     font area of an EGA or VGA card.  Use FONTSELECT() to determine which
     fonts serve as normal and high density for output.

     You may already have some of these fonts on the CA-Clipper Tools disk,
     and others can be created with the accompanying font editor.

 Technical Background

     The EGA and VGA cards permit you to modify a portion or all 256
     characters of the character generator with software.  To do this, a
     previously created pixel pattern for the character is loaded in the
     corresponding position in a font area on the screen card.  Normally, an
     EGA card has a maximum of four font areas and a VGA has eight, within
     which you can redefine all 256 characters.  Use MAXFONT() to determine
     the exact count of font areas.

     Building fonts into a program requires unnecessary memory space.
     Constructing fonts as a string within a program is also awkward.  With
     the GETFONT() and SETFONT() functions, you can load a font from a screen
     card into a string variable, or from such a variable, into a font area
     on the card.  However, FONTLOAD() only allows you to load a font from a
     file into a particular area of the screen card.  In both cases, use
     ONTSELECT() to activate the loaded font.

     On the CA-Clipper Tools sample disk, you will find a font editor to
     construct new fonts in CA-Clipper source code.

 Variable Pixel Height

     In principle, EGA and VGA screen adapters provide the opportunity to
     display fonts with 2 to 32 pixels per character (1 pixel/character only,
     when there are 200 scan lines).  ROM fonts are only available for pixel
     heights of 8, 14 and 16, which accounts for the great expansion of the
     EGA 25-/43-line modes and VGA 25-/28-/50-line modes.  You must construct
     individual fonts for all other pixel heights.  The CA-Clipper font
     editor can make this easy.

     When FONTLOAD() loads a font, it also computes the pixel height from the
     font data length.  Since a font file always contains all 256 character
     definitions, there is a formula:

        Pixel height = LEN(Font-Data)/256

     The <lOtherPixelHeight> parameter determines whether the fonts that do
     not match the pixel height just set are accepted.  This must be
     explicitly indicated, since the line count and screen mode will change.
     For this reason, you must always link in the CTUS.LIB Extended Drivers
     (see Table 6-1, returned value -4).

 Notes

     .  You cannot use FONTRESET() when a font is loaded for which
        there is no associated ROM font (all pixel heights except 8, 14, 16).
        Prior to a FONTRESET(), switch back to a permissible mode.

     .  All previously successful FONTSELECT() settings are discarded
        again during FONTLOAD().

     .  If an EGA card does not span the entire memory range, then you
        can reduce a maximum of four available font areas.  MAXFONT()
        determines the number of available fonts.

 Examples

     .  Load all 256 characters of an EGA font in area 2:

        ? FONTLOAD("\FONTS\OLDENG.014", 2)              // 0 OK<
        FONTSELECT(2)

     .  Exchange the fonts for the upper 128 characters in area 3:

        ? FONTLOAD("\FONTS\OLDENG.EGA", 3, 128, 128)    // 0 OK
        FONTSELECT(3)                                   // Select

     .  Load a 24-pixel font in the last font area:

        ? FONTLOAD("\FONTS\PC.024", MAXFONT(), .T.)