GpiRestorePS
This function restores the state of the presentation space to the one that exists when the corresponding GpiSavePS is issued.
Syntax
GpiRestorePS(HPS hps, LONG lPSid)
Parameters
- hps (HPS) - input
- Presentation-space handle.
- lPSid (LONG) - input
- Identifier of the saved presentation space that is to be restored.
- If an error is returned, the stack is unchanged, as is the current presentation space.
- >0
- lPSid must be the identifier of a saved presentation space on the stack. It is an error if it does not exist.
- 0
- Is an error. (This might have resulted from an invalid use of GpiSavePS).
- <0
- The absolute value of lPSid indicates how many saved presentation spaces on the stack are required. Thus -1 means that the most recently saved one is to be restored. It is an error if the absolute value is larger than the number of entries on the stack.
Returns
- rc (BOOL) - returns
- Success indicator.
- TRUE
- Successful completion
- FALSE
- Error occurred.
Errors
Possible returns from WinGetLastError
- PMERR_INV_HPS (0x207F)
- An invalid presentation-space handle was specified.
- PMERR_PS_BUSY (0x20F4)
- An attempt was made to access the presentation space from more than one thread simultaneously.
- PMERR_NOT_IN_DRAW_MODE (0x20DE)
- An attempt was made to issue GpiSavePS or GpiRestorePS while the drawing mode was not set to DM_DRAW.
- PMERR_INV_ID (0x2081)
- An invalid lPSid parameter was specified with GpiRestorePS.
Remarks
The most recently saved presentation space need not be the one that is restored. In this case, any that are skipped over on the stack are discarded.
Any clip regions selected into discarded presentation spaces are automatically destroyed.
This function is valid in an open element bracket and in an open segment bracket if the drawing mode (see GpiSetDrawingMode) is set to draw and within an open element bracket. If it occurs within an open area or path bracket, the corresponding GpiSavePS must have taken place earlier in the same bracket.
It is recommended that GpiSavePS and GpiRestorePS are used in pairs and are NOT split across page boundaries in a multiple-page print job.
Example Code
Definition:
#define INCL_GPICONTROL /* Or use INCL_GPI, INCL_PM, Also in COMMON section */ #include <os2.h> HPS hps; /* Presentation-space handle. */ LONG lPSid; /* Identifier of the saved presentation space that is to be restored. */ BOOL rc; /* Success indicator. */ rc = GpiRestorePS(hps, lPSid);
This example restores the state of the presentation space to the one that exists when the corresponding GpiSavePS is issued.
#define INCL_GPICONTROL
#include <OS2.H>
HPS hps; /* presentation space handle */
LONG lPSid; /* the identifier of a saved presentation */
/* space on the stack. */
GpiRestorePS(hps, lPSid);