All Databases Inside Mac - Basic Toolbox

PicComment

Save any arbitrary data into a picture definition

#include <Quickdraw.h> Quickdraw

void PicComment(dataKind, dataSize, dataHandle );

short dataKind ; application defined

short dataSize ; amount of data, in bytes

Handle dataHandle ; handle to data to insert; NIL=none

PicComment lets you store arbitrary data into a picture definition. It is

called a "comment" since the standard Quickdraw procedure for handling

comments is to ignore them.

dataKind is a short which has meaning for an application that provides a

customized picture- handler. The following symbols are defined in

Quickdraw.h, even though Quickdraw itself ignores all comments:

picLParen 0 left " parenthesis" for grouping draw commands

picRParen 1 right " parenthesis" (end a group)

dataSize is the size of the comment data, in bytes.

dataHandle is a handle to the data to be treated as a comment. See NewHandle.

Returns: none

Notes: This is used by applications that provide a low-level picture-comment

handling function, to replace the standard Quickdraw handler (see

SetStdProcs and StdComment).

For instance, the LaserWriter driver interprets certain comments as

Postscript command text; thus allowing the picture to contain instructions

to the printer as well as the Quickdraw internal screen-drawing language.

Another use would be to store information about any text in the picture, so

that it may be easily edited later.

To install your own comment handler, you may replace the grafProcs field

of the current GrafPort with a pointer to a QDProcs structure of your own.

Set QDProcs.commentProc to point to your custom code. For more details,

please refer to SetStdProcs.

Pictures and the Print Manager

Some applications store data in a native format, and create pictures only at

print time to enable the use of picture comments. For each page of the

document, they open a new picture, record the Quickdraw calls that describe

the document, along with any picture comments they want to use, and

finally close the picture. When this is done, they call DrawPicture and

then start the whole process over again for the next page. This is not

neccessary. Since the Printing Manager already has a picture open, it is

legal to send a picture comment (by using PicComment) in between calls

to PrOpenPage and PrClosePage without having them recorded into a

picture. If you are only recording into pictures so you can use

PicComments, you can avoid the overhead at print time by simply sending

the comments directly.

If you need to create pictures at print time, try to do it before calling

PrOpen since there is no way to predict how much memory a particular

printer driver will require. If you really have to wait until after PrOpen

to create a picture, keep in mind that the Printing Manager replaces the

Quickdraw GrafProcs stored in the GrafPort returned by PrOpenDoc. One

of these procedures is the StdComment procedure which is called

whenever the application calls the Quickdraw PicComment routine. Since

the Printing Manager has these routines patched, creating a picture in the

Printing Manager's GrafPort can cause problems. Remember to set the port

to a standard Quickdraw GrafPort before calling OpenPicture. Any

GrafPort created by Quickdraw (instead of the Printing Manager) will

work fine.

To make sure no one else uses your comments, register them with Apple's

Developer Technical Support.

Referenced by (17):