Click above to get retro games delivered to your door ever month!

 FT_RGNSTACK()
 Push or pop a saved screen region on or off the stack
------------------------------------------------------------------------------

 Syntax

      FT_RGNSTACK( <cAction>, [ <nTop> ], [ <nLeft> ], [ <nBottom> ],
         [ <nRight> ] ) -> NIL

 Arguments

     <cAction> determines what action FT_RGNSTACK() will take.  The
     allowable values for this parameter are "push", "pop", and "pop all".
     If the function is called with any other string as the first parameter
     no action is performed.

     <cAction> with a value of "push" will push a saved screen region onto
     the stack.  A value of "pop" will restore the most recently pushed
     screen region.  "pop all" tells the function to restore all screen
     images which are currently on the stack.

     The use of <nTop>, <nLeft>, <nBottom>, and <nRight> depends on the
     <cAction> parameter.  If <cAction> is "push", the next four parameters
     define the screen region to save.  If <cAction> is "pop" or "pop all"
     the following four parameters are ignored.

 Returns

     FT_RGNSTACK() returns NIL.

 Description

     FT_RGNSTACK() allows multiple screens to be saved and restored from
     a stack.  The stack is implemented with Clipper static array that is
     visible only to FT_RGNSTACK().

     The purpose of FT_RGNSTACK() is to allow multiple screen regions to be
     managed without the need to remember the original coordinates or to
     create variables for each one.

     When called with "push", FT_RGNSTACK() places the saved screen area
     at the end of the static array.  The array size is incremented by one
     to accommodate the new screen area.

     When called with "pop", the function restores the screen image stored
     in the last element of the array, and the array size is decremented by
     one.  If "pop all" is specified, all the saved screens are restored
     until the array is empty.

     FT_RGNSTACK() calls FT_SAVRGN() and FT_RSTRGN().  Refer to the
     documentation for these two functions for more information.

 Examples

     The following example uses FT_RGNSTACK() to save and restore various
     sections of the screen.

     @ 00, 00, 24, 79 BOX "111111111"         // fill the screen with 1's
     FT_RGNSTACK("push", 10, 05, 15, 15)      // push a region
     @ 00, 00, 24, 79 BOX "222222222"         // fill the screen with 2's
     FT_RGNSTACK("push", 10, 20, 15, 30)      // push a region
     @ 00, 00, 24, 79 BOX "333333333"         // fill the screen with 3's
     FT_RGNSTACK("push", 10, 35, 15, 45)      // push a region
     @ 00, 00, 24, 79 BOX "444444444"         // fill the screen with 4's
     FT_RGNSTACK("push", 10, 50, 15, 60)      // push a region
     @ 00, 00, 24, 79 BOX "555555555"         // fill the screen with 5's
     FT_RGNSTACK("push", 10, 65, 15, 75)      // push a region
     CLEAR
     FT_RGNSTACK("pop")        // restore the 5's region
     FT_RGNSTACK("pop")        // restore the 4's region
     FT_RGNSTACK("pop all")    // restore the 3's, 2's and 1's regions

 Source: SCREGION.PRG

 Author: David A. Richardson