Next Page >

Hide TOC

NSSavePanel Class Reference

Inherits from	NSPanel : NSWindow : NSResponder : NSObject
Conforms to	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

Overview

NSSavePanel 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 an NSSavePanel object.

+ (NSSavePanel *)savePanel

Return Value

An initialized NSSavePanel object.

Discussion

The save panel has been initialized with default values.

Availability

Available in Mac OS X v10.0 and later.

Declared In

NSSavePanel.h

Instance Methods

accessoryView

Returns the custom accessory view for the current application.

- (NSView *)accessoryView

Discussion

This view is set by setAccessoryView:.

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

Discussion

If the user specifies a file whose type is in the array of allowed types, they will not be 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 receiver allows the user to save files with an extension that’s not in the list of allowed types.

- (BOOL)allowsOtherFileTypes

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 the directory specified by path and optionally, the file specified by name selected.

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

Discussion

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

The didEndSelector method must be implemented by the modalDelegate. This method is invoked, passing contextInfo as an argument, after the modal session has ended, but before dismissing the Save panel. didEndSelector may dismiss the Save panel itself; otherwise it will be dismissed on return from the method. modalDelegate is not the same as a delegate assigned to the panel. Modal delegates in sheets are temporary and the relationship only lasts until the sheet is dismissed. The NSSavePanel object does not retain the modal delegate.

didEndSelector should have the following signature:

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

The value passed as returnCode will be either NSCancelButton or NSOKButton.

Availability

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

Availability

Available in Mac OS X v10.0 and later.

Declared In

NSSavePanel.h

canCreateDirectories

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

- (BOOL)canCreateDirectories

Availability

Available in Mac OS X v10.3 and later.

Declared In

NSSavePanel.h

canSelectHiddenExtension

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

- (BOOL)canSelectHiddenExtension

Availability

Available in Mac OS X v10.3 and later.

Declared In

NSSavePanel.h

delegate

Returns the receiver’s delegate.

- (id)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 receiver.

- (NSString *)filename

Availability

Available in Mac OS X v10.0 and later.

Declared In

NSSavePanel.h

isExpanded

Returns whether the receiver is expanded.

- (BOOL)isExpanded

Availability

Available in Mac OS X v10.0 and later.

Declared In

NSSavePanel.h

isExtensionHidden

Returns YES if the extension-hiding checkbox is visible and checked.

- (BOOL)isExtensionHidden

Discussion

Returns NO otherwise.

Availability

Available in Mac OS X v10.1 and later.

Declared In

NSSavePanel.h

message

Returns the message displayed in the save panel.

- (NSString *)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 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

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

Availability

Available in Mac OS X v10.0 and later.

Declared In

NSSavePanel.h

prompt

Returns the prompt of the default button.

- (NSString *)prompt

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

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 receiver and begins its event loop with the current working (or last selected) directory as the default starting point.

- (NSInteger)runModal

Discussion

Invokes runModalForDirectory:file: (file argument is an empty NSString object), which in turn performs NSApplication‘s runModalForWindow: method with self as the argument. Returns NSFileHandlingPanelOKButton (if the user clicks the OK button) or NSFileHandlingPanelCancelButton (if the user clicks the Cancel button). 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.

Declared In

NSSavePanel.h

runModalForDirectory:file:

Initializes the receiver to the directory specified by path and, optionally, the file specified by filename, then displays it and begins its modal event loop; path and filename can be empty strings.

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

Discussion

If path is nil, the previous directory the Save panel was in is used. This method invokes NSApplication’s runModalForWindow: method with self as the argument. Returns NSFileHandlingPanelOKButton (if the user clicks the OK button) or NSFileHandlingPanelCancelButton (if the user clicks the Cancel button). 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.

Declared In

NSSavePanel.h

setAccessoryView:

Customizes the panel for the application by adding a custom NSView (aView) to the panel.

- (void)setAccessoryView:(NSView *)aView

Discussion

The custom NSView that’s 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.

Declared In

NSSavePanel.h

setAllowedFileTypes:

Specifies the allowed file types for the receiver.

- (void)setAllowedFileTypes:(NSArray *)types

Discussion

types may 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.

Declared In

NSSavePanel.h

setAllowsOtherFileTypes:

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

- (void)setAllowsOtherFileTypes:(BOOL)flag

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.

Declared In

NSSavePanel.h

setCanCreateDirectories:

Sets whether the receiver allows the user to create directories.

- (void)setCanCreateDirectories:(BOOL)flag

Availability

Available in Mac OS X v10.3 and later.

Declared In

NSSavePanel.h

setCanSelectHiddenExtension:

Sets whether the receiver allows the user to hide or show extensions to flag.

- (void)setCanSelectHiddenExtension:(BOOL)flag

Discussion

This method must be called before the panel is displayed.

Availability

Available in Mac OS X v10.1 and later.

Declared In

NSSavePanel.h

setDelegate:

Makes anObject the receiver’s delegate, after verifying which delegate methods are implemented.

- (void)setDelegate:(id)anObject

Availability

Available in Mac OS X v10.0 and later.

Declared In

NSSavePanel.h

setDirectory:

Sets the current pathname in the receiver’s browser.

- (void)setDirectory:(NSString *)path

Discussion

The path argument must be an absolute pathname.

Availability

Available in Mac OS X v10.0 and later.

Declared In

NSSavePanel.h

setExtensionHidden:

Sets the value of the extension-hiding checkbox to flag.

- (void)setExtensionHidden:(BOOL)flag

Discussion

This method should rarely be used since 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.

Declared In

NSSavePanel.h

setMessage:

Sets the message text displayed in the panel.

- (void)setMessage:(NSString *)message

Discussion

Availability

Available in Mac OS X v10.3 and later.

Declared In

NSSavePanel.h

setNameFieldLabel:

Sets the text displayed in front of the text field to label.

- (void)setNameFieldLabel:(NSString *)label

Discussion

By default the label is “Save As:”.

Availability

Available in Mac OS X v10.3 and later.

Declared In

NSSavePanel.h

setPrompt:

Sets the prompt of the default button.

- (void)setPrompt:(NSString *)prompt

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.

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

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.

Declared In

NSSavePanel.h

setTitle:

Sets the title of the receiver to title.

- (void)setTitle:(NSString *)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.

Declared In

NSSavePanel.h

setTreatsFilePackagesAsDirectories:

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

- (void)setTreatsFilePackagesAsDirectories:(BOOL)flag

Discussion

If flag is YES, the user is shown files and subdirectories within a file package. If NO, the receiver shows each file package as a file, thereby giving no indication that it is a directory.

Availability

Available in Mac OS X v10.0 and later.

Declared In

NSSavePanel.h

title

Returns the title of the receiver.

- (NSString *)title

Availability

Available in Mac OS X v10.0 and later.

Declared In

NSSavePanel.h

treatsFilePackagesAsDirectories

Returns a Boolean value that indicates whether the receiver displays file packages to the user as directories.

- (BOOL)treatsFilePackagesAsDirectories

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 receiver as a URL.

- (NSURL *)URL

Availability

Available in Mac OS X v10.0 and later.

Declared In

NSSavePanel.h

validateVisibleColumns

Validates and possibly reloads the browser columns visible in the receiver 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 sender.

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

Discussion

This method should return:

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

The flag argument, if YES, indicates that the ordering is to be case-sensitive.

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:

Sent when the user has changed the selected directory in the NSSavePanel object sender.

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

Discussion

path contains the newly selected directory.

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

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). The delegate determines whether it wants the file identified by filename; it returns 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. 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

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. The delegate returns YES if filename should be selectable, and NO if the save panel should disable the file or directory.

Availability

Available in Mac OS X v10.0 and later.

Declared In

NSSavePanel.h

panel:userEnteredFilename:confirmed:

Sent when the user confirms a filename choice by hitting OK or Return in the NSSavePanel object sender.

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

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:

Sent when the NSSavePanel object sender 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

Availability

Available in Mac OS X v10.0 and later.

Declared In

NSSavePanel.h

panelSelectionDidChange:

Sent when the user has changed the selection in the NSSavePanel object sender.

- (void)panelSelectionDidChange:(id)sender

Availability

Available in Mac OS X v10.3 and later.

Declared In

NSSavePanel.h

Constants

Button tags

NSSavePanel defines these constants to 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.