_gtRest()
 Display a saved screen region at a specified location
------------------------------------------------------------------------------
 C Prototype

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

 Arguments

     uiTop, uiLeft, uiBottom, and uiRight define the coordinates
     where the saved screen region will be restored.  If uiBottom is greater
     than _gMaxRow() or uiRight is greater than _gtMaxCol(), the screen is
     clipped.

     vlpScrBuff is a far pointer to a character that, in most cases, is a
     value returned from _gtSave().

 Returns

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

 Description

     _gtRest() restores a screen region previously saved with _gtSave().  The
     target screen location may be the same as or different than the original
     location when the screen region was saved.  If you specify a new screen
     location, the new screen region must be the same size or you will get
     ambiguous results.

     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.