<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