Introduction to Print Dialogs

By Dave Kelly, MacTutor Editorial Board

Exploring the Printing Manager

This month we'll explore the Macintosh Printing Manager. The Printing Manager is a set of RAM-based routines that allow you to use standard Quickdraw routines to print text or graphics on a printer. Take a look at Inside Macintosh for details on the Printing Manager (starting on page II-147). Then when you're thoroughly confused, come back here and I'll try to clarify some points by example.

The examples that I've prepared here are written in ZBasic and Lightspeed Pascal. The pascal example is included to help clarify how the Printing Manager is actually used. ZBasic routines call parts of the Printing Manager to enable you to have some control over your graphics or text output. However, ZBasic does not give you full support even though it does support the Printing Manager in more specific ways than does MS Basic as of this writing. ZBasic Toolbox calls DO NOT support the Printing Manager routines (i.e., they are not available). Also, we've found that the ZBasic example here does not work as cleanly as the Pascal example, so we invite our readers to compare the two and try some alternative Basic approaches to improve its performance.

In ZBasic there is a short list of commands available to us which pertain to the Printing Manager (Found on page D-58 thru D-63 in the ZBasic manual). They are:

DEF LPRINT: this command calls up the job dialog box so the user may select the page range, print quality, etc.

DEF PAGE: this command calls up the page setup dialog box. The user selects the paper size and orientation via this dialog.

PRCANCEL: this function returns a true when the user has pressed the cancel button in the job dialog box (called with DEF LPRINT.

PRHANDLE: this function returns a pointer to the print record created by the Printing Manager. By using PEEK WORD (two byte peek) the records may be examined and important information can be read (see ZBasic manual page D-62).

ROUTE X: this statement routes the output of all printing to a specified device X. ROUTE 0 sends output to the screen; ROUTE 128 sends output to the printer driver. (Note Route 0 does not seem to effect the Printing Manager).

CLEAR LPRINT: abruptly closes the printer driver. If you haven't printed anything, a single sheet of paper (blank) is fed out of the printer.

Fig. 1 Our sample shows print record info

The whole idea of the Printing Manager is to have one set of printing routines that are independent of the type of printer used, to which all printed output can be sent. The Printing Manager will select the selected printer driver (must be on the system disk and chosen by the Chooser desk accessory) and directs the printing operation. The ROUTE 128 statement directs all output to the specified device, after which whatever Quickdraw commands are sent will be executed. In ZBasic, the PLOT, CIRCLE, BOX, COLOR, PEN, PICTURE commands use Quickdraw, and therefore are supported for printing. At this point, Quickdraw commands sent to the printer are executed the same as if they were sent to the screen (which you've probably done before). One thing lacking in the ZBasic implementation is control over the PrOpenDoc, PrOpenPage, PrClosePage, PrCloseDoc routines as discussed in Inside Macintosh.. Instead the CLEAR LPRINT command is used to "CLEAR" out all the impending printing. I'm not sure exactly which routines the CLEAR LPRINT statement actually calls.

The PRHANDLE command returns a handle to the Printing Manager record. It should be noted that until the Printing Manager is opened, the record will contain whatever random garbage was located in the memory allocated for the print record. You must open the print manager by using DEF PAGE or DEF LPRINT. Then the PRHANDLE function may be used. The document and page is opened when the DEF LPRINT statement is executed. The ZBasic manual does not give more than an example to indicate the parameters which are returned by PEEKing into the print record memory locations. The actual parameters are explained in detail in Inside Macintosh.. I attempted to duplicate the data referred to in the ZBasic manual (pg. D-62) in the Pascal program. I found that it was not hard to follow the data, but there were a few mistakes in the ZBasic implementation. Both the printer port and the printer type parameters did not seem to function properly. These parameters are labeled in the demo program. It should also be noted that until a document is printed the printing record does not contain the correct information (appears to be random stuff). After printing, the data appears to be mostly correct except for those noted. The pascal program gave correct results every time (before and after printing). I have no explanation for why ZBasic does not behave like Pascal except that this may indicate another area that needs debugging for Zedcor so beware.

The ZBasic demo demonstrates a technique in using the printing manager from your Zbasic application. The program opens the printing manager using the DEF LPRINT statement and then prints the print record parameters (as outlined in the ZBasic manual), after which a Quickdraw command is given to draw a box around the page. The page size was determined from the print parameters. A helpful command to use was the COORDINATE command. Notice that the coordinates of the page were used as the coordinates for the quickdraw drawing rectangle (the Grafport) by using the following statement: COORDINATE PEEK WORD(P+28),PEEK WORD(P+26) which reads the page size from the printing record. If your printed output will use fonts, etc., you may want to know the page size so you know where to place the characters on the page.

Lightspeed Pascal shows you how the Printing Manager is really used. It should be helpful to walk through the setup of the Pascal procedures in order to understand the Printing Manager better. First off for those just beginning or not familiar with Lightspeed Pascal, you must create a new project and add the PrLink and MacPrint routines from the Resource folder on the Lightspeed Pascal system disk. These are the routines which will be loaded into RAM when the Printing Manager is opened. Of course, the other Macintosh Toolbox calls are automatically included in the new project. Next, the file containing the Pascal program below must be added to the project. For those using another Pascal or language, note that PrLink is Apple's Print Manager interface that is released only in object file format. However, Paul Snively published a PrLink source file in assembly in a past issue of MacTutor if you are interested. The MacPrint file is the interface from LS Pascal to the Print Manager and an equivalent set of glue code should be supplied by any compiler maker.

The Print Manager

Assuming we already have a ready made event loop set up that we can use, we will continue by setting up our pascal procedures. The first one we'll call from our print routine will be 'openprintmgr'. This routine uses PrOpen to open the printing manager and get a handle pointing to the print record. As called for in Inside Macintosh , the print record is created with the statement: prRecHdl := THPrint(NewHandle( SIZEOF(TPrint)));. This statement gets a NewHandle to the print record 'TPrint'. The record is outlined on page II-149 of IM. Keep in mind that the toolbox procedures and functions are provided in the MacPasLib and MacTraps libraries files, therefore it is not necessary to type in the predefined records and other such information (I didn't realize this the first time I wrote a program with Lightspeed Pascal). The predefined procedures and functions are listed in the appendix of the Lightspeed Pascal manual. These functions and procedures match those listed in IM.

Ordinarily when you are preparing to print something when you run an application, you will want to be sure that the PageSetup is correct (you especially want to do this after changing drivers with the Chooser DA). In the procedure DoCommand for the case of the menu selection of PageSetup, the statement valid := PrStlDialog(prRecHdl); is used to select the Page Setup dialog (also called the style dialog). This pascal function returns a boolean reply for the buttons the user may have selected (true for 'OK' and false for 'Cancel'). The Jobsetup menu case uses the statement valid := PrJobDialog(prRecHdl); to call the Job dialog. The boolean is returned once again indicating what button the user selected.

So we see that setup of the printing is done as easily in Pascal as in Basic! However, printing is quite different in Pascal than in Basic. In the example, the print item of the menu first selects the PrJobDialog function to get the Job information from the user. Next the output must be specified. As we discussed earlier, all ZBasic printing is routed to the device selected by the ROUTE statement. In Pascal the printing grafport is opened with the PrOpenDoc function. In Quickdraw all output is sent to the current Grafport. In the program the statement myPrPort := PrOpenDoc( prRecHdl, NIL, NIL); opens the printing grafport to be used. Next, if there is no error, the program calls the PrOpenPage procedure PrOpenPage(myPrPort, NIL); to open a printing page. The next set of statements or procedures call Quickdraw statements and are drawn to the page that has been opened. When each page is finished (the example has only one page to print) the PrClosePage(myPrPort); statement should be called and PrOpenPage to open each new page. Next, you need to check to see if spooling was done. If spooling was done, then your pages were saved to the disk or memory to be spooled to the printer later. To spool to the printer, the PrPicFile procedure should be called. If draft printing was selected, then the pages are printed immediately (no spooling). You should test to see whether spooling was done, and if so, print the spooled document. You may want to free some memory so that there will be more memory for printing the spooled document. Details and another Pascal example are given on pages II-154 and II-155 of the Printing Manager section of IM.

Some hints that you should keep in mind when using Quickdraw for printing:

• Reset font and other grafport information with each new page. The grafport is completely reinitialized with each new page!.

• Don't use calls that don't do anything on the printer such as erasing, clipping etc. (See comments below on LaserWriter restrictions.)

• Don't use clipping to select the text to be printed. The page size may not match your screen size exactly.

• Don't use non-proportional spaced fonts to align columns of text.

For printing to the LaserWriter (according to IM ):

• Regions are not supported.

• Clipping should be limited to rectangles

• "Invert" routines are not supported.

• Copy is the only transfer mode supported for all objects except text and bit images. BIC is supported for Text. XOR is the only mode not supported for bit images.

• Don't change the grafPort's local coordinate system (with SetOrigin) within the printing loop (between PrOpenPage and PrClosePage).

Print Record Information

Access to the printing record information may be retrieved by using the commands in the getprintinfo procedure of the example program. The details here are very clear if you refer to the example program and IM. IM details information about saving your own print records for use by the printing manager instead of the default parameters.

Termination of the printing manager is done by calling the PrClose procedure. There is no need to close the driver after each print procedure unless you have a need to free up memory. Other low-level driver access information may be found in Inside Macintosh also.

I hope that the examples will help those of you that are trying to print graphics with your programs.

Basic Update

Here it is a few months after the release of several new Basic products and there have not been too many significant improvements to any of the Basics except for ZBasic. The latest Beta copy of now released version 3.02 appears to be a big improvement over the earlier versions. A few changes: menus have been redesigned and the program looks and feels much more "Mac-like". A bug (something to do with the window I/O) was located which had been causing a large number of the bombs. It looks like version 3.02 will be one we can trust!! The latest word is that Zedcor is now writing a new Editor (similar to the MSBasic editor) to replace the very poor editor in the previous copies. I hope to be able to comment about it some more next month if it has been completed by then. Appletalk commands are not yet implemented and will bomb if you try to use them. Bugs were fixed involving Edit fields, Box fill, POWERS statements. The startup screen has been replaced by a simple startup dialog box that appears with Andy Gariepy's picture. A SHUTDOWN command and auto repeat scroll bars have been added. DIALOG(16) may be used to read keypresses during event loops. (This replaces INKEY$ during event trapping). Looks like it's coming right along! A 33-page addendum to the ZBasic manual outlines the additions, changes and enhancements in version 3.02. For those of you that have earlier versions of ZBasic, you will be much more satisfied with the improvements. You may want to contact Zedcor about upgrade information.

Rumors are still in the air about the MS Basic compiler and improvements to MS Basic. Word is that Absoft has completed the compiler and Microsoft has purchased the rights to the CLR toolbox libraries and will be bundling the CLR libraries with the Absoft MS Basic compiler. More to come when I have more to tell.

REM ZBasic PrintDemo
REM By Dave Kelly
REM ©1986 by MacTutor
WINDOW OFF
WINDOW #1,"ZBasic printing",(50,50)-(450,300),3
W1=WINDOW(2)-1:W2=WINDOW(3)-1
DEFDBL INT P:DEF TAB 32
 MENU 1,0,1,"File"
 MENU 1,1,0,"Print to screen"
 MENU 1,2,1,"Print to printer"
 MENU 1,3,1,"Page Setup"
 MENU 1,4,1,"Job Setup"
 MENU 1,5,0,"-"
 MENU 1,6,1,"Clear Screen"
 MENU 1,7,1,"Quit"
ON DIALOG GOSUB "Dialogselection"
DIALOG ON
ON MENU GOSUB "Menuselection"
MENU ON

"Loop":
GOTO "Loop"
"Dialogselection":
 THEEVENT=DIALOG(0)
 IF THEEVENT<>5 THEN RETURN
 RETURN
"Menuselection":
 MENUNUMBER=MENU(0)
 MENUITEM=MENU(1)
 MENU OFF:MENU:DIALOG OFF
 ON MENUITEM GOSUB "Printscr", "Printptr", "Page", "Job",      "dummy", 
"Clrscr", "Quit"
 MENU ON:DIALOG OFF
 RETURN
"dummy":
 RETURN
"Clrscr":
 WINDOW PICTURE #1,0
 CLS:RETURN
"Printscr":
 COORDINATE WINDOW
 ROUTE 0
 PICTURE ON  
 GOSUB "Your print routine"
 PRINT@(X,19) "Parameters printed to screen may be in error."
 BOX 0,0 TO W1,W2
 PICTURE OFF, Pic&
 PICTURE,Pic&
 WINDOW PICTURE #1,Pic&
 RETURN
"Printptr":
 DEF LPRINT:CLS
 IF PRCANCEL<>0 THEN RETURN
 P=PEEK LONG(PRHANDLE)
 COORDINATE PEEK WORD(P+28),PEEK WORD(P+26)
 ROUTE 128
 GOSUB "Your print routine"
 BOX 0,0 TO PEEK WORD (P+28)-1,PEEK WORD(P+26)-1
 CLEAR LPRINT
 ROUTE 0
 MENU 1,1,1
 RETURN
"Job":
 DEF LPRINT
 MENU 1,1,1
 RETURN
"Page":
 DEF PAGE
 MENU 1,1,1
 RETURN
"Your print routine":
 X=5
 PRINT@(X,5) "Print Manager version",PEEK WORD(P)
 PRINT@(X,6) "Driver Info (What's that?)",PEEK WORD(P+2)
 PRINT@(X,7) "Vertical resolution",PEEK WORD(P+4)
 PRINT@(X,8) "Horizontal resolution",PEEK WORD(P+6)
 PRINT@(X,9) "Page Rectangle",PEEK WORD(P+8);PEEK WORD(P+10); PEEK WORD(P+12); 
PEEK WORD(P+14)
 PRINT@(X,10) "Paper Rectangle",PEEK WORD(P+16);PEEK WORD(P+18);PEEK 
WORD(P+20);PEEK WORD(P+22)
 PRINT@(X,11) "Paper height,width",PEEK WORD(P+26); ","; PEEK WORD (P+28)
 PRINT@(X,12) "Printer port  (ERROR!)",PEEK WORD(P+30)
 PRINT@(X,13) "Printer type  (ERROR!)",PEEK WORD (P+32)
 PRINT@(X,14) "First page",PEEK WORD(P+62)
 PRINT@(X,15) "Last page",PEEK WORD(P+64)
 PRINT@(X,16) "# of copies..",PEEK WORD(P+66)
 RETURN
"Quit":
 KILL PICTURE Pic&
 END


{ Printdemo program by Dave Kelly }
{ for MacTutor Dec 1986}
{ Lightspeed Pascal 1.0}

PROGRAM Printdemo;
USES
 MacPrint;
CONST
 appleID = 1;
 fileID = 2;
 appleMenu = 1;
 fileMenu = 2;
 menuCount = 2;
 printscr = 1;
 printptr = 2;
 pagesetup = 3;
 Jobsetup = 4;
 clrscr = 6;
 quit = 7;
 plainDBox = 2;

VAR
 myMenus :  ARRAY[1..menuCount] OF MenuHandle;
 theChar :  CHAR;
 extended : BOOLEAN;
 doneFlag : BOOLEAN;
 myEvent :  EventRecord;
 wRecord :  WindowRecord;
 Windowport :  Windowptr;
 whichWindow :   Windowptr;
 UpdateWindow :  Windowptr;
 windowsize :  longint;
 height, width : integer;
 sizeRect, size, dragRect : Rect;
 valid, screenprinted : boolean;
 prRecHdl : THPrint;
 printmgr : boolean;
 myPrPort : TPPrPort;
 myStRec :  TPrStatus;
 P : ARRAY[1..15] OF longint;
 pheight : longint;
 pwidth : longint;
 Ptype : integer;

PROCEDURE SetUpMenus;
VAR
 i : INTEGER;
BEGIN
 myMenus[appleMenu] := NewMenu(AppleID, chr(appleMark));
 AddResMenu(myMenus[appleMenu], 'DRVR');
 myMenus[fileMenu] := NewMenu(fileID, 'File ');
 appendmenu(myMenus[fileMenu], '(Print to screen;Print to printer;Page 
Setup;Job Setup;(-;Clear Screen;Quit/Q');
 FOR i := 1 TO menuCount DO
 InsertMenu(myMenus[i], 0);
 DrawMenuBar;
END;

PROCEDURE openprintmgr;
BEGIN
 PrOpen;
 prRecHdl := THPrint(NewHandle(SIZEOF(TPrint)));
 printmgr := true;
 EnableItem(myMenus[fileMenu], printscr);
END;

PROCEDURE getprintinfo;
BEGIN
 P[1] := prRecHdl^^.iPrVersion; { Print Manager version}
 P[2] := prRecHdl^^.prInfo.iVRes; { Vertical resolution}
 P[3] := prRecHdl^^.prInfo.iHRes; { Horiz resolution}
 P[4] := prRecHdl^^.prInfo.rPage.top; { Page Rec}
 P[5] := prRecHdl^^.prInfo.rPage.left;
 P[6] := prRecHdl^^.prInfo.rPage.bottom;
 P[7] := prRecHdl^^.prInfo.rPage.right;
 P[8] := prRecHdl^^.rPaper.top; { Paper Rectangle}
 P[9] := prRecHdl^^.rPaper.left;
 P[10] := prRecHdl^^.rPaper.bottom;
 P[11] := prRecHdl^^.rPaper.right;
 pheight := ((P[10] - P[8]) * 120 DIV P[2]); { Paper height}
 pwidth := ((P[11] - P[9]) * 120 DIV P[3]);{ Paper width}
 Ptype := (prRecHdl^^.prStl.wDev); {printer type}
 Ptype := (BitAnd(Ptype, 65280) DIV 256);
 P[12] := prRecHdl^^.prJob.iFstPage; { First page}
 P[13] := prRecHdl^^.prJob.iLstPage; { Last page}
 P[14] := prRecHdl^^.prJob.iCopies; { # of copies}
END;

PROCEDURE printinfo;
BEGIN
 Getprintinfo;
 textfont(monaco);
 textsize(9);
 moveto(20, 20);
 WriteDraw('Print Manager Version');
 moveto(150, 20);
 WriteDraw(P[1]);
 moveto(20, 30);
 WriteDraw('Vertical resolution');
 moveto(150, 30);
 WriteDraw(P[2]);
 moveto(20, 40);
 WriteDraw('Horizontal resolution');
 moveto(150, 40);
 WriteDraw(P[3]);
 moveto(20, 50);
 WriteDraw('Page Rectangle');
 moveto(150, 50);
 WriteDraw(P[4], P[5], P[6], P[7]);
 moveto(20, 60);
 WriteDraw('Papar Rectangle');
 moveto(150, 60);
 WriteDraw(P[8], P[9], P[10], P[11]);
 moveto(20, 70);
 WriteDraw('Paper height');
 moveto(150, 70);
 WriteDraw(pheight);
 moveto(20, 80);
 WriteDraw('Paper width');
 moveto(150, 80);
 WriteDraw(pwidth);
 moveto(20, 90);
 WriteDraw('Printer type');
 moveto(150, 90);
 WriteDraw(Ptype);
 moveto(20, 100);
 WriteDraw('First Page');
 moveto(150, 100);
 WriteDraw(P[12]);
 moveto(20, 110);
 WriteDraw('Last Page');
 moveto(150, 110);
 WriteDraw(P[13]);
 moveto(20, 120);
 WriteDraw('# of copies');
 moveto(150, 120);
 WriteDraw(P[14]);
END;

PROCEDURE DrawingProc;
BEGIN
 framerect(myPrPort^.gPort.portRect);
 printinfo;
END;

PROCEDURE DoCommand (mResult : LONGINT);
VAR
 theItem : INTEGER;
 theMenu :  INTEGER;
 name : Str255;
 temp, i :  INTEGER;
BEGIN
 theItem := LoWord(mResult);
 theMenu := HiWord(mResult);
 CASE theMenu OF
 appleID : 
 BEGIN
 GetItem(myMenus[appleMenu], theItem, name);
 temp := OpenDeskAcc(name);
 SetPort(Windowport);
 END;
 fileID : 
 CASE theItem OF
 printscr : 
 BEGIN
 IF printmgr THEN
 BEGIN
 SetPort(Windowport);
 eraserect(Windowport^.portrect);
 FrameRect(Windowport^.portrect);
 printinfo;
 validRect(Windowport^.PortRect);
 screenprinted := true;
 END;
 END; { printscr}

 printptr : 
 BEGIN
 IF NOT printmgr THEN
 openprintmgr;
 valid := PrJobDialog(prRecHdl);
 IF valid THEN
 BEGIN
 myPrPort := PrOpenDoc(prRecHdl, NIL, NIL);
 IF PrError = noErr THEN
 BEGIN
 PrOpenPage(myPrPort, NIL);
 IF PrError = noErr THEN
 DrawingProc;
 PrClosePage(myPrPort);
 END;
 PrCloseDoc(myPrPort);
 IF (prRecHdl^^.prJob.bjDocLoop = bSpoolLoop) AND (PrError = noErr) THEN
 PrPicFile(prRecHdl, NIL, NIL, NIL, myStRec);
 END;
 END;
 Jobsetup : 
 BEGIN
 IF NOT printmgr THEN
 openprintmgr;
 valid := PrJobDialog(prRecHdl);
 END;
 pagesetup : 
 BEGIN
 IF NOT printmgr THEN
 openprintmgr;
 valid := PrStlDialog(prRecHdl);
 END;
 clrscr : 
 BEGIN
 eraserect(Windowport^.portrect);
 screenprinted := false;
 END;
 quit : 
 BEGIN
 IF printmgr THEN
 BEGIN
 PrClose;
 printmgr := false;
 END;
 doneFlag := TRUE;
 END;
 OTHERWISE
 ;
 END; {itemCase}
 OTHERWISE
 ;
 END; { menuCase }
 SetPort(Windowport);
 HiliteMenu(0);
END;

{Here is the Main Program}

BEGIN
InitGraf(@thePort);
InitFonts;
FlushEvents(everyEvent, 0);
InitWindows;
InitMenus;
InitDialogs(NIL);
InitCursor;

SetRect(sizeRect, 50, 50, 450, 300);
dragRect := sizeRect;
doneFlag := FALSE;
printmgr := false;
screenprinted := false;
Windowport := Newwindow(@wRecord, sizeRect, '', true,    plainDBox, POINTER(-1), 
false, 0);
SetPort(Windowport);
SetUpMenus;

{ This is the main event loop}

REPEAT
SystemTask;
IF GetNextEvent(everyEvent, myEvent) THEN
CASE myEvent.what OF
mouseDown : 
 CASE FindWindow(myEvent.where, whichWindow) OF
 inDesk : 
 ; {Not used}
 inMenuBar : 
 DoCommand(MenuSelect(myEvent.where));
 inSysWindow : 
 SystemClick(myEvent, whichWindow);
 inContent : 
 BEGIN
 IF whichWindow <> FrontWindow THEN
 SelectWindow(whichWindow)
 ELSE
 BEGIN
 GlobalToLocal(myEvent.where);
 extended := BitAnd(myEvent.modifiers, shiftKey) <> 0;
 END;
 END;
 inDrag : 
 ; {Not used}
 inGrow : 
 ; {Not used}
 inGoAway : 
 ; {Not used}
 END;
mouseUp : 
 ; {Not used}
keydown, autokey : 
 BEGIN
 theChar := CHR(BitAnd(myEvent.message, charCodeMask));
 IF BitAnd(myEvent.modifiers, cmdKey) <> 0 THEN
 DoCommand(MenuKey(theChar));
 END;
keyUp : 
 ; {Not used}
updateEvt : 
 IF screenprinted THEN
 BEGIN
 UpdateWindow := WindowPtr(myEvent.message);
 BeginUpdate(UpdateWindow);
 SetPort(UpdateWindow);
 eraserect(UpdateWindow^.portrect);
 FrameRect(UpdateWindow^.portrect);
 printinfo;
 EndUpdate(UpdateWindow);
 END;
diskEvt : 
 ; {Not used}
activateEvt :
 ; {Not used}
networkEvt : 
 ; {Not used}
driverEvt : 
 ; {Not used}
OTHERWISE
 ;
END;
UNTIL doneFlag;
END.