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
$103.30
Apple Inc.
+0.80
MSFT
$45.09
Microsoft Corpora
-0.34
GOOG
$577.33
Google Inc.
+5.73

MacTech Search:
Community Search:

Software Updates via MacUpdate

TextSoap 7.4.0 - Flexible text editing u...
TextSoap is for people who work with text. TextSoap effortlessly cleans up text from endlessly different formats. Wash away unwanted characters, spaces, tabs. Fix paragraphs with hard returns at the... Read more
NetShade 6.0.2 - Browse privately using...
NetShade is an Internet security tool that conceals your IP address on the web. NetShade routes your Web connection through either a public anonymous proxy server, or one of NetShade's own dedicated... Read more
Mac DVDRipper Pro 5.0 - Copy, backup, an...
Mac DVDRipper Pro is the DVD backup solution that lets you protect your DVDs from scratches, save your batteries by reading your movies from your hard disk, manage your collection with just a few... Read more
pwSafe 3.1 - Secure password management...
pwSafe provides simple and secure password management across devices and computers. pwSafe uses iCloud to keep your password databases backed-up and synced between Macs and iOS devices. It is... Read more
StatsBar 1.8 - Monitor system processes...
StatsBar gives you a comprehensive and detailed analysis of the following areas of your Mac: CPU usage Memory usage Disk usage Network and bandwidth usage Battery power and health (MacBooks only)... Read more
Path Finder 6.5.5 - Powerful, award-winn...
Path Finder is a file browser that combines the familiar Finder interface with the powerful utilities and innovative features. Just a small selection of the Path Finder 6 feature set: Dual pane... Read more
QuarkXPress 10.2.1 - Desktop publishing...
With QuarkXPress, you can communicate in all the ways you need to -- and always look professional -- in print and digital media, all in a single tool. Features include: Easy to Use -- QuarkXPress is... Read more
Skype 6.19.0.450 - Voice-over-internet p...
Skype allows you to talk to friends, family and co-workers across the Internet without the inconvenience of long distance telephone charges. Using peer-to-peer data transmission technology, Skype... Read more
VueScan 9.4.41 - Scanner software with a...
VueScan is a scanning program that works with most high-quality flatbed and film scanners to produce scans that have excellent color fidelity and color balance. VueScan is easy to use, and has... Read more
Cloud 3.0.0 - File sharing from your men...
Cloud is simple file sharing for the Mac. Drag a file from your Mac to the CloudApp icon in the menubar and we take care of the rest. A link to the file will automatically be copied to your clipboard... Read more

Latest Forum Discussions

See All

Modern Combat 5 Gets a Major Multiplayer...
Modern Combat 5 Gets a Major Multiplayer Update Posted by Jessica Fisher on September 2nd, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Alien Creeps TD Review
Alien Creeps TD Review By Jennifer Allen on September 2nd, 2014 Our Rating: :: EXPENSIVE DEFENSESUniversal App - Designed for iPhone and iPad Alien Creeps TD would be a fun if unremarkable Tower Defense game, but its heavy focus on... | Read more »
The Journey Down: Chapter Two Review
The Journey Down: Chapter Two Review By Jennifer Allen on September 2nd, 2014 Our Rating: :: DARK YET ENTICINGUniversal App - Designed for iPhone and iPad It’s a little dark, in every sense of the word, but The Journey Down:... | Read more »
Function Space, a Social Network App for...
Function Space, a Social Network App for Science, Launches on iOS Posted by Ellis Spice on September 2nd, 2014 [ permalink ] | Read more »
Stupidfast – How Taylor Martinez Switche...
How do you make an Endless Running game more than just another Endless Running game? By adding real life prizes to it, of course! That’s the thinking behind StupidFast: a game designed for football enthusiasts, and the brainchild of former college... | Read more »
Little Raiders: Robin’s Revenge Review
Little Raiders: Robin’s Revenge Review By Jennifer Allen on September 2nd, 2014 Our Rating: :: CASUAL RAIDINGUniversal App - Designed for iPhone and iPad Combining simple combat with village building is a potent combination for... | Read more »
Treasure Tombs: Ra Deal Coming from Bulk...
Treasure Tombs: Ra Deal Coming from Bulkypix and Dark Tonic This Fall Posted by Jessica Fisher on September 2nd, 2014 [ permalink ] Dark Tonic and | Read more »
Pirate Bash Review
Pirate Bash Review By Nadia Oxford on September 2nd, 2014 Our Rating: :: BAD PIRATES, GOOD TIMESUniversal App - Designed for iPhone and iPad Pirate Bash’s turn-based battles add an intriguing twist to a typical physics game.   | Read more »
Tiny Tower Vegas Review
Tiny Tower Vegas Review By Jennifer Allen on September 2nd, 2014 Our Rating: :: STEADY DEVELOPMENTUniversal App - Designed for iPhone and iPad Build a huge tower again but Vegas-style in Tiny Tower Vegas.   | Read more »
The Manhattan Project Review
The Manhattan Project Review By Andrew Fisher on September 2nd, 2014 Our Rating: :: ROCKET SCIENCEUniversal App - Designed for iPhone and iPad The Manhattan Project offers a great Euro-style gameplay experience, but it is totally... | Read more »

Price Scanner via MacPrices.net

Apple refurbished iPads available for up to $...
Apple is offering Certified Refurbished iPad Airs for up to $140 off MSRP. Apple’s one-year warranty is included with each model, and shipping is free. Stock tends to come and go with some of these... Read more
Are We Now In The Post-Post-PC Era?
A longtime and thoroughgoing laptop aficionado, I was more than a little dismayed by Steve Jobs’s declaration back in 2010 when he sprang the iPad on an unsuspecting world. that we’d entered a “post-... Read more
PC Outlook Improves, But 2014 Shipments Still...
According to the International Data Corporation (IDC) Worldwide Quarterly PC Tracker, worldwide PC shipments are expected to fall by -3.7 percent in 2014. To hat’s actually an improvement from the... Read more
IDC Lowers Tablet Sales Projections for 2014...
Following a second consecutive quarter of softer than expected demand, International Data Corporation (IDC) has lowered its worldwide tablet plus 2-in-1 forecast for 2014 to 233.1 million units. The... Read more
Apple now offering refurbished 21-inch 1.4GHz...
The Apple Store is now offering Apple Certified Refurbished 21″ 1.4GHz iMacs for $929 including free shipping plus Apple’s standard one-year warranty. Their price is $170 off the cost of new models,... Read more
Save $50 on the 2.5GHz Mac mini, on sale for...
B&H Photo has the 2.5GHz Mac mini on sale for $549.99 including free shipping. That’s $50 off MSRP, and B&H will also include a free copy of Parallels Desktop software. NY sales tax only. Read more
Save up to $300 on an iMac with Apple refurbi...
The Apple Store has Apple Certified Refurbished iMacs available for up to $300 off the cost of new models. Apple’s one-year warranty is standard, and shipping is free. These are the best prices on... Read more
The Rise of Phablets
Carlisle & Gallagher Consulting Group, a businesses and technology consulting firm focused solely on the financial services industry, has released an infographic depicting the convergence of... Read more
Bad Driver Database App Allows Good Drivers t...
Bad Driver Database 1.4 by Facile Group is a new iOS and Android app that lets users instantly input and see how many times a careless, reckless or just plain stupid driver has been added to the... Read more
Eddy – Cloud Music Player for iPhone/iPad Fre...
Ukraine based CapableBits announces the release of Eddy, its tiny, but smart and powerful cloud music player for iPhone and iPad that allows users to stream or download music directly from cloud... Read more

Jobs Board

*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
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
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.