GreNotifyClipChange

GreNotifyClipChange is called whenever there is any change to the DC region. The call gives the presentation driver an opportunity to optimize clipping by enumerating the clip rectangles and caching them whenever they change.

This function must be supported by the presentation driver. GreNotifyClipChange is called from the graphics engine whenever an application calls a GPI function that modifies the clipping rectangles within the device context. This function can be handled by bit-map simulation.

Simulation support

None. This function is mandatory for all drivers.

Syntax

GreNotifyClipChange(hdc, prclBound, cRect, idClipPath, pInstance, lFunction)

Parameters

hdc (HDC) - input

Device context handle.

prclBound (PRECTL) - input

Pointer to a rectangle that bounds the new clip region in screen coordinates.

This rectangle is inclusive on the left and bottom borders, and exclusive on the right and top borders.

cRect (ULONG) - input

Number of rectangles in the new clip region as returned by GetClipRects.

idClipPath (ULONG) - input

Current ClipPath ID.

For display devices, when idClipPath is passed as NCC_CLEANDC, the handling routine should clear the HDC_IS_DIRTY flag and return Successful. See VisRegionNotify and GreDeviceInvalidateVisRegion.

Presentation drivers for other devices ignore this parameter.

pInstance (PVOID) - input

Pointer to instance data.

lFunction (ULONG) - input

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

Return Code

rc (BOOL) - returns

Return Code.

On completion, the handling routine must return a BOOLEAN value to indicate success or an error.

• TRUE Successful
• FALSE Error

Note

Presentation drivers that do not cache the clip rectangles should return TRUE, if there are no errors.

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_INV_COORDINATE
• PMERR_INV_HDC
• PMERR_INV_RECT
• PMERR_INV_REGION_CONTROL

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

Remarks

Typically, the handling routine would allocate more memory for the new DC region (when necessary) and call GreGetClipRects (see GreGetClipRects ) to get the set of rectangles that define the new DC region. Also (for display devices only), the handling routine must clear the HDC_IS_DIRTY flag.

On completion, the handling routine must re-dispatch this call to the graphics engine using the pointer supplied in the default dispatch table.

Sample Code

#define INCL_GRE_DEVMISC2
#include <os2.h>

HDC       hdc;        /* Device context handle. */
PRECTL    prclBound;  /* Pointer to a rectangle that bounds the new clip region in screen coordinates. */
ULONG     cRect;      /* Number of rectangles in the new clip region as returned by GetClipRects. */
ULONG     idClipPath; /* Current ClipPath ID. */
PVOID     pInstance;  /* Pointer to instance data. */
ULONG     lFunction;  /* High-order WORD=flags; low-order WORD=NGreNotifyClipChange. */
BOOL      rc;         /* Return Code. */

rc = GreNotifyClipChange(hdc, prclBound, cRect, idClipPath, pInstance, lFunction);