MACINTOSH C CARBON: A Hobbyist's Guide To Programming the Macintosh in C
© 2001 K. J. Bricknell
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.
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.
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.
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.
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.
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.
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
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.
The following describes accessor functions you can use to obtain information contained within PMPageFormat objects.
Gets the paper size.
On return, the paperRect parameter contains a rectangle describing the size of the paper after scaling, application drawing resolution and orientation settings are applied. The paperRect parameter is of type PMRect:
The size returned is in your application drawing resolution, which you can obtain by calling PMGetResolution.
Gets the page size.
On return, the pageRect parameter contains a rectangle describing the size of the page after scaling, application drawing resolution, and orientation settings are applied. The pageRect parameter is of type PMRect. The size returned is in your application drawing resolution, which you can obtain by calling PMGetResolution.
Gets the true size of the paper in points, unaffected by rotation, resolution, or scaling.
Sets printing to a particular paper size, unaffected by rotation, resolution, or scaling.
This function allows applications to request a particular paper size. If the driver cannot handle the specified size an error of kPMValueOutOfRange is returned. If the size is accepted, the application should still call PMGetUnadjustedPaperRect to verify.
Gets the size of the imageable area in points, unaffected by rotation, resolution, or scaling.
Gets the application's current drawing resolution.
On return, the res parameter contains a pointer to a structure of type PMResolution, which describes the resolution at which the Carbon Printing Manager expects your application to render images:
double hRes; // The horizontal resolution in dpi.
double vRes; // The vertical resolution in dpi.
Sets the application's drawing resolution.
Gets the current page orientation setting.
On return, the orientation parameter contains a pointer to a variable of type PMOrientation, which describes the current page orientation:
kPMPortrait = 1,
kPMLandscape = 2,
kPMReversePortrait = 3,
kPMReverseLandscape = 4
Sets the page orientation for printing.
Returns the scaling factor currently applied to the page and paper rectangles.
Sets print scaling.
Gets additional page format data previously stored by your application.
Stores your application-supplied data in a PMPageFormat object.
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.
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.
The following describes accessor functions you can use to obtain information contained within PMPrintSettings objects.
Reports the starting page number of the pages to be printed.
Sets the page number at which to begin printing.
Gets the last page number of the pages to be printed.
Sets the page number at which to end printing.
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.
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.
Gets the number of copies to be printed.
Sets the default value to be displayed for the number of copies to be printed.
Gets additional print settings previously saved by your application.
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.
PMSessionPageSetupDialogInit These functions must be called
PMSessionPrintDialogInit before PMSessionBeginDocument
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
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,
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
KPMNoData = NULL
KPMDontWantSize = NULL
KPMDontWantData = NULL
KPMDontWantBoolean = NULL
KPMNoPrintSettings = NULL
kPMNoPageFormat = NULL
kPMNoReference = NULL
kPMPortrait = 1
kPMLandscape = 2
kPMReversePortrait = 3
kPMReverseLandscape = 4
kPMCancel = 128
kPMPrintAllPages = -1
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
typedef struct OpaquePMPrintSession* PMPrintSession;
typedef struct OpaquePMPageFormat* PMPageFormat;
typedef struct OpaquePMPrintSettings* PMPrintSettings;
typedef struct OpaquePMPrintContext* PMPrintContext;
typedef struct OpaquePMDialog* PMDialog;
Managing Printing Objects
OSStatus PMRetain(PMObject object);
OSStatus PMRelease(PMObject object);
OSStatus PMCreateSession(PMPrintSession *printSession);
OSStatus PMSessionBeginDocument(PMPrintSession printSession,PMPrintSettings printSettings,
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,
OSStatus PMSessionValidatePageFormat(PMPrintSession printSession,PMPageFormat pageFormat,
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,
OSStatus PMSessionPrintDialog(PMPrintSession printSession,PMPrintSettings printSettings,
PMPageFormat constPageFormat,Boolean* accepted);
OSStatus PMSessionUseSheets(PMPrintSession printSession,WindowRef documentWindow,
Customising Page Setup and Print Dialogs
OSStatus PMSessionPageSetupDialogInit(PMPrintSession printSession,PMPageFormat pageFormat,
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,
OSStatus PMSetPageFormatExtendedData(PMPageFormat pageFormat,OSType dataID,UInt32 size,
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);
OSStatus PMSessionError(PMPrintSession printSession);
Application-Defined (Callback) Functions
void myPMDialogSheetDoneFunction(PMPrintSession printSession, WindowRef documentWindow,