Legacy Document

Inside Macintosh: Imaging With QuickDraw /

Chapter 4 - Color QuickDraw / Color QuickDraw Reference

Data Structures /

CGrafPort

A color graphics port, which is defined by a data structure of type CGrafPort, defines a complete drawing environment that determines where and how color graphics operations take place.

All graphics operations are performed in graphics ports. Before a color graphics port can be used, it must be allocated and initialized with the OpenCPort procedure, which is described on page 4-55. Normally, you don't call OpenCPort yourself. In most cases your application draws into a color window you've created with the GetNewCWindow or NewCWindow function or draws into an offscreen graphics world created with the NewGWorld function. The two Window Manager functions (described in the chapter "Window Manager" in Inside Macintosh: Macintosh Toolbox Essentials) and the NewGWorld function (described in the chapter "Offscreen Graphics Worlds" in this book) call OpenCPort to create the window's graphics port.

You can have many graphics ports open at once; each one has its own local coordinate system, pen pattern, background pattern, pen size and location, font and font style, and pixel map in which drawing takes place.

Several fields in this record define your application's drawing area. All drawing in a graphics port occurs in the intersection of the graphics port's boundary rectangle and its port rectangle. Within that intersection, all drawing is cropped to the graphics port's visible region and its clipping region.

The Window Manager and Dialog Manager routines GetNewWindow, GetNewDialog, Alert, StopAlert, NoteAlert, and CautionAlert (described in Inside Macintosh: Macintosh Toolbox Essentials) create a color graphics port if color-aware resources (such as resource types 'wctb', 'dctb', or 'actb') are present.

The CGrafPort record is the same size as the GrafPort record, and most of its fields are identical. The structure of the CGrafPort record, is as follows:

TYPE CGrafPtr\xDD\xDD=\xDD^CGrafPort;
CGrafPort = 
RECORD
   device:        Integer;       {device ID for font selection}
   portPixMap:    PixMapHandle;  {handle to PixMap record}
   portVersion:   Integer;       {highest 2 bits always set}
   grafVars:      Handle;        {handle to a GrafVars record}
   chExtra:       Integer;       {added width for nonspace characters}
   pnLocHFrac:    Integer;       {pen fraction}
   portRect:      Rect;          {port rectangle}
   visRgn:        RgnHandle;     {visible region}
   clipRgn:       RgnHandle;     {clipping region}
   bkPixPat:      PixPatHandle;  {background pattern}
   rgbFgColor:    RGBColor;      {requested foreground color}
   rgbBkColor:    RGBColor;      {requested background color}
   pnLoc:         Point;         {pen location}
   pnSize:        Point;         {pen size}
   pnMode:        Integer;       {pattern mode}
   pnPixPat:      PixPatHandle;  {pen pattern}
   fillPixPat:    PixPatHandle;  {fill pattern}
   pnVis:         Integer;       {pen visibility}
   txFont:        Integer;       {font number for text}
   txFace:        Style;         {text's font style}
   txMode:        Integer;       {source mode for text}
   txSize:        Integer;       {font size for text}
   spExtra:       Fixed;         {added width for space characters}
   fgColor:       LongInt;       {actual foreground color}
   bkColor:       LongInt;       {actual background color}
   colrBit:       Integer;       {plane being drawn}
   patStretch:    Integer;       {used internally}
   picSave:       Handle;        {picture being saved, used internally}
   rgnSave:       Handle;        {region being saved, used internally}
   polySave:      Handle;        {polygon being saved, used internally}
   grafProcs:     CQDProcsPtr;   {low-level drawing routines}
END;

WARNING

You can read the fields of a CGrafPort record directly, but you should not store values directly into them. Use the QuickDraw routines described in this book to alter the fields of a graphics port.

Field Description

device

Device-specific information that's used by the Font Manager to achieve the best possible results when drawing text in the graphics port. There may be physical differences in the same logical font for different output devices, to ensure the highest-quality printing on the device being used. For best results on the screen, the default value of the device field is 0.

portPixMap

A handle to a PixMap record (described on page 4-37), which describes the pixels in this color graphics port.

portVersion

In the highest 2 bits, flags set to indicate that this is a CGrafPort record and, in the remainder of the field, the version number of Color QuickDraw that created this record.

grafVars

A handle to the GrafVars record (described on page 4-53), which contains additional graphics fields of color information.

chExtra

A fixed-point number by which to widen every character, excluding the space character, in a line of text. This value is used in proportional spacing. The value in this field is in 4.12 fractional notation: 4 bits of signed integer are followed by 12 bits of fraction. This value is multiplied by the value in the txSize field before it is used. By default, this field contains the value 0.

pnLocHFrac

The fractional horizontal pen position used when drawing text. The value in this field represents the low word of a Fixed number; in decimal, its initial value is 0.5.

portRect

The port rectangle that defines a subset of the pixel map to be used for drawing.\xDD\xDDAll drawing done by the application occurs inside the port rectangle. (In a window's graphics port, the port rectangle is also called the content region.) The port rectangle uses the local coordinate system defined by the boundary rectangle in the portPixMap field of the PixMap record. The upper-left corner (which for a window is called the window origin) of the port rectangle usually has a vertical coordinate of 0 and a horizontal coordinate of 0, although you can use the SetOrigin procedure (described in the chapter "Basic QuickDraw") to change the coordinates of the window origin. The port rectangle usually falls within the boundary rectangle, but it's not required to do so.

visRgn

The region of the graphics port that's actually visible on the
screen--that is, the part of the window that's not covered by other windows. By default, the visible region is equivalent to the port rectangle. The visible region has no effect on images that aren't displayed on the screen.

clipRgn

The graphics port's clipping region, an arbitrary region that you can use to limit drawing to any region within the port rectangle. The default clipping region is set arbitrarily large; using the ClipRect procedure (described in the chapter "Basic QuickDraw"), you have full control over its setting. Unlike the visible region, the clipping region affects the image even if it isn't displayed on the screen.

bkPixPat

A handle to a PixPat record (described on page 4-49) that describes the background pixel pattern. Procedures such as ScrollRect (described in the chapter "Basic QuickDraw") and EraseRect (described in the chapter "QuickDraw Drawing") use this pattern for filling scrolled or erased areas. Your application can use the BackPixPat procedure (described on page 4-60) to change the background pixel pattern.

rgbFgColor

An RGBColor record (described on page 4-46) that contains the requested foreground color. By default, the foreground color is black, but you can use the RGBForeColor procedure (described on page 4-61) to change the foreground color.

rgbBkColor

An RGBColor record that contains the requested background color. By default, the background color is white, but you can use the RGBBackColor procedure (described on page 4-63) to change the background color.

pnLoc

The point where QuickDraw will begin drawing the next line, shape, or character. It can be anywhere on the coordinate plane; there are no restrictions on the movement or placement of the pen. The location of the graphics pen is a point in the graphics port's coordinate system, not a pixel in a pixel image. The upper-left corner of the pen is at the pen location; the graphics pen hangs below and to the right of this point. The graphics pen is described in detail in the chapter "QuickDraw Drawing."

pnSize

The vertical height and horizontal width of the graphics pen. The default size is a 1-by-1 pixel square; the vertical height and horizontal width can range from 0 by 0 to 32,767 by 32,767. If either the pen width or the pen height is 0, the pen does not draw. Heights or widths of less than 0 are undefined. You can use the PenSize procedure (described in the chapter "QuickDraw Drawing") to change the value in this field.

pnMode

The pattern mode--that is, a Boolean operation that determines the how Color QuickDraw transfers the pen pattern to the pixel map during drawing operations. When the graphics pen draws into
a pixel map, Color QuickDraw first determines what pixels in the pixel image are affected and finds their corresponding pixels in the pen pattern. Color QuickDraw then does a pixel-by-pixel comparison based on the pattern mode, which specifies one of eight Boolean transfer operations to perform. Color QuickDraw stores the resulting pixel in its proper place in the image. Pattern modes for a color graphics port are described in "Boolean Transfer Modes With Color Pixels" beginning on page 4-23.

pnPixPat

A handle to a PixPat record (described on page 4-49) that describes a pixel pattern used like the ink in the graphics pen. Color QuickDraw uses the pixel pattern defined in the PixPat record when you use the Line and LineTo procedures to draw lines with the pen, framing procedures such as FrameRect to draw shape outlines with the pen, and painting procedures such as PaintRect to paint shapes with the pen.

fillPixPat

A handle to a PixPat record (described on page 4-49) that describes the pixel pattern that's used when you call a procedure such as FillRect to fill an area. Notice that this is not in the same location as the fillPat field in a GrafPort record.

pnVis

The graphics pen's visibility--that is, whether it draws on the screen. The graphics pen is described in detail in the chapter "QuickDraw Drawing."

txFont

A font number that identifies the font to be used in the graphics port. The font number 0 represents the system font. (A font is defined as a collection of images that represent the individual characters of the font.) Fonts are described in detail in Inside Macintosh: Text.

txFace

The character style of the text, with values from the set defined by the Style data type, which includes such styles as bold, italic, and shaded. You can apply stylistic variations either alone or in combination. Character styles are described in detail in Inside Macintosh: Text.

txMode

One of three Boolean source modes that determines the way characters are placed in the bit image. This mode functions much like a pattern mode specified in the pnMode field: when drawing a character, Color QuickDraw determines which pixels in the image are affected, does a pixel-by-pixel comparison based on the mode, and stores the resulting pixels in the image. Only three source modes--srcOr, srcXor, and srcBic--should be used for drawing text. See the chapter "QuickDraw Text" in Inside Macintosh: Text for more information about QuickDraw's text-handling capabilities.

txSize

The text size in pixels. The Font Manager uses this information to provide the bitmaps for text drawing. (The Font Manager is described in detail in the chapter "Font Manager" in Inside Macintosh: Text.) The value in this field can be represented by

point size device resolution / 72 dpi

where point is a typographical term meaning approximately
1/72 inch.

spExtra

A fixed-point number equal to the average number of pixels by which each space character should be widened to fill out the line. The spExtra field is useful when a line of characters is to be aligned with both the left and the right margin (sometimes called full justification).

fgColor

The pixel value of the foreground color supplied by the Color Manager. This is the best available approximation in the CLUT to the color specified in the rgbFgColor field.

bkColor

The pixel value of the background color supplied by the Color Manager. This is the best available approximation in the CLUT to the color specified in the rgbBkColor field.

colrBit

Reserved.

patStretch

A value used during output to a printer to expand patterns if necessary. Your application should not change this value.

picSave

The state of the picture definition. If no picture is open, this field contains NIL; otherwise it contains a handle to information related to the picture definition. Your application shouldn't be concerned about exactly what information the handle leads to; you may, however, save the current value of this field, set the field to NIL to disable the picture definition, and later restore it to the saved value to resume defining the picture. Pictures are described in the chapter "Pictures" in this book.

rgnSave

The state of the region definition. If no region is open, this field contains NIL; otherwise it contains a handle to information related to the region definition. Your application shouldn't be concerned about exactly what information the handle leads to; you may, however, save the current value of this field, set the field to NIL to disable the region definition, and later restore it to the saved value to resume defining the region.

polySave

The state of the polygon definition. If no polygon is open, this field contains NIL; otherwise it contains a handle to information related to the polygon definition. Your application shouldn't be concerned about exactly what information the handle leads to; you may, however, save the current value of this field, set the field to NIL to disable the polygon definition, and later restore it to the saved value to resume defining the polygon.

grafProcs

An optional pointer to a CQDProcs record (described on page 4-51) that your application can store into if you want to customize Color QuickDraw drawing routines or use Color QuickDraw in other advanced, highly specialized ways.

All Color QuickDraw operations refer to a graphics port by a pointer defined by the data type CGrafPtr. (For historical reasons, a graphics port is one of the few objects in the Macintosh system software that's referred to by a pointer rather than a handle.) All Window Manager routines that accept a window pointer also accept a pointer to a color graphics port.

Your application should never need to directly change the fields of a CGrafPort record. If you find it absolutely necessary for your application to so, immediately use the PortChanged procedure to notify Color QuickDraw that your application has changed the CGrafPort record. The PortChanged procedure is described on page 4-90.