Next Page >

Hide TOC

PDEPlugIn Protocol Reference

(informal protocol)

Adopted by	NSObject
Framework	/System/Library/Frameworks/Carbon.framework
Declared in	PDEPluginInterface.h

Overview

The PDEPlugIn informal protocol defines methods that a Cocoa printing dialog extension plug-in (Cocoa PDE) must implement to add one or more custom panes to a printing dialog. The printing system provides the type of pane needed (Page Setup or Print dialog) as well as information about the print job. A Cocoa PDE can use this information to determine which panes should be created. Each pane must conform to the PDEPanel informal protocol. Both applications and printer drivers can use PDEs to add panes to printing dialogs.

The name of the class that implements the PDEPlugIn protocol must be declared in the Cocoa PDE’s Info.plist file. The key for this class name is the string NSPrincipalClass. For example, if the PDE uses a class named OutputBinsPDEPlugIn to implement this protocol, the Info.plist file in the PDE should contain this entry:

<key>NSPrincipalClass</key>

<string>OutputBinsPDEPlugIn</string>

An application can host one or more Cocoa PDEs. An application PDE should be stored in the PlugIns directory inside the application bundle. To declare application PDEs to the printing system, you should add an array containing their names to the Info.plist file for the application. The key for this array is the string PrintDialogExtensions. For example, if an application contains a PDE named AppCustomPDE.bundle, the application’s Info.plist file should contain this entry:

<key>PrintDialogExtensions</key>

<array>

   <string>AppCustomPDE.bundle</string>

</array>

A printer driver can host one or more Cocoa PDEs. A printer driver PDE is typically stored somewhere inside a vendor directory located in /Library/Printers/. The path to each PDE should be declared in the printer driver’s PPD file using the APDialogExtension keyword. For example, if a printer driver has an associated PDE named OutputBinsPDE.bundle, the PPD file should contain an entry that looks something like this:

*APDialogExtension: "/Library/Printers/MyCompany/PDEs/OutputBinsPDE.bundle"

Tasks

Initialization

Pane Instantiation

Instance Methods

initWithBundle:

Initializes the plug-in.

- (BOOL)initWithBundle:(NSBundle *)theBundle

Parameters

theBundle: The plug-in bundle.

Return Value

YES if initialization succeeded; otherwise, NO.

Discussion

In this required method, you can perform PDE initialization tasks when the user displays the Page Setup or Print dialog and the PDE is being loaded. For example, you could retain the PDE bundle for later use.

If you return NO or do not implement this method, the printing system does not load the PDE and send it the PDEPanelsForType:withHostInfo: message.

Availability

Available in Mac OS X v10.4 and later.

Declared In

PDEPluginInterface.h

PDEPanelsForType:withHostInfo:

Returns an array of panes to be added to a printing dialog.

- (NSArray *)PDEPanelsForType:(NSString *)pdeType withHostInfo:(id)host

Parameters

pdeType

A constant, provided by the printing system, that indicates the type of panes this method should return. The constants are defined in PMPrintingDialogExtensions.h. There are three possible values:

kAppPageSetupDialogTypeIDStr: This an application plug-in and the panes you return are added to the Page Setup dialog.
kAppPrintDialogTypeIDStr: This an application plug-in and the panes you return are added to the Print dialog.
kPrinterModuleTypeIDStr: This is a printer driver plug-in and the panes you return are added to the Print dialog.

host

An object, provided by the printing system, that implements the methods in the PDEPlugInCallbackProtocol informal protocol. A Cocoa PDE can use the host to obtain information about the current print job. For example:

Your PDE can use the host to obtain the PMPrintSettings or PMPageFormat object to save a custom pane’s settings.
If your PDE has printer-specific panes, the PDE can use the host to obtain the PMPrinter object to aid in determining the panes that should be available.