66.1.2 Region Operations

Applications can operate on regions by combining them, comparing them, painting the interior, inverting the interior, drawing a frame around them, retrieving their dimensions, and testing to see whether or not the cursor lies within their boundaries.

66.1.2.1 Region Combinations

An application combines two regions by calling the CombineRgn function. Using this function, an application can combine: the intersecting parts of two regions, all but the intersecting parts of two regions, the two original regions in their entirety, and so on. The following illustration shows a square and circular region that were combined using each of the five combinations allowed by the CombineRgn function:

Combining Regions

66.1.2.2 Region Comparisons

An application compares two regions to determine whether or not they are identical by calling the EqualRgn function.

66.1.2.3 Region Drawing and Painting

An application fills (or paints) regions by calling the FillRgn function. This function paints the interior of regions using the brush that is currently selected into the application's device context. A brush is an 8-by-8 pixel bitmap that drawn repeatedly to simulate a “painting” operation. (For more information about brushes and painting, see Chapter 64, “Brushes.”)

An application inverts the colors that appear within a region by calling the InvertRgn function.

An application draws a border around a region by calling the FrameRgn function and specifying the border width and brush pattern that Windows should use when drawing the frame.

66.1.2.4 Bounding-Rectangle Retrieval

An application retrieves the dimensions of a region's bounding rectangle by calling the GetRgnBox function. If the region is rectangular, this function returns the dimensions of the region. If the region is elliptical, this function returns the dimensions of the smallest rectangle that can be drawn around the ellipse—the longest sides of the rectangle are the same length as the ellipse's major axis; the shortest sides of the rectangle are the same length as the ellipse's minor axis. If the region is polygonal, this function returns the dimensions of the smallest rectangle that can be drawn around the entire polygon.

66.1.2.5 Region Hit-Testing

An application performs hit-testing on regions by retrieving the current cursor coordinates and passing these coordinates as well as a handle identifying the region in question to the PtInRegion function. The function's return value indicates whether or not the point lies within the given region.