Regions are used in many operations. There are several functions that determine the characteristics of regions because these characteristics influence the outcome of the operation being performed.
To determine whether two regions are identical, call GpiEqualRegion. This function accepts, as input, the two region handles. Regions are identical if the only difference between them is an empty region. For example, a rectangular region whose lower-left corner is at 10,10 is not identical to a region whose lower-left corner is at 50,50, even if the regions have exactly the same dimensions. The two regions also must be of the same device class to be considered identical.
To determine the rectangles that compose a region, call GpiQueryRegionRects, which retrieves the coordinates of a series of rectangles that, when ORed together, define the shape of the regions.
Note: The individual regions returned may differ in size and number from those originally used to specify the region.
GpiQueryRegionRects accepts, as input, the region handle and the maximum number of rectangles that can be returned. The division of the region into multiple rectangles is handled automatically by the PM.
It is not necessary for an application to retrieve all the rectangles in a single function. Your application can call GpiQueryRegionRects any number of times. Therefore, the application must specify the maximum number of rectangles and the rectangle number to start from in each function.
No assumptions can be made about the number and coordinates of rectangles returned except that they will define the specified region precisely. The purpose of specifying the number of rectangles in the query is to ensure that the system does not return more coordinates than can fit in the RECTL array.
To determine whether a point is inside the borders of a region, call GpiPtInRegion. This function is especially useful in applications that must determine whether the mouse pointer is over a region. The particular point must be expressed in device coordinates.
To determine whether any part of a specified rectangle lies within a region, call GpiRectInRegion. This function accepts, as input, the region handle and the rectangle as specified in device coordinates.
To determine the coordinates of the smallest rectangle that encloses a region, call GpiQueryRegionBox. This function accepts the region handle as input. The output from this function tells you whether the bounding region is rectangular, NULL, or complex.