GreGetRegionRects

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

GreGetRegionRects fills the array pointed to by parclRect with a list of (X,Y) coordinate pairs specifying the rectangles that together define the region associated with hrgn. All rectangle coordinates are inclusive at the bottom-left corner, and exclusive at the top-right corner. Notice that the coordinates of the bounding box, and the rectangles returned, will be in device coordinates. GreGetRegionRects raises an error when hrgn is the handle of a currently selected clip region.

This function can be hooked by the presentation driver.

This function can be used to determine if the banding rectangle is inside, outside, or crossing the device's clip rectangle.

Syntax

GreGetRegionRects(hdc, hrgn, prclBoundRect, pControl, parclRect, pInstance, lFunction)

Parameters

hdc (HDC) - input

Device context handle.

hrgn (HRGN) - input

Region handle.

prclBoundRect (PRECTL) - input

Pointer to bounding rectangle.

RECTL structure:

xLeft Minimum x-coordinate of window
yBottom Minimum y-coordinate
xRight Maximum x-coordinate of window
yTop Maximum y-coordinate

Only rectangles intersecting this bounding rectangle are returned. If this pointer is NULL, all rectangles in the region are enumerated. If this pointer is not NULL, only rectangles that intersect the bounding rectangle are returned. Each of these rectangles is the intersection of the bounding rectangle with a rectangle in the region.

pControl (PRGNRECT) - input

This is a pointer to a RGNRECT structure.

parclRect (PRECTL) - input

Pointer to array of rectangle structures that define the region.

pInstance (PVOID) - input

Pointer to instance data.

lFunction (ULONG) - input

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

Return Code

rc (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_HRGN_BUSY
PMERR_INV_COORDINATE
PMERR_INV_HRGN
PMERR_INV_RECT
PMERR_INV_REGION_CONTROL
PMERR_REGION_IS_CLIP_REGION

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

Example Code

#define INCL_GRE_REGIONS
#include <os2.h>

HDC         hdc;            /*  Device context handle. */
HRGN        hrgn;           /*  Region handle. */
PRECTL      prclBoundRect;  /*  Pointer to bounding rectangle. */
PRGNRECT    pControl;       /*  This is a pointer to a RGNRECT structure: */
PRECTL      parclRect;      /*  Pointer to array of rectangle structures that define the  region. */
PVOID       pInstance;      /*  Pointer to instance data. */
ULONG       lFunction;      /*  High-order WORD=flags; low-order WORD=NGreGetRegionRects. */
BOOL        rc;             /*  Return codes. */

rc = GreGetRegionRects(hdc, hrgn, prclBoundRect, pControl, parclRect, pInstance, lFunction);