Next Previous

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.

**Table 3-1** Carbon replacements for functions in the old Printing Manager
Classic function	Carbon Printing Manager function
`PrOpen`	`PMCreateSession`
`PrClose`	`PMRelease`
`PrOpenDoc`	`PMSessionBeginDocument`
`PrCloseDoc`	`PMSessionEndDocument`
`PrOpenPage`	`PMSessionBeginPage`
`PrClosePage`	`PMSessionEndPage`
`PrintDefault`	`PMSessionDefaultPrintSettings`
	`PMSessionDefaultPageFormat`
`PrValidate`	`PMSessionValidatePrintSettings`
	`PMSessionValidatePageFormat`
`PrJobInit`	`PMSessionPrintDialogInit`
`PrJobDialog`	`PMSessionPrintDialog`
`PrStlInit`	`PMSessionPageSetupDialogInit`
`PrStlDialog`	`PMSessionPageSetupDialog`
`PrDlgMain`	`PMSessionPrintDialogMain`
	`PMSessionPageSetupDialogMain`
`PrGeneral`	`PMSessionGeneral` Specific accessors replace common calls, see the Carbon Manager Reference documentation.
`PrSetError`	`PMSessionSetError`
`PrError`	`PMSessionError`
`MyDoPrintIdle`	`PMIdleProcPtr`
`MyPrDialogAppend`	`PMPageSetupDialogInitProcPtr`
	`PMPrintDialogInitProcPtr`

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.

**Table 3-2** Old Printing Manager functions that are not supported in Carbon
`PrPicFile`
`PrPurge`
`PrNoPurge`
`PrLoadDriver`
`PrDrvrDCE`
`PrDrvrOpen`
`PrDrvrClose`
`PrDrvrVers`
`PrCtlCall`
`PrJobMerge`

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.

**Table 3-3** Carbon accessor functions for the old Print Manager print record (TPrint) fields
Data structure	Element	Accessor function
`TPrint`	`iPrVersion`	Not supported (Use `PMPrinterGetDriverReleaseInfo` to obtain a driver’s version strings. The version strings are not normally needed.)
	`prInfo`	See `TPrInfo`
	`rPaper`	`PMGetAdjustedPaperRect`
	`prStl`	See `TPrStl`
	`prInfoPT`	Not supported
	`prXInfo`	not supported
	`prJob`	See `TPrJob`
	`printX[19]`	Not supported

`TPrInfo`	`iDev`	Not supported
	`iVRes`	`PMGetResolution`
	`iHRes`	`PMGetResolution`
	`rPage`	`PMGetAdjustedPageRect`

`TPrStl`	`wDev`	`PMGetOrientation`
	`iPageV`	`PMGetUnadjustedPaperRect`
	`iPageH`	`PMGetUnadjustedPaperRect`
	`bPort`	Not supported
	`feed`	Not supported

`TPrJob`	`iFstPage`	`PMGetFirstPage`
	`iLstPage`	`PMGetLastPage`
	`iCopies`	`PMGetCopies`
	`bJDocLoop`	Not supported
	`fFromUsr`	Not supported
	`pIdleProc`	`PMSessionSetIdleProc` This does nothing in Mac OS X; only used for Mac OS 8 and 9.
	`pFileName`	Not supported
	`iFileVol`	Not supported
	`bFileVers`	Not supported
	`bJobX`	Not supported

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.

**Table 3-4** Carbon support for PrGeneral opcodes
Opcode	Value	Accessor function
`GetRslDataOp`	4	`PMPrinterGetIndexedPrinterResolution`
`SetRslOp`	5	`PMSetResolution`
`DraftBitsOp`	6	`PMSessionGeneral` supports this opcode in Mac OS 8/9
`NoDraftBitsOp`	7	`PMSessionGeneral` supports this opcode in Mac OS 8/9
`getRotnOp`	8	`PMGetOrientation`
`NoGrayScl`	9	`PMSessionGeneral` supports this opcode in Mac OS 8/9
`GetPSInfoOp`	10	`PMSessionGeneral` supports this opcode in Mac OS 8/9; `PMPrinterGetLanguageInfo` supported in Mac OS 8/9 and Mac OS X
`PSIntentionsOp`	11	`PMSessionGeneral` supports this opcode in Mac OS 8/9
`EnableColorMatchingOp`	12	`PMSessionGeneral` supports this opcode in Mac OS 8/9
`PSAdobeOp`	14	`PMSessionGeneral` supports this opcode in Mac OS 8/9
`PSPrimaryPPDOp`	15	`PMPrinterGetDescriptionURL`
`kLoadCommProcsOp`	16	`PMSessionGeneral` supports this opcode in Mac OS 8/9
`kUnloadCommProcsOp`	17	`PMSessionGeneral` supports this opcode in Mac OS 8/9
`kPrinterDirectOpCode`	20	`PMSessionGeneral` supports this opcode in Mac OS 8/9
`kPrVersionOp`	22	`PMPrinterGetDriverCreator`
`kGetPrinterInfo`	23	`PMSessionGeneral` supports this opcode in Mac OS 8/9
`kIsSamePrinterInfo`	24	`PMSessionGeneral` supports this opcode in Mac OS 8/9
`kSetDefaultPrinterInfo`	25	`PMSessionGeneral` supports this opcode in Mac OS 8/9
`kPrEnablePartialFonts`	26	`PMSessionGeneral` supports this opcode in Mac OS 8/9

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.

**Table 3-5** Picture comments supported by the Carbon Printing Manager
Name	Value	Data size	Data handle	Description
Text picture comments
`TextBegin`	150	6	`TTxtPicRec`	Begin text function
`TextEnd`	151	0	NULL	End text function
`StringBegin`	152	0	NULL	Begin string delimitation
`StringEnd`	153	0	NULL	End string delimitation
`TextCenter`	154	8	`TCenterRec`	Offset to center of rotation for text
`LineLayoutOff`	155	0	NULL	Turn printer driver’s line layout off
`LineLayoutOn`	156	0	NULL	Turn printer driver’s line layout on
`ClientLineLayout`	157	16	`TClientLLRec`	Customize line layout error distribution; not supported in Mac OS X

Graphics picture comments
`PolyBegin`	160	0	NULL	Begin special polygon
`PolyEnd`	161	0	NULL	End special polygon
`PolyIgnore`	163	0	NULL	Ignore following polygon data
`PolySmooth`	164	1	`TPolyVerbRec`	Mark that the polygon should be smoothed and indicate whether to frame, fill, and/or close
`PolyClose`	165	0	NULL	Mark the polygon as closed
`RotateBegin`	200	8	`TRotationRec`	Begin rotated port
`RotateEnd`	201	0	`NULL`	End rotation
`RotateCenter`	202	8	`TCenterRec`	Offset to center of rotation

Line-drawing picture comments
`DashedLine`	180	Size of a `TDashedLineRec` record	`TDashedLineRec`	Draw following line as dashed
`DashedStop`	181	0	`NULL`	End dashed lines
`SetLineWidth`	182	4	`TLineWidthHdl`	Set fractional line widths

PostScript picture comments are provided only for LaserWriter 8 compatibility.
`PostScriptBegin`	190	0	`NULL`	Set driver state to PostScript
`PostScriptEnd`	191	0	`NULL`	Restore QuickDraw state
`PostScriptHandle`	192	Size of the PostScript data in handle	a handle	PostScript data referenced by handle
`PostScriptFile`	193	Size of the PostScript data in handle	a handle	Filename referenced by handle
`TextIsPostScript`	194	0	`NULL`	If compatible with LaserWriter8, QuickDraw text is sent as PostScript
`PSBeginNoSave`	196	0	`NULL`	Set driver state to PostScript

ColorSync picture comments
`cmBeginProfile`	220	variable	version 1 profile data	Begin ColorSync profile; not supported in Mac OS X
`cmEndProfile`	221	0	`NULL`	End ColorSync profile; not supported in Mac OS X
`cmEnableMatching`	222	0	`NULL`	Begin ColorSync color matching
`cmDisableMatching`	223	0	`NULL`	End ColorSync color matching
`cmComment`	224	variable	a handle	Contents are a selector with data following

Next Previous