SETFONT()
 Loads the font directly out of a string
------------------------------------------------------------------------------
 Syntax

     SETFONT(<cFontString>, [<nFontArea>], [<nOffset>],
        [<nCounter>]) -->nErrorCode

     or

     ETFONT(<cFontString>, [<nFontArea>], [<lCompute>])
        --> nErrorCode

 Arguments

     <cFontString>  Designates a string that contains a valid font
     definition.

     <nFontArea>  Designates the number of the desired font area.  For
     EGA adapters, the values are 1 to 4, for VGA, they are 1 to 8 or the
     number allowed by MAXFONT().

     <nOffset>  Designates the character position at which the font table
     is transmitted to the screen adapter.  The default value is 0.

     <nCounter>  Designates the number of characters for which a new font
     is loaded.  The default value is 256.

     <lCompute>  Use this parameter only when <nOffset> and <nCounter>
     are not in concurrent use.  When designated as .T., the function
     computes the pixel height from the length of the font string.

 Returns

     The function returns an error code with the following definitions:

     Table 6-4: Error Code Definitions
     ------------------------------------------------------------------------
     Error Code   Definition
     ------------------------------------------------------------------------
      0           Font loaded successfully
     -1           Invalid font area designated
     -2           Impossible in current video mode
     -4           The <lOtherPixelHeight> mode is invalid (the Extended
                  Drivers has not been linked in)
     ------------------------------------------------------------------------

 Description

     With SETFONT(), you can load a screen font from a string into the font
     area of an EGA or VGA card.  FONTSELECT() allows you to determine the
     font to serve for normal and the font to serve for high-density output.

 Technical Background

     EGA and VGA cards permit you to modify all 256 characters of the
     character generator or any portion of it with software.  For this
     purpose, load a previously created pixel pattern for the character 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.  You
     can redefine any of the 256 characters within these font areas.  Use
     MAXFONT() to determine the actual number of font areas.

     Building fonts into a program requires unnecessary memory space.  It is
     also awkward to construct string fonts within a program.  The GETFONT()
     and SETFONT() functions 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 offers the ability to load a font from a file
     into a particular area of the screen card.  In both cases, use
     FONTSELECT() to activate the loaded font when necessary.

     To construct new fonts, a font editor is included in CA-Clipper.

 Variable Pixel Height

     In principle, the EGA and VGA screen adapters provide the ability 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 explains the great expansion of the EGA
     25/43-line and VGA 25/28/50-line modes.  You must construct individual
     fonts for all other pixel heights.  This is easy with the
     CA-Clipper Tools font editor.

     If you deviate from the mode just set, use SETFONT() to implement other
     desired pixel heights, where the <lCompute> parameter is designated as
     .T.  The pixel height is computed with the following formula:

               Pixel height = LEN(Font-String)/256

     Partial fonts cannot be used for this calculation, only fonts that
     contain the full 256 characters.

     Since a change in pixel height also leads to a change in the screen mode
     and line count, always link in the CTUS.LIB Extended Drivers.

 Notes

     .  The screen adapters do not permit you to mix fonts with
        different pixel heights.

     .  When an EGA card does not require the full use of memory, you
        can reduce a maximum number of four font areas.  Use MAXFONT() to
        determine the number of available fonts at any given time.

 Examples

     .  Load all 256 font characters in font area 2:

        ? SETFONT(cFontString, 2)      // 0 < OK
        FONTSELECT(2)                  // Font area 2 for<R>
                                       // non-highlighted

     .  Exchange the top 128 characters of a font in font area 3:

        ? SETFONT(cFontString, 3, 128, 128)   // 0 <F128M><142><F255D><N>OK
        FONTSELECT(3)                         // Font area 3 for<R>
                                              // non-highlighted

     .  In this example, the just-installed font height is doubled
        wherever possible.  This is simple, since each byte in the font
        string is doubled:

        cFont  :=  GETFONT()
        SETFONT(CHARMIX(cFont, cFont), .T.)

     .  The font strings can be torn down to individual pixel lines.
        This example shows pixel lines as a bit pattern in a binary display:

        cFont  :=  GETFONT()
        nPixel :=  CHARPIX()

        FOR A = 0 TO 255
           FOR B = 1 TO nPixel
              nByte  := ASC(SUBSTR(cFont, (nPixel * A) + B, 1))
              ? NTOC(nByte, 2, 8, "0")
           NEXT B
           INKEY(0)
           ?
        NEXT A