GreRestoreRegion

GreRestoreRegion is called during RestoreDC and CloseDC to allow the region handling routines to restore their local data structures. When a DC is closed, GreRestoreRegion is called with a count of 0 to free its local data. The clip region currently selected into the DC is deleted by this function.

This function can be hooked by the presentation driver.

Simulation support

This function is simulated by a handling routine in the graphics engine.

Syntax

GreRestoreRegion(hdc, cSave, pInstance, lFunction)

Parameters

hdc (HDC) - input

Device context handle.

cSave (LONG) - input

DC save level.

Indicates the saved DC state, which the handling routine uses to restore the region. When this is passed as -1, the handling routine resets the region to its initial state (-1 is passed to this routine from GreResetDC and is the only valid negative value). A value of 0 indicates that the region is restored to its initial state. Other positive values identify which saved level is restored. See RestoreDCState.

pInstance (PVOID) - input

Pointer to instance data.

lFunction (ULONG) - input

High-order WORD=flags; low-order WORD=NGreRestoreRegion.

Return Code

fSuccess (BOOL) - returns

Return codes.

This function returns BOOLEAN (fSuccess).

• TRUE Successful
• FALSE Error

Possible Errors Detected: When an error is detected, the handling routine must call WinSetErrorInfo to post the condition. Error codes for conditions that the handling routine is expected to check include:

• PMERR_DEV_FUNC_NOT_INSTALLED
• PMERR_HDC_BUSY
• PMERR_INSUFFICIENT_MEMORY
• PMERR_INV_COORDINATE
• PMERR_INV_HDC
• PMERR_INV_HRGN
• PMERR_INV_RECT
• PMERR_INV_REGION_CONTROL

Refer to the "Error Explanations" section in the Presentation Manager Programming Reference for further explanation.

Remarks

This function is required to ensure that memory is freed.

Declaration

#define INCL_GRE_CLIP
#include <os2.h>

HDC      hdc;        /*  Device context handle. */
LONG     cSave;      /*  DC save level. */
PVOID    pInstance;  /*  Pointer to instance data. */
ULONG    lFunction;  /*  High-order WORD=flags; low-order WORD=NGreRestoreRegion. */
BOOL     fSuccess;   /*  Return codes. */

fSuccess = GreRestoreRegion(hdc, cSave, pInstance, lFunction);