Legacy Document

Inside Macintosh: Imaging With QuickDraw /

Chapter 4 - Color QuickDraw / Color QuickDraw Reference

Color QuickDraw Routines / Managing a Color Graphics Pen

PenPixPat

To set the pixel pattern to be used by the graphics pen in the current color graphics port, use the PenPixPat procedure. To assign a pixel pattern as the background pattern, you can use the BackPixPat procedure; this allows the ScrollRect procedure and the shape-erasing procedures (for example, EraseRect) to fill the background with a colored, patterned "ink."

PROCEDURE PenPixPat (ppat: PixPatHandle); 

ppat

A handle to the pixel pattern to use as the pen pattern.

DESCRIPTION

The PenPixPat procedure sets the graphics pen to use the pixel pattern that you specify in the ppat parameter. The PenPixPat procedure is similar to the basic QuickDraw procedure PenPat, except that you pass PenPixPat a handle to a multicolored pixel pattern rather than a bit pattern.

The PenPixPat procedure stores the handle to the pixel pattern in the pnPixPat field of the CGrafPort record. Because the handle to the pixel pattern is stored in the CGrafPort record, you should not dispose of this handle. QuickDraw removes all references to your pattern from an existing graphics port when you dispose of it.

If you use PenPixPat to set a pixel pattern in a basic graphics port, the data in the pat1Data field of the PixPat record is placed into the pnPat field of the GrafPort record.

SPECIAL CONSIDERATIONS

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

SEE ALSO

The PixPat record is described on page 4-49. To define your own pixel pattern, you can create a pixel pattern resource, which is described on page 4-94, or you can use the NewPixPat function, which is described on page 4-79.

The GrafPort record is described in the chapter "Basic QuickDraw." To set the graphics pen to use a bit pattern, you can also use the PenPat procedure, which is described in the chapter "QuickDraw Drawing" in this book. The PenPat procedure creates a handle, of type PixPatHandle, for the bit pattern and stores this handle in the pnPixPat field of the CGrafPort record.