Legacy Document

Inside Macintosh: Imaging With QuickDraw /

Chapter 3 - QuickDraw Drawing / QuickDraw Drawing Reference

Routines / Creating and Managing Regions

CloseRgn

To organize a collection of lines and shapes into a region definition, use the CloseRgn procedure.

PROCEDURE CloseRgn (dstRgn: rgnHandle);

dstRgn

The handle to the region to close.

DESCRIPTION

The CloseRgn procedure stops the collection of lines and framed shapes, organizes them into a region definition, and saves the result in the region whose handle you pass in the dstRgn parameter. The handle you pass in the dstRgn parameter should be a region handle returned by the NewRgn function.

The CloseRgn procedure does not create the destination region; you must have already allocated space for it by using the OpenRgn procedure. The CloseRgn procedure calls the ShowPen procedure, balancing the call to the HidePen procedure made by OpenRgn.

When you no longer need the memory occupied by the region, use the DisposeRgn procedure, described next.

SPECIAL CONSIDERATIONS

Regions are limited to 32 KB in size in basic QuickDraw and 64 KB in Color QuickDraw. When you record drawing operations in an open region, the resulting region description may overflow this limit. Should this happen in Color QuickDraw, the QDError function (described in the chapter "Color QuickDraw" in this book) returns the result code regionTooBigError. Since the resulting region is potentially corrupt, the CloseRgn procedure returns an empty region if it detects QDError has returned regionTooBigError.

The CloseRgn procedure may move or purge memory blocks in the application heap. Your application should not call this procedure at interrupt time.

SEE ALSO

Listing 3-8 on page 3-24 illustrates how to use this procedure.