DISPBOX()
 Display a box on the screen
------------------------------------------------------------------------------
 Syntax

     DISPBOX(<nTop>, <nLeft>, <nBottom>, <nRight>,
        [<cnBoxString>], [<cColorString>]) --> NIL

 Arguments

     <nTop>, <nLeft>, <nBottom>, and <nRight> define the
     coordinates of the box.  DISPBOX() draws a box using row values from
     zero to MAXROW(), and column values from zero to MAXCOL().  If <nBottom>
     and <nRight> are larger than MAXROW() and MAXCOL(), the bottom-right
     corner is drawn off the screen.

     <cnBoxString> is a numeric or character expression that defines the
     border characters of the box.  If specified as a numeric expression, a
     value of 1 displays a single-line box and a value of 2 displays a
     double-line box.  All other numeric values display a single-line box.

     If <cnBoxString> is a character expression, it specifies the characters
     to be used in drawing the box.  This is a string of eight border
     characters and a fill character.  If <cnBoxString> is specified as a
     single character, that character is used to draw the whole box.

     If this argument is not specified, a single-line box is drawn.

     <cColorString> defines the display color of the box that is drawn.
     If not specified, the box is drawn using the standard color setting of
     the current system color as defined by SETCOLOR().

 Returns

     DISPBOX() always returns NIL.

 Description

     DISPBOX() is a screen function that draws a box at the specified display
     coordinates in the specified color.  If you specify <cnBoxString>,
     DISPBOX() draws a box on the screen using configurable border and fill
     characters.  DISPBOX() draws the box using <cnBoxString> 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 DISPBOX() executes, the cursor is located in the upper corner of
     the boxed region at <nTop> + 1 and <nLeft> + 1.  ROW() and COL() are
     also updated to reflect the new cursor position.

     Note that Box.ch, located in \INCLUDE, provides constants for various
     border configurations.

 Examples

     .  This code example displays a double-line box using a numeric
        value to specify the box border:

        #define B_SINGLE   1
        #define B_DOUBLE   2
        //
        DISPBOX(1, 1, 10, 10, B_DOUBLE, "BG+/B")

     .  This example displays a single-line top and double-line side
        box by specifying border characters with a manifest constant defined
        in Box.ch:

        #include "Box.ch"
        //
        DISPBOX(1, 1, 10, 10, B_SINGLE_DOUBLE, "BG+/B")

 Files:  Library is CLIPPER.LIB, header file is Box.ch.