GpiRestorePS: Difference between revisions
Created page with "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 ''lPS..." |
mNo edit summary |
||
| (One intermediate revision by one other user not shown) | |||
| Line 1: | Line 1: | ||
This function restores the state of the presentation space to the one that exists when the corresponding GpiSavePS is issued. | This function restores the state of the presentation space to the one that exists when the corresponding [[GpiSavePS]] is issued. | ||
==Syntax== | ==Syntax== | ||
GpiRestorePS( | GpiRestorePS(hps, lPSid) | ||
==Parameters== | ==Parameters== | ||
;''hps'' (HPS) - input | ;''hps'' (HPS) - input:Presentation-space handle. | ||
:Presentation-space handle. | ;''lPSid'' (LONG) - input:Identifier of the saved presentation space that is to be restored. | ||
;''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. | :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== | ==Returns== | ||
;''rc'' (BOOL) - returns | ;''rc'' (BOOL) - returns:Success indicator. | ||
:Success indicator. | ::TRUE - Successful completion | ||
: | ::FALSE - Error occurred. | ||
: | |||
==Errors== | ==Errors== | ||
Possible returns from WinGetLastError | Possible returns from WinGetLastError | ||
:PMERR_INV_HPS (0x207F) :An invalid presentation-space handle was specified. | |||
: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. | |||
:An attempt was made to access the presentation space from more than one thread simultaneously. | :PMERR_INV_ID (0x2081) :An invalid lPSid parameter was specified with GpiRestorePS. | ||
:An attempt was made to issue GpiSavePS or GpiRestorePS while the drawing mode was not set to DM_DRAW. | |||
:An invalid lPSid parameter was specified with GpiRestorePS. | |||
==Remarks== | ==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. | 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. | ||
| Line 40: | Line 29: | ||
Any clip regions selected into discarded presentation spaces are automatically destroyed. | 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. | 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. | 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== | ==Example Code== | ||
This example restores the state of the presentation space to the one that exists when the corresponding GpiSavePS is issued. | |||
<pre> | <pre> | ||
#define INCL_GPICONTROL | #define INCL_GPICONTROL | ||
#include <os2.h> | #include <os2.h> | ||
HPS hps; /* presentation space handle */ | HPS hps; /* presentation space handle */ | ||
LONG lPSid; /* the identifier of a saved presentation */ | LONG lPSid; /* the identifier of a saved presentation */ | ||
/* space on the stack. */ | /* space on the stack. */ | ||
GpiRestorePS(hps, lPSid); | GpiRestorePS(hps, lPSid); | ||
</pre> | </pre> | ||
| Line 77: | Line 55: | ||
* [[GpiSetPS]] | * [[GpiSetPS]] | ||
* [[GpiPop]] | * [[GpiPop]] | ||
[[Category:Gpi]] | [[Category:Gpi]] | ||
Latest revision as of 04:13, 26 November 2023
This function restores the state of the presentation space to the one that exists when the corresponding GpiSavePS is issued.
Syntax
GpiRestorePS(hps, 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
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);