GpiSetPS
This function sets the presentation space size, units, and format.
Syntax
GpiSetPS (hps, psizlsize, flOptions)
Parameters
- hps (HPS) - input
- Presentation-space handle.
- psizlsize (PSIZEL) - input
- Presentation-space size.
- flOptions (ULONG) - input
Options.
This contains fields of option bits. For each field, one value should be selected (unless the default is suitable). These values can then be ORed together to generate the parameter.
- PS_UNITS
- Presentation page size units.
- Indicates the units for the presentation page size. In each case, the origin is at the bottom left. Possible values are shown in the following list:
- PU_ARBITRARY
- Application-convenient units
- PU_PELS
- Pel coordinates
- PU_LOMETRIC
- Units of 0.1 mm
- PU_HIMETRIC
- Units of 0.01 mm
- PU_LOENGLISH
- Units of 0.01 inch
- PU_HIENGLISH
- Units of 0.001 inch
- PU_TWIPS
- Units of 1/1440 inch.
- PS_FORMAT
- Coordinate format.
- Indicates options to be used when storing coordinate values internally in the segment store.
- For most calls, the format is not directly visible to an application. However, it is visible during editing (for example, GpiQueryElement). The format also has an effect on the amount of storage required for segment store.
One of these can be selected, for a GPIT_NORMAL presentation space (for a GPIT_MICRO presentation space, only GPIF_DEFAULT is allowed):
- GPIF_DEFAULT
- Default local format (same as GPIF_LONG)
- GPIF_SHORT
- 2-byte integers
- GPIF_LONG
- 4-byte integers.
- PS_NORESET
- Inhibit full reset indicator.
- Inhibits the full reset of the presentation space. If this flag is set, a reset equivalent to GRES_SEGMENTS is performed. If it is not set, a full reset (GRES_ALL) is performed.
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_INV_HDC (0x207C)
- An invalid device-context handle or (micro presentation space) presentation-space handle was specified.
- PMERR_INV_PS_SIZE (0x20BA)
- An invalid size parameter was specified with GpiCreatePS or GpiSetPS.
- PMERR_INV_OR_INCOMPAT_OPTIONS (0x20A9)
- An invalid or incompatible (with micro presentation space) options parameter was specified with GpiCreatePS or GpiSetPS.
- PMERR_INV_FOR_THIS_DC_TYPE (0x2074)
- An attempt has been made to issue GpiRemoveDynamics or GpiDrawDynamics to a presentation space associated with a metafile device context.
Remarks
The presentation space is re-initialized to the same state that occurs as if it had been created using the specified size and option values; however, whether the presentation space is a micro presentation space or a normal presentation space cannot be changed, and any device context that is already associated remains associated.
The presentation space code page is set to the current process code page.
On completion, the presentation space is reset with the equivalent of GRES_ALL (see GpiResetPS), unless PS_NORESET is specified, in which case only the equivalent of a GRES_SEGMENTS reset is performed.
This function cannot be used to a presentation space that is associated with a device context of type OD_QUEUED, OD_METAFILE, or OD_METAFILE_NOQUERY.
The following options for flOptions are ignored:
- PS_TYPE
- Presentation space.
- PS_MODE
- Mode
- PS_ASSOCIATE
- Association indicator
Example Code
#define INCL_GPICONTROL /* Or use INCL_GPI, INCL_PM, */ #include <os2.h> HPS hps; /* Presentation-space handle. */ PSIZEL psizlsize; /* Presentation-space size. */ ULONG flOptions; /* Options. */ BOOL rc; /* Success indicator. */ rc = GpiSetPS(hps, psizlsize, flOptions);
In this example, GpiSetPS is used to reset the presentation space.
#include <OS2.H>
#define INCL_GPICONTROL
HPS hps; /* presentation space handle */
PSIZEL psizlsize; /* presentation space size */
ULONG flOptions; /* reset options */
flOptions = PU_ARBITRARY | /* arbitrary units */
GPIF_DEFAULT; /* normal ps format */
GpiSetPS(hps, psizlsize, flOptions);