Creating and Painting Regions

A region is a description of an area of the display that is a combination of rectangles, other polygons, and ellipses. You can use regions for drawing or for clipping. You use a region for clipping by selecting the region into the device context.

Like pens, brushes, and bitmaps, regions are GDI objects. (The fifth and final type of GDI object is the logical font, which we'll look at in Chapter 15.) You must treat regions the same way you treat the other GDI objects: Delete any regions that you create, but don't delete a region while it is selected in the device context.

When you create a region, Windows returns a handle to the region of type HRGN. The simplest type of region describes a rectangle. You can create a rectangular region in one of two ways:

hRgn = CreateRectRgn (xLeft, yTop, xRight, yBottom) ;

or:

hRgn = CreateRectRgnIndirect (&rect) ;

Regions are always expressed in terms of device coordinates.

You can also create elliptical regions using:

hRgn = CreateEllipticRgn (xLeft, yTop, xRight, yBottom) ;

or:

hRgn = CreateEllipticRgnIndirect (&rect) ;

The CreatRoundRectRgn creates a rectangular region with rounded corners.

Creating a polygonal region is similar to using the Polygon function:

hRgn = CreatePolygonRgn (&point, nCount, nPolyFillMode) ;

The point parameter is an array of structures of type POINT, nCount is the number of points, and nPolyFillMode is either ALTERNATE or WINDING. You can also create multiple polygonal regions using CreatePolyPolygonRgn.

So what, you say? What makes these regions so special? Here's the function that unleashes the power of regions:

nRgnType = CombineRgn (hDestRgn, hSrcRgn1, hSrcRgn2, nCombine) ;

This combines two source regions (hSrcRgn1 and hSrcRgn2) and causes the destination region handle (hDestRgn) to refer to that combined region. All three region handles must be valid, but the region previously described by hDestRgn is destroyed. (When you use this function, you might want to make hDestRgn refer initially to a small rectangular region.)

The nCombine parameter describes how the hSrcRgn1 and hSrcRgn2 regions are to be combined:

The nRgnType value returned from CombineRgn is one of the following: NULLREGION, indicating an empty region; SIMPLEREGION, indicating a simple rectangle, ellipse, or polygon; COMPLEXREGION, indicating a combination of rectangles, ellipses, or polygons; and ERROR, meaning that an error has occurred.

Once you have a handle to a region, you can use it with four drawing functions:

FillRgn (hdc, hRgn, hBrush) ;

FrameRgn (hdc, hRgn, hBrush, xFrame, yFrame) ;

InvertRgn (hdc, hRgn) ;

PaintRgn (hdc, hRgn) ;

The FillRgn, FrameRgn, and InvertRgn functions are similar to the FillRect, FrameRect, and InvertRect functions. The xFrame and yFrame parameters to FrameRgn are the width and height of the frame to be painted around the region. Although regions always use device coordinates, these two parameters are specified in terms of logical units. The PaintRgn function fills in the region with the brush currently selected in the device context.

When you are finished with a region, you can delete it using the same function that deletes other GDI objects:

DeleteObject (hRgn) ;