Advanced Search

Log In | Not a Member?

Contact ADC

Next Page > Hide TOC

PDEPanel Protocol Reference

(informal protocol)

Overview

The PDEPanel informal protocol declares the methods that a class should implement to display a custom pane in a printing dialog. Some of the methods are required; others are optional. Note that a class that implements the PDEPlugIn protocol can provide multiple pane objects that each implement the PDEPanel protocol.

Tasks

Providing Pane Information

• – panelName
• – panelKind
• – panelView
• – summaryInfo

Handling Changes in Pane Visibility

• – willShow
• – shouldHide

Saving and Restoring Pane Settings

• – saveValuesAndReturnError:
• – restoreValuesAndReturnError:

Supporting PPD Options

PPD options are printer options specified in the destination printer’s PPD (PostScript printer description) file.

• – supportedPPDOptionKeys
• – PPDOptionKeyValueDidChange:ppdChoice:

Instance Methods

panelKind

Returns the kind ID of the pane.

- (NSString *)panelKind

Return Value

A unique string that identifies the pane.

Discussion

In this required method, you should return a string that uniquely identifies your custom pane. Typically, your pane’s kind ID is a reverse-domain name such as com.mycompany.print.pde.

Availability

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

Declared In

panelName

Returns the localized name of the pane.

- (NSString *)panelName

Return Value

The localized name of the pane.

Discussion

In this required method, you should return a string that contains the localized name of your custom pane. The printing system uses the name to represent the pane in the user interface of the printing dialog. The name is used in the pane menu and, for panes displayed in the Print dialog, in the Summary pane.

Availability

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

Declared In

panelView

Returns a view that contains the pane’s user interface.

- (NSView *)panelView

Return Value

A view that contains the pane’s user interface.

Discussion

In this required method, you should return a view that contains your custom pane’s user interface. The view can contain elements such as controls, static text, and images. The printing system embeds this view in the target dialog. The dimensions of the view are arbitrary, but the width of the view should not exceed 420 pixels. The printing system automatically centers the view in the dialog, so you should design the view to be as small as possible.

Availability

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

Declared In

PPDOptionKeyValueDidChange:ppdChoice:

Handles a change in the value of a PPD option that the pane supports.

- (void)PPDOptionKeyValueDidChange:(NSString *)option ppdChoice:(NSString *)choice

Parameters

option

The PPD option that changed.

choice

The new value of the PPD option.

Discussion

The printing system invokes this method to inform your custom pane that the value of a PPD option you claimed to support via the supportedPPDOptionKeys method has changed. Typically, this method is invoked if the user changes the value of a supported PPD option to resolve a conflict with the value of another option.

In this optional method, you can update any internal data you maintain for this PPD option.

Special Considerations

The printing system does not invoke this method in Mac OS X v10.4.

Availability

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

Declared In

restoreValuesAndReturnError:

Restores the pane’s settings.

- (BOOL)restoreValuesAndReturnError:(NSError **)error

Parameters

error

If an error occurs, in addition to returning NO you may use this parameter to return information to further describe the error. If you elect to do so, you should create an error object and use it to pass back the error information.

Return Value

YES to indicate that the settings have been initialized or restored.

Discussion

The printing system invokes this method before the pane is first shown or after the user selects a new preset.

In this required method, you should initialize or restore your custom pane’s user interface settings and internal settings. If a problem occurs, you should alert the user, initialize the settings to reasonable values as needed, and then return YES. Returning YES indicates that the printing system can proceed to show your pane.

A pane’s settings are based on values stored in printing system objects associated with the print job. To provide access to these printing system objects, the printing system creates a host object that conforms to the PDEPlugInCallbackProtocol informal protocol. The printing system passes the host object to your PDE when it sends the PDEPanelsForType:withHostInfo: message, a method in the PDEPlugIn informal protocol. Your PDE is responsible for making this host object available to its panes.

Print dialog panes use values from the print settings object or the PPD file object. Page Setup dialog panes use values from the page format object. If these printing system objects don’t contain values that correspond to your pane’s settings, you should use default values.

Availability

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

Declared In

saveValuesAndReturnError:

Verifies that the pane’s settings are valid and have been saved.

- (BOOL)saveValuesAndReturnError:(NSError **)error

Parameters

error

If an error occurs, in addition to returning NO you may use this parameter to return information to further describe the error. If you elect to do so, you should create an error object and use it to pass back the error information.

Return Value

YES if the current settings are valid and have been saved; otherwise, NO. If you return NO, the printing system takes no further action and continues to display your pane in the dialog.

Discussion

The printing system invokes this method when your custom pane is visible and the user selects a different pane, dismisses the dialog (other than via cancel), or requests that a preset be saved.

In this required method, you should check the user's input, handle any final interaction with the user, and verify that the pane’s user interface settings and internal settings have been saved. If you need more interaction with the user, perhaps because some of the input values were invalid, you should return NO. Returning YES indicates that the input values have been validated and saved, and the printing system can allow the user to show another pane or dismiss the dialog.

A pane’s user interface settings are based on values stored in printing system objects associated with the current print job. To provide access to these printing system objects, the printing system creates a host object that conforms to the PDEPlugInCallbackProtocol informal protocol. The printing system passes the host object to your PDE when it sends the PDEPanelsForType:withHostInfo: message, a method in the PDEPlugIn informal protocol. Your PDE is responsible for making this host object available to its panes.

Panes use several different mechanisms for saving their settings or options:

• If the user changes a PPD option, your pane should save the option’s new value immediately by sending the willChangePPDOptionKeyValue:ppdChoice: message to the host object.

• If the user changes a custom option, your pane should save the option’s new value in the host object’s PMPrintSettings or PMPageFormat object. You can save the value immediately when the user changes the option, or wait until this method is invoked.

Availability

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

Declared In

shouldHide

Prepares the pane to be hidden.

- (BOOL)shouldHide

Return Value

YES if it is okay to hide the pane; otherwise, NO.

Discussion

In this required method, you should take any action that’s appropriate just before the printing system hides your custom pane. For example, you could remove notifications or accessory windows that are no longer needed. Returning YES indicates that the printing system can proceed to hide the pane, probably to show another pane or to dismiss the dialog.

Availability

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

Declared In

summaryInfo

Returns localized text descriptions of the pane’s current settings.

- (NSDictionary *)summaryInfo

Return Value

A dictionary containing key-value pairs that describe your custom pane’s settings and their current values. Each key in the dictionary must be an NSString object providing the name of a setting. The key’s corresponding value must be an NSString object describing the current value of the setting. For example, a key in the dictionary for the Copies and Pages pane might be @"Page Range" and the corresponding value might be @"1 to 5". The strings should be localized for the current user.

Users expect Print dialog panes to provide summary information, so you are encouraged to provide summary information for your custom pane. If for some compelling reason you do not want to do so, you may return nil.

Discussion

In this method, you should return localized text descriptions of your custom pane’s current settings for display in the Summary pane of the Print dialog. This method is required only if your pane is displayed in Print dialog.

The order in which your pane’s settings are listed in the Summary pane is arbitrary. However, you can specify the order by adding an extra key-value pair to the dictionary you return. The key should be the string constant SUMMARY_DISPLAY_ORDER. The value associated with this key should be an array that contains the names of all your settings in the order you desire. This feature is supported in Mac OS X v10.5 and later.

Availability

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

Declared In

supportedPPDOptionKeys

Declares that the pane supports one or more PPD options.

- (NSArray *)supportedPPDOptionKeys

Return Value

An array of strings declaring the PPD options that this pane supports.

Discussion

In this optional method, a custom pane in the Print dialog can inform the printing system that the pane provides a user interface for one or more options in the destination printer’s PPD file. PPD option keys are strings defined in the PPD file. For example, to declare that the pane supports a single PPD option named OutputBin, this method could return:

NSArray *myOptionArray = [NSArray arrayWithObjects:@"OutputBin", nil];

After all the Print dialog panes are loaded, the printing system creates a user interface for any remaining unclaimed PPD options and presents a user interface for these options in the Print dialog’s Printer Features pane. Printer vendors are encouraged to support as many of these unclaimed PPD options as possible. If you intend to support a PPD option, you must declare it when this method is invoked.

Availability

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

Declared In

willShow

Prepares the pane for display.

- (void)willShow

Discussion

In this optional method, you can complete any final preparations needed just before your custom pane is displayed in the dialog. For example, you may want to lazily prepare the pane’s user interface. You could also perform other tasks such as adding notifications or accessory windows.

Availability

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

Declared In

Next Page > Hide TOC

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.

	Get information on Apple products. Visit the Apple Store online or at retail locations. 1-800-MY-APPLE Copyright © 2007 Apple Inc. All rights reserved. | Terms of use | Privacy Notice