◄Function Group►  ◄Overview►                          ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
#define INCL_GPICONTROL
 
BOOL GpiRestorePS(hps, idPS)
HPS hps;      /* presentation-space handle             */
LONG idPS;    /* identifier for the presentation space */
 
The GpiRestorePS function restores the state of the presentation space by
popping the state from the presentation space (PS) stack. The function sets
the attributes and resources of the presentation space to the values that
were saved previously by using the GpiSavePS function.
 
The PS stack, maintained internally by the system, can contain one or more
saved presentation spaces. Each saved presentation space has a unique
identifier. The GpiRestorePS function restores a specific presentation space
if the idPS parameter contains the corresponding identifier. The function
also accepts negative identifiers. In this case, the function uses the
absolute value of the identifier to determine how many presentation spaces
to pop from the PS stack. For example, if it is -2, the function pops two
presentation spaces from the stack. In either case, identifier or negative
number, the function discards any presentation spaces that are skipped over
on the PS stack.
 
Parameter  Description
────────────────────────────────────────────────────────────────────────────
 
hps        Identifies the presentation space.
 
idPS       Specifies the identifier of the saved presentation space to
           restore, or a negative number indicating the number of saved
           presentation spaces to pop. If it is an identifier, it must have
           been returned previously by the GpiSavePS function. It must not
           be zero.
 
Return Value
 
The return value is GPI_OK if the function is successful or GPI_ERROR if an
error occurred.
 
Errors
 
Use the WinGetLastError function to retrieve the error value, which may be
one of the following:
 
     PMERR_INV_HPS
     PMERR_INV_ID
     PMERR_NOT_IN_DRAW_MODE
     PMERR_PS_BUSY
 
Comments
 
The function can be used in an open segment only if the drawing mode is
DM_DRAW. The function can also be used in an element, area, or path bracket.
If it is in an area or path bracket, the corresponding GpiSavePS function
must have been called in the same bracket.
 
If an error occurs, the function leaves the PS stack and the current
presentation space unchanged.
 
See Also
 
GpiPop, GpiSavePS, GpiSetDrawingMode, WinGetLastError
 
                                      ♦