Next Page >

Hide TOC

NSSavePanel Class Reference

Inherits from	NSPanel : NSWindow : NSResponder : NSObject
Conforms to	NSUserInterfaceValidations (NSWindow) NSAnimatablePropertyContainer (NSWindow) NSCoding (NSResponder) NSObject (NSObject)
Framework	/System/Library/Frameworks/AppKit.framework
Availability	Available in Mac OS X v10.0 and later.
Declared in	NSSavePanel.h
Companion guides	Application File Management Sheet Programming Topics for Cocoa
Related sample code	CIVideoDemoGL QTAudioExtractionPanel Quartz Composer WWDC 2005 TextEdit TextEditPlus WhackedTV

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.

Tasks

Creating Panels

Configuring Panels

Configuring Panel Content

Running Panels

Accessing User Selection

Handling Actions

Deprecated

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 Mac 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

In order to free up unused memory after closing the receiver, the accessory view is released after the panel is closed. If you rely on the receiver to hold onto the accessory view until the next time you use it, the accessory view may be deallocated unexpectedly. If you retain the accessory view in your own code, though, this deallocation should not be a problem.

Availability

Available in Mac 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

If the user specifies a file whose type is in the array of allowed types, the user is not presented with another dialog (see allowsOtherFileTypes for details about this dialog) when trying to save. Examples of common file types are “rtf”, “tiff”, and “ps”. File type strings encoding HFS file types are not valid values for this attribute. A nil return value, which is the default, indicates that the user can save to any ASCII file.

Availability

Available in Mac 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; NO otherwise.

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 Mac OS X v10.3 and later.

Declared In

NSSavePanel.h

beginSheetForDirectory:file:modalForWindow:modalDelegate:didEndSelector:contextInfo:

Presents a Save panel as a sheet with a specified path and, optionally, a specified file in that path.

- (void)beginSheetForDirectory:(NSString *)path file:(NSString *)name modalForWindow:(NSWindow *)docWindow modalDelegate:(id)modalDelegate didEndSelector:(SEL)didEndSelector contextInfo:(void *)contextInfo

Parameters

path

Directory whose files the panel displays. When nil, the directory is the same directory used in the previous invocation of the panel; this is probably the best choice for most situations.

name

Specifies a particular file in path that is selected when the Save panel is presented to a user. When nil, no file is initially selected.

docWindow

If not nil, the Save panel slides down as a sheet running as a document modal window in docWindow. If nil, the behavior defaults to a standalone modal window.

modalDelegate

This is not the same as a delegate assigned to the panel. This delegate is temporary and the relationship only lasts until the panel is dismissed. The NSSavePanel object does not retain the modal delegate.

didEndSelector

Message sent to modalDelegate after the modal session has ended, but before dismissing the Save panel. didEndSelector may dismiss the Save panel itself; otherwise, it is dismissed on return from the method. The corresponding method should have the following signature:

- (void)savePanelDidEnd:(NSSavePanel *)sheet returnCode:(int)returnCode contextInfo:(void *)contextInfo;

The value passed as returnCode is either NSCancelButton or NSOKButton.

contextInfo

Context information passed to modalDelegate in the didEndSelector message.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

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 Mac 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; NO otherwise.

Discussion

The default value is YES.

Availability

Available in Mac 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; NO otherwise.

Availability

Available in Mac OS X v10.3 and later.

Declared In

NSSavePanel.h

delegate

Returns the panel’s delegate.

- (id)delegate

Return Value

The panel’s delegate.

Availability

Available in Mac OS X v10.3 and later.

Declared In

NSSavePanel.h

filename

Returns the absolute pathname of the file currently shown in the panel.

- (NSString *)filename

Return Value

The absolute pathname of the file.

Availability

Available in Mac OS X v10.0 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; NO otherwise.

Availability

Available in Mac 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; NO otherwise.

Availability

Available in Mac OS X v10.1 and later.

Related Sample Code

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 Mac 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 Mac OS X v10.3 and later.

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.

Availability

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

Declared In

NSSavePanel.h

requiredFileType

Returns the required file type (if any).

- (NSString *)requiredFileType

Return Value

The required file type (if any).

Discussion

A file specified in the Save panel is saved with the designated filename and this file type as an extension. Examples of common file types are “rtf”, “tiff”, and “ps”. File type strings encoding HFS file types are not valid values for this attribute. An nil return value indicates that the user can save to any ASCII file.

This method is equivalent to calling allowedFileTypes and returning the first element of the list of allowed types, or nil if there are none.

Availability

Available in Mac 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 runModalForDirectory:file: (file argument is an empty NSString object), which in turn performs NSApplication‘s runModalForWindow: method with self as the argument. Do not invoke filename or directory within a modal loop because the information these methods fetch is updated only upon return.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

Declared In

NSSavePanel.h

runModalForDirectory:file:

Initializes the panel to the directory and file specified, if any, then displays it and begins its modal event loop.

- (NSInteger)runModalForDirectory:(NSString *)path file:(NSString *)filename

Parameters

path: Directory whose files the panel displays. When nil, the directory is the same directory used in the previous invocation of the panel; this is probably the best choice for most situations.
filename: Specifies a particular file in path that is selected when the Save panel is presented to a user. When nil, no file is initially selected.

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. Do not invoke filename or directory within a modal loop because the information these methods fetch is updated only upon return.

Availability

Available in Mac 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 Mac 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: Array to set as the panel’s array of allowed file types.

Discussion

The parameter must not be empty. A file type is an extension to be appended to any selected files that don’t already have that extension; “nib” and “rtf” are examples. The items in types should not include the period that begins the extension. File type strings encoding HFS file types are not valid values. Pass nil to allow any file type, which is the default.

Availability

Available in Mac OS X v10.3 and later.

Related Sample Code

TimelineToTC

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: YES specifies that the panel allows the user to save files with an extension that’s not in the list of allowed types; NO specifies otherwise.

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 Mac 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: YES specifies that the panel allows the user to create directories; NO specifies otherwise.

Availability

Available in Mac OS X v10.3 and later.

Related Sample Code

Declared In

NSSavePanel.h

setCanSelectHiddenExtension:

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

- (void)setCanSelectHiddenExtension:(BOOL)flag

Parameters

flag: YES specifies that the panel allows the user to hide or show extensions; NO specifies otherwise.

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 Mac 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)anObject

Parameters

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

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

Declared In

NSSavePanel.h

setDirectory:

Sets the current pathname in the panel’s browser.

- (void)setDirectory:(NSString *)path

Parameters

path: String to set as the panel’s current pathname.

Discussion

The path argument must be an absolute pathname.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

Declared In

NSSavePanel.h

setExtensionHidden:

Sets the value of the extension-hiding checkbox.

- (void)setExtensionHidden:(BOOL)flag

Parameters

flag: YES specifies that the extension-hiding checkbox is visible and checked; NO specifies otherwise.

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 Mac OS X v10.1 and later.

Related Sample Code

Fiendishthngs

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 Mac 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 Mac OS X v10.3 and later.

Related Sample Code

CustomSave

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 Mac OS X v10.0 and later.

Related Sample Code

Declared In

NSSavePanel.h

setRequiredFileType:

Specifies the type, an extension to be appended to any selected files that don’t already have that extension; “nib” and “rtf” are examples.

- (void)setRequiredFileType:(NSString *)type

Parameters

type: String to set as the extension to be appended to any selected files that don’t already have that extension.

Discussion

The argument type should not include the period that begins the extension. Pass nil to indicate any type. File type strings encoding HFS file types are not valid values for this attribute. You need to invoke this method each time the Save panel is used for another file type within the application.

This method is equivalent to calling setAllowedFileTypes: with an array containing only type (unless type is nil, and then it’s equivalent to calling setAllowedFileTypes: with nil).

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

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 Mac 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: YES specifies that the panel will display file packages as directories; NO specifies otherwise.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

Declared In

NSSavePanel.h

title

Returns the title of the panel.

- (NSString *)title

Return Value

The title of the panel.

Availability

Available in Mac 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; NO otherwise.

Availability

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

Declared In

NSSavePanel.h

Delegate Methods

panel:compareFilename:with:caseSensitive:

Controls the ordering of files presented by the NSSavePanel object specified.

- (NSComparisonResult)panel:(id)sender compareFilename:(NSString *)fileName1 with:(NSString *)fileName2 caseSensitive:(BOOL)flag

Parameters

sender: Panel requesting the ordering.
fileName1: String representing the first filename to order.
fileName2: String representing the second filename to order.
flag: YES specifies that the ordering is to be case-sensitive; NO specifies otherwise.

Return Value

One of the following:

NSOrderedAscending if fileName1 should precede fileName2
NSOrderedSame if the two names are equivalent
NSOrderedDescending if fileName2 should precede fileName1

Discussion

Don’t reorder filenames in the Save panel without good reason, because it may confuse the user to have files in one Save panel or Open panel ordered differently than those in other such panels or in the Finder. The default behavior of Save and Open panels is to order files as they appear in the Finder. Note also that by implementing this method you will reduce the operating performance of the panel.

Availability

Available in Mac OS X v10.0 and later.

Declared In

NSSavePanel.h

panel:directoryDidChange:

Tells the delegate that the user has changed the selected directory in the NSSavePanel object specified.

- (void)panel:(id)sender directoryDidChange:(NSString *)path

Parameters

sender: Panel whose directory has changed.
path: String representing the new directory’s path.

Availability

Available in Mac OS X v10.3 and later.

Declared In

NSSavePanel.h

panel:isValidFilename:

Gives the delegate the opportunity to validate selected items.

- (BOOL)panel:(id)sender isValidFilename:(NSString *)filename

Parameters

sender: Panel requesting filename validation.
filename: String representing the filename to validate.

Return Value

YES if the filename is valid, or NO if the save panel should stay in its modal loop and wait for the user to type in or select a different filename or names.

Discussion

The NSSavePanel object sender sends this message just before the end of a modal session for each filename displayed or selected (including filenames in multiple selections). If the delegate refuses a filename in a multiple selection, none of the filenames in the selection is accepted.

Availability

Available in Mac OS X v10.0 and later.

Declared In

NSSavePanel.h

panel:shouldShowFilename:

Gives the delegate the opportunity to filter items that it doesn’t want the user to choose.

- (BOOL)panel:(id)sender shouldShowFilename:(NSString *)filename

Parameters

sender: Panel that is querying whether it should show a certain file.
filename: String representing the name of the file to be loaded in the browser.

Return Value

YES if filename should be selectable, and NO if the save panel should disable the file or directory.

Discussion

The NSSavePanel object sender sends this message to the panel’s delegate for each file or directory (filename) it is about to load in the browser.

Availability

Available in Mac OS X v10.0 and later.

Declared In

NSSavePanel.h

panel:userEnteredFilename:confirmed:

Tells the delegate that the user confirmed a filename choice by hitting OK or Return in the Save panel.

- (NSString *)panel:(id)sender userEnteredFilename:(NSString *)filename confirmed:(BOOL)okFlag

Parameters

sender: Panel reporting the user’s confirmation of a filename choice.
filename: String representing the filename the user chose.
okFlag: YES specifies the user clicked the OK button; NO specifies otherwise.

Return Value

String representing the filename that should be used for saving.

Discussion

You can either leave the filename alone, return a new filename, or return nil to cancel the save (and leave the Save panel as is). This method is sent before any required extension is appended to the filename and before the Save panel asks the user whether to replace an existing file.

Note that in the future, this method may be called multiple times in the sessions as the user types. In those cases, okFlag will be NO until the user confirms the choice, in which case okFlag will become YES. If the delegate does extensive validation or puts up alerts, it should do so only when okFlag is YES.

Availability

Available in Mac OS X v10.0 and later.

Declared In

NSSavePanel.h

panel:willExpand:

Tells the delegate that the Save panel is about to expand or collapse because the user clicked the disclosure triangle that displays or hides the file browser.

- (void)panel:(id)sender willExpand:(BOOL)expanding

Parameters

sender: Panel that is about to expand or collapse.
expanding: YES specifies that the panel is expanding; NO specifies that it is collapsing.

Availability

Available in Mac OS X v10.0 and later.

Declared In

NSSavePanel.h

panelSelectionDidChange:

Tells the delegate that the user changed the selection in the specified Save panel.

- (void)panelSelectionDidChange:(id)sender

Parameters

sender: Panel whose selection has changed.

Availability

Available in Mac OS X v10.3 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 Mac OS X v10.0 and later.

Declared in NSSavePanel.h.

NSFileHandlingPanelOKButton

The OK button.

Available in Mac OS X v10.0 and later.

Declared in NSSavePanel.h.

NSFileHandlingPanelImageButton

Deleted in Mac OS X v10.3.