Next Page > Hide TOC

NSPrintPanel Class Reference

Overview

An NSPrintPanel object creates the Print panel used to query the user for information about a print job. This panel may lets the user select the range of pages to print and the number of copies before executing the Print command.

Print panels can display a simplified interface when printing certain types of data. For example, the panel can display a list of print-setting presets, which lets the user enable print settings in groups as opposed to individually. The setJobStyleHint: method activates the simplified interface and identifies which presets to display.

Tasks

Creating an NSPrintPanel

• + printPanel

Customizing the Panel

• – jobStyleHint
• – setJobStyleHint:
• – options
• – setOptions:
• – defaultButtonTitle
• – setDefaultButtonTitle:
• – helpAnchor
• – setHelpAnchor:

Managing Accessory Views

• – addAccessoryController:
• – removeAccessoryController:
• – accessoryControllers

Running the Panel

• – beginSheetWithPrintInfo:modalForWindow:delegate:didEndSelector:contextInfo:
• – runModal
• – runModalWithPrintInfo:

Communicating with the NSPrintInfo Object

• – printInfo
• – finalWritePrintInfo Deprecated in Mac OS X v10.5
• – updateFromPrintInfo Deprecated in Mac OS X v10.5

Deprecated Methods

• – pickedButton:
• – pickedAllPages:
• – pickedLayoutList:
• – accessoryView Deprecated in Mac OS X v10.5
• – setAccessoryView: Deprecated in Mac OS X v10.5

Class Methods

printPanel

Returns a new NSPrintPanel object.

+ (NSPrintPanel *)printPanel

Return Value

The print panel object.

Availability

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

Declared In

Instance Methods

accessoryControllers

Returns the array of controller objects used to manage the Print panel’s accessory views.

- (NSArray *)accessoryControllers

Return Value

An array of NSViewController objects, each of which manages an accessory view for the Print panel.

Discussion

This method returns the accessory views that were added using the addAccessoryController: method.

Availability

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

See Also

• – addAccessoryController:

Declared In

addAccessoryController:

Adds a custom controller to the Print panel to manage an accessory view.

- (void)addAccessoryController:(NSViewController < NSPrintPanelAccessorizing > *)accessoryController

Parameters

accessoryController

The view controller that manages your custom accessory views.

Discussion

You can invoke this method multiple times to add multiple accessory views to the receiver’s Print panel. The title for the accessory view is obtained from the title method of the view controller object.

Availability

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

See Also

• – removeAccessoryController:

Declared In

beginSheetWithPrintInfo:modalForWindow:delegate:didEndSelector:contextInfo:

Displays a Print panel sheet and runs it modally for the specified window.

- (void)beginSheetWithPrintInfo:(NSPrintInfo *)printInfo modalForWindow:(NSWindow *)docWindow delegate:(id)modalDelegate didEndSelector:(SEL)didEndSelector contextInfo:(void *)contextInfo

Parameters

printInfo

The printing information for the current job.

docWindow

The window on which to display the sheet.

modalDelegate

A modal delegate object assigned to handle the closing of the Print panel sheet.

didEndSelector

The selector to call on the modal delegate object when the sheet is dismissed. The signature of this method is listed in the Discussion section.

contextInfo

A pointer to context data the didEndSelector method needs to process the sheet. This data is user-defined and may be NULL.

Discussion

When the modal session ends, if modalDelegate and didEndSelector contain non-nil values, the method specified by didEndSelector is invoked on the object in modalDelegate. The data you specify in contextInfo is passed as a parameter to the didEndSelector method. The object in modalDelegate is not the same as a delegate assigned to the panel. Modal delegates for sheets are temporary and the relationship lasts only until the sheet is dismissed.

The didEndSelector argument must have the following signature:

- (void)printPanelDidEnd:(NSPrintPanel *)printPanel returnCode:(int)returnCode  contextInfo: (void *)contextInfo;

The value passed as returnCode is either NSCancelButton or NSOKButton. The value NSOKButton is returned even if the user clicked the Preview button.

Availability

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

Declared In

defaultButtonTitle

Returns the title of the Print panel’s default button.

- (NSString *)defaultButtonTitle

Return Value

The title of the default button.

Availability

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

See Also

• – setDefaultButtonTitle:

Declared In

helpAnchor

Returns the HTML help anchor associated with the Print panel.

- (NSString *)helpAnchor

Return Value

The current help anchor.

Availability

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

See Also

• – setHelpAnchor:

Declared In

jobStyleHint

Returns the type of content that the Print panel is representing.

- (NSString *)jobStyleHint

Return Value

A string containing the job style hint or nil if no hint has been set.

Availability

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

See Also

• – setJobStyleHint:

Declared In

options

Returns the current configuration options for the Print panel.

- (NSPrintPanelOptions)options

Return Value

One or more configuration constants added together. To determine if a particular option is set, AND the return value with the appropriate constants found in “NSPrintPanelOptions.”

Availability

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

See Also

• – setOptions:

Declared In

pickedAllPages:

Deprecated. (Deprecated. No alternative. Do not use.)

- (void)pickedAllPages:(id)sender

Availability

• Available in Mac OS X v10.0 through Mac OS X v10.4.

Declared In

pickedButton:

Deprecated. (Deprecated. No alternative. Do not use.)

- (void)pickedButton:(id)sender

Availability

• Available in Mac OS X v10.0 through Mac OS X v10.4.

Declared In

pickedLayoutList:

Deprecated. (Deprecated. No alternative. Do not use.)

- (void)pickedLayoutList:(id)sender

Availability

• Available in Mac OS X v10.0 through Mac OS X v10.4.

Declared In

printInfo

Returns the printing information associated with the running Print panel.

- (NSPrintInfo *)printInfo

Return Value

The current printing information. May return nil if the Print panel is not currently running.

Discussion

This method is a convenience method that your delegate can use to get the printing information while the Print Panel is visible.

Availability

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

Declared In

removeAccessoryController:

Removes the specified controller and accessory view from the Print panel.

- (void)removeAccessoryController:(NSViewController < NSPrintPanelAccessorizing > *)accessoryController

Parameters

accessoryController

The view controller to remove.

Discussion

You use this method to remove any view controllers responsible for displaying accessory views you do not want to include in the Print panel.

Availability

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

See Also

• – addAccessoryController:

Declared In

runModal

Displays the receiver's Print panel and begins the modal loop.

- (NSInteger)runModal

Return Value

NSCancelButton if the user clicks the Cancel button; otherwise NSOKButton.

Discussion

This method uses the printing information associated with the current printing operation.

Availability

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

See Also

• – printInfo (NSPrintOperation)

Declared In

runModalWithPrintInfo:

Displays the receiver’s Print panel and runs the modal loop using the specified printing information.

- (NSInteger)runModalWithPrintInfo:(NSPrintInfo *)printInfo

Parameters

printInfo

The printing information to use while displaying the Print panel.

Return Value

NSCancelButton if the user clicks the Cancel button; otherwise NSOKButton.

Availability

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

Declared In

setDefaultButtonTitle:

Sets the title of the Print panel’s default button.

- (void)setDefaultButtonTitle:(NSString *)defaultButtonTitle

Parameters

defaultButtonTitle

The string to use for the button title.

Discussion

You can use this method to change the default button title from "Print” to something more appropriate for your usage of the panel. For example, if you are using the Print panel to save a representation of the document to a file, you might change the title to “Save”.

Availability

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

See Also

• – defaultButtonTitle

Declared In

setHelpAnchor:

Sets the HTML help anchor for the print panel.

- (void)setHelpAnchor:(NSString *)helpAnchor

Parameters

helpAnchor

The anchor name in your Apple Help file. This parameter should contain just the name portion of the HTML anchor element.

Discussion

For information on how to insert anchors into your Apple Help files, see Authoring User Help in Apple Help Programming Guide.

Availability

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

See Also

• – helpAnchor

Declared In

setJobStyleHint:

Sets the type of content the Print panel is representing.

- (void)setJobStyleHint:(NSString *)hint

Parameters

hint

For a list of supported job style hints, see “Constants.” Pass nil to this method to deactivate the simplified Print panel interface and use the standard interface instead.

Discussion

This method controls the set of items that appear in the Presets menu of the simplified Print panel interface.

Availability

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

See Also

• – jobStyleHint

Declared In

setOptions:

Sets the configuration options for the Print panel.

- (void)setOptions:(NSPrintPanelOptions)options

Parameters

options

The configuration options, which you specify by adding together the appropriate constant values found in “NSPrintPanelOptions.”

Availability

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

See Also

• – options

Declared In

Constants

Job Style Hints

This constant can be passed to the setJobStyleHint: method to activate the simplified Print panel interface and specify which presets to display.

NSString *NSPrintPhotoJobStyleHint;

Constants

NSPrintPhotoJobStyleHint

Output contains photographic data.

Available in Mac OS X v10.2 and later.

Declared in NSPrintPanel.h.

Declared In

NSPrintPanelOptions

These constants are used to configure the contents of the main Print panel.

   
enum {
   NSPrintPanelShowsCopies = 0x01,
   NSPrintPanelShowsPageRange = 0x02,
   NSPrintPanelShowsPaperSize = 0x04,
   NSPrintPanelShowsOrientation = 0x08,
   NSPrintPanelShowsScaling = 0x10,
   NSPrintPanelShowsPageSetupAccessory = 0x100,
   NSPrintPanelShowsPreview = 0x20000
};
typedef NSInteger NSPrintPanelOptions;

Constants

NSPrintPanelShowsCopies

The Print panel includes a field for manipulating the number of copies being printed. This field is separate from any accessory views.

Available in Mac OS X v10.5 and later.

Declared in NSPrintPanel.h.

NSPrintPanelShowsPageRange

The Print panel includes a set of fields for manipulating the range of pages being printed. These fields are separate from any accessory views.

Available in Mac OS X v10.5 and later.

Declared in NSPrintPanel.h.

NSPrintPanelShowsPaperSize

The Print panel includes a control for manipulating the paper size of the printer. This control is separate from any accessory views.

Available in Mac OS X v10.5 and later.

Declared in NSPrintPanel.h.

NSPrintPanelShowsOrientation

The Print panel includes a control for manipulating the page orientation. This control is separate from any accessory views.

Available in Mac OS X v10.5 and later.

Declared in NSPrintPanel.h.

NSPrintPanelShowsScaling

The Print panel includes a control for scaling the printed output. This control is separate from any accessory views.

Available in Mac OS X v10.5 and later.

Declared in NSPrintPanel.h.

NSPrintPanelShowsPageSetupAccessory

The Print panel includes a separate accessory view for manipulating the paper size, orientation, and scaling attributes. Page setup fields that are already configured for display on the main portion of the Print panel appear there and not on this accessory panel.

Available in Mac OS X v10.5 and later.

Declared in NSPrintPanel.h.

NSPrintPanelShowsPreview

The Print panel displays a built-in preview of the document contents. This option is only appropriate when the Print panel is used in conjunction with an NSPrintOperation object to print a document.

Available in Mac OS X v10.5 and later.

Declared in NSPrintPanel.h.

Declared In

Next Page > Hide TOC