Retired Document
Important: This document may not represent best practices for current development. Links to downloads and other resources may no longer be valid.
Adopting the Carbon Printing Manager
This chapter provides information that will help you convert printing code that uses the old Printing Manager so that your code uses the Carbon Printing Manager. The Carbon Printing Manager was designed to let Carbon applications take advantage of new features in Mac OS X, while still working correctly in previous versions of the Mac OS.
If you want to port an application that runs in Mac OS 9 and earlier versions of the Mac OS to one that runs in Mac OS X, you should read Inside Carbon: Carbon Porting Guide. The guide covers all porting topics, except for porting printing code, which is covered in this chapter.
Updating your application to use the Carbon Printing Manager is a straightforward process. These are the basic steps:
Remove all references to the
Printing.h
header file from your project.If you are building your application so that is runs only in Mac OS X, make sure you link against the Application Services and Carbon frameworks. If you are building your application so that it can run in Mac OS 9 as well as in Mac OS X, you also need to add the
CarbonLib
library to your project.Convert your code to use the new printing functions and opaque data types, as described in the following sections.
New and Changed Printing Functions
Because the Carbon Printing Manager replaces all of the functions in the old Printing Manager, the first step in converting your code is to locate and replace your old Printing Manager function calls with their equivalents from the Carbon Printing Manager. In most cases there is a one-to-one mapping between the new functions and the original functions they replace. Table 4-1 lists the Carbon equivalents for old Printing Manager functions.
Some of the functionality provided by the old Printing Manager is no longer supported. Table 4-2 lists the old functions that are not supported by the Carbon Printing Manager.
The PrPicFile
function was removed because the “deferred” printing style is no longer supported. All print records must use “draft” style, and printer drivers must perform their own despooling or, in Mac OS 8 and 9, use the Desktop Printer Spooler. Refer to the old Printing Manager documentation for information about draft and deferred printing styles. The Desktop Printer Spooler is described in Tech Note 1097.
A direct replacement for the PrJobMerge
function is unnecessary because the PMPageFormat
and PMPrintSettings
objects can be used independently. You can print multiple documents, each with their own saved page format, using a single PMPrintSettings
object.
New Data Types and Accessor Functions
The Carbon Printing Manager replaces the old Print Manager print record (TPrint
) with two opaque data types, the PMPrintSettings
object and the PMPageFormat
object. All references to elements of the TPrint
record in your code must be updated to refer to one of these objects, using the new accessor functions provided.
Because the PMPrintSettings
and PMPageFormat
objects are opaque, your application must not make assumptions about their size or internal structure. You will need to update any code that loads, stores, or directly manipulates the TPrint
record.
Table 4-3 lists the accessor functions you can use to examine elements of the PMPrintSettings
and PMPageFormat
objects.
When you use these accessor functions, be sure to pass the appropriate constant for any parameters you do not want to pass to the function or receive from it. For example, pass the kPMDontWantData
constant in place of a parameter that returns data you’re not interested in.
Your application must dispose of any structures, references, or other data returned by Carbon Printing Manager functions. Your application should also release the PMPrintSettings
and PMPageFormat
objects it creates when they are no longer needed.
Supported PrGeneral Opcodes
The Carbon Printing Manager provides the PMSessionGeneral
function as a replacement for the old Printing Manager function PrGeneral
. However, Apple suggests that you reduce your reliance on these functions because they are not currently supported by all printer drivers, and because they are not likely to be supported in future versions of the Mac OS.
Table 4-4 lists PrGeneral
opcodes that are supported in Carbon in Mac OS 8 and 9, but not in Mac OS X. For opcodes that have an associated accessor function, you use that function instead of passing the opcode to PMSessionGeneral
. For example, use PMGetOrientation
instead of passing the getRotnOp
constant to PMSessionGeneral
. The PMSessionGeneral
function returns the result code kPMNotImplemented
for any unsupported opcodes, and for opcodes that have Carbon accessor functions.
Supported Picture Comments
Table 4-5 lists picture comments supported by the Carbon Printing Manager. Except where noted, these have the same behavior in Mac OS X as they do with LaserWriter 8 in Mac OS 8 and 9. Note that by default PostScript picture comments are ignored in Mac OS X; they are supported only when printing with LaserWriter 8 compatibility mode.
Copyright © 2001, 2004 Apple Computer, Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2004-08-31