Customizing QuickDraw Operations

http://mcosre.sourceforge.net/docs/customizing_QD.html
12/30/2004

	D o c u m e n t a t i o n `Customizing QuickDraw Operations`

`[Home] \| [About McOS Re] \| [FAQ] \| [Changes] \| [Progress] \| [Documentation] \| [Links]`

Customizing QuickDraw Operations

For each shape that QuickDraw can draw, there are procedures that perform these basic graphics operations on the shape: frame, paint, erase, invert, and fill. Those procedures in turn call a low-level drawing routine for the shape. For example, the FrameOval, PaintOval, EraseOval, InvertOval, and FillOval procedures all call the low-level procedure StdOval, which draws the oval.

Other low-level routines defined by QuickDraw are:

The procedure called by CopyBits that performs bit and pixel transfer.
The function that measures the width of text and is called by the QuickDraw text routines CharWidth, StringWidth, and TextWidth.
The procedure that processes picture comments. The standard procedure ignores picture comments.
The procedure that saves drawing commands as the definition of a picture, and the procedure that retrieves them. These two enable your application to draw on remote devices, print to the disk, get picture input from the disk, and support large pictures.

For each type of object QuickDraw can draw, including text and lines, there's a pointer to one of these low-level routines. The standard QuickDraw low-level routines should be called only from your customized routines.

The grafProcs field of a GrafPort or CGrafPort record determines which low-level routines are called. If that field contains the value of NIL, the standard routines are called. You can set the grafProcs field to point to a record of pointers to your own routines. For a basic graphics port, this record of pointers is defined by a QDProcs record.


textProc:           equ     0   * text drawing procedure, UPP
lineProc:           equ     4   * line drawing procedure, UPP
rectProc:           equ     8   * rectangle drawing procedure, UPP
rRectProc:          equ     12  * roundRect drawing procedure, UPP
ovalProc:           equ     16  * oval drawing procedure, UPP
arcProc:            equ     20  * arc/wedge drawing procedure, UPP
polyProc:           equ     24  * polygon drawing procedure, UPP
rgnProc:            equ     28  * region drawing procedure, UPP
bitsProc:           equ     32  * bit transfer procedure, UPP
commentProc:        equ     36  * picture comment processing, UPP
txMeasProc:         equ     40  * text width measurement, UPP
getPicProc:         equ     44  * picture retrieval procedure, UPP
putPicProc:         equ     48  * picture saving procedure, UPP

For a color graphics port, these pointers are contained in a CQDProcs record.


textProc:           equ     0   * text drawing procedure, UPP
lineProc:           equ     4   * line drawing procedure, UPP
rectProc:           equ     8   * rectangle drawing procedure, UPP
rRectProc:          equ     12  * roundRect drawing procedure, UPP
ovalProc:           equ     16  * oval drawing procedure, UPP
arcProc:            equ     20  * arc/wedge drawing procedure, UPP
polyProc:           equ     24  * polygon drawing procedure, UPP
rgnProc:            equ     28  * region drawing procedure, UPP
bitsProc:           equ     32  * bit transfer procedure, UPP
commentProc:        equ     36  * picture comment processing, UPP
txMeasProc:         equ     40  * text width measurement, UPP
getPicProc:         equ     44  * picture retrieval procedure, UPP
putPicProc:         equ     48  * picture saving procedure, UPP

opCodeProc:         equ     52  * reserved for future use, UPP
newProc1:           equ     56  * reserved for future use, UPP
newProc2:           equ     60  * reserved for future use, UPP
newProc3:           equ     64  * reserved for future use, UPP
newProc4:           equ     68  * reserved for future use, UPP
newProc5:           equ     72  * reserved for future use, UPP
newProc6:           equ     76  * reserved for future use, UPP

By changing these pointers, you can install your own routines, and either completely override the standard ones or call them after your routines have modified their parameters as necessary. The routines you install in a QDProcs record must have the same calling sequences as the standard routines.


PROCEDURE StdText (byteCount: Integer; textBuf: Ptr; numer, denom: Point);

byteCount   The number of bytes of text to draw.
textBuf     A memory structure containing the text to draw.
numer       Scaling numerator.
denom       Scaling denominator.

PROCEDURE StdLine (newPt: Point);

newPt       The point to which to draw the line.

PROCEDURE StdRect (verb: GrafVerb; r: Rect);

verb        One of the following actions to perform, as defined for 
            the GrafVerb data type:
                GrafVerb = (frame, paint, erase, invert, fill);
r           The rectangle to draw.

PROCEDURE StdRRect (verb: GrafVerb; r: Rect; ovalwidth, ovalHeight: Integer);

verb        One of the following actions to perform, as defined for 
            the GrafVerb data type:
                GrafVerb = (frame, paint, erase, invert, fill);
r           The rectangle to draw.
ovalwidth   The width diameter for the corner oval.
ovalHeight  The height diameter for the corner oval.

PROCEDURE StdOval (verb: GrafVerb; r: Rect);

verb        One of the following actions to perform, as defined for 
            the GrafVerb data type:
                GrafVerb = (frame, paint, erase, invert, fill);
r           The rectangle to contain the oval.

PROCEDURE StdArc (verb: GrafVerb; r: Rect; startAngle, arcAngle: Integer);

verb        One of the following actions to perform, as defined for 
            the GrafVerb data type:
                GrafVerb = (frame, paint, erase, invert, fill);
r           The rectangle to contain the arc.
startAngle  The beginning angle.
arcAngle    The ending angle.

PROCEDURE StdPoly (verb: GrafVerb; poly: PolyHandle);

verb        One of the following actions to perform, as defined for 
            the GrafVerb data type:
                GrafVerb = (frame, paint, erase, invert, fill);
poly        A handle to the polygon data.

PROCEDURE StdRgn (verb: GrafVerb; rgn: RgnHandle);

verb        One of the following actions to perform, as defined for 
            the GrafVerb data type:
                GrafVerb = (frame, paint, erase, invert, fill);
rgn         A handle to the region data.

PROCEDURE StdBits (VAR srcBits: BitMap; VAR srcRect, dstRect: Rect; 
                   mode: Integer; maskRgn: RgnHandle);

srcBits     A bitmap or pixel map containing the image to copy.
srcRect     The source rectangle.
dstRect     The destination rectangle.
mode        The source mode for the copy.
maskRgn     A handle to a region acting as a mask for the transfer.

PROCEDURE StdComment (kind,dataSize: Integer; dataHandle: Handle);

kind        The type of comment.
dataSize    The size of additional data.
dataHandle  A handle to additional data.

FUNCTION StdTxtMeas (byteCount: Integer; textAddr: Ptr; VAR numer, denom: Point; 
                     VAR info: FontInfo): Integer;

byteCount   The number of text bytes to measure.
textAddr    A pointer to the memory structure containing the text.
numer       Scaling numerator.
denom       Scaling denominator.
info        A FontInfo record.

PROCEDURE StdGetPic (dataPtr: Ptr; byteCount: Integer);

dataPtr     A pointer to the collected picture data.
byteCount   The size of the picture data.

PROCEDURE StdPutPic (dataPtr: Ptr; byteCount: Integer);

dataPtr     A pointer to the collected picture data.
byteCount   The size of the picture data.

To assist you in setting up a record, basic QuickDraw provides the SetStdProcs procedure. You can use this procedure to get a QDProcs record with fields that point to basic QuickDraw's standard low-level routines. You can then reset the routines with which you are concerned. By pointing to your modified QDProcs record in the grafProcs field of a GrafPort record, you can replace some or all of basic QuickDraw's standard low-level routines.


PROCEDURE SetStdProcs (VAR procs: QDProcs);

In the procs parameter, the SetStdProcs procedure returns a QDProcs record with fields that point to the standard low-level routines. You can change one or more fields of this record to point to your own routines and then set the basic graphics port to use this modified QDProcs record.

Replacing QuickDraw's standard low-level picture-writing routine

QuickDraw's standard StdPutPic procedure writes picture data to memory. For large "PICT" files, it is useful to spool the picture data to disk instead of writing it all directly into memory.

To save a picture in a "PICT" file, you should use File Manager routines, such as FSpCreate, FSpOpenDF, FSWrite, and FSClose. To save a picture in a "PICT" resource, you should use Resource Manager routines, such as FSpOpenResFile (to open your application's resource fork), ChangedResource (to change an existing "PICT" resource), AddResource (to add a new "PICT" resource), WriteResource (to write the data to the resource), and CloseResFile and ReleaseResource (to conclude saving the resource).

Remember that the first 512 bytes of a "PICT" file are reserved for your application's own purposes. Your application should store the data (that is, the Picture record) after this 512-byte header.

To place a picture in the scrap--for example, in response to the user choosing the Copy command to copy a picture to the Clipboard--use the Scrap Manager function PutScrap.

D o c u m e n t a t i o n