Click above to get retro games delivered to your door ever month!

 _gtBox()
 Draw a box on the screen
------------------------------------------------------------------------------
 C Prototype

     #include "gt.api"
     ERRCODE _gtBox(
                     USHORT uiTop,
                     USHORT uiLeft,
                     USHORT uiBottom,
                     USHORT uiRight,
                     BYTEP fpBoxString
                   )

 Arguments

     uiTop, uiLeft, uiBottom, and uiRight define the coordinates
     of the box.  Allowable row values are from zero to _gtMaxRow() and
     allowable column values are from zero to _gtMaxCol().  Coordinates that
     are not within this range will result in that area being drawn off the
     screen.

     fpBoxString defines a string of eight border characters and a fill
     character to be used in drawing the box.

 Returns

     _gtBox() returns zero if successful.  Any other value indicates an
     error.

 Description

     _gtBox() draws a box at the specified display coordinates.  _gtBox()
     draws the box using the characters in fpBoxString starting from the
     upper lefthand corner, proceeding clockwise and filling the screen
     region with the ninth character.  If the ninth character is not
     specified, the screen region within the box is not painted.  Existing
     text and color remain unchanged.

     After _gtBox() executes, the cursor is located in the upper corner of
     the boxed region (uiTop + 1 and uiLeft + 1).  The internal row and
     column coordinates are updated so the CA-Clipper functions, ROW() and
     COL() will reflect the new cursor position.

     The following table shows the manifest constants defined in Gt.api that
     you can use with this function to facilitate its use:

     Manifest Constants for Box Drawing
     ------------------------------------------------------------------------
     Gt.api              Description
     ------------------------------------------------------------------------
     _B_SINGLE           Single-line box
     _B_DOUBLE           Double-line box
     _B_SINGLE_DOUBLE    Single horizontal lines, double vertical lines
     _B_DOUBLE_SINGLE    Double horizontal lines, single vertical lines
     ------------------------------------------------------------------------

 Examples

     .  This example draws framed text at a specified screen row and
        column.  The frame is made up of single horizontal lines and double
        vertical lines:

        #include "gt.api"

        void boxText( USHORT uiRow, USHORT uiCol, BYTEP fpStr );

        void boxText( USHORT uiRow, USHORT uiCol, BYTEP fpStr )
        {
           _gtBox( uiRow, uiCol, uiRow + 2, uiCol + strlen( fpStr ) + 2,
                   _B_SINGLE_DOUBLE );
           _gtWrite( fpStr, strlen( fpStr ) );
        }

 Files:  Library is CLIPPER.LIB, header file is Gt.api.