SAVESCREEN()
 Save a screen region for later display
------------------------------------------------------------------------------
 Syntax

     SAVESCREEN([<nTop>], [<nLeft>],
        [<nBottom>], [<nRight>]) --> cScreen

 Arguments

     <nTop>, <nLeft>, <nBottom>, and <nRight> define the
     coordinates of the screen region to be saved.  If either <nBottom> or
     <nRight> is greater than MAXROW() or MAXCOL(), the screen is clipped.
     If you specify no coordinates, the entire screen (i.e., from 0,0 to
     MAXROW(), MAXCOL()) is saved.

 Returns

     SAVESCREEN() returns the specified screen region as a character string.

 Description

     SAVESCREEN() is a screen function that saves a screen region to a
     variable of any storage class including a field variable.  Later, you
     can redisplay the saved screen image to the same or a new location using
     RESTSCREEN().  Screen regions are usually saved and restored when using
     a pop-up menu routine or dragging a screen object.

     Warning!  SAVE SCREEN, RESTORE SCREEN, SAVESCREEN(), and
     RESTSCREEN() are supported when using the default (IBM PC memory mapped)
     screen driver.  Other screen drivers may not support saving and
     restoring screens.

 Examples

     .  The following user-defined function creates a pop-up menu
        using ACHOICE() with SAVESCREEN() and RESTSCREEN(), returning the
        selection in the array of choices:

        FUNCTION PopMenu( nTop, nLeft, nBottom, nRight, ;
                             aItems, cColor )
           LOCAL cScreen, nChoice, cLastColor := ;
                 SETCOLOR(cColor)
           //
           cScreen:= SAVESCREEN(nTop, nLeft, nBottom, nRight)
           @ nTop, nLeft TO nBottom, nRight DOUBLE
           //
           nChoice:= ACHOICE(++nTop, ++nLeft, ;
                        --nBottom, --nRight, aItems)
           //
           RESTSCREEN(--nTop, --nLeft, ++nBottom, ++nRight, ;
                          cScreen)
           SETCOLOR(cLastColor)
           RETURN nChoice

 Files   Library is EXTEND.LIB.

See Also: RESTSCREEN()