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

 * 1) define INCL_GRE_DEVMISC2
 * 2) include 

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);

