NSSavePanel Class Reference

Inherits from	NSPanel : NSWindow : NSResponder : NSObject
Conforms to	NSUserInterfaceValidations (NSWindow) NSAnimatablePropertyContainer (NSWindow) NSUserInterfaceItemIdentification (NSWindow) NSCoding (NSResponder) NSObject (NSObject)
Framework	/System/Library/Frameworks/AppKit.framework
Availability	Available in OS X v10.0 and later.
Declared in	NSSavePanel.h
Companion guides	File System Programming Guide Sheet Programming Topics
Related sample code	CocoaSpeechSynthesisExample CustomSave ImageApp MassiveImage Quartz 2D Transformer

Overview

An NSSavePanel object creates and manages a Save panel and allows you to run the panel in a modal loop. The Save panel provides a simple way for a user to specify a file to use when saving a document or other data. It can restrict the user to files of a certain type, as specified by an extension.

An NSSavePanel object manages a panel that allows users to specify the directory and name under which a file is saved. It supports browsing of the file system, and it accommodates custom accessory views.

An NSSavePanel object may have a delegate. The methods that delegates of NSSavePanel may implement are specified by the NSOpenSavePanelDelegate protocol.

In a sandboxed app, when a user saves a document, the Save dialog is presented by the powerbox, not AppKit. OS X then adds the saved file to the app’s sandbox (if necessary) to allow the app to write to the file.

Tasks

Creating Panels

Configuring Panels

Configuring Panel Content

Running Panels

Accessing User Selection

Handling Actions

Class Methods

savePanel

Returns a Save panel that has been initialized with default values.

+ (NSSavePanel *)savePanel

Return Value

The initialized Save panel.

Availability

Available in OS X v10.0 and later.

Related Sample Code

Declared In

NSSavePanel.h

Instance Methods

accessoryView

Returns the custom accessory view for the current application.

- (NSView *)accessoryView

Return Value

The custom accessory view for the current application.

Discussion

The panel relinquishes ownership of the accessory view after the panel is closed. If you want to reuse the accessory view, you should not rely on the panel to hold onto the accessory view until the next time you use it; instead, you should maintain your own strong reference to the view.

Availability

Available in OS X v10.0 and later.

Declared In

NSSavePanel.h

allowedFileTypes

Returns an array of the allowed file types.

- (NSArray *)allowedFileTypes

Return Value

An array of the allowed file types.

Discussion

For a full discussion, see setAllowedFileTypes:.

Availability

Available in OS X v10.3 and later.

Declared In

NSSavePanel.h

allowsOtherFileTypes

Returns a Boolean value that indicates whether the panel allows the user to save files with an extension that’s not in the list of allowed types.

- (BOOL)allowsOtherFileTypes

Return Value

YES if the panel allows the user to save files with an extension that’s not in the list of allowed types; otherwise, NO.

Discussion

If the user tries to save a filename with a recognized extension that's not in the list of allowed types they are presented with a dialog. If this method returns YES, then the dialog presents the option of using the extension the user specified.

The default setting is NO.

Availability

Available in OS X v10.3 and later.

Declared In

NSSavePanel.h

beginSheetModalForWindow:completionHandler:

Presents the panel as a sheet modal to the specified window.

- (void)beginSheetModalForWindow:(NSWindow *)window completionHandler:(void (^)(NSInteger result))handler

Parameters

window: The window in which the panel will be presented.
handler: The block called after the user has closed the panel. The argument passed in will be NSFileHandlingPanelOKButton if the user chose the OK button or NSFileHandlingPanelCancelButton if the user chose the Cancel button.

Discussion

Any properties of the panel you wish to set should be set before calling this method.

Availability

Available in OS X v10.6 and later.

Related Sample Code

Declared In

NSSavePanel.h

beginWithCompletionHandler:

Presents the panel as a modeless window.

- (void)beginWithCompletionHandler:(void (^)(NSInteger result))handler

Parameters

handler: The block called after the user has closed the panel. The argument passed in will be NSFileHandlingPanelOKButton if the user chose the OK button or NSFileHandlingPanelCancelButton if the user chose the Cancel button.

Discussion

Any properties of the panel you wish to set should be set before calling this method.

Availability

Available in OS X v10.6 and later.

Declared In

NSSavePanel.h

cancel:

This action method is invoked when the user clicks the panel’s Cancel button.

- (IBAction)cancel:(id)sender

Parameters

sender: The NSSavePanel object whose Cancel button was clicked.

Availability

Available in OS X v10.0 and later.

Declared In

NSSavePanel.h

canCreateDirectories

Returns a Boolean value that indicates whether the panel allows the user to create directories.

- (BOOL)canCreateDirectories

Return Value

YES when the panel allows the user to create directories; otherwise, NO.

Discussion

The default value is YES.

Availability

Available in OS X v10.3 and later.

Declared In

NSSavePanel.h

canSelectHiddenExtension

Returns a Boolean value that indicates whether the panel allows the user to hide or show extensions.

- (BOOL)canSelectHiddenExtension

Return Value

YES when the panel allows the user to hide or show extensions; otherwise, NO.

Availability

Available in OS X v10.3 and later.

Declared In

NSSavePanel.h

delegate

Returns the panel’s delegate.

- (id <NSOpenSavePanelDelegate>)delegate

Return Value

The panel’s delegate.

Availability

Available in OS X v10.3 and later.

Declared In

NSSavePanel.h

directoryURL

Returns the directory shown in the panel as a URL.

- (NSURL *)directoryURL

Return Value

The directory’s URL.

Availability

Available in OS X v10.6 and later.

Related Sample Code

Declared In

NSSavePanel.h

isExpanded

Returns a Boolean value that indicates whether the panel is expanded.

- (BOOL)isExpanded

Return Value

YES if the panel is expanded; otherwise, NO.

Availability

Available in OS X v10.0 and later.

Declared In

NSSavePanel.h

isExtensionHidden

Returns a Boolean value that indicates whether the extension-hiding checkbox is visible and checked.

- (BOOL)isExtensionHidden

Return Value

YES when the extension-hiding checkbox is visible and checked; otherwise, NO.

Availability

Available in OS X v10.1 and later.

Declared In

NSSavePanel.h

message

Returns the message displayed in the save panel.

- (NSString *)message

Return Value

The message displayed in the save panel.

Discussion

This prompt appears on all NSSavePanel objects (or all NSOpenPanel objects if the receiver of this message is an NSOpenPanel instance) in your application. The default message text is an empty string.

Availability

Available in OS X v10.3 and later.

Declared In

NSSavePanel.h

nameFieldLabel

Returns the string displayed in front of the filename text field.

- (NSString *)nameFieldLabel

Return Value

The string displayed in front of the filename text field.

Discussion

By default the label is “Save As:”.

Availability

Available in OS X v10.3 and later.

Declared In

NSSavePanel.h

nameFieldStringValue

Returns the user-editable filename currently shown in the name field.

- (NSString *)nameFieldStringValue

Return Value

The filename currently selected.

Availability

Available in OS X v10.6 and later.

Related Sample Code

ScreenSnapshot

Declared In

NSSavePanel.h

ok:

This action method is invoked when the user clicks the panel’s OK button.

- (IBAction)ok:(id)sender

Parameters

sender: The NSSavePanel object whose OK button was clicked.

Discussion

Sandboxed apps cannot programmatically invoke the OK button.

Availability

Available in OS X v10.0 and later.

Declared In

NSSavePanel.h

prompt

Returns the prompt of the default button.

- (NSString *)prompt

Return Value

The prompt of the default button.

Discussion

This prompt appears on all NSSavePanel objects (or all NSOpenPanel objects if the receiver of this message is an NSOpenPanel instance) in your application. By default, the text in the default button is “Open” for an open panel and “Save” for a Save panel.

Availability

Available in OS X v10.0 and later.

Declared In

NSSavePanel.h

runModal

Displays the panel and begins its event loop with the current working (or last selected) directory as the default starting point.

- (NSInteger)runModal

Return Value

NSFileHandlingPanelOKButton (if the user clicks the OK button) or NSFileHandlingPanelCancelButton (if the user clicks the Cancel button).

Discussion

This method invokes NSApplication‘s runModalForWindow: method with self as the argument.

Availability

Available in OS X v10.0 and later.

Related Sample Code

Declared In

NSSavePanel.h

setAccessoryView:

Customizes the panel for the application by adding a custom view to the panel.

- (void)setAccessoryView:(NSView *)aView

Parameters

aView: View to set as the panel’s accessory view.

Discussion

The custom object that is added appears just above the OK and Cancel buttons at the bottom of the panel. The NSSavePanel object automatically resizes itself to accommodate aView. You can invoke this method repeatedly to change the accessory view as needed. If aView is nil, the Save panel removes the current accessory view.

Availability

Available in OS X v10.0 and later.

Related Sample Code

Declared In

NSSavePanel.h

setAllowedFileTypes:

Specifies the allowed file types for the panel.

- (void)setAllowedFileTypes:(NSArray *)types

Parameters

types

An array of NSString objects specifying the file types the user can save the file as. A nil value indicates that any file type can be used.

If the array is not nil and the array contains no items, an exception is raised.

Discussion

A file type can be a common file extension, or a UTI. A nil value indicates that any file type can be used. The default value is nil.

If no extension is given by the user, the first item in the allowedFileTypes will be used as the extension for the save panel. If the user specifies a type not in the array, and allowsOtherFileTypes is YES, they will be presented with another dialog when prompted to save.

NSOpenPanel: In versions of OS X less than v10.6, this property is ignored. For applications that link against v10.6 and higher, this property determines which files should be enabled in the open panel. Using the deprecated methods to show the open panel (the ones that take a types: parameter) will overwrite this value, and should not be used. The allowed file types can be changed while the panel is running (for example, from an accessory view). The file type can be a common file extension, or a UTI. This is also known as the “enabled file types.” A nil value indicates that all files should be enabled.

Availability

Available in OS X v10.3 and later.

Related Sample Code

Declared In

NSSavePanel.h

setAllowsOtherFileTypes:

Sets whether the panel allows the user to save files with an extension that’s not in the list of allowed types.

- (void)setAllowsOtherFileTypes:(BOOL)flag

Parameters

flag: If YES, the panel allows the user to save files with an extension that’s not in the list of allowed types; if NO, it does not.

Discussion

If the user tries to save a filename with a recognized extension that's not in the list of allowed types they are presented with a dialog. If allowsOtherFileTypes is YES, then the dialog presents the option of using the extension the user specified.

The default setting is NO.

Availability

Available in OS X v10.3 and later.

Related Sample Code

Declared In

NSSavePanel.h

setCanCreateDirectories:

Sets whether the panel allows the user to create directories.

- (void)setCanCreateDirectories:(BOOL)flag

Parameters

flag: If YES, the panel allows the user to create directories; if NO, the panel does not.

Availability

Available in OS X v10.3 and later.

Declared In

NSSavePanel.h

setCanSelectHiddenExtension:

Sets whether the panel allows the user to hide or show extensions.

- (void)setCanSelectHiddenExtension:(BOOL)flag

Parameters

flag: If YES, the panel allows the user to hide or show extensions; if NO, it does not.

Discussion

This method must be called before the panel is displayed. If set to YES, isExtensionHidden and setExtensionHidden:, respectively, can be used to get and set the value of the checkbox that hides or shows extensions.

Availability

Available in OS X v10.1 and later.

Related Sample Code

Declared In

NSSavePanel.h

setDelegate:

Sets an object as the panel’s delegate, after verifying which delegate methods are implemented.

- (void)setDelegate:(id <NSOpenSavePanelDelegate>)anObject

Parameters

anObject: Object to set as the panel’s delegate.

Availability

Available in OS X v10.0 and later.

Related Sample Code

Declared In

NSSavePanel.h

setDirectoryURL:

Sets the directory shown in the panel to the directory with the specified URL.

- (void)setDirectoryURL:(NSURL *)url

Parameters

url: The URL of the directory to set.

Availability

Available in OS X v10.6 and later.

Related Sample Code

Declared In

NSSavePanel.h

setExtensionHidden:

Sets the value of the extension-hiding checkbox.

- (void)setExtensionHidden:(BOOL)flag

Parameters

flag: If YES, the extension-hiding checkbox is visible and checked; if NO, it is not.

Discussion

This method should rarely be used because the state is saved on a per-application basis. Use this method to set whether a file’s extension should be indicated as being shown.

Availability

Available in OS X v10.1 and later.

Related Sample Code

ScreenSnapshot

Declared In

NSSavePanel.h

setMessage:

Sets the message text displayed in the panel.

- (void)setMessage:(NSString *)message

Parameters

message: String to set as the panel’s message.

Discussion

Availability

Available in OS X v10.3 and later.

Related Sample Code

Declared In

NSSavePanel.h

setNameFieldLabel:

Sets the text displayed in front of the text field.

- (void)setNameFieldLabel:(NSString *)label

Parameters

label: String to set as the text displayed in front of the panel’s text field.

Discussion

By default the label is “Save As:”.

Availability

Available in OS X v10.3 and later.

Related Sample Code

CustomSave

Declared In

NSSavePanel.h

setNameFieldStringValue:

Sets the filename in the name field to the specified value.

- (void)setNameFieldStringValue:(NSString *)value

Parameters

value: The filename to set. The value must not be nil.

Availability

Available in OS X v10.6 and later.

Related Sample Code

Declared In

NSSavePanel.h

setPrompt:

Sets the prompt of the default button.

- (void)setPrompt:(NSString *)prompt

Parameters

prompt: String to set as the prompt of the panel’s default button.

Discussion

It is intended that short words or phrases, such as “Open,” “Save,” “Set,” or “Choose,” be used on the button. The button is not resized to accommodate long prompts.

Since this method previously affected a title field, any colon at the end of prompt is removed.

Availability

Available in OS X v10.0 and later.

Related Sample Code

Declared In

NSSavePanel.h

setShowsHiddenFiles:

Specifies whether the panel displays files that are normally hidden from the user.

- (void)setShowsHiddenFiles:(BOOL)flag

Parameters

flag: If YES, the panel displays hidden files; if NO, it does not.

Availability

Available in OS X v10.6 and later.

Declared In

NSSavePanel.h

setTitle:

Sets the title of the panel.

- (void)setTitle:(NSString *)title

Parameters

title: String to set as the panel’s title.

Discussion

By default, “Save” is the title string. If you adapt the NSSavePanel object for other uses, its title should reflect the user action that brings it to the screen.

Availability

Available in OS X v10.0 and later.

Related Sample Code

Declared In

NSSavePanel.h

setTreatsFilePackagesAsDirectories:

Sets the panel’s behavior for displaying file packages (for example, MyApp.app) to the user.

- (void)setTreatsFilePackagesAsDirectories:(BOOL)flag

Parameters

flag: If YES, the panel will display file packages as directories; if NO, it will not.

Availability

Available in OS X v10.0 and later.

Related Sample Code

Declared In

NSSavePanel.h

showsHiddenFiles

Returns whether the panel displays files that are normally hidden from the user.

- (BOOL)showsHiddenFiles

Return Value

YES if the panel displays hidden files; otherwise, NO.

Discussion

The default value is NO.

Availability

Available in OS X v10.6 and later.

Declared In

NSSavePanel.h

title

Returns the title of the panel.

- (NSString *)title

Return Value

The title of the panel.

Availability

Available in OS X v10.0 and later.

Declared In

NSSavePanel.h

treatsFilePackagesAsDirectories

Returns a Boolean value that indicates whether the panel displays file packages as directories.

- (BOOL)treatsFilePackagesAsDirectories

Return Value

YES if the panel displays file packages as directories; otherwise, NO.

Availability

Available in OS X v10.0 and later.

Declared In

NSSavePanel.h

URL

Returns the absolute pathname of the file currently shown in the panel as a URL.

- (NSURL *)URL

Return Value

The absolute pathname of the file currently shown in the panel as a URL.

Availability

Available in OS X v10.0 and later.

Related Sample Code

Declared In

NSSavePanel.h

validateVisibleColumns

Validates and possibly reloads the browser columns visible in the panel by invoking the delegate method panel:shouldShowFilename:.

- (void)validateVisibleColumns

Discussion

You might use this method if you want the browser to only allow selection of files with certain extensions based on the selection made in an accessory-view pop-up list. When the user changes the selection, you would invoke this method to revalidate the visible columns.

Availability

Available in OS X v10.0 and later.

Declared In

NSSavePanel.h

Constants

Button tags

Button tags that refer to items on the panel.

enum {
   NSFileHandlingPanelCancelButton = NSCancelButton,
   NSFileHandlingPanelOKButton = NSOKButton
};

Constants

NSFileHandlingPanelCancelButton

The Cancel button.

Available in OS X v10.0 and later.

Declared in NSSavePanel.h.

NSFileHandlingPanelOKButton

The OK button.

Available in OS X v10.0 and later.

Declared in NSSavePanel.h.

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.

NSSavePanel Class Reference

Overview

Tasks

Creating Panels

Configuring Panels

Configuring Panel Content

Running Panels

Accessing User Selection

Handling Actions

Class Methods

savePanel

Return Value

Availability

Related Sample Code

Declared In

Instance Methods

accessoryView

Return Value

Discussion

Availability

See Also

Declared In

allowedFileTypes

Return Value

Discussion

Availability

See Also

Declared In

allowsOtherFileTypes

Return Value

Discussion

Availability

See Also

Declared In

beginSheetModalForWindow:completionHandler:

Parameters

Discussion

Availability

Related Sample Code

Declared In

beginWithCompletionHandler:

Parameters

Discussion

Availability

Declared In

cancel:

Parameters

Availability

See Also

Declared In

canCreateDirectories

Return Value

Discussion

Availability

See Also

Declared In

canSelectHiddenExtension

Return Value

Availability

See Also

Declared In

delegate

Return Value

Availability

See Also

Declared In

directoryURL

Return Value

Availability

See Also

Related Sample Code

Declared In

isExpanded

Return Value

Availability

Declared In

isExtensionHidden

Return Value

Availability

See Also