GpiSavePS

This function saves information about the presentation space on a LIFO (last in, first out) stack.

Syntax

GpiSavePS (hps)

Parameters

hps (HPS) - input

Presentation-space handle.

Returns

lPSid (LONG) - returns

Identifier of saved presentation space.

This may be used on a subsequent GpiRestorePS call. The identifier is equal to the depth of the saved presentation space on the save/restore stack, with 1 representing the base level:

>=1

Identifier of saved presentation space

GPI_ERROR

Error.

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.

Remarks

The stack is different from the one used to save attribute values (see GpiSetAttrMode) in a normal presentation space.

This function, and GpiRestorePS, can be used with a micro presentation space, as well as a normal presentation space (in draw drawing mode only).

The presentation space itself is unchanged.

The following are saved:

• Current attributes
• Current transforms, viewing limits, and clip path
• Current position
• Reference to selected clip region
• Any loaded logical color table
• References to any loaded logical fonts
• References to the regions created on the associated device context.

The following are not saved:

• Draw controls
• Drawing mode
• Edit mode and attribute mode
• The visible region.

Note: Only references to resources, rather than the actual resources (such as clip region, logical fonts, and regions) are copied by this function, so the actual resources must not be changed.

This function is valid in an open segment bracket, but only if the drawing mode (see GpiSetDrawingMode) is set to draw. This function can occur within an open element bracket. When it occurs within an open area or path bracket, GpiRestorePS must be called before the bracket is closed.

If this function occurs during the generation of a metafile, the drawing mode must be set to draw when the metafile is replayed.

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

#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 saved presentation space. */

lPSid = GpiSavePS(hps);

This example uses the GpiSavePS function to save the state of the presentation space. The identifier returned by the function is used in the call to the GpiRestorePS function to restore the saved state.

#define INCL_GPICONTROL
#include <OS2.H>

 HPS hps;    /* presentation-space handle. */
 LONG idPS;

 idPS = GpiSavePS(hps);   /* saves the presentation-space state */
      .
      .
      .
 /* restores the presentation-space state */
 GpiRestorePS(hps, idPS);

Related Functions

• GpiAssociate
• GpiCreatePS
• GpiDestroyPS
• GpiQueryDevice
• GpiQueryPS
• GpiResetPS
• GpiRestorePS
• GpiSetPS