GpiCreateRegion

This function creates a region, for a particular class of device, using a series of rectangles.

Syntax

GpiCreateRegion(hps, lCount, arclRectangles)

Parameters

hps (HPS) - input: Presentation-space handle.; A region suitable for use with the currently associated device is created.

lCount (LONG) - input: The number of rectangles.; The number specified in arclRectangles. If lCount is 0, an empty region is created, and arclRectangles is ignored.

arclRectangles (PRECTL) - input: An array of rectangles.; The rectangles are specified in device coordinates.; For each rectangle in the array, the value of xRight must be greater than (or equal to) xLeft, and yTop must be greater than (or equal to) yBottom.

Return Value

hrgn (HRGN) - returns

Region handle.

<>0: Region handle
RGN_ERROR: Error.

Remarks

The new region is defined by the logical-OR of all of the rectangles specified. 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. The region is owned by the process from which this function is issued. It cannot be accessed directly from any other process. If it still exists when the process terminates, it is automatically deleted by the system.

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_LENGTH_OR_COUNT (0x2092): An invalid length or count parameter was specified.
PMERR_INV_COORDINATE (0x205B): An invalid coordinate value was specified.
PMERR_INV_RECT (0x20BD): An invalid rectangle parameter was specified.

Example Code

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

HPS     hps;             /* Presentation-space handle. */
LONG    lCount;          /* The number of rectangles. */
PRECTL  arclRectangles;  /* An array of rectangles. */
HRGN    hrgn;            /* Region handle. */

hrgn = GpiCreateRegion(hps, lCount, arclRectangles);

This example uses the GpiCreateRegion function to create a region consisting of the union of three rectangles.

#define INCL_GPIREGIONS /* Region functions */
#include <os2.h>

HPS hps; /* presentation space handle */
HRGN hrgn; /* handle for region */
RECTL arcl[3] = { 100, 100, 200, 200, /* 1st rectangle */
                  150, 150, 250, 250, /* 2nd rectangle */
                  200, 200, 300, 300 }; /* 3rd rectangle */

hrgn = GpiCreateRegion(hps, /* presentation space */
                         3L, /* three rectangles */
                         arcl); /* address of array of rectangles */

Related Functions