GpiSetRegion
This function changes a region to be the logical-OR of a set of rectangles.
Syntax
GpiSetRegion(hps, hrgn, lcount, arclRectangles)
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.
- lcount (LONG) - input
- Count of rectangles.
- This is the number of rectangles specified in arclRectangles. If lcount = 0, the region is set to EMPTY, and arclRectangles is ignored.
- arclRectangles (PRECTL) - input
- 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
- rc (BOOL) - returns
- Success indicator.
- TRUE
- Successful completion
- FALSE
- Error occurred.
Remarks
This function is similar to GpiCreateRegion, except that it changes an already existing region to be the logical-OR of the supplied rectangles, instead of creating a new region. The previous contents of the region are irrelevant. Points on the right-hand and top boundaries are not included in the changed 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).
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_HRGN (0x2080)
- An invalid region handle was specified.
- 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.
Example Code
#define INCL_GPIREGIONS /* Or use INCL_GPI, INCL_PM, */ #include <os2.h> HPS hps; /* Presentation-space handle. */ HRGN hrgn; /* Region handle. */ LONG lcount; /* Count of rectangles. */ PRECTL arclRectangles; /* Array of rectangles. */ BOOL rc; /* Success indicator. */ rc = GpiSetRegion(hps, hrgn, lcount, arclRectangles);
In this example we change the region to be the logical-or of a set of rectangles.
#define INCL_GPIREGIONS
#include <OS2.H>
#define maxrects 2
BOOL flResult; /* success indicator. */
HPS hps; /* presentation space handle. */
HRGN hrgn; /* region handle. */
RECTL arclRect[maxrects] = {{20l, 20L, 40L, 40L},
{40L, 20L, 60L, 40L}}; /* array of rectangle structures */
flResult = GpiSetRegion(hps, hrgn, (LONG)maxrects, arclRect); /* array of two rectangles. */