GpiCreatePS
It is used to create a presentation space (PS). A presentation space is a logical container that is used to hold and manage graphical objects, such as lines, curves, text, and images.
Syntax
GpiCreatePS( hab, hdc, psizlSize, flOptions)
or
HPS GpiCreatePS(HAB hab, HDC hdc, PSIZEL psizl, ULONG flOptions)
Parameters
- hab (HAB) - input
- A handle to an anchor block (AB) that identifies the process that is creating the PS.
- hdc (HDC) - input
- A handle to a device context (DC) that specifies the device that the PS will be associated with.
- psizlSize (PSIZEL) - input
- A PSIZEL structure that specifies the size and resolution of the PS.
- flOptions (ULONG)
- A set of flags that specify options for creating the PS.
Returns
- rc (HPS)
- The function returns a handle to the created PS, or NULL if an error occurs.
Errors
- ERROR_INVALID_HANDLE
- The handle to the anchor block (hab) or the device context (hdc) is invalid.
- ERROR_INVALID_PARAMETER
- The psizl parameter is invalid or NULL.
- ERROR_NOT_ENOUGH_MEMORY
- There is not enough memory available to create the PS.
- ERROR_INVALID_FLAGS
- The flOptions parameter specifies an invalid combination of flags.
Remarks
There are two types of presentation spaces:
- Micro presentation space
- Normal presentation space.
Only a restricted subset of calls is allowed to a micro presentation space; the main difference is that graphic segments (primitives, attributes, and so on) can be retained by the system, for subsequent redraw or editing, in a normal presentation space, but not in a micro presentation space. However, the storage and execution overheads are lower for a micro presentation space.
An initial association of the new presentation space with a device context may be performed (this is mandatory for a micro presentation space), by specifying GPIA_ASSOC.
When a presentation space is associated with a device context, either using this function with GPIA_ASSOC, or explicitly with GpiAssociate, a page viewport in device space is automatically constructed, to which the page is mapped to form the device transform. The value of PS_UNITS and the psizlSize parameter, are taken into account.
In general, the size parameter can be safely set to zeroes except when using PU_ARBITRARY units. In that case, use a size in device coordinates obtained from DevQueryCaps. For units other than PU_PELS, a non-zero size can cause a transform to be in effect for the resulting PS.
Sample
This example uses the GpiCreatePS function to create a micro presentation space for a memory device context. The function associates the presentation space with the device context and sets the page units to pels. By default, the presentation space is a normal presentation space that uses local storage format.
#define INCL_GPICONTROL /* GPI control Functions */
#include <os2.h>
HAB hab; /* anchor block handle */
HDC hdc; /* device context handle */
HPS hps; /* presentation space handle */
SIZEL sizl = { 0, 0 }; /* use same page size as device */
/**************************
* context data structure *
**************************/
DEVOPENSTRUC dop = {0L, "DISPLAY", NULL, 0L, 0L, 0L, 0L, 0L, 0L};
/* create memory device context */
hdc = DevOpenDC(hab, OD_MEMORY, "*", 5L, (PDEVOPENDATA)&dop, NULLHANDLE);
/* Create the presentation and associate the memory device
context. */
hps = GpiCreatePS(hab, hdc, &sizl, PU_PELS |
GPIT_MICRO | GPIA_ASSOC);
Other sample:
HAB hab;
HDC hdc;
PSIZEL psizl;
HPS hps;
hab = WinQueryAnchorBlock(HWND_DESKTOP);
hdc = WinOpenWindowDC(HWND_DESKTOP);
psizl.cx = 640;
psizl.cy = 480;
hps = GpiCreatePS(hab, hdc, &psizl, PU_PELS | GPIF_DEFAULT);
if (hps == NULL) {
// An error occurred, handle it here
}