ADC Home > Reference Library > Reference > Carbon > Printing > Carbon Printing Reference >

< Previous PageNext Page > Hide TOC

Deprecated Carbon Printing Functions

A function identified as deprecated has been superseded and may become unsupported in the future.

Deprecated in Mac OS X v10.4

DisposePMItemUPP

Disposes of a universal procedure pointer (UPP) to a dialog item event handling callback. (Deprecated in Mac OS X v10.4. Use a printing dialog extension instead.)

void DisposePMItemUPP (
   PMItemUPP userUPP
);

Parameters
userUPP

The universal procedure pointer.

Discussion

See the PMItemProcPtr callback function.

Availability
Declared In
PMApplicationDeprecated.h

DisposePMPageSetupDialogInitUPP

Disposes of a universal procedure pointer (UPP) to a Page Setup dialog initialization callback. (Deprecated in Mac OS X v10.4. Use a printing dialog extension instead.)

void DisposePMPageSetupDialogInitUPP (
   PMPageSetupDialogInitUPP userUPP
);

Parameters
userUPP

The universal procedure pointer.

Discussion

See the PMPageSetupDialogInitProcPtr callback function.

Availability
Declared In
PMApplicationDeprecated.h

DisposePMPrintDialogInitUPP

Disposes of a universal procedure pointer (UPP) to a Print dialog initialization callback function. (Deprecated in Mac OS X v10.4. Use a printing dialog extension instead.)

void DisposePMPrintDialogInitUPP (
   PMPrintDialogInitUPP userUPP
);

Parameters
userUPP

The universal procedure pointer.

Discussion

See the PMPrintDialogInitProcPtr callback function.

Availability
Declared In
PMApplicationDeprecated.h

InvokePMItemUPP

Calls a dialog item event handling callback. (Deprecated in Mac OS X v10.4. Use a printing dialog extension instead.)

void InvokePMItemUPP (
   DialogRef theDialog,
   short item,
   PMItemUPP userUPP
);

Discussion

You should not need to use the function InvokePMInvokeUPP, as the printing system calls your item event handling callback function for you. See the PMItemProcPtr callback function.

Availability
Declared In
PMApplicationDeprecated.h

InvokePMPageSetupDialogInitUPP

Calls a Page Setup dialog initialization callback. (Deprecated in Mac OS X v10.4. Use a printing dialog extension instead.)

void InvokePMPageSetupDialogInitUPP (
   PMPageFormat pageFormat,
   PMDialog *theDialog,
   PMPageSetupDialogInitUPP userUPP
);

Discussion

You should not need to use the function InvokePMPageSetupDialogInitUPP, as the printing system calls your Page Setup dialog initialization callback function for you. See the PMPageSetupDialogInitProcPtr callback function.

Availability
Declared In
PMApplicationDeprecated.h

InvokePMPrintDialogInitUPP

Calls a Print dialog initialization callback. (Deprecated in Mac OS X v10.4. Use a printing dialog extension instead.)

void InvokePMPrintDialogInitUPP (
   PMPrintSettings printSettings,
   PMDialog *theDialog,
   PMPrintDialogInitUPP userUPP
);

Discussion

You should not need to use the function InvokePMPrintDialogInitUPP, as the printing system calls your Print dialog initialization callback function for you. See the PMPrintDialogInitProcPtr callback function.

Availability
Declared In
PMApplicationDeprecated.h

NewPMItemUPP

Creates a new universal procedure pointer (UPP) to a dialog item event handling callback. (Deprecated in Mac OS X v10.4. Use a printing dialog extension instead.)

PMItemUPP NewPMItemUPP (
   PMItemProcPtr userRoutine
);

Parameters
userRoutine

A pointer to your dialog item event handling callback.

Return Value

On return, a UPP to the dialog item event handling callback.

Discussion

See the PMItemProcPtr callback function.

Availability
Declared In
PMApplicationDeprecated.h

NewPMPageSetupDialogInitUPP

Creates a new universal procedure pointer (UPP) to a Page Setup dialog initialization callback. (Deprecated in Mac OS X v10.4. Use a printing dialog extension instead.)

PMPageSetupDialogInitUPP NewPMPageSetupDialogInitUPP (
   PMPageSetupDialogInitProcPtr userRoutine
);

Parameters
userRoutine

A pointer to your Page Setup dialog initialization callback.

Return Value

On return, a UPP to the Page Setup dialog initialization callback.

Discussion

See the PMPageSetupDialogInitProcPtr callback function.

Availability
Declared In
PMApplicationDeprecated.h

NewPMPrintDialogInitUPP

Creates a new universal procedure pointer (UPP) to a Print dialog initialization callback. (Deprecated in Mac OS X v10.4. Use a printing dialog extension instead.)

PMPrintDialogInitUPP NewPMPrintDialogInitUPP (
   PMPrintDialogInitProcPtr userRoutine
);

Parameters
userRoutine

A pointer to your Print dialog initialization callback.

Return Value

On return, a UPP to the Print dialog initialization callback.

Discussion

See the PMPrintDialogInitProcPtr callback function.

Availability
Declared In
PMApplicationDeprecated.h

PMBeginDocument

Establishes a graphics context for imaging a document. This context is an opaque grafPort. (Deprecated in Mac OS X v10.4. Use PMSessionBeginCGDocument instead.)

OSStatus PMBeginDocument (
   PMPrintSettings printSettings,
   PMPageFormat pageFormat,
   PMPrintContext *printContext
);

Parameters
printSettings

A PMPrintSettings object.

pageFormat

A PMPageFormat object.

printContext

On return, an initialized PMPrintContext object.

Return Value

A result code. See Core Printing Result Codes.

Discussion

Valid within a PMBegin/PMEnd block. You must balance a call to PMBeginDocument with a call to PMEndDocument.

Availability
Declared In
PMApplicationDeprecated.h

PMBeginPage

Initializes a scaling rectangle for printing a page. (Deprecated in Mac OS X v10.4. Use PMSessionBeginPage instead.)

OSStatus PMBeginPage (
   PMPrintContext printContext,
   const PMRect *pageFrame
);

Parameters
printContext

A PMPrintContext object.

pageFrame

A pointer to a bounding rectangle for drawing the page. This value is usually obtained from the function PMGetAdjustedRect, but if no scaling is needed, pass NULL. In Mac OS X, this parameter is ignored.

Return Value

A result code. See Core Printing Result Codes.

Discussion

Valid after calling PMBegin and PMBeginDocument.

Availability
Declared In
PMApplicationDeprecated.h

PMEndDocument

Closes the context created for imaging a document. (Deprecated in Mac OS X v10.4. Use PMSessionEndDocument instead.)

OSStatus PMEndDocument (
   PMPrintContext printContext
);

Parameters
printContext

On return, an invalidated PMPrintContext object.

Return Value

A result code. See Core Printing Result Codes.

Discussion

Valid after calling PMBegin and PMBeginDocument.

Availability
Declared In
PMApplicationDeprecated.h

PMEndPage

Finishes printing the current page. (Deprecated in Mac OS X v10.4. Use PMSessionEndPage instead.)

OSStatus PMEndPage (
   PMPrintContext printContext
);

Parameters
printContext

A PMPrintContext object.

Return Value

A result code. See Core Printing Result Codes.

Discussion

Valid after calling PMBegin, PMBeginDocument, and PMBeginPage.

Availability
Declared In
PMApplicationDeprecated.h

PMGetDialogAccepted

Determines whether the user has confirmed a printing dialog. (Deprecated in Mac OS X v10.4. Use a printing dialog extension instead.)

OSStatus PMGetDialogAccepted (
   PMDialog pmDialog,
   Boolean *process
);

Parameters
pmDialog

A PMDialog object representing your customized Page Setup or Print dialog.

process

Returns true if the user confirms the dialog. In the case of the Page Setup dialog, this means the user clicked the OK button; in the case of the Print dialog, this means the user clicked the Print or Preview button. Returns false if the user clicks the Cancel button.

Return Value

A result code. See Core Printing Result Codes.

Discussion

The function PMGetDialogAccepted is valid between the creation and release of a printing session and while displaying your custom Page Setup or Print dialog.

Availability
Declared In
PMApplicationDeprecated.h

PMGetDialogDone

Determines whether the user has finished with a dialog. (Deprecated in Mac OS X v10.4. Use a printing dialog extension instead.)

OSStatus PMGetDialogDone (
   PMDialog pmDialog,
   Boolean *done
);

Parameters
pmDialog

A PMDialog object representing your customized Page Setup or Print dialog.

done

Returns true if the user clicked the OK, Print, or Cancel button; false if the user did not click any of these buttons.

Return Value

A result code. See Core Printing Result Codes.

Discussion

The function PMGetDialogDone is valid between the creation and release of a printing session and while displaying your Page Setup or Print dialog.

Availability
Declared In
PMApplicationDeprecated.h

PMGetDialogPtr

Obtains the dialog reference for a dialog. (Deprecated in Mac OS X v10.4. Use a printing dialog extension instead.)

OSStatus PMGetDialogPtr (
   PMDialog pmDialog,
   DialogRef *theDialog
);

Parameters
pmDialog

The PMDialog object from which you wish to extract the DialogRecord structure.

theDialog

On return, a pointer to a Dialog Manager DialogRef object.

Return Value

A result code. See Core Printing Result Codes.

Discussion

The function PMGetDialogPtr is valid between the creation and release of a printing session and after calling PMSessionPageSetupDialogInit to initialize a Page Setup dialog, or calling PMSessionPrintDialogInit to initialize a Print dialog.

Availability
Declared In
PMApplicationDeprecated.h

PMGetItemProc

Obtains the item proc callback function for a custom dialog. (Deprecated in Mac OS X v10.4. Use a printing dialog extension instead.)

OSStatus PMGetItemProc (
   PMDialog pmDialog,
   PMItemUPP *itemProc
);

Parameters
pmDialog

A PMDialog object representing the Page Setup or Print dialog for which you want to obtain the item proc function.

itemProc

On return, a pointer to the current dialog item proc function.

Return Value

A result code. See Core Printing Result Codes.

Discussion

The function PMGetItemProc is valid only between the creation and release of a printing session. You can call PMGetItemProc to get the existing item proc function before you replace it with a call to the function PMSetItemProc. You should call this function only if you need to handle events in a custom dialog you create using the AppendDITL method. In Mac OS X, you should create a custom dialog by writing a printing dialog extension. If you use this function to extend a printing dialog in Mac OS X, you cannot use sheets.

Availability
Declared In
PMApplicationDeprecated.h

PMGetModalFilterProc

Obtains the event handling callback function for a modal dialog. (Deprecated in Mac OS X v10.4. Use a printing dialog extension instead.)

OSStatus PMGetModalFilterProc (
   PMDialog pmDialog,
   ModalFilterUPP *filterProc
);

Parameters
pmDialog

A PMDialog object representing the Page Setup or Print dialog for which you want to obtain the event handling function.

filterProc

On return, a pointer to the current dialog event handling function.

Return Value

A result code. See Core Printing Result Codes.

Discussion

The function PMGetModalFilterProc is valid only between the creation and release of a printing session. You can call PMGetModalFilterProc to get the existing event handling function before you replace it with a call to the function PMSetModalFilterProc. The event handling function is not called in Mac OS X.

You should call the function PMGetModalFilterProc only if you create a custom dialog using the AppendDITL method. In Mac OS X, you should create a custom dialog by writing a printing dialog extension. If you use this function to extend a printing dialog in Mac OS X, you cannot use sheets.

Availability
Declared In
PMApplicationDeprecated.h

PMPageSetupDialog

Displays the Page Setup dialog and records the user’s selections in a PMPageFormat object. (Deprecated in Mac OS X v10.4. Use PMSessionPageSetupDialog or PMShowPageSetupDialogAsSheet instead.)

OSStatus PMPageSetupDialog (
   PMPageFormat pageFormat,
   Boolean *accepted
);

Parameters
pageFormat

A PMPageFormat object.

accepted

Returns true if the user clicks the OK button, or false if the user clicks Cancel.

Return Value

A result code. See Core Printing Result Codes.

Discussion

Valid after calling PMBegin and creating a page format object. Never call PMPageSetupDialog between the pages of a document.

Availability
Declared In
PMApplicationDeprecated.h

PMPageSetupDialogInit

Initializes a custom Page Setup dialog. (Deprecated in Mac OS X v10.4. Use a printing dialog extension instead.)

OSStatus PMPageSetupDialogInit (
   PMPageFormat pageFormat,
   PMDialog *newDIalog
);

Parameters
pageFormat

A PMPageFormat object.

newDIalog

On return, a pointer to an initialized PMDialog object, ready for customization by your application. Because the PMPageSetupDialogMain function does not include a parameter for passing this PMDialog object to your dialog initialization callback function, your application should store this pointer in a global variable or as extended data in the PMPageFormat object. See the discussion of the PMPageSetupDialogInitProcPtr callback function for more information.

Return Value

A result code. See Core Printing Result Codes.

Discussion

Valid after calling PMBegin and creating a page format object.

Availability
Declared In
PMApplicationDeprecated.h

PMPageSetupDialogMain

Displays your application’s customized Page Setup dialog. (Deprecated in Mac OS X v10.4. Use a printing dialog extension instead.)

OSStatus PMPageSetupDialogMain (
   PMPageFormat pageFormat,
   Boolean *accepted,
   PMPageSetupDialogInitUPP myInitProc
);

Parameters
pageFormat

A PMPageFormat object.

accepted

Returns true if the user clicks the OK button, or false if the user clicks Cancel.

myInitProc

A universal procedure pointer to your dialog initialization function. Your initialization function is defined by the callback PMPageSetupDialogInitProcPtr.

Return Value

A result code. See Core Printing Result Codes.

Discussion

Valid after calling PMBegin and creating a page format object

Availability
Declared In
PMApplicationDeprecated.h

PMPrintDialog

Displays the Print dialog and records the user’s selections in a PMPrintSettings object. (Deprecated in Mac OS X v10.4. Use PMSessionPrintDialog, PMShowPrintDialogWithOptions, or PMShowPrintDialogWithOptionsAsSheet instead.)

OSStatus PMPrintDialog (
   PMPrintSettings printSettings,
   PMPageFormat constPageFormat,
   Boolean *accepted
);

Parameters
printSettings

A PMPrintSettings object.

constPageFormat

A PMPageFormat object.

accepted

Returns true if the user clicks the OK button, or false if the user clicks Cancel.

Return Value

A result code. See Core Printing Result Codes.

Discussion

Valid after calling PMBegin and creating a page format and print settings object.

Availability
Declared In
PMApplicationDeprecated.h

PMPrintDialogInit

Initializes a custom Print dialog. (Deprecated in Mac OS X v10.4. Use a printing dialog extension instead.)

OSStatus PMPrintDialogInit (
   PMPrintSettings printSettings,
   PMDialog *newDialog
);

Parameters
printSettings

A PMPrintSettings object.

newDialog

On return, a pointer to an initialized PMDialog object, ready for customization by your application. Because the PMPrintDialogMain function does not include a parameter for passing this PMDialog object to your dialog initialization callback function, your application should store this pointer in a global variable or as extended data in the PMPrintSettings object. See the discussion of the PMPrintDialogInitProcPtr callback function for more information.

Return Value

A result code. See Core Printing Result Codes.

Discussion

Valid after calling PMBegin and creating a page format and print settings object.

Availability
Declared In
PMApplicationDeprecated.h

PMPrintDialogInitWithPageFormat

Initializes a custom Print dialog. (Deprecated in Mac OS X v10.4. Use a printing dialog extension instead.)

OSStatus PMPrintDialogInitWithPageFormat (
   PMPrintSettings printSettings,
   PMPageFormat constPageFormat,
   PMDialog *newDialog
);

Parameters
printSettings

A PMPrintSettings object.

constPageFormat

A PMPageFormat object.

newDialog

On return, a pointer to an initialized PMDialog object, ready for customization by your application. Because the PMPrintDialogMain function does not include a parameter for passing this PMDialog object to your dialog initialization callback function, your application should store this pointer in a global variable or as extended data in the PMPrintSettings object. See the discussion of the PMPrintDialogInitProcPtr callback function for more information.

Return Value

A result code. See Core Printing Result Codes.

Discussion

Valid after calling PMBegin and creating a page format and print settings object.

Availability
Declared In
PMApplicationDeprecated.h

PMPrintDialogMain

Displays your application’s custom Print dialog. (Deprecated in Mac OS X v10.4. Use a printing dialog extension instead.)

OSStatus PMPrintDialogMain (
   PMPrintSettings printSettings,
   PMPageFormat constPageFormat,
   Boolean *accepted,
   PMPrintDialogInitUPP myInitProc
);

Parameters
printSettings

A PMPrintSettings object.

constPageFormat

A PMPageFormat object.

accepted

Returns true if the user clicks the OK button, or false if the user clicks Cancel.

myInitProc

A universal procedure pointer to your dialog initialization function. Your initialization function is defined by the callback PMPrintDialogIinitProcPtr.

Return Value

A result code. See Core Printing Result Codes.

Discussion

Valid after calling PMBegin and creating a page format and print settings object.

Availability
Declared In
PMApplicationDeprecated.h

PMSessionPageSetupDialogInit

Initializes a custom Page Setup dialog. (Deprecated in Mac OS X v10.4. Use a printing dialog extension instead.)

OSStatus PMSessionPageSetupDialogInit (
   PMPrintSession printSession,
   PMPageFormat pageFormat,
   PMDialog *newDialog
);

Parameters
printSession

The current printing session.

pageFormat

A page format object.

newDialog

On return, a pointer to an initialized PMDialog object, ready for customization by your application. Because the PMSessionPageSetupDialogMain function does not include a parameter for passing this PMDialog object to your dialog initialization callback function, your application should store this pointer in a global variable or as extended data in the PMPageFormat object.

Return Value

A result code. See Core Printing Result Codes.

Discussion

The function PMSessionPageSetupDialogInit is valid only between the creation and release of a printing session and after creating a page format object. You should call this function only if you create a custom dialog using the AppendDITL method. In Mac OS X, you should create a custom dialog by writing a printing dialog extension. If you use this function to extend a printing dialog in Mac OS X, you cannot use sheets.

Availability
Declared In
PMApplicationDeprecated.h

PMSessionPageSetupDialogMain

Displays your application’s custom Page Setup dialog. (Deprecated in Mac OS X v10.4. Use a printing dialog extension instead.)

OSStatus PMSessionPageSetupDialogMain (
   PMPrintSession printSession,
   PMPageFormat pageFormat,
   Boolean *accepted,
   PMPageSetupDialogInitUPP myInitProc
);

Parameters
printSession

The current printing session.

pageFormat

A page format object.

accepted

A pointer to your Boolean variable. On return, true if the user clicks the OK button, or false if the user clicks Cancel.

myInitProc

A universal procedure pointer to your dialog initialization function. Your initialization function is defined by the callback PMPageSetupDialogInitProcPtr.

Return Value

A result code. See Core Printing Result Codes.

Discussion

The function PMSessionPageSetupDialogMain is valid only between the creation and release of a printing session and after calling the function PMSessionPageSetupDialogInit. You should call this function only if you create a custom dialog using the AppendDITL method. In Mac OS X, you should create a custom dialog by writing a printing dialog extension. If you use this function to extend a printing dialog in Mac OS X, you cannot use sheets.

Your dialog initialization function is called before your custom Page Setup dialog is displayed. Your initialization function can append items to the Page Setup dialog, and should install an item proc using the PMSetItemProc function. You must pass the same page format object to each of the functions PMSessionPageSetupDialogMain and PMSessionPageSetupDialogInit.

Availability
Declared In
PMApplicationDeprecated.h

PMSessionPrintDialogInit

Initializes a custom Print dialog. (Deprecated in Mac OS X v10.4. Use a printing dialog extension instead.)

OSStatus PMSessionPrintDialogInit (
   PMPrintSession printSession,
   PMPrintSettings printSettings,
   PMPageFormat constPageFormat,
   PMDialog *newDialog
);

Parameters
printSession

The current printing session.

printSettings

A print settings object.

constPageFormat

A page format object.

newDialog

On return, a pointer to an initialized PMDialog object, ready for customization by your application. Because the PMSessionPrintDialogMain function does not include a parameter for passing this PMDialog object to your dialog initialization callback function, your application should store this pointer in a global variable or as extended data in the PMPrintSettings object. See the discussion of the PMPrintDialogInitProcPtr callback function for more information.

Return Value

A result code. See Core Printing Result Codes.

Discussion

The function PMSessionPrintDialogInit is valid only between the creation and release of a printing session and after creating a print settings object. You should call this function only if you create a custom dialog using the AppendDITL method. In Mac OS X, you should create a custom dialog by writing a printing dialog extension. If you use this function to extend a printing dialog in Mac OS X, you cannot use sheets.

Availability
Declared In
PMApplicationDeprecated.h

PMSessionPrintDialogMain

Displays your application’s custom Print dialog. (Deprecated in Mac OS X v10.4. Use a printing dialog extension instead.)

OSStatus PMSessionPrintDialogMain (
   PMPrintSession printSession,
   PMPrintSettings printSettings,
   PMPageFormat constPageFormat,
   Boolean *accepted,
   PMPrintDialogInitUPP myInitProc
);

Parameters
printSession

The current printing session.

printSettings

A print settings object.

constPageFormat

A page format object.

accepted

A pointer to your Boolean variable. On return, true if the user accepts the dialog or false if the user cancels the dialog.

myInitProc

A universal procedure pointer to your dialog initialization function. Your initialization function is defined by the callback PMPrintDialogInitProcPtr

Return Value

A result code. See Core Printing Result Codes.

Discussion

The function PMSessionPrintDialogMain is valid only between the creation and release of a printing session and after calling the function PMSessionPrintDialogInit. You should call this function only if you create a custom dialog using the AppendDITL method. In Mac OS X, you should create a custom dialog by writing a printing dialog extension. If you use this function to extend a printing dialog in Mac OS X, you cannot use sheets.

Your dialog initialization function is called before your custom Print dialog is displayed. Your initialization function can append items to the Print dialog, and should install an item proc using the PMSetItemProc function. You must pass the same page format and print settings objects to each of the functions PMSessionPrintDialogMain and PMSessionPrintDialogInit.

Availability
Declared In
PMApplicationDeprecated.h

PMSetDialogAccepted

Indicates that the user confirmed a custom dialog. (Deprecated in Mac OS X v10.4. Use a printing dialog extension instead.)

OSStatus PMSetDialogAccepted (
   PMDialog pmDialog,
   Boolean process
);

Parameters
pmDialog

A PMDialog object representing your customized Page Setup or Print dialog.

process

Pass true if the user confirms the dialog. In the case of the Page Setup dialog, this means the user clicked the OK button; in the case of the Print dialog, this means the user clicked the Print button. Pass false if the user clicks the Cancel button.

Return Value

A result code. See Core Printing Result Codes.

Discussion

The function PMSetDialogAccepted is valid between the creation and release of a printing session and while displaying your custom Page Setup or Print dialog.

Availability
Declared In
PMApplicationDeprecated.h

PMSetDialogDone

Indicates that the user finished with a custom dialog. (Deprecated in Mac OS X v10.4. Use a printing dialog extension instead.)

OSStatus PMSetDialogDone (
   PMDialog pmDialog,
   Boolean done
);

Parameters
pmDialog

A PMDialog object representing your custom Page Setup or Print dialog.

done

Pass true when your callback function has finished with this dialog.

Return Value

A result code. See Core Printing Result Codes.

Discussion

The function PMSetDialogDone is valid between the creation and release of a printing session and while displaying your custom Page Setup or Print dialog.

Availability
Declared In
PMApplicationDeprecated.h

PMSetItemProc

Installs an item proc callback function for items in a custom dialog. (Deprecated in Mac OS X v10.4. Use a printing dialog extension instead.)

OSStatus PMSetItemProc (
   PMDialog pmDialog,
   PMItemUPP itemProc
);

Parameters
pmDialog

A PMDialog object representing your custom Page Setup or Print dialog.

itemProc

A universal procedure pointer to your dialog item event handling function.

Return Value

A result code. See Core Printing Result Codes.

Discussion

The function PMSetItemProc is valid between the creation and release of a printing session and after creating your custom Page Setup or Print dialog.

Availability
Declared In
PMApplicationDeprecated.h

PMSetModalFilterProc

Installs an event handling callback function for a modal dialog. (Deprecated in Mac OS X v10.4. Use a printing dialog extension instead.)

OSStatus PMSetModalFilterProc (
   PMDialog pmDialog,
   ModalFilterUPP filterProc
);

Parameters
pmDialog

A PMDialog object representing the Page Setup or Print dialog for which you want to install an event handling function.

filterProc

A universal procedure pointer to the event handling function you want called while the Page Setup or Print dialog is displayed. In Mac OS X this function is not called.

Return Value

A result code. See Core Printing Result Codes.

Discussion

The function PMSetModalFilterProc is valid between the creation and release of a printing session. You must install your filter procedure before calling PMSessionPageSetupDialogMain or PMSessionPrintDialogMain.

Availability
Declared In
PMApplicationDeprecated.h

Deprecated in Mac OS X v10.5

PMSessionBeginDocument

Begins a print job in which, by default, all drawing is to a QuickDraw graphics port. A printing status dialog informs the user of the job’s progress. (Deprecated in Mac OS X v10.5. Use PMSessionBeginCGDocument instead.)

OSStatus PMSessionBeginDocument (
   PMPrintSession printSession,
   PMPrintSettings printSettings,
   PMPageFormat pageFormat
);

Parameters
printSession

The printing session for the new print job.

printSettings

The print settings for the new print job.

pageFormat

The page format for the new print job.

Return Value

A result code. See Core Printing Result Codes.

Discussion

The function PMSessionBeginDocument starts a print job and should be called within your application’s print loop. This function is similar to the function PMSessionBeginDocumentNoDialog except that the printing status dialog is displayed.

You must call this function between the creation and release of a printing session. See the function PMCreateSession. If you present a printing dialog before you call PMSessionBeginDocument, you should use the same PMPrintSession object you used to present the dialog.

Before you call PMSessionBeginDocument, you should call PMSessionValidatePrintSettings and PMSessionValidatePageFormat to make sure the specified print settings and page format objects are updated and valid. After you call PMSessionBeginDocument, if you call a function that changes the specified print settings or page format object, the change is ignored for the current print job.

This function must be called before its corresponding End function (PMSessionEndDocument). If the function PMSessionBeginDocument function returns noErr, you must later call the End function, even if errors occur within the scope of the Begin and End functions.

The printing system automatically handles printing multiple copies. Your application does not need to perform any tasks other than specifying the number of copies in the printing session.

Special Considerations

In Mac OS X v10.4 and later, Apple recommends using the function PMSessionBeginCGDocument instead of this function. QuickDraw is deprecated and your application should be using Quartz 2D for its rendering.

Availability
Related Sample Code
Declared In
PMApplicationDeprecated.h

< Previous PageNext Page > Hide TOC

© 2001, 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-07-24)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.