NSSavePanel Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.0 and later.
Declared in
NSSavePanel.h
Companion guides
Related sample code

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.
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 dismisses 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. Although the completion handler block is called after the user dismisses the panel, the panel sheet may still be visible onscreen. If you need to remove the sheet from the screen—for example, if the completion block displays an alert—first call [savePanel orderOut:nil] to close the sheet.

Availability
  • Available in OS X v10.6 and later.
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.
See Also
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.
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
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.
See Also
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.
See Also
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.
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.
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.
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.
See Also
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.
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.

This method has no effect if the user has chosen to show all file extensions in Finder.

Availability
  • Available in OS X v10.1 and later.
Related Sample Code
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

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.
See Also
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
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.
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

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.

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.
See Also
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

setShowsTagField:

Sets whether the panel displays the Tags field.

- (void)setShowsTagField:(BOOL)flag
Parameters
flag

If YES, the panel displays the Tags field; if NO, the panel doesn’t display the Tags field.

Discussion

If you pass YES to this method, you are responsible for setting tag names on the resulting file after saving is complete. It’s recommended that you invoke this method directly and either set tag names or opt out of tagging altogether. If this method is never invoked, OS X will automatically show the tag field and attempt to apply the tags to the file. (To set tags on files, use the NSURLTagNamesKey, described in Common File System Resource Keys.)

Note that the Tags field is appropriate only in a Save panel.

Availability
  • Available in OS X v10.9 and later.
Declared In
NSSavePanel.h

setTagNames:

Specifies the initial tag names that should be displayed in the panel.

- (void)setTagNames:(NSArray *)tagNames
Parameters
tagNames

An array of strings that represent the inital set of tag names to display in the panel. If nil or an empty array, no initial tag names are displayed in the panel.

Discussion

When showsTagField returns YES, use this method to set initial tag names to be displayed prior to displaying the receiver. Note that the Tags field is appropriate only in a Save panel.

Availability
  • Available in OS X v10.9 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.
See Also
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.
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

showsTagField

Returns a Boolean value that indicates whether the panel displays the Tags field.

- (BOOL)showsTagField
Return Value

YES when the panel displays the Tags field; otherwise, NO. (The Tags field is appropriate only in a Save panel.)

Availability
  • Available in OS X v10.9 and later.
Declared In
NSSavePanel.h

tagNames

The tag names to set on the file the user has saved.

- (NSArray *)tagNames
Discussion

If showsTagField returns YES, this method returns a non-nil array, regardless of whether the array is empty; if showsTagField returns NO, this method returns nil. Note that the Tags field is appropriate only in a Save panel.

Availability
  • Available in OS X v10.9 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.
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.