ShadowBox()
 Display a shadowed box save the background.
-------------------------------------------------------------------------------

 Syntax:

     ShadowBox( <nTop>, <nLeft>, <nBottom>, <nRight>,
        [<cnBoxString>], [<cColorString>], [<lShadow>] ) --> <cScreenImage>

 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 0 displays no box, 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().

     <lShadow> is an optional parameter which indicates whether the box is
     to be shadowed or not.  The default is determined by SetShadow().

 Returns:

     ShadowBox() always returns the screen image under it along with the
     coordinates burned into it.

 Description:

     ShadowBox() is a screen function that draws a box at the specified
     display coordinates in the color specified.  If <cnBoxString> is
     specified ShadowBox() draws a box on the screen using configurable
     border and fill characters.  ShadowBox() draws the box using
     <cnBoxString> starting from the upper left hand 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 ShadowBox() 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, is supplied with constants
     for various border configurations.

 Examples:

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

        #define B_SINGLE 1
        #define B_DOUBLE 2
        //
        cScreen := ShadowBox(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"
        //
        cScreen := ShadowBox(1, 1, 10, 10, B_SINGLE_DOUBLE, "BG+/B")


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