Aug 99 Getting Started
Volume Number: 15
Issue Number: 8
Column Tag: Getting Started
By Dan Parks Sydow
How a Mac program sends document data to a
printer
In the previous few Getting Started articles we've focused on the use of files to provide
users of your Macintosh applications with the means to save program output. This
month we'll look at a second data-saving technique - printing. By adding printing
capabilities to your program, both text and graphics can be sent to any printer that's
attached to the user's computer.
Printing Basics
In this article you'll see how to write a program that displays the two standard
printing dialog boxes found in most Mac programs. The Printing Style dialog box,
shown in Figure 1, allows the user to select page preferences such as page orientation.
The Printing Job dialog box, pictured in Figure 2, lets the user specify the print
quality and the page range. For reasons explained ahead, the dialog boxes you see on
your Mac may look somewhat different than the ones shown here.
Figure 1.A typical Printing Style dialog box.
Figure 2.A typical Printing Job dialog box.
Your program can display both the Printing Style and Printing Job dialog boxes
through the use of Printing Manager routines. Like other Toolbox managers, the
Printing Manager is a collection of system software routines. Unlike the other
managers, the code that makes up each Printing Manager routine isn't found in ROM or
in the System File. Rather, the Toolbox printing routines are nothing more than empty
shells, or stub routines. When your application makes a call to a Toolbox printing
function, the program is directed to code that exists in a printer resource file. Printer
resource files enable the Printing Manager to work with all printers that come with a
Macintosh printer driver.
When an application calls a routine from a manager other than the Printing Manager,
the program jumps to Toolbox code that originates in ROM or in the System File. The
code that makes up that one routine - whatever routine it is - is then carried out. If
the call is to, say, Line(100, 0), QuickDraw draws a line 100 pixels long to the
current port. This is true regardless of the kind of monitor hooked up to the Mac. For
printers, this “one generic code works on all” principle doesn't apply. There are
countless third-party printers that can be hooked up to a Macintosh, and no uniform
standard of how Toolbox calls should be handled by a printer. So Apple leaves it up to
the manufacturer of each printer to supply the code that makes the printing functions
work. This code is found in the printer resource file that accompanies a printer that is
Mac-compatible.
Every printer that works with a Macintosh comes supplied with a printer resource
file. This file, which is placed in the Extensions folder in the System Folder, holds the
code that actually carries out Printing Manager routines. The file, which has a name
that often includes the name of the printer, must be present in order for the printer to
function. Since each type of printer has its own printer resource file, and since a
Macintosh can have more than one printer connected to it, a Mac can have more than
one printer resource file. The printer (and thus the printer resource file) that a
Macintosh uses is governed by the Chooser program found under the Apple menu.
The printer resource file holds resources of several types. Resources of type PDEF are
printer definition functions - they hold the compiled code that executes when a
Printing Manager function is called. When a Mac application makes a call to a Printing
Manager routine the call is routed to the printer resource file. There, the code that
makes up one of the many PDEF resources is loaded and executed. By having each
printer manufacturer support all the same Printing Manager routines, the burden of
worrying about which printer is connected to a user's system is lifted from the
Macintosh software developer. When you write an application that calls Printing
Manager routines, you won't have to consider the type of printer that any one user
might have. Instead, just make the function call. It will be up to the printer resource
file to handle that function call as is appropriate for that printer.
Printing Manager Basics
Like all of the Toolbox managers, the Printing Manager consists of a wealth of
functions. But to get started with printing, you'll need to use only a handful of them.
The Print Record
Before printing, your application must create a print record. This record holds
information specific to the printer being used, such as its resolution, and information
about the document that is to be printed, such as scaling, page orientation, and the
number of copies to print.
In C, the print record is represented by a struct of the type TPrint. Before any
printing takes place, your application must allocate memory for a TPrint structure
and obtain a handle - a THPrint handle - to that memory. By the way, the T in THPrint
stands for type, and the H stands for handle - you'll see this notation used throughout
the functions of the Printing Manager. You can make a call to the Memory Manager
routine NewHandle() or NewHandleClear() to reserve the needed memory and to
receive a handle to that memory. Include the size of a print record as the parameter
and cast the returned generic pointer to a THPrint handle.
THPrint printRecord;
printRecord = (THPrint)NewHandleClear( sizeof (TPrint) );
After creating a new print record, call the Printing Manager routine PrintDefault() to
fill the record with default values. These values will serve as initial values until the
user selects Page Setup and Print from the File menu of your application. The values
entered in the corresponding dialog boxes will overwrite some or all of the values
supplied by PrintDefault().
PrintDefault( printRecord );
Printing Manager Functions
Knowledge of less than a dozen Printing Manager functions is all that's needed to get
your Mac application printing. As you read this section, note that each of the three
Open functions is paired with a Close function: calls to PrOpen(), PrOpenDoc(), and
PrOpenPage() are balanced with calls to PrClose(), PrCloseDoc() and PrClosePage(),
respectively.
The code to execute Printing Manager functions resides in a resource file, so your