_gtSave()
 Save a screen region for later display
------------------------------------------------------------------------------
 C Prototype

     #include "gt.api"
     ERRCODE _gtSave(
                      USHORT uiTop,
                      USHORT uiLeft,
                      USHORT uiBottom,
                      USHORT uiRight,
                      FARP vlpScrBuff
                    )

 Arguments

     uiTop, uiLeft, uiBottom, and uiRight define the coordinates
     of the screen region to save.  If uiBottom is greater than _gMaxRow() or
     uiTop is greater than _gtMaxCol(), the screen is clipped.

     vlpScrBuff is a far pointer to a character string.  To make sure the
     string is large enough to hold the screen region, use _gtRectSize().

 Returns

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

 Description

     _gtSave() saves a screen region to a character string.  Later, you can
     redisplay the saved screen image to the same location, or to a new
     location using _gtRest().

     Some examples of when you might use _gtSave() and _gtRest() are to
     display a pop-up menu or to drag a screen object.

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

 Examples

     .  In this example, _gtRest() and _gtSave() create a see through
        shadow on the screen.  By not manipulating the video memory directly,
        the subroutine RevForeAttr() ensures the integrity of the General
        Terminal system and does not destroy any screen buffers that may be
        in use.  To insure proper memory usage, RevForeAttr() uses the
        Virtual Memory API for screen saves (see the "Virtual Memory API
        Reference" chapter of this guide):

        #include "vm.api"
        #include "gt.api"

        void near Shadow( USHORT uiTRow, USHORT uiLCol,
                          USHORT uiBRow, USHORT uiRCol );

        HIDE void near RevForeAttr( USHORT uiTRow,
                                    USHORT uiLCol,
                                    USHORT uiBRow,
                                    USHORT uiRCol );

        void near Shadow( USHORT uiTRow, USHORT uiLCol,
                          USHORT uiBRow, USHORT uiRCol )
        {
           /* Draw shadow on right side */
           RevForeAttr( uiTRow+1, uiRCol+1, uiBRow+1, uiRCol+2 );

           /* Draw shadow on bottom */
           RevForeAttr( uiBRow+1, uiLCol+2, uiBRow+1, uiRCol );

        }




        /***
        *   Reverse text Attribute for
        *   passed coordinates
        */

        HIDE void near RevForeAttr( USHORT uiTRow,
                                    USHORT uiLCol,
                                    USHORT uiBRow,
                                    USHORT uiRCol )
        {
           FARP vlpScreen;
           HANDLE hVM;
           USHORT uiBuffSize;

           USHORT uiRow;
           USHORT uiCol;
           USHORT i;

           _gtRectSize( uiTRow, uiLCol, uiBRow, uiRCol, &uiBuffSize );

           if !( hVM = _xvalloc( uiBuffSize ) )
              return;

           vlpScreen = _xvlock( hVM );

           _gtSave( uiTRow, uiLCol, uiBRow, uiRCol, vlpScreen );

           for ( uiRow = uiTRow; uiRow <= uiBRow; ++uiRow )
           {
              i = ( (uiRow - uiTRow) * (uiRCol - uiLCol + 1)
                    * 2 ) + 1;
              for ( uiCol = uiLCol; uiCol <= uiRCol; ++uiCol, i += 2 )
              {
                 vlpScreen[i] &= 0x0007;
                 if( !vlpScreen[i] ) vlpScreen[i] = 0x0008;
              }
           }
           _gtRest( uiTRow, uiLCol, uiBRow, uiRCol, vlpScreen );
        }

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