Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

Inside Macintosh: Imaging With QuickDraw /

Chapter 2 - Basic QuickDraw / Basic QuickDraw Reference

GrafPort
A basic graphics port, which is a data structure of type GrafPort, defines a complete drawing environment that determines where and how black-and-white graphics operations take place. (Using the basic eight-color system described in the chapter "QuickDraw Drawing," you can also use a basic graphics port to display eight predefined colors.)
All graphics operations are performed in graphics ports. Before a basic graphics port can be used, it must be allocated and initialized with the OpenPort procedure. Normally, you don't call OpenPort yourself. In most cases your application draws into a window you've created with the GetNewWindow or NewWindow function (or, for color windows, GetNewCWindow or NewCWindow), or it draws into an offscreen graphics world created with the NewGWorld function. These 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 OpenPort to create a basic graphics port. See the description of the OpenPort procedure on page 2-35 for a table of initial graphics port values.
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 bitmap in which drawing takes place. Using the SetPort procedure (described on page 2-39), you can instantly switch from one port to another.
Several fields in the GrafPort 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, and, within that intersection, all drawing is cropped to the graphics port's visible region and its clipping region.
TYPE GrafPtr = ^GrafPort;
GrafPort =
RECORD
   device:     Integer;    {device-specific information}
   portBits:   BitMap;     {bitmap}
   portRect:   Rect;       {port rectangle}
   visRgn:     RgnHandle;  {visible region}
   clipRgn:    RgnHandle;  {clipping region}
   bkPat:      Pattern;    {background pattern}
   fillPat:    Pattern;    {fill pattern}
   pnLoc:      Point;      {pen location}
   pnSize:     Point;      {pen size}
   pnMode:     Integer;    {pattern mode}
   pnPat:      Pattern;    {pen 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;      {extra space}
   fgColor:    LongInt;    {foreground color}
   bkColor:    LongInt;    {background color}
   colrBit:    Integer;    {color bit}
   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:  QDProcsPtr; {low-level drawing routines}
END;
WindowPtr = GrafPtr;
WARNING
You can read the fields of a GrafPort 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.
portBits
The bitmap (described on page 2-26) that describes the boundary rectangle for the graphics port and contains a pointer to the bit image used by the graphics port.
portRect
The port rectangle that defines a subset of the bitmap to be used for drawing.\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 portBits field of the BitMap 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 on page 2-42) 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 offscreen images.
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 on page 2-45), 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.
bkPat
The background bit pattern that's used by procedures such as ScrollRect (described on page 2-40) and EraseRect (described in the chapter "QuickDraw Drawing") for filling scrolled or erased areas. Your application can use the BackPat procedure (described in the chapter "QuickDraw Drawing") to change the background bit pattern. This pattern, like all other patterns drawn in the graphics port, is always aligned with the port's coordinate system.\xDDThe upper-left corner of the pattern is aligned with the upper-left corner of the port rectangle, so that adjacent areas of the same pattern blend into a continuous, coordinated pattern. Bit patterns are described in the chapter "QuickDraw Drawing."
fillPat
The bit pattern that's used when you use a procedure such as FillRect to fill an area. Bit patterns are described in the chapter "QuickDraw Drawing."
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 bit 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. You can use the Move, MoveTo, Line, and LineTo procedures (described in the chapter "QuickDraw Drawing") to move the location of the graphics pen.
pnSize
The vertical and horizontal dimensions of the graphics pen. By default, the pen is 1 pixel high by 1 pixel wide; the height and 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 QuickDraw transfers the pen pattern to the bitmap during drawing operations. When the graphics pen draws into a bitmap, QuickDraw first determines what bits in the bit image are affected and then finds their corresponding bits in the pen pattern. QuickDraw then does a bit-by-bit comparison based on the pattern mode, which specifies one of eight Boolean transfer operations to perform. QuickDraw stores the resulting bit in its proper place in the bit image. Pattern modes for a basic graphics port are described in the chapter "QuickDraw Drawing."
pnPat
A bit pattern that's used like the ink in the pen. As described in the chapter "QuickDraw Drawing," basic QuickDraw uses this pattern 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, or painting procedures such as PaintRect to paint shapes with the pen.
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. A font can consist of up to 255 distinct characters, yet not all characters need to be defined in a single font. In addition, each font contains a missing symbol to be drawn in case of a request to draw a character that's missing from the font.) Fonts are described in detail in Inside Macintosh: Text.
txFace
The font 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. Font 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, QuickDraw determines which bits in the bit image are affected, does a bit-by-bit comparison based on the mode, and stores the resulting bits into the bit 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 margins (sometimes called full justification).
fgColor
The color of the "ink" that QuickDraw uses to draw with. By default, this color is black. You can use the ForeColor procedure, as described in the chapter "QuickDraw Drawing," to specify any color from the eight-color system to be the foreground color in a basic graphics port. This color is recorded when drawing into a QuickDraw picture (described in the chapter "Pictures" in this book)--for example, drawing a line with a red foreground color stores a red line in the picture--but this color cannot be stored in a bitmap. When running in System 7, your application should use the GetForeColor procedure (described in the chapter "Color QuickDraw") to determine the foreground color instead of checking the value of this field.
bkColor
The color of the pixels in the bitmap into which QuickDraw draws. By default, this color is white. You can use the BackColor procedure, as described in the chapter "QuickDraw Drawing," to specify any color from the eight-color system to be the background color in a basic graphics port. This color is recorded when drawing into a QuickDraw picture, but this color cannot be stored in a bitmap. When running in System 7, your application should use the GetBackColor procedure (described in the chapter "Color QuickDraw") to determine the background color instead of checking the value of this field.
colrBit
The plane of the color picture to draw into when printing. As in the preceding two fields, this color cannot be stored in a bitmap.
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 special data structure that your application can store into if you want to customize QuickDraw drawing routines or use QuickDraw in other advanced, highly specialized ways. See the chapter "QuickDraw Drawing" for more information.
All QuickDraw operations refer to a graphics port by a pointer defined by the data type GrafPtr. (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 graphics port.
Your application should never need to directly change the fields of a GrafPort record. If you find it absolutely necessary for your application to do so, immediately use the PortChanged procedure to notify QuickDraw that your application has changed the GrafPort record. The PortChanged procedure is described in the chapter "Color QuickDraw" in this book.

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.