NSPrintPanel Class Reference

Inherits from
NSObject
Conforms to
NSObject (NSObject)
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.0 and later.
Declared in
NSPrintPanel.h
Companion guides
Printing Programming Guide for Mac
Sheet Programming Topics
Related sample code

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

Customizing the Panel

Managing Accessory Views

Running the Panel

Communicating with the NSPrintInfo Object

Deprecated Methods

Class Methods

printPanel

Returns a new NSPrintPanel object.

+ (NSPrintPanel *)printPanel
Return Value

The print panel object.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSPrintPanel.h

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 OS X v10.5 and later.
See Also
Declared In
NSPrintPanel.h

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 OS X v10.5 and later.
See Also
Related Sample Code
Declared In
NSPrintPanel.h

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:(NSInteger)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 OS X v10.0 and later.
Related Sample Code
Declared In
NSPrintPanel.h

defaultButtonTitle

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

- (NSString *)defaultButtonTitle
Return Value

The title of the default button.

Availability
  • Available in OS X v10.5 and later.
See Also
Declared In
NSPrintPanel.h

helpAnchor

Returns the HTML help anchor associated with the Print panel.

- (NSString *)helpAnchor
Return Value

The current help anchor.

Availability
  • Available in OS X v10.5 and later.
See Also
Declared In
NSPrintPanel.h

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 OS X v10.2 and later.
See Also
Declared In
NSPrintPanel.h

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 OS X v10.5 and later.
See Also
Related Sample Code
Declared In
NSPrintPanel.h

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 OS X v10.5 and later.
Declared In
NSPrintPanel.h

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 OS X v10.5 and later.
See Also
Declared In
NSPrintPanel.h

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 OS X v10.0 and later.
See Also
Declared In
NSPrintPanel.h

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 OS X v10.5 and later.
Declared In
NSPrintPanel.h

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 OS X v10.5 and later.
See Also
Declared In
NSPrintPanel.h

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 OS X v10.5 and later.
See Also
Declared In
NSPrintPanel.h

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 “Job Style Hints.” Pass nil to this method to deactivate the simplified Print panel interface and use the standard interface instead (the equivalent of Core Printing’s kPMPresetGraphicsTypeGeneral).

Discussion

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

Availability
  • Available in OS X v10.2 and later.
See Also
Declared In
NSPrintPanel.h

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 OS X v10.5 and later.
See Also
Related Sample Code
Declared In
NSPrintPanel.h

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 *const NSPrintPhotoJobStyleHint;
NSString *const NSPrintAllPresetsJobStyleHint;
NSString *const NSPrintNoPresetsJobStyleHint;
Constants
NSPrintPhotoJobStyleHint

Output contains photographic data.

Available in OS X v10.2 and later.

Declared in NSPrintPanel.h.

NSPrintAllPresetsJobStyleHint

Output appropriate to all graphics types. Equivalent to Core Printing’s kPMPresetGraphicsTypeAll.

Available in OS X v10.6 and later.

Declared in NSPrintPanel.h.

NSPrintNoPresetsJobStyleHint

Output excludes all graphics printing. Equivalent to Core Printing’s kPMPresetGraphicsTypeNone.

Available in OS X v10.6 and later.

Declared in NSPrintPanel.h.

Declared In
NSPrintPanel.h

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,
   NSPrintPanelShowsPrintSelection = 1 << 5,
   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 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 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 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 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 OS X v10.5 and later.

Declared in NSPrintPanel.h.

NSPrintPanelShowsPrintSelection

The Print panel includes an additional selection option for paper range. This control is separate from any accessory views.

Available in OS X v10.6 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 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 OS X v10.5 and later.

Declared in NSPrintPanel.h.

Declared In
NSPrintPanel.h


© 2009 Apple Inc. All Rights Reserved. (Last updated: 2009-06-23)

Did this document help you? Yes It's good, but... Not helpful...