Important: The information in this document is obsolete and should not be used for new development.
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 theNewRgn
function to allocate space for it, and then call theOpenRgn
procedure. You can then use any QuickDraw routines to construct the outline of the region. When you are finished constructing the region, use theCloseRgn
procedure.The
NewRgn
function returns a handle to the newly allocatedRegion
record. After you use theOpenRgn
procedure, QuickDraw begins collecting the drawing information you provide into thisRegion
record. (TheRegion
record is described in the chapter "Basic QuickDraw.")After defining a region in this way, you can display it with the
FrameRgn
,PaintRgn
, andFillRgn
procedures. When you are finished using the region, use theDisposeRgn
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, andCopyRgn
to make a copy of it. You can use theRectRgn
procedure to make a region out of a rectangle. You can use theSectRgn
procedure to calculate the intersection of two regions,UnionRgn
to calculate the union of two regions,DiffRgn
to subtract one region from another,XorRgn
toc
alculate the difference between the union and the intersection of two regions, andEqualRgn
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.
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
- 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 functionGetHandleSize
. (BothMaxMem
andGetHandleSize
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, theQDError
function (described in the chapter "Color QuickDraw" in this book) returns the result coderegionTooBigError
.SetPort
procedure to change to the graphics port containing the points or rectangles, using theLocalGlobal
procedure to convert their locations to global coordinates, usingSetPort
to return to your starting graphics port, and then using theGlobalToLocal
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