GpiAssociate

This function associates a graphics presentation space with, or dissociates it from, a device context.

Syntax

GpiAssociate(hps, hdc)

Parameters

hps (HPS) - input

Presentation-space handle.

hdc (HDC) - input

Device-context handle.

rc (BOOL) - returns

Success indicator.

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_PS_IS_ASSOCIATED (0x20F5)

An attempt was made to destroy a presentation or associate a presentation space that is still associated with a device context.

PMERR_DC_IS_ASSOCIATED (0x2017)

An attempt was made to associate a presentation space with a device context that was already associated or to destroy a device context that was associated.

PMERR_INV_MICROPS_FUNCTION (0x20A1)

An attempt was made to issue a function that is invalid in a micro presentation space.

PMERR_INV_HDC (0x207C)

An invalid device-context handle or (micro presentation space) presentation-space handle was specified.

PMERR_REALIZE_NOT_SUPPORTED (0x20F7)

An attempt was made to create a realizable logical color table on a device driver that does not support this function.

PMERR_PATH_INCOMPLETE (0x20EC)

An attempt was made to open or close a segment either directly or during segment drawing, or to issue GpiAssociate while there is an open path bracket.

PMERR_AREA_INCOMPLETE (0x2005)

One of the following has occurred:

• A segment has been opened, closed, or drawn.
• GpiAssociate was issued while an area bracket was open.
• A drawn segment has opened an area bracket and ended without closing it.

Remarks

Any type of device context may be used.

Subsequent drawing functions direct output to the associated device context.

If a null handle is supplied for the device context, the presentation space is dissociated from its currently-associated device context. An associated presentation space cannot be associated with another device context, and an associated device context cannot be associated with another presentation space.

An error occurs if you try to draw to a presentation space associated with a memory device context that has no bit map selected into it (see GpiSetBitmap).

The processing described for GRES_ATTRS (see GpiResetPS) is performed on the presentation space. Also, bounds data is destroyed, the page viewport is reset to its default value (see GpiCreatePS), and any clip region and path definition are lost. The save/restore presentation-space stack (see GpiSavePS) is purged.

Any palette selected into the presentation space remains selected.

Any dynamic segments left drawn on the device are not subsequently removed by GpiRemoveDynamics.

Example Code

This example releases the current device context and associates a new device context with the presentation space.

#define INCL_GPICONTROL         /* GPI control Functions */
#include <os2.h>

HPS hps;                /* presentation space handle     */
HDC hdcPrinter;         /* device context handle         */

/* release the current device context */
GpiAssociate(hps, NULLHANDLE);
/* associate a printer device context */
GpiAssociate(hps, hdcPrinter);