Overview of Printing Terminology

There are several terms that you’ll see repeatedly in the Carbon Printing Manager documentation: page format, print settings, formatting printer, default printer, and print job.

Page format describes how pages of a document should be printed, and includes such information as paper size and orientation. Although an application can programmatically set up the page format, most applications allow users to set options that control the page format in the Page Setup dialog.

The default page format settings are determined by the formatting printer. The formatting printer is the one that is displayed in the “Format for” pop-up menu in the Page Setup dialog. The default formatting printer is the generic Any Printer, as shown in the Page Setup dialog in Figure 2-1.

Print settings control the execution of a print job on a specific printer, and include such information as the number of copies, which pages to print, and the number of pages per sheet. As with the page format, an application can programmatically set print settings but usually allows users to open the Print dialog and make print settings instead. Figure 2-2 shows the Copies & Pages pane of the Print dialog.

The default print settings, as well as any constraints on those values, are determined by the printer module for the default printer. Before the Print dialog opens, the default printer in Mac OS X is the printer that is currently selected in Print Center. In Mac OS 9, it is the printer that is currently selected in the Chooser. Figure 2-3 shows Print Center with the default printer set to a printer named Kangaroo.

A print job consists of two items:

• the drawing commands that describe a document

• the settings that control printing the document and keep track of it once the job has been added to a printer’s queue

High-Level Printing Tasks

The high-level tasks needed to print in a Carbon application are

• setting up the page format

• setting up the print settings

• printing the job

As you’ll see later in this chapter, Carbon Printing Manager data structures and functions are grouped to support these tasks.

The way you implement the high-level printing tasks depends on whether the printing tasks are driven by the Page Setup and Print dialogs. In most document-based applications, such as a text editing or drawing application, high-level printing tasks are driven by user interaction with these dialogs. The user can choose Page Setup and Print from the File menu and change settings. A document prints when the user clicks Print in the Print dialog.

An application can also support printing without requiring a user to open either the Page Setup or Print dialogs. This is common for applications that provide an option for the user to print one copy using default settings. In this case, an application can programmatically set up the page format and print settings, eliminating the need for the user to make settings in either of the printing dialogs. You’ll see how to do this in Printing One Copy.

Another situation in which your application could bypass the printing dialogs is to provide support for the user to save a document as a portable document format (PDF) file. The default spool file format in Mac OS X is PDF. As a result, it is straightforward for those applications that support printing in Mac OS X (version 10.1 and later) to also support saving a document as a PDF file. You’ll see how to implement this in Saving a Document as a PDF File.

Let’s take a look at what an application needs to do to implement high-level printing tasks in each situation: printing driven by printing dialogs and printing that does not require a user to interact with the printing dialogs.

Printing Objects

The main Carbon Printing Manager objects used to implement the high-level printing tasks are the page format (PMPageFormat), print settings (PMPrintSettings), and printing session (PMPrintSession) objects. The Carbon Printing Manager hides the underlying implementation of these objects, so you can’t access the contents directly. Instead, you must use Carbon Printing Manager functions to access the internal data stored in these objects. See Printing Functions for information on the functions most commonly used with these objects. See the Carbon Printing Manager Reference for information on all the printing objects available.

Printing Functions

This section provides an overview of the functions you use to work with the three main printing objects—page format, print settings, and printing session. The Inside Mac OS X: Carbon Printing Manager Reference provides a complete reference for the functions available to support printing in your application.

The Print Loop

The print loop is your application’s code that calls all the necessary functions to print a selected page range of a document. It is called a print loop because it loops to print each page in the range. The print loop and the Print dialog must use the same printing session object.

The pseudocode in Listing 2-1 shows the calls a typical print loop might make, with the calls divided among Carbon Printing Manager functions, other Carbon functions, and application-defined functions. Not all error handling is shown, but the print loop should check for errors after each call that may return one.

Listing 1-1  Pseudocode for a print loop function

AppPagesInDoc (application-defined function to verify a valid page range)

PMGetFirstPage (gets the number of the first page to be printed)

PMGetLastPage (gets the number of the last page to be printed)

(now know how many pages to print in the print loop)

PMSetLastPage (sets the last page in the print job; used for status dialog)

PMSessionBeginDocument (begin a new print job)

    (for each page to be printed)

    PMSessionError (check for an error before starting a new page;

                    if error, break out of loop)

    PMSessionBeginPage (prepare to print the current page)

        PMSessionGetGraphicsContext (get the printing port)

        SetPort (set current drawing port to the printing port)

        AppDrawPage (application-defined function to draw one page)

        SetPort (restore saved port)

    PMSessionEndPage (finish printing the current page)

PMSessionEndDocument (end the print job)

AppPostPrintingErrors (application-defined function to display

                                error message, if any, to the user)

PMRelease (release the print settings and printing session objects)

You’ll notice that very few of the functions called in the print loop are application-defined functions—most are Carbon Printing Manager functions or other Carbon functions. Your application supplies functions only to determine the maximum number of pages in its document, to draw the pages to be printed, and to display error messages (if any). See Writing the Print Loop for more information.

Sequence, Scope, and Usage

The Carbon Printing Manager enforces a sequence of steps in the print loop, and defines a valid scope for each printing function. This means that your application must call certain functions before calling others. Functions used out of sequence return the result code kPMOutOfScope.

Here are the basic rules for sequence, scope, and usage:

• If you create an object, you must release it. You can pass any Carbon Printing Manager object to the function PMRelease to release it.

• A printing session object is created after a successful call to PMCreateSession and is released by calling PMRelease. Some Carbon Printing Manager functions must only be called between these two calls.

• Any function whose name begins with PMSession can only be called between the creation and release of a printing session object.

• Any function whose name includes Begin (such as PMSessionBeginPage) must be called before the corresponding End function (such as PMSessionEndPage).

• An End function must be called if the corresponding Begin function returns noErr, even if errors occur within the scope of the Begin and End functions.

• You can call the functions PMSessionBeginPage and PMSessionEndPage only within the scope of calls to PMSessionBeginDocument and PMSessionEndDocument.

• The function PMSessionGetGraphicsContext can be called only with the scope of calls to PMSessionBeginPage and PMSessionEndPage.

• If you want to use sheets, you must call the function PMSessionUseSheets before you call the functions PMSessionPageSetupDialog or PMSessionPrintDialog. (Sheets are available only in Mac OS X.)

Listing 2-2 shows a typical calling sequence for code that sets print settings and sends a print job to a printer. The call to PMRelease applies to the printing session object created by the function PMCreateSession.

In general, functions may be called in any order with respect to other functions at the same or lower scope level (represented in Listing 2-2 by indentation). For example, you can call PMSessionGetGraphicsContext only within the scope of a call to PMSessionBeginPage, which in turn must be within the scope of a call to PMSessionBeginDocument. But within the scope of a call to PMCreateSession, you can call PMSessionDefaultPageFormat and PMSessionDefaultPrintSettings in any order.

Listing 1-2  Typical calling sequence for code that adjusts print settings and then prints a document

PMCreateSession

    PMSessionDefaultPrintSettings

    PMSessionValidatePrintSettings

    PMSessionDefaultPageFormat

    PMSessionValidatePageFormat

    PMSessionUseSheets

    PMSessionPrintDialog

    PMSessionBeginDocument

        PMSessionBeginPage

            PMSessionGetGraphicsContext

        PMSessionEndPage

    PMSessionEndDocument

PMRelease

The following list shows some of the printing functions that do not need to be called between the creation and release of a printing session object. Many of these functions are used in the sample code in Printing Tasks. Note however, that the functions with an asterisk (*) must be called before a call to the function PMSessionBeginDocument or before you display the Print dialog.

PMCreatePageFormat*

PMCreatePrintSettings*

PMFlattenPageFormat*

PMUnflattenPageFormat*

PMGetPageFormatExtendedData*

PMSetPageFormatExtendedData*

PMGetUnadjustedPaperRect

PMGetUnadjustedPageRect

PMGetOrientation

PMSetOrientation*

PMFlattenPrintSettings

PMUnflattenPrintSettings*

PMGetPageRange

PMSetPageRange*

PMGetResolution

PMSetResolution*

The functions PMGetAdjustedPaperRect and PMGetAdjustedPageRect also do not need to be called between the creation and release of a printing session object, but it is currently required that you call PMSessionValidatePageFormat before you call either function. Validating a page format object causes the printing system to calculate the adjusted page and paper rectangles.

You can find out more about each function, including when to use it, in the Inside Mac OS X: Carbon Printing Manager Reference.

Page and Paper Rectangles

The page and paper rectangles define the paper sheet size and imageable area for your application's printed page. If you are new to Mac OS X, you should read this section. (Mac OS X uses the same definitions for these rectangles as those used for the old Printing Manager in Mac OS 9.) This section provides the information you need to write a function that draws a single page of a document for your application. It describes the page and paper rectangles and the relationship between them, the adjusted page and paper rectangles, and the margins for the imageable area of the sheet.

Page Rectangle

The page rectangle is the area of the page to which an application can draw. The coordinates for the upper-left corner of the page rectangle are (0,0), as shown in Figure 2-4. The coordinates of the lower-right corner specify the maximum page height and width attainable on the given printer for this page format. Anything drawn outside of the page rectangle is clipped.

The width and height of the drawing area are determined by a number of factors—the user’s settings for orientation and scaling as well as the resolution your application sets by calling the function PMSetResolution. In all cases, the size of the drawing area is limited by the lower-right corner of the page rectangle. Figure 2-4 shows the page rectangle for generic letter-size paper, at 72 dpi, 100% scaling, and portrait orientation.

Your application should always use the page rectangle sizes provided by the printer and should not attempt to change them or add new ones. If your application offers page sizes other than those provided by the printer, you risk compatibility problems.

Adjusted Page and Paper Rectangles

The adjusted page and paper rectangles are more important to your application than the unadjusted ones, as they define the drawing area after orientation, scaling, and resolution are applied. The printing system interprets your application’s drawing relative to these coordinates, but the unadjusted rectangles also provide a reference for the application in case information (such as a print preview) needs to be displayed to the user.

By default, all rectangles specify the page and paper sizes in dots-per-inch (dpi) with a default resolution of 72 dpi. If there are no orientation or scaling changes, and the application resolution is 72 dpi, the adjusted and unadjusted page and paper rectangles are equal. When scaling, orientation, and resolution are taken into account, the adjusted rectangles can define a drawing area quite different from the original unadjusted rectangles.

Scaling increases the amount of content your application can draw to a page when the user specifies a percentage less than 100% and decreases the amount of content your application can draw to a page when the percentage is greater than 100%. For example, if the user specifies 50% scaling, the page and paper rectangles increase in size by a factor of 2 in each dimension relative to the content, as shown in Figure 2-5. While it may not be intuitive for the page and paper rectangles to increase in size when scaling is decreased, increasing the size of the rectangles effectively shrinks the content. The converse is true. If the user specifies 200% scaling, the page and paper rectangles decrease in size by half in each dimension relative to the content, effectively increasing the content size by 200% in each direction.

If the user chooses landscape mode, the adjusted page and paper rectangles become, for most paper sizes, wider than they are tall. Because some papers are naturally wider than they are tall (envelopes, for example), it's best not to calculate page orientation based on the difference between the height and width of the page. Instead, use the function PMGetOrientation. In most cases your application shouldn’t need the orientation, just the dimensions of the adjusted page and paper rectangles.

When your application sets the drawing resolution to a value other than 72 dpi, the adjusted page and paper rectangles change accordingly. For example, setting the resolution to 600 dpi enlarges both rectangles by a factor of 8.3 in both dimensions—a previous page rectangle width of 576 units changes to 4800 units.

If You’ve Used the Old Printing Manager

If you’ve previously used the old Printing Manager, you’ll find that the Mac OS X printing architecture and most of the underlying concepts are slightly different from what you’ve used in Mac OS 9 and earlier. This section outlines the main differences. If you have developed applications for Mac OS 9, you should read this section to find out how the old concepts relate to the new ones. If you want to convert an existing Mac OS 9 application to use the Carbon Printing Manager, make sure you also read Adopting the Carbon Printing Manager. If you are not modifying an existing application, you can skip this section.

A key aspect of the Mac OS X printing system is its robust support for Carbon applications. Because the Carbon Printing Manager is supported in Mac OS 8 and 9 as well as Mac OS X, a Carbon application is able to print as expected in both environments. For example, when running in Mac OS 8 and 9, the application utilizes the traditional user interface and drivers. In Mac OS X, the application automatically takes advantage of the new printing system’s more consistent set of printing dialogs and its flexible printing architecture.

Prior to Mac OS X, printing was supported by the old Printing Manager interface. This interface is not used by Carbon applications. The Carbon Printing Manager interface is defined in the header files PMApplication.h, PMCore.h, and PMDefinitions.h.

If you need to convert existing printing code to use the Carbon Printing Manager, you should be aware of the following changes. You can find more details about converting your code in Adopting the Carbon Printing Manager.

• The old Printing Manager print record (TPrint) is replaced by two opaque objects: a print settings object (PMPrintSettings) and a page format object (PMPageFormat). You create these objects using the PMCreatePrintSettings and PMCreatePageFormat functions, each of which returns a reference that you can pass to other Carbon Printing Manager functions to obtain information stored in the objects.

• Your application must not make assumptions about the size or content of the print settings and page format objects. Your application can attach extended data to both objects using Carbon Printing Manager functions, but applications must not assume a specific size when storing or retrieving flattened versions of these objects with documents.

• The Carbon Printing Manager provides functions for flattening and restoring the print settings and page format objects. In most cases, your application should store only the flattened page format object. If older versions of your application store a print record (created by the old Printing Manager) with a saved document, you may continue to do so for backward compatibility. However, some information may be lost when converting a page format object into a old print record (or vice versa), due to limitations of the print record structure in the old Printing Manager.

• In Mac OS X, Carbon applications can create multiple printing session objects and run more than one print loop at a time. Each print loop is independent of other print loops. In Mac OS 8 and 9, applications are limited to a single printing session object, and therefore one print loop at a time.

• The Carbon Printing Manager enforces an order in which some functions should be called. Any function used out of order returns the result code kPMOutOfScope.

• The style dialog box is now called the Page Setup dialog, and the job dialog box is now called the Print dialog.

• If your application requires customizing the Page Setup or Print dialogs, you should consider creating a printing dialog extension (PDE). If you want your application’s custom dialog to be displayed as a sheet in Mac OS X, you must create a printing dialog extension. For more information, see Extending Printing Dialogs.

• Low-level driver functions such as PrLoadDriver are not supported.