Legacy Document

Inside Macintosh: Imaging With QuickDraw /

Chapter 7 - Pictures / Pictures Reference

QuickDraw and Picture Utilities Routines / Creating and Disposing of Pictures

PicComment

To insert a picture comment into a picture that you are defining or into your printing code, use the PicComment procedure.

PROCEDURE PicComment (kind,dataSize:\xDDInteger; 
                     dataHandle:\xDDHandle);

kind

The type of comment. Because the vast majority of picture comments are interpreted by printer drivers, the constants that you can supply in this parameter--and values they represent--are listed in Appendix B, "Using Picture Comments for Printing," in this book.

dataSize

Size of any additional data passed in the dataHandle parameter. Data sizes for the various kinds of picture comments are listed in Appendix B, "Using Picture Comments for Printing," in this book. If no additional data is used, specify 0 in this parameter.

dataHandle

A handle to additional data, if used. If no additional data is used, specify NIL in this parameter.

DESCRIPTION

When used after your application begins creating a picture with the OpenCPicture (or OpenPicture) function, the PicComment procedure inserts the specified comment into the Picture record. When sent to a printer driver after your application uses the PrOpenPage procedure, PicComment passes the data or commands in the specified comment directly to the printer.

Picture comments contain data or commands for special processing by output devices, such as printers. For example, using the SetLineWidth comment, your application can draw hairlines--which are not available with standard QuickDraw calls--on any PostScript LaserWriter printer and on the QuickDraw LaserWriter SC printer.

Usually printer drivers process picture comments, but applications can also do so. For your application to process picture comments, it must replace the StdComment procedure pointed to by the commentProc field of the CQDProcs or QDProcs record, which in turn is pointed to by the grafProcs field of a CGrafPort or GrafPort record. The default StdComment procedure provided by QuickDraw does no comment processing whatsoever. You can use the SetStdCProcs procedure to assist you in changing the CQDProcs record, and you can use the SetStdProcs procedure to assist you in changing the QDProcs record.

If you create and process your own picture comments, you should define comments so that they contain information that identifies your application (to avoid using the same comments as those used by Apple or by other third-party products). You should define a comment as an ApplicationComment comment type with a kind value of 100. The first 4 bytes of the data for the comment should specify your application's signature. (See the chapter "Finder Interface" in Inside Macintosh: Macintosh Toolbox Essentials for information about application signatures.) You can use the next 2 bytes to identify the type of comment--that is, to specify a kind value to your own application.

Suppose your application signature were 'WAVE', and you wanted to use the value 128 to identify a kind value to your own application. You would supply values to the kind and data parameters to PicComment as follows:

kind = 100; data = 'WAVE' [4 bytes] + 128 [2 bytes] + additional data [n bytes]

Your application can then parse the first 6 bytes of the comment to determine whether and how to process the rest of the data in the comment. It is up to you to publish information about your comments if you wish them to be understood and used by other applications.

SPECIAL CONSIDERATIONS

These former picture comments are now obsolete: SetGrayLevel, ResourcePS, PostScriptFile, and TextIsPostScript.

The PicComment procedure may move or purge memory.

SEE ALSO

See Appendix B, "Using Picture Comments for Printing," in this book for information about using picture comments to print with features that are unavailable with QuickDraw. See the chapter "QuickDraw Drawing" in this book for information about the QDProcs record and the StdComment and SetStdProcs procedures. See the chapter "Color QuickDraw" in this book for information about the CQDProcs record and the SetStdCProcs procedure.