GpiQueryRegionRects

This function determines what rectangles that, when ORed together, define the specified region and then returns either the number of rectangles or the rectangles themselves.

Syntax

GpiQueryRegionRects(hps, hrgn, prclBound, prgnrcControl, prclRect)

Parameters

hps (HPS) - input

Presentation-space handle.

The region must be owned by the device identified by the currently associated device context.

hrgn (HRGN) - input

Region handle.

prclBound (PRECTL) - input

Bounding rectangle.

NULL - Return all the rectangles in the region.

Other - Return only rectangles that intersect with the bounding rectangle. Each rectangle returned is the intersection of the bounding rectangle with a rectangle in the region.

prgnrcControl (PRGNRECT) - in/out

Processing-control structure.

prclRect (PRECTL) - output

Pointer to an array of rectangle structures or NULL

NULL - Return the number of rectangles in the region.

The number of rectanges is returned in the crcReturned field of the RGNRECT structure identified by the prgnrcControl parameter. The ircStart field will always be 1. If a bounding rectangle is specified, the crc and crcReturned fields will be set as follows:

If the given rectangle is:	crc	crcReturned
Completely inside.	RRGN_INSIDE	1
Completely outside.	RRGN_OUTSIDE	0
Partially inside.	RRGN_PARTIAL	Number of rectangles

Other - Return only rectangles that intersect with the bounding rectangle. Each rectangle returned is the intersection of the bounding rectangle with a rectangle in the region.

Pointer to an array of rectangle structures in which the rectangles are returned.

The maximum number of rectangles that can be returned is specified by the crc parameter of the RGNRECT structure identified by the prgnrcControl parameter.

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_INV_HRGN (0x2080)

An invalid region handle was specified.

PMERR_INV_REGION_CONTROL (0x20BE)

An invalid control parameter was specified with GpiQueryRegionRects.

PMERR_INV_COORDINATE (0x205B)

An invalid coordinate value was specified.

PMERR_INV_RECT (0x20BD)

An invalid rectangle parameter was specified.

PMERR_REGION_IS_CLIP_REGION (0x20F8)

An attempt was made to perform a region operation on a region that is selected as a clip region.

PMERR_HRGN_BUSY (0x2034)

An internal region busy error was detected. The region was locked by one thread during an attempt to access it from another thread.

Remarks

Points on the right-hand and top boundaries are not included in the region. Points on the left-hand and bottom boundaries, that are not also on the right-hand or top boundaries (that is, the top-left and bottom-right corner points), are included.

It is invalid if the specified region is currently selected as the clip region (by GpiSetClipRegion).

Example Code

#define INCL_GPIREGIONS /* Or use INCL_GPI, INCL_PM, */
#include <os2.h>

HPS         hps;            /*  Presentation-space handle. */
HRGN        hrgn;           /*  Region handle. */
PRECTL      prclBound;      /*  Bounding rectangle. */
PRGNRECT    prgnrcControl;  /*  Processing-control structure. */
PRECTL      prclRect;       /*  Pointer to an array of rectangle structures. */
BOOL        rc;             /*  Success indicator. */

rc = GpiQueryRegionRects(hps, hrgn, prclBound, prgnrcControl, prclRect);

In this example we determine the rectangles that can be OR'ed together to determine the specified region.

#define INCL_GPIREGIONS
#include <OS2.H>
#define MAXRECTS 12

BOOL flResult;      /* success indicator.         */
HPS hps;            /* presentation space handle. */
HRGN hrgn;          /* region handle.             */
RECTL rclBound;     /* bounding rectangle         */
RGNRECT rgnrcControl;  /* processing control      */
RECTL arclRect[MAXRECTS];  /* array of rectangle structures */
                           /* in which the rectangles are returned. */

rgnrcControl.ircStart = 1;    /* start numbering rectangles from 1.                 */
rgnrcControl.crc = MAXRECTS;  /* maximum number of rectangles that can be returned. */
rgnrcControl.usDirection = RECTDIR_LFRT_TOPBOT;
                               /* order rectangles left-to-right and top-to-bottom. */
flResult =  GpiQueryRegionRects(hps,
                                hrgn,
                                &rclBound,      /* output */
                                &rgnrcControl,  /* rgnrcControl.crcReturned is the */
                                                /* number of rectangles returned.  */
                                &arclRect[0]);