Legacy Document

Inside Macintosh: Imaging With QuickDraw /

Chapter 3 - QuickDraw Drawing / QuickDraw Drawing Reference

Routines

Creating and Managing Regions

To define a region, you can use any set of lines or shapes, including other regions, so long as the region's outline consists of one or more closed loops. To begin defining a region, you must use the NewRgn function to allocate space for it, and then call the OpenRgn procedure. You can then use any QuickDraw routines to construct the outline of the region. When you are finished constructing the region, use the CloseRgn procedure.

The NewRgn function returns a handle to the newly allocated Region record. After you use the OpenRgn procedure, QuickDraw begins collecting the drawing information you provide into this Region record. (The Region record is described in the chapter "Basic QuickDraw.")

After defining a region in this way, you can display it with the FrameRgn, PaintRgn, and FillRgn procedures. When you are finished using the region, use the DisposeRgn procedure to release its memory.

You can use the SetEmptyRgn procedure to set a region to be empty, SetRectRgn to change it into a rectangle, OffsetRgn to move it, InsetRgn to shrink or expand it, PtInRgn to determine whether a pixel lies within it, RectInRgn to determine whether a rectangle intersects it, EmptyRgn to determine whether it is an empty region, and CopyRgn to make a copy of it. You can use the RectRgn procedure to make a region out of a rectangle. You can use the SectRgn procedure to calculate the intersection of two regions, UnionRgn to calculate the union of two regions, DiffRgn to subtract one region from another, XorRgn to calculate the difference between the union and the intersection of two regions, and EqualRgn to determine whether two regions have identical sizes, shapes, and locations.

When using these procedures, you refer to a region by the handle returned by NewRgn when you first allocated memory for the region.

WARNING

Ensure that the memory for a region is valid before calling these routines to manipulate that region; if there isn't sufficient memory, the system may crash. Regions are limited to 32 KB in size in basic QuickDraw and 64 KB in Color QuickDraw. Before defining a region, you can use the Memory Manager function MaxMem to determine whether the memory for the region is valid. You can determine the current size of an existing region by calling the Memory Manager function GetHandleSize. (Both MaxMem and GetHandleSize are described in Inside Macintosh: Memory.) When you record drawing operations in an open region, the resulting region description may overflow the 32 KB or 64 KB limit. Should this happen in Color QuickDraw, the QDError function (described in the chapter "Color QuickDraw" in this book) returns the result code regionTooBigError.

If the points or rectangles supplied to these routines are defined in a graphics port other than your current graphics port, you must convert them to the local coordinate system of your current graphics port. You can accomplish this by using the SetPort procedure to change to the graphics port containing the points or rectangles, using the LocalGlobal procedure to convert their locations to global coordinates, using SetPort to return to your starting graphics port, and then using the GlobalToLocal procedure to convert the locations of points or rectangles to the local coordinates of your current graphics port. These procedures are described in the chapter "Basic QuickDraw."

---

Subtopics

NewRgn

OpenRgn

CloseRgn

DisposeRgn

CopyRgn

SetEmptyRgn

SetRectRgn

RectRgn

OffsetRgn

InsetRgn

SectRgn

UnionRgn

DiffRgn

XorRgn

PtInRgn

RectInRgn

EqualRgn

EmptyRgn