TweetFollow Us on Twitter

MACINTOSH C CARBON
MACINTOSH C CARBON: A Hobbyist's Guide To Programming the Macintosh in C
Version 1.0
2001 K. J. Bricknell
Go to Contents Go to Program Listing

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.

Function

Description

PMGetAdjustedPaperRect

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:

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

The size returned is in your application drawing resolution, which you can obtain by calling PMGetResolution.

PMGetAdjustedPageRect

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.

PMGetUnadjustedPaperRect

Gets the true size of the paper in points, unaffected by rotation, resolution, or scaling.

PMSetUnadjustedPaperRect

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.

PMGetUnadjustedPageRect

Gets the size of the imageable area in points, unaffected by rotation, resolution, or scaling.

PMGetResolution

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:

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

Sets the application's drawing resolution.

PMGetOrientation

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:

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

Sets the page orientation for printing.

PMGetScale

Returns the scaling factor currently applied to the page and paper rectangles.

PMSetScale

Sets print scaling.

PMGetPageFormatExtendedData

Gets additional page format data previously stored by your application.

PMSetPageFormatExtendedData

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.

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);

 
AAPL
$102.99
Apple Inc.
+0.52
MSFT
$44.38
Microsoft Corpora
-0.50
GOOG
$532.71
Google Inc.
+6.17

MacTech Search:
Community Search:

Software Updates via MacUpdate

OmniOutliner 4.1.3 - Organize your ideas...
OmniOutliner is a flexible program for creating, collecting, and organizing information. Give your creativity a kick start by using an application that's actually designed to help you think. It's... Read more
BBEdit 11.0 - Powerful text and HTML edi...
BBEdit is the leading professional HTML and text editor for the Mac. Specifically crafted in response to the needs of Web authors and software developers, this award-winning product provides a... Read more
Apple Security Update 2014-005 - For OS...
Apple Security Update is recommended for all users and improves the security of Mac OS X. For information on the security content of this update, please visit this website: http://support.apple.com/... Read more
EyeTV 3.6.6 - Watch and record TV on you...
EyeTV brings a rich TV experience to your Mac. Watch live TV on your Mac. Pause, rewind, and record whenever you want. EyeTV gives you powerful control over what you watch and how you watch it. Put... Read more
RapidWeaver 6.0 - Create template-based...
RapidWeaver is a next-generation Web design application to help you easily create professional-looking Web sites in minutes. No knowledge of complex code is required, RapidWeaver will take care of... Read more
NTFS 12.0.39 - Provides full read and wr...
Paragon NTFS breaks down the barriers between Windows and OS X. Paragon NTFS effectively solves the communication problems between the Mac system and NTFS, providing full read and write access to... Read more
RestoreMeNot 2.0.3 - Disable window rest...
RestoreMeNot provides a simple way to disable the window restoration for individual applications so that you can fine-tune this behavior to suit your needs. Please note that RestoreMeNot is designed... Read more
Command-C 1.1.5 - Clipboard sharing tool...
Command-C is a revolutionary app which makes easy to share your clipboard between iOS and OS X using your local WiFi network, even if the app is not currently opened. Copy anything (text, pictures,... Read more
Macgo Blu-ray Player 2.10.9.1750 - Blu-r...
Macgo Mac Blu-ray Player can bring you the most unforgettable Blu-ray experience on your Mac. Overview Macgo Mac Blu-ray Player can satisfy just about every need you could possibly have in a Blu-ray... Read more
Apple iOS 8.1 - The latest version of Ap...
The latest version of iOS can be downloaded through iTunes. Apple iOS 8 comes with big updates to apps you use every day, like Messages and Photos. A whole new way to share content with your family.... Read more

Latest Forum Discussions

See All

Fighting Fantasy: Caverns of the Snow Wi...
Fighting Fantasy: Caverns of the Snow Witch 1.0 Device: iOS Universal Category: Games Price: $5.99, Version: 1.0 (iTunes) Description: Travel to Northern Allansia’s perilous Icefinger Mountains to defeat the wicked Snow Witch in this... | Read more »
TinType by Hipstamatic (Photography)
TinType by Hipstamatic 1.0 Device: iOS iPhone Category: Photography Price: $.99, Version: 1.0 (iTunes) Description: Create hauntingly beautiful, soul capturing portraits with TinType by Hipstamatic. Inspired by daguerreotypes,... | Read more »
The Latest Update for Heroes of Dragon A...
The Latest Update for Heroes of Dragon Age Introduces Daily PvE Challenges Posted by Ellis Spice on October 22nd, 2014 [ permalink ] | Read more »
A New Trailer has Been Revealed for Epic...
A New Trailer has Been Revealed for Epic of Kings Posted by Jessica Fisher on October 22nd, 2014 [ permalink ] Dead Mage Inc. has released a new, action-packed trailer for the upcoming Epic of Kings. | Read more »
Find the Line Review
Find the Line Review By Campbell Bird on October 22nd, 2014 Our Rating: :: INSLIDE THE LINESUniversal App - Designed for iPhone and iPad Tease out beautiful line drawings in this unique, free-to-play puzzle game.   | Read more »
The Silent Age Episode 2 Review
The Silent Age Episode 2 Review By Jennifer Allen on October 22nd, 2014 Our Rating: :: ROUNDING THINGS OFF NICELYUniversal App - Designed for iPhone and iPad Rounding off a great point and click adventure comes The Silent Age... | Read more »
Craft Your Own Mini-Games with Papercade
Craft Your Own Mini-Games with Papercade Posted by Jessica Fisher on October 22nd, 2014 [ permalink ] iPad Only App - Designed for the iPad Scrapbookers move over, Scrapgaming is the new thing. | Read more »
Reshape Review
Reshape Review By Jennifer Allen on October 22nd, 2014 Our Rating: :: SIMPLE SHAPESUniversal App - Designed for iPhone and iPad Match triangles together to form cubes in this fast-paced and twitchy game.   | Read more »
Miika (Games)
Miika 1.0.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0.0 (iTunes) Description: Miika is a beautiful 3D puzzle game based on camera perspectives combined with the use of optical illusions. Miika challenges... | Read more »
Infuse Pro (Photography)
Infuse Pro 3.0 Device: iOS Universal Category: Photography Price: $9.99, Version: 3.0 (iTunes) Description: ** All-new version 3 includes fully licensed and certified DTS® and DTS-HD® audio! ** | Read more »

Price Scanner via MacPrices.net

Save with Best Buy’s College Student Deals
Take an additional $50 off all MacBooks and iMacs at Best Buy Online with their College Students Deals Savings, valid through November 1st. Anyone with a valid .EDU email address can take advantage... Read more
iPad Air 2 & iPad mini 3 Best Tablets Yet...
The new iPads turned out to be pretty much everything I’d been hoping for and more than I’d expected.”More” particularly in terms of a drinking-from-a-firehose choice of models and configurations,... Read more
Drafts 4 Reinvents iOS Productivity App
N Richland Hills, Texas based Agile Tortoise has announced the release of Drafts 4 for iPhone and iPad. Drafts is a quick capture note taking app with flexible output actions. Drafts 4 scales from... Read more
AT&T accepting preorders for new iPads fo...
AT&T Wireless is accepting preorders for the new iPad Air 2 and iPad mini 3, cellular models, for $100 off MSRP with a 2-year service agreement: - 16GB iPad Air 2 WiFi + Cellular: $529.99 - 64GB... Read more
Apple offering refurbished Mac Pros for up to...
The Apple Store is offering Apple Certified Refurbished 2013 Mac Pros for up to $600 off the cost of new models. An Apple one-year warranty is included with each Mac Pro, and shipping is free. The... Read more
Select MacBook Airs $100 off MSRP, free shipp...
B&H Photo has 2014 a couple of MacBook Airs on sale for $100 off MSRP. Shipping is free, and B&H charges NY sales tax only. They also include free copies of Parallels Desktop and LoJack for... Read more
13-inch 2.5GHz MacBook Pro on sale for $100 o...
B&H Photo has the 13″ 2.5GHz MacBook Pro on sale for $999.99 including free shipping plus NY sales tax only. Their price is $100 off MSRP. Read more
Strong iPhone, Mac And App Store Sales Drive...
Apple on Monday announced financial results for its fiscal 2014 fourth quarter ended September 27, 2014. The Company posted quarterly revenue of $42.1 billion and quarterly net profit of $8.5 billion... Read more
Apple Posts How-To For OS X Recovery
OS X 10.7 Lion and later include OS X Recovery. This feature includes all of the tools you need to reinstall OS X, repair your disk, and even restore from a Time Machine backup. OS X Recovery... Read more
Mac OS X Versions (Builds) Supported By Vario...
Apple Support has posted a handy resource explaining which Mac OS X versions (builds) originally shipped with or are available for your computer via retail discs, downloads, or Software Update. Apple... Read more

Jobs Board

Senior Event Manager, *Apple* Retail Market...
…This senior level position is responsible for leading and imagining the Apple Retail Team's global event strategy. Delivering an overarching brand story; in-store, Read more
*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
Project Manager / Business Analyst, WW *Appl...
…a senior project manager / business analyst to work within our Worldwide Apple Fulfillment Operations and the Business Process Re-engineering team. This role will work Read more
*Apple* Retail - Multiple Positions (US) - A...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
Position Opening at *Apple* - Apple (United...
…customers purchase our products, you're the one who helps them get more out of their new Apple technology. Your day in the Apple Store is filled with a range of Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.