---

PDEPlugInCallbackProtocol Reference

(informal protocol)

Overview

The PDEPlugInCallbackProtocol informal protocol is implemented by the printing system to allow a Cocoa printing dialog extension plug-in (Cocoa PDE) that implements the PMPlugIn protocol to access information about the current print job. The printing system uses the PDEPanelsForType:withHostInfo: message to pass an object that implements PDEPlugInCallbackProtocol to the PDE. The PDE can retain this object and use it to exchange information with the printing system.

Tasks

Accessing Print Job Information

• – printSession
• – printSettings
• – pageFormat
• – PMPrinter
• – ppdFile

Changing PPD Options

• – willChangePPDOptionKeyValue:ppdChoice:

Changing the Pane Size

• – panelViewDidResize

Not Recommended

These methods are not relevant in Cocoa PDEs written for applications or CUPS printer drivers.

• – jobTemplate
• – printerInfoTicket

Instance Methods

jobTemplate

Returns the job template for the current printer.

- (PMTemplateRef) jobTemplate

Return Value

The current printer’s job template.

Discussion

This method is relevant only in a Cocoa PDE associated with a Tioga printer module. A PDE associated with an application or a CUPS printer driver should use the ppdFile method to get information about the destination printer.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

PDEPluginInterface.h

pageFormat

Returns the current page format object.

- (PMPageFormat) pageFormat

Return Value

The page format object for the current print job. Note that both the Page Setup and Print dialogs have a page format object.

Discussion

You may send this message to the receiver to obtain the page format object for the current print job.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

PDEPluginInterface.h

panelViewDidResize

Notifies the printing system that the size of the pane’s view has changed.

- (void)panelViewDidResize

Discussion

You should send this message to the receiver if your pane’s view size has changed. In response, the printing system resizes the dialog to show as much of the view as possible. For example, the view size may increase if the user clicks a disclosure control that reveals additional settings.

Special Considerations

If your PDE is running in Mac OS X v10.4, this method is available but does nothing. You should display your view in its fully disclosed state.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

PDEPluginInterface.h

PMPrinter

Returns the current printer object.

- (PMPrinter) PMPrinter

Return Value

The printer object for the currently selected printer.

Discussion

You may send this message to the receiver to obtain the printer object for the currently selected printer in the dialog. If your PDE is extending the Page Setup dialog, this method returns the formatting printer. If your PDE is extending the Print dialog, this method returns the destination printer.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

PDEPluginInterface.h

ppdFile

Returns a CUPS object used to access information about the current printer.

- (ppd_file_t *) ppdFile

Return Value

The CUPS object that contains information about the current printer.

Discussion

This method gives you access to information in the PPD file associated with the destination printer for the current print job. The PPD file contains information such as optional hardware and features the printer supports.

When you send this message, the receiver returns a CUPS PPD file object that you can pass to CUPS functions to get information about the PPD file. The printing system owns the returned object, and the object should be considered read-only. You should not change this object explicitly or by using CUPS functions.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

PDEPluginInterface.h

printerInfoTicket

Returns the printer information ticket for the current printer.

- (PMTicketRef) printerInfoTicket

Return Value

The printer information ticket for the current printer.

Discussion

This method is relevant only in a Cocoa PDE associated with a Tioga printer module. A PDE associated with an application or a CUPS printer driver should use the ppdFile method to get information about the destination printer.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

PDEPluginInterface.h

printSession

Returns the current print session object.

- (PMPrintSession) printSession

Return Value

The print session object for the current print job.

Discussion

You may send this message to the receiver to obtain the print session object for the current print job.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

PDEPluginInterface.h

printSettings

Returns the current print settings object.

- (PMPrintSettings) printSettings

Return Value

The print settings object for the current print job. If your PDE is not extending the Print dialog, this method returns nil.

Discussion

You may send this message to the receiver to obtain the print settings object for the current print job, if the object exists.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

PDEPluginInterface.h

willChangePPDOptionKeyValue:ppdChoice:

Requests a change in the value of a PPD option.

- (BOOL)willChangePPDOptionKeyValue:(NSString *)option ppdChoice:(NSString *)choice

Parameters

option

The main key for an option in the printer's PPD file.

choice

The new value of the specified option.

Return Value

YES if the specified choice is accepted; otherwise NO.

Discussion

You should send this message to the receiver whenever your PDE or the user requests a change in the value of a PPD option for the current print job. A return value of YES indicates that the printing system accepts the change, and the change has been recorded in the print settings object and the CUPS PPD file object. Note that your PDE should not attempt to modify the print settings or the CUPS PPD file object directly; the printing system handles this task for you.

If the desired choice is in conflict with other currently selected PPD options, the printing system tries to resolve the conflict. This may include presenting the user with a dialog explaining the conflict and allowing the user to cancel the change. A return value of NO indicates that the printing system rejects the change, and you should ensure that the user interface representing the option reverts to the value prior to the requested change.

Special Considerations

If your PDE is running in Mac OS X v10.4, this method is available but does nothing.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

PDEPluginInterface.h

---