MACINTOSH C CARBON: A Hobbyist's Guide To Programming the Macintosh in C
Version 1.0
� 2001 K. J. Bricknell

CHAPTER 15

CARBON PRINTING

The Carbon Printing Manager

The inclusion of the word "Carbon" in the title of this chapter is quite deliberate, reflecting the fact that, in Carbon, the original Printing Manager has been replaced by the new Carbon Printing Manager. The Carbon Printing Manager provides a bridge between the fundamentally different Mac OS X and Mac OS 8/9 printing architectures.

When running on Mac OS 8/9, Carbon applications use Classic printer drivers and, generally speaking, Carbon Printing Manager functions simply call through to their original Printing Manager counterparts. When running on Mac OS X, Carbon applications use the new printing architecture and print through different drivers.

The most significant difference between the old Printing Manager and the Carbon Printing Manager is that all data structures are now opaque. Accessor functions are provided to access the information in these objects.

Printing Sessions

In Carbon Printing Manager parlance, an individual printing task is known as a session. Carbon applications running on Mac OS X can initiate multiple simultaneous printing sessions, each of which is completely independent of the other. On Mac OS 8/9, printing sessions are also supported, but with the limitation that an application can only ever have one printing session running.

Categories of Carbon Printing Manager Function

The Carbon Printing Manager API comprises:

• Session functions.

• Non-session functions.

• Universal functions.

The non-session functions do not support simultaneous printing sessions and inherit many of the limitations of the original Printing Manager. For this reason, Apple strongly recommends that the session functions be used instead. (Session and non-session functions must not be mixed within an application.) Accordingly, this chapter addresses the session and universal functions only.

Printer Drivers

Each type of printer has its own printer driver. Printer drivers performs the actual printing, translating system software drawing functions as required and send the translated instructions and data to the printer. On Mac OS 8/9, printer drivers are stored in printer resource files.

The current printer (on Mac OS 8/9, the printer selected by the user in the Chooser) is the printer driver that actually implements the functions defined by the Carbon Printing Manager.

Types and Characteristics of Printer Drivers

In general, there are two types of printer driver:

• QuickDraw printer drivers.

• PostScript printer drivers.

QuickDraw Printer Drivers

QuickDraw printers use QuickDraw to render images, which are then sent to the printer as bitmaps or pixel maps. Since they rely on the rendering capabilities of the Macintosh computer, QuickDraw printers are not required to have any intelligent rendering capabilities. Instead, they simply accept instructions from the printer driver to place dots on the page in specified places.

PostScript Printers

Unlike QuickDraw printers, PostScript printers have their own rendering capabilities. Instead of rendering the entire page on the Macintosh computer and sending all the pixels to the printer, PostScript printer drivers convert QuickDraw operations into equivalent PostScript operations and send the resulting drawing commands directly to the printer. The printer then renders the images by interpreting these commands. In this way, image processing is offloaded from the computer.

Background Printing and Spool Files

Most printer drivers allow users to specify background printing, which allows a user to work with an application while documents are printing in the background. On Mac OS 8/9, these printer drivers send printing data to a spool file in the PrintMonitor Documents folder in the System Folder.

Page and Paper Rectangles

Because of an individual printer's mechanical limitations, the printable area of a page is ordinarily less than the physical size of the paper.

Page Rectangle

The paper rectangle (see Fig 1) represents the physical paper size expressed in the same coordinate system as the page rectangle. The upper left coordinates of the paper rectangle are thus usually negative.

Paper Rectangle

The paper rectangle (see Fig 1) gives the physical paper size, defined in the same coordinate system as the page rectangle. Thus the upper left coordinates of the paper rectangle are typically negative, and its lower-right coordinates are greater than those of the page rectangle.

Page Setup Dialogs and Print Dialogs

If it is likely that the user will want to print the data created with your application, you should support both the Page Setup... command and the Print... command in your application's File menu.

Page Setup Dialog

In response to the user choosing the Page Setup� item from the File menu, your application should display the Page Setup dialog. For Mac OS 8/9, each printer driver defines its own Page Setup dialog. For Mac OS X, printer manufacturers can extend the standard Page Setup dialog with options specific to their printer. Fig 2 shows the Page Setup dialog.

Displaying the Page Setup Dialog and Accessing Settings

PMSessionPageSetupDialog is used to display the Page Setup dialog defined by the printer driver for the current printer. This function handles all user interaction in the items defined by the printer driver until the user clicks the OK or Cancel button.

Settings made in a Page Setup dialog are stored in a PMPageFormat object (see below). Your application can use accessor functions to extract information, such as orientation and scaling settings, from this object.

Print Dialog

In response to the user choosing the Print� item in the File menu, your application should display the Print dialog. For Mac OS 8/9, each printer driver defines its own Print dialog. For Mac OS X, printer manufacturers can extend the standard Print dialog with options specific to their printer. Fig 2 shows the Print dialog.

Displaying the Print Dialog and Accessing Settings

PMSessionPrintDialog is used to display the Print dialog defined by the printer driver for the current printer. This function handles all user interaction in the items defined by the printer driver until the user clicks the Print or Cancel button.

Settings made in a Print dialog are stored in a PMPrintSettings object (see below). Your application can use accessor functions to extract information, such as the page numbers to print, from this object.

Customised Page Setup and Print Dialogs

Many applications add items to the basic Page Setup and Print dialogs so as to provide the user with additional control over printing operations within that application.

If you wish to customise the Page Setup and/or Print dialogs so as to solicit additional information from the user, one option is to use what is sometimes referred to as the AppendDITL method. This requires that you provide an initialisation function, an item evaluation function and, possibly, an event filter function. A universal procedure pointer to the initialisation function is passed as a parameter in the functions PMSessionPageSetupDialogMain and PMSessionPrintDialogMain, which are used to display, respectively, customised Page Setup and customised Print dialogs. (See Customising the Page Setup and Print Dialogs, below.)

Preserving the User's Printing Preferences

The only information you should preserve each time the user prints the document should be that obtained via the Page Setup dialog. The information supplied by the user through the Print dialog should pertain to the document only while the document prints, and you should not re-use this information if the user prints the document again.

You can preserve the information obtained via the Page Setup dialog by saving the PMPageFormat object associated with a document in that document's data or resource fork. (See Saving and Retrieving a Page Format Object, below.)

The values specified by the user via the Page Setup dialog apply only to the printing of the document in the active window.

Printing Sessions - The PMPrintSession Object

A call to PMCreateSession creates a context for printing operations, called a printing session, and initialises a PMPrintSession object.

The PMPageFormat, PMPrintSettings, and PMPrintContext Objects

PMPageFormat Object

The PMPageFormat object stores information about how the pages of a document should be printed, for example, on what paper size, in what printable area, and in what orientation (landscape or portrait).

You use the function PMCreatePageFormat to create an instance of this opaque object. PMCreatePageFormat returns a reference to the object, which is created empty of settings. When your application displays a Page Setup dialog, and the user clicks the OK button to dismiss the dialog, the Carbon Printing Manager saves the settings in the PMPageFormat object.

As will be seen, PMPageFormat objects are extensible, meaning that your application can store additional data in them and that your application should never assume that they are of a fixed size.

PMPageFormat objects may be disposed of using the function DisposePageFormat.

Accessor Functions

The following describes accessor functions you can use to obtain information contained within PMPageFormat objects.

     struct PMRect
     {
       double top;
       double left;
       double right
       double bottom;
     }

     struct PMResolution
     {
       double hRes;  // The horizontal resolution in dpi.
       double vRes;  // The vertical resolution in dpi.
     };

     enum PMOrientation
     {
       kPMPortrait = 1,
       kPMLandscape = 2,
       kPMReversePortrait = 3,
       kPMReverseLandscape = 4
     };

Assigning Default Parameters

A call to PMSessionDefaultPageFormat will assign default parameters to a PMPageFormat object for the specified printing session.

Validating a PMPageFormat Object

A call to PMSessionValidatePageFormat will validate a PMPageFormat object's parameters within the context of the specified printing session. true is returned in the result parameter if any parameters had to be changed.

PMPrintSettings Object

The PMPrintSettings object stores information, such as the number of copies, range of pages to print, and print quality, for a particular printing session.

You use the function PMCreatePrintSettings to create an instance of this opaque object. PMCreatePrintSettings returns a reference to the object, which is created empty of settings. When your application displays a Print dialog, and the user clicks the Print button to dismiss the dialog, the Carbon Printing Manager saves the settings in the PMPrintSettings object.

As will be seen, PMNewPrintSettings objects are extensible, meaning that your applications can store additional data in them and that your application should never assume that they are of a fixed size.

PMPrintSettings objects may be disposed of using the function DisposePrintSettings.

Accessor Functions

The following describes accessor functions you can use to obtain information contained within PMPrintSettings objects.

Function	Description
PMGetFirstPage	Reports the starting page number of the pages to be printed.
PMSetFirstPage	Sets the page number at which to begin printing.
PMGetLastPage	Gets the last page number of the pages to be printed.
PMSetLastPage	Sets the page number at which to end printing.
PMGetPageRange	Gets the valid range of pages to print, previously set by PMSetPageRange. If none was set by the application, the default range (1-32000) is returned.
PMSetPageRange	Sets the valid range of pages to be printed. On Mac OS X, if the user enters a value outside this range in the Print dialog, an alert message is displayed. This feature is not supported on Mac OS 8/9. The relationship between the page range set by the application using PMSetPageRange and the first and last pages set by the user in the Print dialog (and retrieved by PMGetFirstPage and PMGetLastPage) is shown at Fig 4.
PMGetCopies	Gets the number of copies to be printed.
PMSetCopies	Sets the default value to be displayed for the number of copies to be printed.
PMGetPrintSettingsExtendedData	Gets additional print settings previously saved by your application.
PMSetPrintSettingsExtendedData	Stores application-supplied data in a PMPrintSettings object.
Note: You pass true in the lock parameter of the functions PMSetCopies, PMSetFirstPage, and PMSetLastPage if you wish to lock, respectively, the number-of-copies, first-page, and last-page fields in the Print dialog. Passing true only affects printer drivers for Mac OS X and LaserWriter printer drivers version 8.7 and later. If you pass true for other printer drivers, these functions will return kPMLockIgnored.

Assigning Default Parameters

A call to PMSessionDefaultPrintSettings will assign default parameters to a PMPrintSettings object for the specified printing session.

Validating a PMPrintSettings Object

A call to PMSessionValidatePrintSettings will validate a PMPrintSettings object's parameters within the context of the specified printing session. true is returned in the result parameter if any parameters had to be changed.

Printing a Document

The following describes a typical approach to printing a document.

When the User Chooses Page Setup... From the File Menu

When the user invokes the Page Setup dialog:

• Call a function which:
  • Calls PMCreateSession to create a PMPrintSession object, and associates that object with the document's window.

  • If a PMPageFormat object has not previously been created and associated with the document's window:

  • Calls PMCreatePageFormat to create a PMPageFormat object.

  • Calls PMSessionDefaultPageFormat to assign default parameters to the PMPageFormat object.

  • Associates the PMPageFormat object with the document's window.

  • If a PMPageFormat object has previously been created and associated with the document's window, calls PMSessionValidatePageFormat to validate the PMPageFormat object's parameters within the context of this printing session.

• Call PMSessionPageSetupDialog to present the Page Setup dialog, handle all user interaction within the dialog, and record the user's settings in the PMPageFormat object.

• When the user dismisses the Page Setup dialog, call PMRelease to release the PMPrintSession object.

When the User Chooses Print... From the File Menu

When the user invokes the Print dialog:

• As when the Page Setup dialog is invoked (see above), call a function which:

  • Creates a PMPrintSession object and associates it with the document's window.

  • Either creates a PMPageFormat object, assigns default parameters to it, and associates it with the document's window or, if this has previously been done, validates the existing PMPageFormat object's parameters.

• Call PMCreatePrintSettings to create a PMPrintSettings object.

• Call PMSessionDefaultPrintSettings to assign default parameters to the PMPrintSettings object.

• Associate the PMPrintSettings object with the document's window.

• For Mac OS X only:

  • Call PMSetPageRange to set the valid range of pages that can be printed.

  • Call PMSetFirstPage and PMSetLastPage to set the default first and last pages to be printed, as displayed in the From and To fields of the Print dialog. (To clear the From and To fields and select the All radio button, pass kPMPrintAllPages in the PMSetLastPage call.)

• Call PMSessionPrintDialog to present the Print dialog, handle all user interaction within the dialog, and record the user's settings in the PMPrintSettings object.

• If the user clicks the Cancel button in the Print dialog, call PMRelease to release the PMPrintSettings and PMPrintSession objects, and disassociate them from the document's window.

• If the user clicks the Print button in the Print dialog, call your application's printing loop function.

The Printing Loop Function

The printing loop is the part of your application's code that performs the actual printing. The function containing the printing loop should perform the following actions:

• Call PMGetFirstPage and PMGetLastPage to get the first and last pages to print, as entered by the user in the Print dialog.

• Call a function which calculates the actual number of pages in the document. If necessary, adjust the value in the variable containing the last page as returned by PMGetLastPage.

• For Mac OS X, call PMSetFirstPage and PMSetLastPage to tell the Carbon Printing Manager which pages will be spooled so that the progress dialog can display an accurate page count. Pass in the values returned by the PMGetFirstPage and PMGetLastPage calls, the latter adjusted as necessary.

• Call PMSessionBeginDocument to create an instance of a PMPrintContext object and thus establish a graphics context for imaging the document. (As will be seen, a function exists to obtain the graphics port (that is, the printing port) associated with this object.)

• Print the pages. In the page-printing loop, all of the pages in the document should be spooled and the Carbon Printing Manager relied upon to print the correct page range as specified in the Print dialog. Note that your printing loop does not have to concern itself with the number of copies, since this is handled automatically by the Carbon Printing Manager. The pages loop should:

  • Call PMSessionBeginPage to initialise the printing port. (Note that, for Mac OS 8/9 only, you can pass a scaling (bounding) rectangle in the pageFrame parameter, in which case all items drawn in the printing port will be scaled to fit this page rectangle. If no scaling is required, pass NULL in the pageFrame parameter.)

  • Call GetPort to save the current graphics port, call PMSessionGetGraphicsContext to obtain the current printing port, and call SetPort to set that port as the current port.

  • Call a function which draws the relevant page in the printing port, then call SetPort to set the port saved by the GetPort call as the current port.

  • Call PMSessionEndPage to print the page.

• When all copies of all pages have been printed, call PMSessionEndDocument to close the printing graphics port.

• Call PMRelease to release the PMPrintSettings and PMPrintSession objects.

Call Sequence And Scope

When writing functions which call Carbon Printing Manager functions, bear in mind that the Carbon Printing Manager enforces a sequence of steps in the printing loop, and defines a valid scope for each routine. Routines used out of sequence will return an result code of kPMOutOfScope.

Sequence and Scope: Session Functions

The following, in which scope level is represented by indentation, shows calling sequence and scope requirements of the session printing functions mentioned in this chapter. It shows, for example, that you can call PMSessionGetGraphicsContext only after calling PMSessionBeginPage.

     PMCreateSession
        PMSessionDefaultPageFormat
        PMSessionValidatePageFormat
        PMSessionDefaultPrintSettings
        PMSessionValidatePrintSettings
        PMSessionError

        PMSessionPageSetupDialog
        PMSessionPrintDialog
        PMSessionPageSetupDialogInit  These functions must be called
        PMSessionPrintDialogInit      before PMSessionBeginDocument
        PMSessionPrintDialogMain
        PMSessionPageSetupDialogMain

        PMSessionBeginDocument
           PMSessionBeginPage
              PMSessionGetGraphicsContext
           PMSessionEndPage
        PMSessionEndDocument

Sequence and Scope: Universal Functions

The following are the unrestricted functions referred to in this chapter which have no calling sequence or scope, and which may generally be used anywhere in your printing code:

     PMCreatePageFormat        PMGetLastPage             PMGetScale
     PMFlattenPageFormat       PMSetLastPage             PMSetScale
     PMUnflattenPageFormat     PMGetCopies               PMGetResolution
     PMCreatePrintSettings     PMSetCopies               PMSetResolution
     PMFlattenPrintSettings    PMGetAdjustedPaperRect    PMGetPageFormatExtendedData
     PMUnflattenPrintSettings  PMGetAdjustedPageRect     PMSetPageFormatExtendedData
     PMGetPageRange            PMGetUnadjustedPageRect   PMGetPrintSettingsExtendedData
     PMSetPageRange            PMSetUnadjustedPaperRect  PMSetPrintSettingsExtendedData
     PMGetFirstPage            PMGetOrientation
     PMSetFirstPage            PMSetOrientation

Handling Printing Errors

The Carbon Printing Manager must necessarily bear the heavy burden of maintaining backward compatibility with early printer models and of maintaining compatibility with a great many existing printer drivers. For this reason, you must be especially wary of, and defensive about, possible error conditions when using Carbon Printing Manager functions.

Do not display an alert or dialog to report an error until the end of the printing loop. This is important for two reasons:

• If you display an alert in the middle of a printing loop, it could cause errors that might terminate an otherwise normal printing operation.

• The printer driver may have already displayed its own alert reporting the error.

Text on the Screen and the Printed Page

At the application level, printing on the Macintosh computer is not fundamentally different from drawing on the screen. That said, printing text poses special challenges.

A common complication results from the difference in resolution and pixel size between screen and printer. QuickDraw measurements are theoretically in terms of points, which are nominally equivalent to screen pixels. High resolution printers have very much smaller pixels, although printer drivers are expected to take this into account so that the same QuickDraw calls will produce text lines of the same width on the screen and on the printer. Nevertheless, this higher resolution, and the fact that printers may use different fonts from those used for screen display, can result in some loss of fidelity from the screen to the printed page. In this regard, the following is relevant:

• QuickDraw places text glyphs on the screen at screen pixel intervals, whereas a printer can provide much finer placements on the printed page. This situation presents a choice between optimising the appearance of text on the screen or on the printed page. In effect, that choice is whether to specify fractional glyph widths or integer glyph widths.

  A glyph is the visual representation of a character. See Chapter 21.

  Fractional glyph widths are measurements of a glyph's width which can include fractions of a pixel. Using fractional glyph widths improves the appearance of printed text because it makes it possible for the printer, with its very high resolution, to print with better spacing. However, because screen glyphs are made up of whole pixels, QuickDraw cannot draw a fractional glyph on the screen, so it rounds off the fractional parts. This results in some degradation in the appearance of the text, in terms of character spacing, on the screen.

  The alternative (integer glyph widths) gives more pleasing screen results because the characters are drawn with regular pixel spacing, but this may possibly be at the price of a printed page which is typographically unacceptable.

  The Font Manager function SetFractEnable is used to turn fractional glyph widths on and off. SetFractEnable affects functions which draw text and which calculate text and character widths.

• Printer drivers attempt to reproduce faithfully the text formatting as drawn by QuickDraw on the screen, including keeping the same intended character spacing, line breaks and page breaks. However, because printers can have resident fonts that are different from the fonts that QuickDraw uses, because the drivers may handle text layout somewhat differently than QuickDraw, and because font metrics do not always scale linearly, fidelity may not always be achieved. Typically, identical line breaks and page breaks can be maintained, but character spacing can be noticeably different.

Customising the Page Setup and Print Dialogs

As previously stated, you may want to add additional options to the style and job dialogs so that the user can further customise the printing process. For example, you might want to add a "skip blank pages" checkbox to a Print dialog.

On Mac OS X, the printing dialog extension (PDE) mechanism may be used to extend the Page Setup and Print dialogs. The PDE mechanism provides great flexibility in extending printing dialogs. However, because the PDE mechanism applies only to Mac OS X, that method of extending Page Setup and Print dialogs is not addressed in this book. The method addressed is sometimes referred to as the AppendDITL method. A limitation of the AppendDITL method is that it prevents you from creating the Page Setup and Print dialogs as window-modal (sheet) dialogs. This limitation does not apply when the PDE method is used.

The functions PMSessionPageSetUpDialogMain and PMSessionPrintDialogMain are used to display customised Page Setup and Print dialogs.

The PMDialog Object

Your application uses a reference to a PMDialog object when creating custom Page Setup and Print dialogs. The functions PMSessionPageSetUpDialogInit and PMSessionPrintDialogInit functions are used to create and initialise instances of this opaque object. Taking the reference to this object as a parameter, the function PMGetDialogPtr returns a pointer to the dialog structure.

Customising a Print Dialog

As an example, to customise a Print dialog, you must modify the contents of the PMDialog object before the dialog is drawn on the screen. This involves:

• Providing a 'DITL' resource containing the required additional items.

• Defining an item evaluation function that handles events involving the additional items.

• Defining and installing an initialisation function that:

  • Calls AppendDITL to append the additional items to the dialog.

  • Using PMGetItemProc, gets the universal procedure pointer to the printer driver's item evaluation function from the PMDialog object, and saves it. (The printer driver's item evaluation function will need to be called from your item evaluation function to handle hits on the dialog's standard items.)

  • Calls PMSetItemProc to set a universal procedure pointer to your item evaluation function in the PMDialog object.

• If required, defining a custom event filter function and setting a universal procedure pointer to it in the PMDialog object using PMSetModalFilterProc.

A universal procedure pointer to the initialisation function should then be passed in the myInitProc parameter of PMSessionPrintDialogMain, which displays the customised Print dialog.

Displaying Page Setup and Print Dialogs as Window-Modal (Sheet) Dialogs

To cause Page Setup and Print dialogs to be created as window-modal (sheet) dialogs on Mac OS X, you should call the function PMSessionUseSheets immediately before the calls to PMSessionPageSetupDialog and PMSessionPrintDialog, passing the window reference for the parent window in the documentWindow parameter and a universal procedure pointer to an application-defined (callback) function in the sheetDoneProc parameter. The callback function should perform the actions required immediately following dismissal of the dialog, and should be declared like this:

     void  myPageSetupSheetDoneFunction(PMPrintSession printSession, WindowRef documentWindow,
                                        Boolean accepted);

The accepted formal parameter will be set to true if the Print/OK push button is clicked and to false if the Cancel push button is clicked.

The functions NewPMSheetDoneUPP and DisposePMSheetDoneUPP create and dispose of the universal procedure pointers.

Saving and Retrieving a Page Format Object

As previously stated, the only information you should preserve each time the user prints a document should be that obtained via the Page Setup dialog. Ordinarily, therefore, you will want your application to save the flattened PMPageFormat object associated with a specific document in either the data fork or the resource fork of that document's file when you save the document itself.

You can store additional application-defined data inside the PMPageFormat object before it is flattened and saved by calling PMSetPageFormatExtendedData, whose parameters include a unique code identifying the data, the size of the data, and a pointer to the data. When the flattened PMPageFormat object is retrieved and unflattened, you can obtain this data by calling PMGetPageFormatExtendedData.

Saving a flattened PMPageFormat object to the resource fork of a file, and retrieving the flattened object from the file, is demonstrated in the demonstration program associated with Chapter 19.

Printing From the Finder - Mac OS 8/9

Users generally print documents that are open on the screen one at a time while the application that created the document is running. However, on Mac OS 8/9, users can also print one or more documents from the Finder by selecting the documents and choosing Print... from the Finder's File menu. This causes the Finder to launch the application and pass it a required Apple event (the Print Documents event) indicating the documents to be printed. In response to a Print Documents event, your application should:

• Use saved or default page setup settings instead of displaying the Page Setup dialog.

• Display the Print dialog once only, and use PMCopyPrintSettings to apply the information specified by the user to all of the selected documents.

• Remain open unless and until the Finder sends it a Quit Application event.

Main Carbon Printing Manager Constants, Data Types and Functions

Constants

Unwanted Data

KPMNoData               = NULL
KPMDontWantSize         = NULL
KPMDontWantData         = NULL
KPMDontWantBoolean      = NULL
KPMNoPrintSettings      = NULL
kPMNoPageFormat         = NULL
kPMNoReference          = NULL

PMOrientation

enum PMOrientation
kPMPortrait             = 1
kPMLandscape            = 2
kPMReversePortrait      = 3
kPMReverseLandscape     = 4

User Cancelled

kPMCancel               = 128

For PMSetPageRange

kPMPrintAllPages        = -1

Result Codes

kPMNoError               = 0
kPMGeneralError          = -30870
kPMOutOfScope            = -30871
kPMInvalidParameter      = paramErr
kPMNoDefaultPrinter      = -30872
kPMNotImplemented        = -30873
kPMNoSuchEntry           = -30874
kPMInvalidPrintSettings  = -30875
kPMInvalidPageFormat     = -30876
kPMValueOutOfRange       = -30877
kPMLockIgnored           = -30878
kPMInvalidPrintSession   = -30879
kPMInvalidPrinter        = -30880
kPMObjectInUse           = -30881

Data Types

Opaque Types

typedef struct OpaquePMPrintSession*  PMPrintSession;
typedef struct OpaquePMPageFormat*    PMPageFormat;
typedef struct OpaquePMPrintSettings* PMPrintSettings;
typedef struct OpaquePMPrintContext*  PMPrintContext;
typedef struct OpaquePMDialog*        PMDialog;

PMRect

struct PMRect
{
  double top;
  double left;
  double right;
  double bottom;
}

PMResolution

struct PMResolution
{
  double hRes;
  double vRes;
}

Functions

Managing Printing Objects

OSStatus  PMRetain(PMObject object);
OSStatus  PMRelease(PMObject object);

Print Loop

OSStatus  PMCreateSession(PMPrintSession *printSession);
OSStatus  PMSessionBeginDocument(PMPrintSession printSession,PMPrintSettings printSettings,
          PMPageFormat pageFormat);
OSStatus  PMSessionEndDocument(PMPrintSession printSession);
OSStatus  PMSessionBeginPage(PMPrintSession printSession,PMPageFormat pageFormat,
          const PMRect *pageFrame);
OSStatus  PMSessionEndPage(PMPrintSession printSession);
OSStatus  PMSessionSetIdleProc(PMPrintSession printSession,PMIdleUPP idleProc);
OSStatus  PMSessionGetGraphicsContext(PMPrintSession printSession,
          CFStringRef graphicsContextType,void **graphicsContext);

Page Format and Print Settings Objects

OSStatus  PMCreatePageFormat(PMPageFormat *pageFormat);
OSStatus  PMCreatePrintSettings(PMPrintSettings *printSettings);
OSStatus  PMSessionDefaultPageFormat(PMPrintSession printSession,PMPageFormat pageFormat);
OSStatus  PMSessionDefaultPrintSettings(PMPrintSession printSession,
          PMPrintSettings printSettings);
OSStatus  PMSessionValidatePageFormat(PMPrintSession printSession,PMPageFormat pageFormat,
          Boolean *result);
OSStatus  PMSessionValidatePrintSettings(PMPrintSession printSession,
          PMPrintSettings printSettings,Boolean *result);
OSStatus  PMCopyPageFormat(PMPageFormat formatSrc,PMPageFormat formatDest);
OSStatus  PMCopyPrintSettings(PMPrintSettings settingSrc,PMPrintSettings settingDest);
OSStatus  PMFlattenPageFormat(PMPageFormat pageFormat,Handle *flatFormat);
OSStatus  PMUnflattenPageFormat(Handle flatFormat,PMPageFormat *pageFormat);
OSStatus  PMFlattenPrintSettings(PMPrintSettings printSettings,Handle *flatSetting);
OSStatus  PMUnflattenPrintSettings(Handle flatSetting,PMPrintSettings *printSettings);

Displaying the Page Setup and Print Dialogs

OSStatus  PMSessionPageSetupDialog(PMPrintSession printSession,PMPageFormat pageFormat,
          Boolean *accepted);
OSStatus  PMSessionPrintDialog(PMPrintSession printSession,PMPrintSettings printSettings,
          PMPageFormat constPageFormat,Boolean* accepted);
OSStatus  PMSessionUseSheets(PMPrintSession printSession,WindowRef documentWindow,
          PMSheetDoneUPP sheetDoneProc);

Customising Page Setup and Print Dialogs

OSStatus  PMSessionPageSetupDialogInit(PMPrintSession printSession,PMPageFormat pageFormat,
          PMDialog *newDialog);
OSStatus  PMSessionPrintDialogInit(PMPrintSession printSession,PMPrintSettings printSettings,
          PMPageFormat constPageFormat,PMDialog *newDialog);
OSStatus  PMSessionPageSetupDialogMain(PMPrintSession printSession,PMPageFormat pageFormat,
          Boolean *accepted,PMPageSetupDialogInitUPP myInitProc);
OSStatus  PMSessionPrintDialogMain(PMPrintSession printSession,PMPrintSettings printSettings,
          PMPageFormat constPageFormat,Boolean *accepted,PMPrintDialogInitUPP myInitProc);
OSStatus  PMSetModalFilterProc(PMDialog pmDialog,ModalFilterUPP filterProc);
OSStatus  PMSetItemProc(PMDialog pmDialog,PMItemUPP itemProc);
OSStatus  PMGetItemProc(PMDialog pmDialog,PMItemUPP *itemProc);
OSStatus  PMGetDialogPtr (PMDialog pmDialog, DialogRef *theDialog);

Getting and Setting Page Setup Information

OSStatus  PMGetAdjustedPaperRect(PMPageFormat pageFormat,PMRect *paperRect);
OSStatus  PMGetAdjustedPageRect(PMPageFormat pageFormat,PMRect *pageRect);
OSStatus  PMGetUnadjustedPaperRect(PMPageFormat pageFormat,PMRect *paperSize);
OSStatus  PMSetUnadjustedPaperRect(PMPageFormat pageFormat,const PMRect paperSize);
OSStatus  PMGetUnadjustedPageRect(PMPageFormat pageFormat,PMRect *pageSize);
OSStatus  PMGetResolution(PMPageFormat pageFormat,PMResolution *res);
OSStatus  PMSetResolution(PMPageFormat pageFormat,const PMResolution res);
OSStatus  PMSetOrientation(PMPageFormat pageFormat,PMOrientation orientation,Boolean lock);
OSStatus  PMGetOrientation(PMPageFormat pageFormat,PMOrientation *orientation);
OSStatus  PMGetScale(PMPageFormat pageFormat,double *scale);
OSStatus  PMSetScale(PMPageFormat pageFormat,double scale);
OSStatus  PMGetPageFormatExtendedData(PMPageFormat pageFormat,OSType dataID,UInt32 *size,
          void *extendedData);
OSStatus  PMSetPageFormatExtendedData(PMPageFormat pageFormat,OSType dataID,UInt32 size,
          void *extendedData);

Getting and Setting Printing Information

OSStatus  PMGetFirstPage(PMPrintSettings printSettings,UInt32 *first);
OSStatus  PMSetFirstPage(PMPrintSettings printSettings,UInt32 first,Boolean lock);
OSStatus  PMGetLastPage(PMPrintSettings printSettings,UInt32 *last);
OSStatus  PMSetLastPage(PMPrintSettings printSettings,UInt32 last,Boolean lock);
OSStatus  PMGetPageRange(PMPrintSettings printSettings,UInt32 *minPage,UInt32 *maxPage);
OSStatus  PMSetPageRange(PMPrintSettings printSettings,UInt32 minPage,UInt32 maxPage);
OSStatus  PMGetCopies(PMPrintSettings printSettings,UInt32 *copies);
OSStatus  PMSetCopies(PMPrintSettings printSettings,UInt32 copies,Boolean lock);
OSStatus  PMGetPrintSettingsExtendedData(PMPrintSettings printSettings,OSType dataID,
          UInt32 *size,void *extendedData);
OSStatus  PMSetPrintSettingsExtendedData(PMPrintSettings printSettings,OSType dataID,
          UInt32 size,void *extendedData);

Creating and Disposing of Universal Procedure Pointers

PMPageSetupDialogInitUPP NewPMPageSetupDialogInitUPP(PMPageSetupDialogInitProcPtr userRoutine);
PMPrintDialogInitUPP     NewPMPrintDialogInitUPP(PMPrintDialogInitProcPtr userRoutine);
PMItemUPP                NewPMItemUPP(PMItemProcPtr userRoutine);
PMIdleUPP                NewPMIdleUPP(PMIdleProcPtr userRoutine);
PMSheetDoneUPP           NewPMSheetDoneUPP(PMSheetDoneProcPtr userRoutine);
void      DisposePMPageSetupDialogInitUPP(PMPageSetupDialogInitUPP userUPP);
Void      DisposePMPrintDialogInitUPP	(PMPrintDialogInitUPP userUPP);
void      DisposePMItemUPP(PMItemUPP userUPP);
void      DisposePMIdleUPP(PMIdleUPP userUPP);
void      DisposePMSheetDoneUPP(PMSheetDoneUPP userUPP);

Errors

OSStatus  PMSessionError(PMPrintSession printSession);

Application-Defined (Callback) Functions

void      myPMDialogSheetDoneFunction(PMPrintSession printSession, WindowRef documentWindow,
                                      Boolean accepted);