Apple II Technical Notes _____________________________________________________________________________ Developer Technical Support Apple IIgs #97: Picture Comments and Printing Written by: Matt Deatherage, Suki Lee & Ben Koning November 1990 This Technical Note discusses QuickDraw Auxiliary picture comments and how they can be used to help control the printing process. _____________________________________________________________________________ What's a Picture Comment? Picture comments are a way in which extra information beyond normal QuickDraw II calls can be embedded in a QuickDraw II picture. Comments can contain virtually anything; they consist of a length, a handle containing the comment and a "kind" that identifies the general type of information in the comment. Picture comment kinds less than or equal to 256 ($100) are reserved for Apple Computer, Inc. For comments to have any significance, there must be a way that a routine can take special action on them. One of the standard bottleneck procedures is called every time a picture comment is encountered, and it is passed the picture comment's kind, size, and handle on QuickDraw II's direct page. You can insert the address of a custom picture comment handler into the grafProcs field of a grafPort as described in Apple IIgs Technical Note #34, Low-Level QuickDraw II Routines. If no custom comment handler is present in the grafPort, the system calls its own StdComment routine, which ignores all comments. The current picture comment handling routine (either a custom one or the system's default one) is called whenever a picture comment is generated (with the QuickDraw Auxiliary call PicComment) or played back from a picture (from within DrawPicture). Since the picture comment handling procedure is called when the comment is created, a picture does not have to be open for this facility to work. Picture comments are ideal ways for applications to pass information to printer drivers as they are generated through toolbox calls and are easily accessible to any desktop program. If the printer driver is printing in immediate mode, it can intercept and act on the picture comment when it is generated. If the printer driver is printing in deferred mode and recording page images with QuickDraw II pictures, it can intercept and act on the picture comment when the picture is played back. Apple's ImageWriter, ImageWriter LQ and LaserWriter drivers (from System Software 5.0.3) all support various kinds of picture comments for controlling printed output. Applications are encouraged to use these picture comments for finer control over printing. Authors of printer drivers are encouraged to act on these picture comments where appropriate, so applications which use them achieve similar results across printing platforms. The LaserWriter Driver's Picture Comments Version 2.2 and later of the LaserWriter driver support the following five PostScriptr picture comments: Name Kind Size Handle ------------------------------------------------------ PostScriptBegin 190 0 NIL PostScriptEnd 191 0 NIL PostScriptHandle 192 - PostScript data PostScriptFile 193 - PostScript path name TextIsPostScript 194 0 NIL ------------------------------------------------------ Table 1-PostScript Picture Comments The print loop must be completed normally with or without any PostScript picture comments that are included. PostScript transmission must begin with the PostScriptBegin picture comment and end with the PostScriptEnd picture comment. Never nest PostScriptBegin and PostScriptEnd picture comments. The PostScriptHandle picture comment takes a handle containing PostScript commands (in the form of ASCII data) and sends it to the LaserWriter. The size field must contain the size of the handle. The PostScriptFile picture comment takes a handle containing the pathname of a disk file containing PostScript commands. The size field must contain the size of the pathname. The TextIsPostScript picture comment takes text drawn through the QuickDraw II StdText bottleneck and sends it to the LaserWriter as PostScript. This picture comment has the effect, from the application's point of view, of interpreting all strings passed to DrawString and similar calls as PostScript. This picture comment is specific to LaserWriters (idev = $0003). Other drivers do not implement this picture comment; therefore, text drawn through QuickDraw II is simply printed-it is neither interpreted as PostScript nor ignored. The driver does not check for PostScript errors, so the data sent to the LaserWriter must be correct. Always terminate PostScript text with a carriage return character. The transformation the driver uses flips text and prints it upside down on the page. Applications should set their own transformation matrices to serve their needs. Never use the LaserWriter's userdict-define a local dictionary for your application's use. Never use exitserver, initgraphics, grestoreall, erasepage, or showpage PostScript commands, as these commands can alter the driver's environment. See Chapter 3 of the LaserWriter Reference Manual for some examples of how to use picture comments. The ImageWriter Driver's Picture Comments ImageWriter driver version 4.0 and later uses three picture comments to control alternate color selection: Name Kind Size Handle ----------------------------------------- Reserved 250 - Reserved FillColorTable 251 42 See below ChangeSCBs 252 14 See below ----------------------------------------- The structure passed in the handle to FillColorTable looks like the following: version word must be zero signature word must be $A55A tableno word the color table to be modified (0-15) table 32 bytes The new color values for the color table reserved long must be zero The structure passed in the handle to ChangeSCBs looks like the following: version word must be zero signature word must be $A55A Y1 word line number of first SCB to change (from zero to rPage.Y2) Y2 word line number of last SCB to change (from zero to rPage.Y2) SCBvalue word the new scan line control byte reserved long must be zero PrOpenPage reinitializes the printing grafPort, so these picture comments should be used immediately after PrOpenPage to set custom colors. Having lines with both 320- and 640-mode is not recommended and will probably not be supported in the future. The ImageWriter driver uses picture comment 250 to internally mark the end of a page. Applications must not use this picture comment; use PrClosePage to end a page's definition. Further Reference _____________________________________________________________________________ o Apple IIgs Toolbox Reference, Volumes 1-3 o Apple IIgs Technical Note #34, Low-Level QuickDraw II Routines o Apple IIgs Technical Note #35, Printer Driver Specifications o Apple IIgs Technical Note #93, Compatible Printing o d e v e l o p, October 1990, Issue 4, "Driving to Print" PostScript is a registered trademark of Adobe Systems, Incorporated.