Discussion

AddComp creates and allocates a CProcRec data structure.

Discussion

The AddPt function adds the coordinates of the point specified in the srcPt parameter to the coordinates of the point specified in the dstPt parameter, and returns the result in the dstPt parameter.

Discussion

AddSearch creates and allocates an SProcRec data structure.

Discussion

Under normal circumstances, you should never need to use this function, since Color QuickDraw handles reallocation of cursor memory.

Discussion

The AllowPurgePixels function allows the Memory Manager to free the memory it occupies if available memory space becomes low. By default, NewGWorld creates an unpurgeable base address for an offscreen pixel image.

To get a handle to an offscreen pixel map, first use the GetGWorldPixMap function. Then supply this handle for the pm parameter of AllowPurgePixels.

Your application should call the LockPixels function before drawing into or copying from an offscreen pixel map. If the Memory Manager has purged the base address for its pixel image, LockPixels returns FALSE. In that case either your application should use the UpdateGWorld function to begin reconstructing the offscreen pixel image, or it should draw directly to an onscreen graphics port.

Only unlocked memory blocks can be made purgeable. If you use LockPixels, you must use the UnlockPixels function before calling AllowPurgePixels.

Discussion

The background color is the color of the pixels in the bitmap wherever no drawing has taken place. By default the background color of a GrafPort is white.

The BackColor function sets the background color for the current graphics port to the color that you specify in the color parameter. When you draw with the patCopy and srcCopy transfer modes, for example, white pixels are drawn in the color you specify with BackColor.

All nonwhite colors appear as black on black-and-white screens. Before you use BackColor, use the DeviceLoop function to determine the color characteristics of the current screen.

Discussion

The BackPat function sets the bit pattern defined in the Pattern structure, which you specify in the pat parameter, to be the background pattern. (The standard bit patterns white, black, gray, ltGray, and dkGray are predefined; the initial background pattern for the graphics port is white.) This pattern is stored in the bkPat field of a GrafPort structure.

The BackPat function also sets a bit pattern for the background color in a color graphics port. The BackPat function creates a handle, of type PixPatHandle, for the bit pattern and stores this handle in the bkPixPat field of the CGrafPort structure. As in basic graphics ports, Color QuickDraw draws patterns in color graphics ports at the time of drawing, not at the time you use PenPat to set the pattern.

To define your own patterns, you typically create pattern, ‘PAT’, or pattern list, ‘PAT#’, resources.

Discussion

Setting the background pattern allows the ScrollRect function and the shape-erasing functions (for example, EraseRect) to fill the background with a colored patterned “ink.”

The BackPixPat function is similar to the basic QuickDraw function BackPat, except that you pass BackPixPat a handle to a multicolored pixel pattern instead of a bit pattern.

The handle to the pixel pattern is stored in the bkPixPat field of the CGrafPort structure, therefore, you should not dispose of this handle since QuickDraw removes all references to your pattern from an existing graphics port when you dispose of it.

If you use BackPixPat to set a background pixel pattern in a basic graphics port, the data in the pat1Data field of the PixPat structure is placed into the bkPat field of the GrafPort structure.

To define your own pixel pattern, create a pixel pattern resource, x is described on 'ppat', or use the NewPixPat function. To set the background pattern to a bit pattern, you can also use the QuickDraw function, BackPat.

Discussion

The BitMapToRegion function converts a given BitMap or PixMap structure to a region. Pixels are added to the region where the corresponding entries in the bitmap have a value of 1. You would generally use this region later for drawing operations.

Discussion

Specify a source image in the srcBits parameter and in the srcRect parameter, specify a rectangle within that source image. Starting from the edges of this rectangle, CalcCMask calculates which pixels cannot be filled. By default, CalcCMask returns 1’s in the mask to indicate which pixels have the exact color that you specify in the seedRGB parameter and which pixels are enclosed by shapes whose outlines consist entirely of pixels with this color.

For instance, if the source image in srcBits contains a dark blue rectangle on a red background, and your application sets seedRGB equal to dark blue, then CalcCMask returns a mask with 1’s in the positions corresponding to the edges and interior of the rectangle, and the 0’s outside of the rectangle.

If you set the matchProc and matchData parameters to 0, CalcCMask uses the exact color specified in the RGBColor structure that you supply in the seedRGB parameter. You can customize CalcCMask by writing your own color search function and pointing to it in the matchProc parameter. As with SeedCFill, you can then use the matchData parameter in any manner useful for your application.

The CalcCMask function does not scale so the source and destination rectangles must be the same size. Calls to CalcCMask are not clipped to the current port and are not stored into QuickDraw pictures.

Discussion

The CalcMask function produces a bit image with 1’s in all pixels to which paint could not flow from any of the outer edges of the rectangle. Use this bit image as a mask with the CopyBits or CopyMask function. A hollow object produces a solid mask, but an open object produces a mask of itself.

As with the SeedFill function, point to the bit image you want to fill with the srcPtr parameter, which can point to the image’s base address or a word boundary within the image. Specify a pixel height and word width with the height and words parameters to define a fill rectangle that delimits the area you want to fill. The fill rectangle can be the entire bit image or a subset of it. Point to a destination image with the dstPtr parameter. Specify the row widths of the source and destination bitmaps (their rowBytes values) with the srcRow and dstRow parameters. (The bitmaps can be different sizes, but they must be large enough to contain the fill rectangle at the origins specified by srcPtr and dstPtr.)

Calls to CalcMask are not clipped to the current port and are not stored into QuickDraw pictures.

Discussion

This function sets the clipping path in the specified context to closely approximate the geometry of the specified region.

Unlike clipping in Quartz 2D, this function does not intersect the new region-based path with the current clipping path—the new path simply replaces the current clipping path.

You should use this function only when absolutely necessary—it’s relatively inefficient when compared to Quartz 2D clipping functions such as CGContextClipToRect.

Discussion

Since ClipRect makes a copy of the given rectangle, any subsequent changes you make to that rectangle do not affect the clipping region of the port.

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

Discussion

The ClosePicture function stops collecting drawing commands and picture comments for the currently open picture. You should perform one and only one call to ClosePicture for every call to the OpenCPicture (or OpenPicture) function.

The ClosePicture function calls the ShowPen function, balancing the call made by OpenCPicture (or OpenPicture) to the HidePen function.

Discussion

The ClosePoly function stops collecting line-drawing commands for the currently open polygon and computes the polyBBox field of the Polygon structure. You should call ClosePoly only once for every call to the OpenPoly function.

The ClosePoly function uses the ShowPen function, balancing the call to the HidePen function made by the OpenPoly function.

Discussion

The CloseRgn function 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 CloseRgn function does not create the destination region; you must have already allocated space for it by using the OpenRgn function. The CloseRgn function calls the ShowPen function, balancing the call to the HidePen function made by OpenRgn.

When you no longer need the memory occupied by the region, use the DisposeRgn function.

If the points or rectangles supplied to this function 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 SetPort function to change to the graphics port containing the points or rectangles, using the LocalGlobal function to convert their locations to global coordinates, using SetPort to return to your starting graphics port, and then using the GlobalToLocal function to convert the locations of points or rectangles to the local coordinates of your current graphics port.

Discussion

You should not call Color2Index from within a custom search function (described in ColorSearchProcPtr ).

Discussion

The ColorBit function is called by printing software for a color printer (or other color-imaging software) to set the GrafPort structure’s colorBit field to the value in the whichBit parameter. This value tells QuickDraw which plane of the color picture to draw into. QuickDraw draws into the plane corresponding to the bit number specified by the whichBit parameter. Since QuickDraw can support output devices that have up to 32 bits of color information per pixel, the possible range of values for whichBit is 0 through 31. The initial value of the colorBit field is 0.

Discussion

The CopyBits function transfers any portion of a bitmap between two basic graphics ports, or any portion of a pixel map between two color graphics ports. Use CopyBits to move offscreen graphic images into an onscreen window, to blend colors for the image in a pixel map, and to shrink and expand images.

Specify a source bitmap in the srcBits parameter and a destination bitmap in the dstBits parameter. When copying images between color graphics ports, you must coerce each CGrafPort structure to a GrafPort structure, dereference the portBits fields of each, and then pass these “bitmaps” in the srcBits and dstBits parameters. If your application copies a pixel image from a color graphics port called MyColorPort, for example, you could specify (* GrafPtr(MyColorPort)).portBits in the srcBits parameter. In a CGrafPort structure, the high 2 bits of the portVersion field are set. This field, which shares the same position in a CGrafPort structure as the portBits.rowBytes field in a GrafPort structure, indicates to CopyBits that you have passed it a handle to a pixel map rather than a bitmap.

Using the srcRect and dstRect parameters, you can specify identically or differently sized source and destination rectangles; for differently sized rectangles, CopyBits scales the source image to fit the destination. If the bit image is a circle in a square source rectangle, and the destination rectangle is not square, the bit image appears as an oval in the destination. When you specify rectangles in the srcRect and dstRect parameters, use the local coordinate systems of, respectively, the source and destination graphics ports.

The CopyDeepMask function combines the functions of the CopyBits and CopyMask functions.

Discussion

CopyDeepMask combines the effects of the CopyBits and CopyMask functions. You specify a mask to CopyDeepMask so that it transfers the source image to the destination image only where the bits of the mask are set to 1. Use CopyDeepMask to move offscreen graphic images into an onscreen window, to blend colors for the image in a pixel map, and to shrink and expand images.

When copying images between color graphics ports, you must coerce each port’s CGrafPort structure to a GrafPort structure, dereference the portBits fields of each, and then pass these “bitmaps” in the srcBits and dstBits parameters. If your application copies a pixel image from a color graphics port called MyColorPort, for example, you could specify (* GrafPtr(MyColorPort)).portBits in the srcBits parameter. The transfer can be performed in any of the transfer modes—with or without adding the ditherCopy constant—that are available to CopyBits.

Using the srcRect and dstRect parameters, you can specify identically or differently sized source and destination rectangles; for differently sized rectangles, CopyDeepMask scales the source image to fit the destination. When you specify rectangles in the srcRect and dstRect parameters, use the local coordinate systems of, respectively, the source and destination graphics ports.

If you specify pixel maps to CopyDeepMask, they may range from 1 to 32 pixels in depth. The pixel depth of the mask that you specify in the maskBits parameter is applied as a filter between the source and destination pixel maps that you specify in the srcBits and dstBits parameters. A black mask pixel value means that the copy operation is to take the source pixel a white value means that the copy operation is to take the destination pixel. Intermediate values specify a weighted average, which is calculated on a color component basis. For each pixel’s color component value, the calculation is

(1 – mask) x source + (mask) x destination

Thus high mask values for a pixel’s color component reduce that component’s contribution from the source PixMap structure.

Discussion

The CopyMask function copies the source bitmap or pixel map that you specify in the srcBits parameter to a destination bitmap or pixel map that you specify in the dstBits parameter—but only where the bits of the mask bitmap or pixel map that you specify in the maskBits parameter are set to 1. When copying images between color graphics ports, you must coerce each CGrafPort structure to a GrafPort structure, dereference the portBits fields of each, and then pass these “bitmaps” in the srcBits and dstBits parameters. If your application copies a pixel image from a color graphics port called MyColorPort, for example, you could specify (* GrafPtr(MyColorPort)).portBits in the srcBits parameter.

Using the srcRect and dstRect parameters, you can specify identically or differently sized source and destination rectangles; for differently sized rectangles, CopyMask scales the source image to fit the destination. When you specify rectangles in the srcRect and dstRect parameters, use the local coordinate systems of, respectively, the source and destination graphics ports.

If you specify pixel maps to CopyMask, they may range from 1 to 32 pixels in depth. The pixel depth of the mask that you specify in the maskBits parameter is applied as a filter between the source and destination pixel maps that you specify in the srcBits and dstBits parameters. A black mask pixel value means that the copy operation is to take the source pixel a white value means that the copy operation is to take the destination pixel. Intermediate values specify a weighted average, which is calculated on a color component basis. For each pixel’s color component value, the calculation is

(1 – mask) x source + (mask) x destination

Thus high mask values for a pixel’s color component reduce that component’s contribution from the source PixMap structure.

Use the bitmap returned by CalcMask as the mask in order to implement a mask copy similar to that performed by the MacPaint lasso tool. In the same way, you can use the pixel map returned by the CalcCMask function.

The CopyDeepMask function combines the functions of the CopyMask and CopyBits functions.

Discussion

Typically, you do not need to call this function in your application code, because the CopyPixMap function copies the contents of the source PixMap structure to the destination PixMap structure. The contents of the color table are copied, so the destination PixMap has its own copy of the color table. Because the baseAddr field of the PixMap structure is a pointer, the pointer, but not the image itself, is copied.

Discussion

The CopyPixPat function copies all of the fields in the source PixPat structure, including the contents of the data handle, expanded data handle, expanded map, pixel map handle, and color table.

Generally, your application should create a pixel pattern in a 'ppat' resource, instead of using this function.

Discussion

The CopyRgn function copies the mathematical structure of the region whose handle you pass in the srcRgn parameter into the region whose handle you pass in the dstRgn parameter; that is, CopyRgn makes a duplicate copy of srcRgn. When calling CopyRgn, pass handles that have been returned by the NewRgn function in the srcRgn and dstRgn parameters.

Once this is done, the region indicated by srcRgn may be altered (or even disposed of) without affecting the region indicated by dstRgn. The CopyRgn function does not create the destination region; space must already have been allocated for it by using the NewRgn function.

Discussion

This function is not recommended in Mac OS X version 10.1 and later. For information about its replacement, see QDBeginCGContext.

Discussion

This function returns a graphics port used to draw directly to a display. The pixel map for the new port is taken from the GDevice record corresponding to the display. There is no back buffer associated with the port.

Before calling this function, you should capture the display. For information about capturing displays, see Quartz Display Services Reference.

You should not call this function and then attempt to create a Quartz drawing environment inside the port. Instead, applications using Quartz 2D can call CGDisplayGetDrawingContext to obtain a context suitable for drawing directly to a captured display.

Discussion

The CTabChanged function calls the function GetCTSeed and gets a new, unique identifier in the ctSeed field of the ColorTable structure, and notifies QuickDraw of the change.

Your application should never need to directly modify a ColorTable structure and use the CTabChanged function; instead, your application should use the QuickDraw functions provided for manipulating the values in a ColorTable structure.

Discussion

You should not cast the result to a Point data structure. Instead, use HiWord and LoWord to obtain the horizontal and vertical differences.

For example:

    Point pointDiff;

    SInt32 difference = DeltaPoint(p1, p2);

    pointDiff.h = LoWord(difference);

    pointDiff.v = HiWord(difference);

While DeltaPoint is supported in Carbon, you can achieve the same result in a more direct manner using the function SubPt.

Discussion

The DeviceLoop function searches for graphics devices that intersect your window’s drawing region, and it calls your drawing function for each dissimilar video device it finds.

Because DeviceLoop provides your drawing function with the pixel depth and other attributes of each video device, your drawing function can optimize its drawing for each video device.

See DeviceLoopDrawingProcPtr for a description of the drawing function you must provide for the drawingProc parameter.

Discussion

The DiffRgn procedure subtracts the region whose handle you pass in the srcRgnB parameter from the region whose handle you pass in the srcRgnA parameter and places the difference in the region whose handle you pass in the dstRgn parameter. If the first source region is empty, DiffRgn sets the destination to the empty region defined by the rectangle (0,0,0,0).

The DiffRgn procedure does not create the destination region; you must have already allocated memory for it by using the NewRgn function. The destination region may be one of the source regions, if desired.

Discussion

Use DisposeCCursor for each call to the GetCCursor function.

The DisposeCCursor function is also available as the DisposCCursor function.

Discussion

The DisposeCTable procedure disposes of the ColorTable record whose handle you pass in the cTable parameter.

Discussion

Generally, you should never need to use this function. Color QuickDraw calls this function when appropriate. The DisposeGDevice function is also available as the DisposGDevice function.

When your application uses the DisposeGWorld function to dispose of an offscreen graphics world, DisposeGDevice disposes of its GDevice structure.

Discussion

The DisposeGWorld function disposes of all the memory allocated for the specified offscreen graphics world, including the pixel map, color table, pixel image, and GDevice structure (if one was created).

Call DisposeGWorld only when your application no longer needs the pixel image associated with this offscreen graphics world. If this offscreen graphics world was the current device, the current device is reset to the device stored in the global variable MainDevice.

Discussion

The CloseCPort function calls DisposePixMap.

Your application typically does not need to call this function. This function is also available as DisposPixMap.

If your application uses DisposePixMap, take care that it does not dispose of a PixMap structure whose color table is the same as the current device’s CLUT.

Discussion

The DisposePixPat function disposes of the data handle, expanded data handle, and pixel map handle allocated to the pixel pattern that you specify in the ppat parameter.

The DisposePixPat function is also available as the DisposPixPat function.

Discussion

Use DisposeRgn only after you are completely through with a region.

Discussion

Generally, applications do not need to use DisposeScreenBuffer. The DisposeGWorld function uses the DisposeScreenBuffer function when disposing of an offscreen graphics world.

The DisposeScreenBuffer function disposes of the memory allocated for the base address of an offscreen pixel image.

Discussion

Within the rectangle that you specify in the dstRect parameter, the DrawPicture function draws the picture that you specify in the myPicture parameter.

The DrawPicture function passes any picture comments to the StdComment function pointed to by the commentProc field of the CQDProcs or QDProcs structure, which in turn is pointed to by the grafProcs field of a CGrafPort or GrafPort structure. The default StdComment function provided by QuickDraw does no comment processing whatsoever. If you want to process picture comments when drawing a picture, use the SetStdCProcs function to assist you in changing the CQDProcs structure and use the SetStdProcs function to assist you in changing the QDProcs structure.

Discussion

If the points or rectangles supplied to this function 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 SetPort function to change to the graphics port containing the points or rectangles, using the LocalGlobal function to convert their locations to global coordinates, using SetPort to return to your starting graphics port, and then using the GlobalToLocal function to convert the locations of points or rectangles to the local coordinates of your current graphics port.

Discussion

The EmptyRgn function does not create an empty region. To create an empty region, you can perform any of the following operations:

• Use NewRgn.

• Pass the handle to an empty region to CopyRgn.

• Pass an empty rectangle to either SetRectRgn or RectRgn.

• Call CloseRgn without a previous call to OpenRgn.

• Call CloseRgn without performing any drawing after calling OpenRgn.

• Pass an empty region to OffsetRgn.

• Pass an empty region or too large an inset to InsetRgn

• Pass two nonintersecting regions to SectRgn.

• Pass two empty regions to UnionRgn.

• Pass two identical or nonintersecting regions to DiffRgn or XorRgn.

Discussion

The EqualPt function compares the points specified in the pt1 and pt2 parameters and returns TRUE if their coordinates are equal or FALSE if they are not.

Discussion

If the points or rectangles supplied to this function 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 SetPort function to change to the graphics port containing the points or rectangles, using the LocalGlobal function to convert their locations to global coordinates, using SetPort to return to your starting graphics port, and then using the GlobalToLocal function to convert the locations of points or rectangles to the local coordinates of your current graphics port.

Discussion

The EqualRgn function compares the two regions whose handles you pass in the rgnA and rgnB parameters and returns TRUE if they’re equal or FALSE if they’re not.

The two regions must have identical sizes, shapes, and locations to be considered equal. Any two empty regions are always equal.

Discussion

Using the patCopy pattern mode, the EraseArc function draws a wedge of the oval bounded by the rectangle that you specify in the r parameter with the background pattern for the current graphics port. As in FrameArc , use the startAngle and arcAngle parameters to define the arc of the wedge.

This function leaves the location of the graphics pen unchanged.

Discussion

Using the background pattern for the current graphics port and the patCopy pattern mode, the EraseOval function draws the interior of an oval just inside the bounding rectangle that you specify in the r parameter. This effectively erases the oval bounded by the specified rectangle.

This function leaves the location of the graphics pen unchanged.

Discussion

Using the patCopy pattern mode, the ErasePoly function draws the interior of the polygon whose handle you pass in the poly parameter with the background pattern for the current graphics port.

This function leaves the location of the graphics pen unchanged.

This function temporarily converts the polygon into a region to perform their operations. The amount of memory required for this temporary region may be far greater than the amount required by the polygon alone.

You can estimate the size of this region by scaling down the polygon with the MapPoly , converting the polygon into a region, checking the region’s size with the Memory Manager function GetHandleSize, and multiplying that value by the factor by which you scaled the polygon.

The result of this graphics operation is undefined whenever any horizontal or vertical line drawn through the polygon would intersect the polygon’s outline more than 50 times.

Discussion

Using the patCopy pattern mode, the EraseRect function draws the interior of the rectangle that you specify in the r parameter with the background pattern for the current graphics port. This effectively erases the rectangle, making the shape blend into the background pattern of the graphics port. For example, use EraseRect to erase the port rectangle for a window before redrawing into the window.

This function leaves the location of the graphics pen unchanged.

Discussion

Using the patCopy pattern mode, the EraseRgn function draws the interior of the region whose handle you pass in the rgn parameter with the background pattern for the current graphics port.

This function leaves the location of the graphics pen unchanged.

This function depends on the local coordinate system of the current graphics port. If you draw a region in a graphics port different from the one in which you defined the region, it may not appear in the proper position in the graphics port.

If any horizontal or vertical line drawn through the region would intersect the region’s outline more than 50 times, the results of this graphics operation are undefined.

Discussion

Using the patCopy pattern mode, the EraseRoundRect function draws the interior of the rounded rectangle bounded by the rectangle that you specify in the r parameter with the background pattern of the current graphics port. This effectively erases the rounded rectangle. Use the ovalWidth and ovalHeight parameters to specify the diameters of curvature for the corners of the rounded rectangle.

This function leaves the location of the graphics pen unchanged.

Discussion

Using the patCopy pattern mode and the pattern defined in the Pattern structure that you specify in the pat parameter, the FillArc function draws a wedge of the oval bounded by the rectangle that you specify in the r parameter. As in FrameArc use the startAngle and arcAngle parameters to define the arc of the wedge.

This function leaves the location of the graphics pen unchanged.

Use GetPattern and GetIndPattern to get a pattern stored in a resource.

Use PaintArc to draw a wedge with the pen pattern for the current graphics port.

To fill a wedge with a pixel pattern, use the FillCArc function.

Discussion

Use the startAngle and arcAngle parameters to define the arc of the wedge. This function ignores the pnPat, pnMode, and bkPat fields of the current graphics port and leaves the pen location unchanged.

Discussion

This function ignores the pnPat, pnMode, and bkPat fields of the current graphics port and leaves the pen location unchanged.

Discussion

This function ignores the pnPat, pnMode, and bkPat fields of the current graphics port and leaves the pen location unchanged.

Discussion

This function ignores the pnPat, pnMode, and bkPat fields of the current graphics port and leaves the pen location unchanged.

Discussion

This function ignores the pnPat, pnMode, and bkPat fields of the current graphics port and leaves the pen location unchanged.

Discussion

Use the ovalWidth and ovalHeight parameters to specify the diameters of curvature for the corners. This function ignores the pnPat, pnMode, and bkPat fields of the current graphics port and leaves the pen location unchanged.

Discussion

Using the patCopy pattern mode and the bit pattern defined in the Pattern structure that you specify in the pat parameter, the FillOval function draws the interior of an oval just inside the bounding rectangle that you specify in the r parameter. The pen location does not change.

Use GetPattern and GetIndPattern , to get a pattern stored in a resource. Use the PaintOval function to draw the interior of an oval with the pen pattern for the current graphics port.

To fill an oval with a pixel pattern, use the FillCOval function.

Discussion

Using the patCopy pattern mode, the FillPoly function draws the interior of the polygon whose handle you pass in the poly parameter with the pattern defined in the Pattern structure that you specify in the pat parameter.

This function leaves the location of the graphics pen unchanged.

This function temporarily converts the polygon into a region to perform their operations. The amount of memory required for this temporary region may be far greater than the amount required by the polygon alone.

You can estimate the size of this region by scaling down the polygon with the MapPoly , converting the polygon into a region, checking the region’s size with the Memory Manager function GetHandleSize, and multiplying that value by the factor by which you scaled the polygon.

The result of this graphics operation is undefined whenever any horizontal or vertical line drawn through the polygon would intersect the polygon’s outline more than 50 times.

Use GetPattern and GetIndPattern to get a pattern stored in a resource.

Use PaintPoly to draw the interior of a polygon with the pen pattern for the current graphics port. To fill a polygon with a pixel pattern, use the FillCPoly function.

Discussion

Using the patCopy pattern mode, the FillRect function draws the interior of the rectangle that you specify in the r parameter with the pattern defined in the Pattern structure that you specify in the pat parameter. This function leaves the pen location unchanged.

Use GetPattern and GetIndPattern , to get a pattern stored in a resource.

Use the PaintRect to draw the interior of a rectangle with the pen pattern for the current graphics port. To fill a rectangle with a pixel pattern, use the FillCRect function.

Discussion

Using the patCopy pattern mode, the FillRgn function draws the interior of the region with the pattern defined in the Pattern structure that you specify in the pat parameter.

This function leaves the location of the graphics pen unchanged.

This function depends on the local coordinate system of the current graphics port. If you draw a region in a graphics port different from the one in which you defined the region, it may not appear in the proper position in the graphics port.

If any horizontal or vertical line drawn through the region would intersect the region’s outline more than 50 times, the results of this graphics operation are undefined.

Use GetPattern and GetIndPattern to get a pattern stored in a resource.

Use PaintRgn to draw the interior of a region with the pen pattern for the current graphics port. To fill a region with a pixel pattern, use the FillCRegion function.

Discussion

Using the patCopy pattern mode, the FillRoundRect function draws the interior of the rounded rectangle bounded by the rectangle that you specify in the r parameter with the bit pattern defined in the Pattern structure that you specify in the pat parameter. Use the ovalWidth and ovalHeight parameters to specify the diameters of curvature for the corners. The pen location does not change.

To fill a rounded rectangle with a pixel pattern, use the FillCRoundRect function.

Use GetPattern and GetIndPattern to get a pattern stored in a resource. Use PaintRoundRect to draw the interior of a rounded rectangle with the pen pattern for the current graphics port.

Discussion

By default, the foreground color of a GrafPort is black.

The ForeColor function sets the foreground color for the current graphics port to the color that you specify in the color parameter. When you draw with the patCopy and srcCopy transfer modes, for example, black pixels are drawn in the color you specify with ForeColor.

When printing, use the ColorBit function to set the foreground color.

All nonwhite colors appear as black on black-and-white screens. Before you use ForeColor, use the DeviceLoop function to determine the color characteristics of the current screen.

Discussion

Using the pattern, pattern mode, and size of the graphics pen for the current graphics port, the FrameArc function draws an arc of the oval bounded by the rectangle that you specify in the r parameter. Use the startAngle parameter to specify where the arc begins as modulo 360. Use the arcAngle parameter to specify how many degrees the arc covers. Specify whether the angles are in positive or negative degrees a positive angle goes clockwise, while a negative angle goes counterclockwise. Zero degrees is at 12 o’clock high, 90 (or –270) is at 3 o’clock, 180 (or –180) is at 6 o’clock, and 270 (or –90) is at 9 o’clock. Measure other angles relative to the bounding rectangle.

A line from the center of the rectangle through its upper-right corner is at 45, even if the rectangle is not square a line through the lower-right corner is at 135, and so on.

The arc is as wide as the pen width and as tall as the pen height. The pen location does not change.

Discussion

Using the pattern, pattern mode, and size of the graphics pen for the current graphics port, the FrameOval function draws an outline just inside the oval with the bounding rectangle that you specify in the r parameter. The outline is as wide as the pen width and as tall as the pen height. The pen location does not change.

If a region is open and being formed, the outside outline of the new oval is mathematically added to the region’s boundary.

Discussion

Using the current graphics port’s pen pattern, pattern mode, and size, the FramePoly function plays back the line-drawing commands that define the polygon whose handle you pass in the poly parameter.

The graphics pen hangs below and to the right of each point on the boundary of the polygon. Thus, the drawn polygon extends beyond the right and bottom edges of the polygon’s bounding rectangle (which is stored in the polyBBox field of the Polygon structure) by the pen width and pen height, respectively. All other graphics operations, such as painting a polygon with the PaintPoly function, occur strictly within the boundary of the polygon.

If a polygon is open and being formed, FramePoly affects the outline of the polygon just as if the line-drawing functions themselves had been called. If a region is open and being formed, the outside outline of the polygon being framed is mathematically added to the region’s boundary.

The result of this function is undefined whenever any horizontal or vertical line through the polygon would intersect the polygon’s outline more than 50 times.

Discussion

Using the pattern, pattern mode, and size of the graphics pen for the current graphics port, the FrameRect function draws an outline just inside the rectangle that you specify in the r parameter. The outline is as wide as the pen width and as tall as the pen height. The pen location does not change.

If a region is open and being formed, the outside outline of the new rectangle is mathematically added to the region’s boundary.

Discussion

Using the current graphics port’s pen pattern, pattern mode, and pen size, the FrameRgn function draws an outline just inside the region whose handle you pass in the rgn parameter. The outline never goes outside the region boundary. The pen location does not change.

If a region is open and being formed, the outside outline of the region being framed is mathematically added to that region’s boundary.

This function depends on the local coordinate system of the current graphics port. If you draw a region in a graphics port different from the one in which you defined the region, it may not appear in the proper position in the graphics port.

If any horizontal or vertical line drawn through the region would intersect the region’s outline more than 50 times, the results of this graphics operation are undefined. The FrameRgn function in particular requires that there would be no more than 25 such intersections.

Discussion

Using the pattern, pattern mode, and size of the graphics pen for the current graphics port, the FrameRoundRect function draws an outline just inside the rounded rectangle bounded by the rectangle that you specify in the r parameter. The outline is as wide as the pen width and as tall as the pen height. The pen location does not change.

Use the ovalWidth and ovalHeight parameters to specify the diameters of curvature for the corners of the rounded rectangle.

If a region is open and being formed, the outside outline of the new rounded rectangle is mathematically added to the region’s boundary.

Discussion

If your application changes the pmTable field of the PixMap structure specified in a GDevice structure, call GDeviceChanged. If your application changes the content of the ColorTable structure referenced by the PixMap structure, call both GDeviceChanged and CTabChanged.

Your application should never need to directly modify a GDevice structure and use the GDeviceChanged function; instead, your application should use the QuickDraw functions described in this book for manipulating the values in a GDevice structure.

Discussion

This function operates for graphics ports defined by both the GrafPort and CGrafPort structures. If the current graphics port is defined by a CGrafPort structure, the returned value is taken directly from the rgbBkColor field.

If the current graphics port is defined by a GrafPort structure, then only eight possible colors can be returned. These eight colors are determined by the values in a global variable named QDColors, which is a handle to a color table containing the current QuickDraw colors.

Use the RGBBackColor function to change the background color.

Discussion

The GetCCursor function creates a new CCrsr structure and initializes it using the information in the ‘crsr’ resource with the specified ID.

Since the GetCCursor function creates a new CCrsr structure each time it is called, do not call the GetCCursor function before each call to the SetCCursor function. Unlike the way GetCursor and SetCursor are normally used, GetCCursor does not dispose of or detach the resource, so resources of type 'crsr' should typically be purgeable. Call the DisposeCCursor function when you are finished using the color cursor created with GetCCursor.

Discussion

You can use the GetClip and SetClip functions to preserve the current clipping region: use GetClip to save the current port’s clipping region, and use SetClip to restore it. If, for example, you want to draw a half-circle on the screen, you can set the clipping region to half of the square that would enclose the whole circle, and then draw the whole circle. Only the half within the clipping region is actually drawn in the graphics port.

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

Discussion

Use the SetCPixel function to change the color of this pixel.

Discussion

Before you modify a ColorTable structure, change its ctSeed field to invalidate it. To do this, use the CTabChanged function.

The GetCTable function recognizes a number of standard 'clut' resource IDs. You can obtain the default grayscale color table for a given pixel depth by calling GetCTable, adding 32 (decimal) to the pixel depth, and passing these values in the ctID parameter:

• A pixel depth of 1. Pass a resource ID of 33. Color table composition: black, white.

• A pixel depth of 2. Pass a resource ID of 34. Color table composition: black, 33% gray, 66% gray, white.

• A pixel depth of 4. Pass a resource ID of 36. Color table composition: black, 14 shades of gray, white.

• A pixel depth of 8. Pass a resource ID of 40. Color table composition: black, 254 shades of gray, white.

For full color, obtain the default color tables by adding 64 to the pixel depth and passing these values in the ctID parameter:

• A pixel depth of 2. Pass a resource ID of 66. Color table composition: black, 50% gray, highlight color, white.

• A pixel depth of 4. Pass a resource ID of 68. Color table composition: black, 14 colors including the highlight color, white.

• A pixel depth of 8. Pass a resource ID of 72. Color table composition: black, 254 colors including the highlight color, white.

Discussion

The seed value guarantees that the color table is recognized as distinct from the destination, and that color table translation is performed properly.

Discussion

To get a handle to a color cursor, use the GetCCursor function.

Discussion

All existing GDevice structures are linked together in the device list. After using this function to obtain a handle to the current GDevice structure, your application can use the GetNextDevice function to obtain a handle to the next GDevice structure in the list.

Discussion

This function operates for graphics ports defined by both the GrafPort and CGrafPort structures. If the current graphics port is defined by a CGrafPort structure, the returned value is taken directly from the rgbFgColor field.

If the current graphics port is defined by a GrafPort structure, then only eight possible RGB values can be returned. These eight values are determined by the values in a global variable named QDColors, which is a handle to a color table containing the current QuickDraw colors.

Use the RGBForeColor function to change the foreground color.

Discussion

At any given time, exactly one video device is the current device—that is, the one on which drawing is actually taking place.

Color QuickDraw stores a handle to the current device in the global variable TheGDevice.

All existing GDevice structures are linked together in the device list. After using this function to obtain a handle to the current GDevice structure, your application can use the GetNextDevice function to obtain a handle to the next GDevice structure in the list.

You can also use the GetGWorld function to get a handle to the GDevice structure for the current device.

Discussion

After using GetGWorld to save a graphics port and a GDevice structure, use the SetGWorld function to restore them.

Discussion

The GetIndPattern function calls the following Resource Manager function with these parameters:

GetResource('PAT#', patternListID);

There is a pattern list resource in the System file that contains the standard Macintosh patterns used by MacPaint. The resource ID is represented by the constant sysPatListID.

Discussion

A handle to the main device is kept in the global variable MainDevice.

All existing GDevice structures are linked together in the device list. After using this function to obtain a handle to the current GDevice structure, your application can use the GetNextDevice function to obtain a handle to the next GDevice structure in the list.

Discussion

All existing GDevice structures are linked together in the device list. After using this function to obtain a handle to the current GDevice structure, your application can use the GetNextDevice function to obtain a handle to the next GDevice structure in the list.

Discussion

After using any of the functions GetDeviceList , GetGDevice , GetMainDevice , or GetMaxDevice to obtain a handle to a GDevice structure, use the GetNextDevice function to obtain a handle to the next GDevice structure in the list.

Discussion

The GetPattern function calls the following Resource Manager function with these parameters:

GetResource('PAT', patID);

When you are finished using the pattern, dispose of its handle with the Memory Manager function DisposeHandle.

Discussion

In the pt parameter, the GetPen procedure returns the current pen position. The point returned is in the local coordinates of the current graphics port.

Discussion

After changing the graphics pen as necessary, restore these pen states with the SetPenState function.

This pen-manipulation function uses the local coordinate system of the current graphics port. Remember that each graphics port has its own pen, the state of which is stored in several fields of its GrafPort or CGrafPort structure. If you draw in one graphics port, change to another, and return to the first, the pen for the first graphics port has the same state as when you left it.

Discussion

The GetPicture function calls the Resource Manager function GetResource as follows:

GetResource(‘PICT’, picID)

Discussion

The baseAddr field of the PixMap structure for an offscreen graphics world contains a handle instead of a pointer, which is what the baseAddr field for an onscreen pixel map contains. You must use the GetPixBaseAddr function to obtain a pointer to the PixMap structure for an offscreen graphics world.

Your application should never directly access the baseAddr field of the PixMap structure for an offscreen graphics world; instead, always use GetPixBaseAddr. If your application is using 24-bit mode, use the PixMap32Bit function to determine whether a pixel map requires 32-bit addressing mode for access to its pixel image.

Discussion

The selected pixel is immediately below and to the right of the point whose coordinates you supply in the h and v parameters, in the local coordinates of the current graphics port. There’s no guarantee that the specified pixel actually belongs to the current graphics port, however it may have been drawn in a graphics port overlapping the current one. To see if the point indeed belongs to the current graphics port, you could use the PtInRgn function to test whether the point is in the current graphics port’s visible region.

Discussion

After using GetPixelsState to save this state information, use the SetPixelsState function to restore this state to the offscreen graphics world.

After using GetPixelsState and before using SetPixelsState, temporarily use the AllowPurgePixels function to make the base address for an offscreen pixel image purgeable, the NoPurgePixels function to make it unpurgeable, the LockPixels function to prevent it from being moved, and the UnlockPixels function to allow it to be moved.

Discussion

When you are finished with the pixel pattern, use the DisposePixPat function. For more information on the pixel pattern resource, see 'ppat'.

Pixel patterns can use colors at any pixel depth and can be of any width and height that’s a power of 2. To create a pixel pattern, you typically define it in a 'ppat' resource, which you store in a resource file. To retrieve the pixel pattern stored in a 'ppat' resource, you can use the GetPixPat function.

Discussion

When your application runs in Color QuickDraw or uses offscreen graphics worlds, it should use the GetGWorld function instead of GetPort. The GetGWorld function saves the current graphics port for basic and color graphics ports as well as offscreen graphics worlds.

Discussion

The Color Manager uses the Color2Index function for each RGBColor data structure in the color table of the myColors parameter. It determines the best match in the target table and stores that index value in the value field of the color table of the myColors parameter.

Depending on the requested resolution, building the inverse table can require large amounts of temporary space in the application heap: twice the size of the table itself, plus a fixed overhead of 3–15 KB for each inverse table resolution.

Discussion

The GlobalToLocal procedure takes a point expressed in global coordinates (where the upper-left corner of the main screen has coordinates [0,0]) and converts it into the local coordinates of the current graphics port.

Discussion

The HideCursor function removes the cursor from the screen, restores the bits under the cursor image, and decrements the cursor level (which InitCursor initialized to 0). You might want to use HideCursor when the user is using the keyboard to create content in one of your application’s windows. Every call to HideCursor should be balanced by a subsequent call to the ShowCursor function.

Discussion

The HidePen function is called by the OpenRgn , OpenPicture, and OpenPoly functions so that you can create regions, pictures, and polygons without drawing on the screen.

The HidePen function decrements the pnVis field of the current graphics port. The pnVis field is initialized to 0 by the OpenPort function. Whenever pnVis is negative, the pen does not draw on the screen. The pnVis field keeps track of the number of times the pen has been hidden to compensate for nested calls to the HidePen and ShowPen functions.

Every call to HidePen should be balanced by a subsequent call to ShowPen.

This pen-manipulation function uses the local coordinate system of the current graphics port. Remember that each graphics port has its own pen, the state of which is stored in several fields of its GrafPort or CGrafPort structure. If you draw in one graphics port, change to another, and return to the first, the pen for the first graphics port has the same state as when you left it.

Discussion

All drawing operations that use the hilite transfer mode use the highlight color. When a color graphics port is created, its highlight color is initialized from the global variable HiliteRGB.

If the current graphics port is a basic graphics port, HiliteColor has no effect.

Discussion

This function initializes the standard arrow cursor, sets the current cursor to the standard arrow, and makes the cursor visible. Classic Mac OS applications need to call this function when launching because the system sets the cursor to the watch cursor. Carbon applications running in Mac OS 9 or Mac OS X do not need to call this function.

Discussion

The InitGDevice function sets the graphics device whose driver has the reference number specified in the gdRefNum parameter to the mode specified in the mode parameter. The InitGDevice function then fills out the GDevice structure, previously created with the NewGDevice function, to contain all information describing that mode.

The mode parameter determines the configuration of the device. Possible modes for a device are determined by interrogating the video device’s ROM through Slot Manager functions. The information describing the device’s mode is primarily contained in the video device’s ROM. If the video device has a fixed color table, then that table is read directly from the ROM. If the video device has a variable color table, then InitGDevice uses the default color table defined in a 'clut' resource, contained in the System file, that has a resource ID equal to the video device’s pixel depth.

In general, your application should never need to call InitGDevice. All video devices are initialized at start time, and users change modes through the Monitors control panel.

If your program uses NewGDevice to create a graphics device without a driver, InitGDevice does nothing; instead, your application must initialize all fields of the GDevice structure. After your application initializes the color table for the GDevice structure, call the Color Manager function MakeITable to build the inverse table for the graphics device.

Discussion

The InsetRect function shrinks or expands the rectangle that you specify in the r parameter: the left and right sides are moved in by the amount you specify in the dh parameter; the top and bottom are moved toward the center by the amount you specify in the dv parameter. If the value you pass in dh or dv is negative, the appropriate pair of sides is moved outward instead of inward. The effect is to alter the size by 2*dh horizontally and 2*dv vertically, with the rectangle remaining centered in the same place on the coordinate plane.

If the resulting width or height becomes less than 1, the rectangle is set to the empty rectangle (0,0,0,0).

If the points or rectangles supplied to this function 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 SetPort function to change to the graphics port containing the points or rectangles, using the LocalGlobal function to convert their locations to global coordinates, using SetPort to return to your starting graphics port, and then using the GlobalToLocal function to convert the locations of points or rectangles to the local coordinates of your current graphics port.

Discussion

The InsetRgn function moves all points on the region boundary of the region whose handle you pass in the rgn parameter inward by the vertical distance that you specify in the dv parameter and by the horizontal distance that you specify in the dh parameter. If you specify negative values for dh or dv, the InsetRgn function moves the points outward in that direction.

The InsetRgn function leaves the region’s center at the same position, but moves the outline in (for positive values of dh and dv) or out (for negative values of dh and dv). Using InsetRgn on a rectangular region has the same effect as using the InsetRect function.

Discussion

The InvertArc function inverts the pixels enclosed by a wedge of the oval bounded by the rectangle that you specify in the r parameter. Every white pixel becomes black and every black pixel becomes white. As in FrameArc , use the startAngle and arcAngle parameters to define the arc of the wedge.

This function leaves the location of the graphics pen unchanged.

Discussion

The InvertOval function inverts the pixels enclosed by an oval just inside the bounding rectangle that you specify in the r parameter. Every white pixel becomes black and every black pixel becomes white. The pen location does not change.

Discussion

The InvertPoly function inverts the pixels enclosed by the polygon whose handle you pass in the poly parameter. Every white pixel becomes black and every black pixel becomes white.

This function leaves the location of the graphics pen unchanged.

InvertPoly temporarily converts the polygon into a region to perform their operations. The amount of memory required for this temporary region may be far greater than the amount required by the polygon alone.

You can estimate the size of this region by scaling down the polygon with the MapPoly , converting the polygon into a region, checking the region’s size with the Memory Manager function GetHandleSize, and multiplying that value by the factor by which you scaled the polygon.

The result of this graphics operation is undefined whenever any horizontal or vertical line drawn through the polygon would intersect the polygon’s outline more than 50 times.

Discussion

The InvertRect function inverts the pixels enclosed by the rectangle that you specify in the r parameter. Every white pixel becomes black and every black pixel becomes white. The pen location does not change.

Discussion

The InvertRgn function inverts the pixels enclosed by the region whose handle you pass in the rgn parameter. Every white pixel becomes black and every black pixel becomes white.

This function leaves the location of the graphics pen unchanged.

This function depends on the local coordinate system of the current graphics port. If you draw a region in a graphics port different from the one in which you defined the region, it may not appear in the proper position in the graphics port.

If any horizontal or vertical line drawn through the region would intersect the region’s outline more than 50 times, the results of this graphics operation are undefined.

Discussion

The InvertRoundRect function inverts the pixels enclosed by the rounded rectangle bounded by the rectangle that you specify in the r parameter. Every white pixel becomes black and every black pixel becomes white. The ovalWidth and ovalHeight parameters specify the diameters of curvature for the corners. The pen location does not change.

Discussion

Use this function only when you are completely finished with a picture.

Discussion

Use KillPoly only when you are completely through with a polygon.

Discussion

Starting at the current location of the graphics pen, the Line function draws a line the horizontal distance that you specify in the dh parameter and the vertical distance that you specify in the dv parameter. The Line function calls

LineTo(h+dh,v+dv)