For any printing session, an application will need to:

The data types for printing session, page setup, and print settings objects are described in detail in Section 9.1.3 and Carbon Printing Manager functions are described in more detail in Section 9.1.4.

As you work through this sample printing session, you’ll see a number of data objects and functions. Functions that start with PM are Carbon Printing Manager functions; those that start with App must be defined by your application. Later sections will provide additional information about the Carbon Printing Manager functions and data types mentioned here. To see a full implementation of a printing session for a working application, see Section 9.2.

Suppose a user opens a text document in the application. Your application would perform steps similar to the following:

The next section takes a more detailed look at the print loop function and the Carbon Printing Manager functions it typically calls.

AppPagesInDoc (application function to verify legal page range)
PMGetFirstPage (get the selected page range, first to last)
PMGetLastPage (adjust if selected range outside legal range)
(now know how many pages to print in the print loop)
PMSetFirstPage (set page range that will show up in progress dialog)
PMSetLastPage
PMSessionBeginDocument (begin a new print job)
    (for each page to be printed)
    PMSessionError (check for an error before starting a new page;
                    if error, break out of loop)
    PMSessionBeginPage (prepare to print the current page)
        PMSessionGetGraphicsContext (get printing port)
        SetPort (Carbon function to set current drawing port 
                    to printing port)
        AppDrawPage (application function to draw one page)
        SetPort (Carbon function to restore saved port)
    PMSessionEndPage (finish printing current page)
PMSessionEndDocument (end the print job)
AppPostPrintingErrors (application function to display any error to user)
PMRelease (release print settings and printing session objects)

The application code that prints a range of pages is called a print loop because it loops to print each page in the range. The Carbon Printing Manager enforces a sequence of steps in a print loop and defines a valid scope for each printing function. This means that your application must call certain functions before calling others. Functions used out of sequence generate an error value of kPMOutOfScope. The rules for calling sequence and scope are different for session and nonsession printing functions. This section provides a brief overview of the requirements for session printing. For additional details, see the Carbon Printing Manager documentation in Carbon Help (available in the Project Builder Help menu).

The following list of functions shows the calling sequence and scope requirements for some of the most commonly used session functions:

PMCreateSession
    PMSessionDefaultPageFormat
    PMSessionValidatePageFormat
    PMSessionDefaultPrintSettings
    PMSessionValidatePrintSettings
    PMSessionUseSheets
    PMSessionPageSetupDialog
    PMSessionPrintDialog
    PMSessionBeginDocument
        PMSessionBeginPage
            PMSessionGetGraphicsContext
        PMSessionEndPage
    PMSessionEndDocument
PMRelease

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

Naturally “begin” functions (such as PMSessionBeginPage) must be called before their corresponding “end” functions (PMSessionEndPage). And some calls make sense only in a certain order within a given scope. For example, if you are using sheets, as the code in this chapter does, you must call PMSessionUseSheets before calling the PMSessionPageSetupDialog or PMSessionPrintDialog function to display a dialog as a sheet.

The following list shows some of the universal printing functions, which can be called at any time:

PMCreatePageFormat
PMCreatePrintSettings
PMFlattenPageFormat
PMUnflattenPageFormat
PMGetPageFormatExtendedData
PMSetPageFormatExtendedData
PMGetAdjustedPaperRect
PMGetAdjustedPageRect
PMGetOrientation
PMSetOrientation
PMFlattenPrintSettings
PMUnflattenPrintSettings
PMGetPageRange
PMSetPageRange

Although these functions are designed to be called at any time, it is currently required that you call PMSessionValidatePageFormat before calling PMGetAdjustedPaperRect or PMGetAdjustedPageRect.

Many of these functions are used in the sample code in this chapter. Two functions that are not used, but that may be of interest, are PMFlattenPageFormat and PMUnflattenPageFormat. You can use these functions to save and restore information from the opaque PMPageFormat data structure, which stores information displayed in the Page Setup dialog (shown in Figure 9.1). You use PMFlattenPageFormat, for example, to flatten a page format object before writing it to a handle, document, or other location, and PMUnflattenPageFormat to recreate a PMPageFormat object after reading flattened data.

Because you can use the PMSetPageFormatExtendedData function to store application data with a page format object and the PMGetPageFormatExtendedData function to retrieve the data, the PMFlattenPageFormat and PMUnflattenPageFormat functions provide a convenient way to save and restore additional application-specific data along with the standard page format data.

The functions PMFlattenPrintSettings and PMUnflattenPrintSettings perform a similar duty for saving and restoring information from the opaque PMPrintSettings data structure, which stores information displayed in the Print dialog (shown in Figure 9.2). However, most applications will not need to save settings information. An application can extend a print settings object with the PMSetPrintSettingsExtendedData and PMGetPrintSettingsExtendedData functions.

An application can extend an instance of the PMPrintSession data type with the PMSessionSetDataInSession and PMSessionGetDataFromSession functions, but the Carbon Printing Manager does not supply functions to flatten and unflatten an instance of this type. Therefore, you can use the extended data structure only within the lifetime of the printing session object (before releasing it).

Don’t look for direct access to global data structures in the Carbon Printing Manager—that’s so 20th century. Instead, the Carbon Printing Manager relies primarily on the opaque data structures shown in Table 9.1. The table also shows the functions you use to create these data types and, for those that can be extended to store application-specific data, the functions for extending them. Each of the creation functions returns a reference to an instance of the specified data type.

Previous sections provided examples of how to use these data types. The next section provides information on functions that work with these types.

Because the primary printing data types for printing sessions are opaque, you cannot directly access any of their internal data. Instead, the Carbon Printing Manager defines accessor functions for manipulating the data in these structures. Table 9.2 shows some of the accessors and other functions available to work with an instance of the opaque data type PMPrintSession.

The Carbon Printing Manager doesn’t supply functions for saving an instance of a printing session because it’s not recommended that you save one. An application typically creates an instance of a printing session as needed (such as before displaying the Page Setup or Print dialog) and releases it when it is no longer needed (as when the print loop has completed).

Table 9.3 shows some of the accessors and other functions available to work with an instance of the opaque data type PMPageFormat, which is used to store information displayed in the Page Setup dialog. Applications typically store page format information with documents and also maintain it between printing sessions, because users expect changes made in the Page Setup dialog to persist with the document. The table describes functions for creating an instance of this data type, setting it to default values, validating it for the current printing session, extracting information from it, and so on.

Table 9.4 shows some of the accessors available to work with an instance of the opaque data type PMPrintSettings, which is used to store information displayed in the Print dialog. Applications don’t typically store print settings information, because users expect the Print dialog to show current default values. The table describes functions for creating an instance of this data type, setting it to default values, validating it for the current printing session, extracting information from it, and so on.

This section should have provided a good description of the basic concepts you’ll use to print with the Carbon Printing Manager. If you’re working on an application with complex printing needs, see the following: