Inherits from | |
Conforms to | |
Framework | /System/Library/Frameworks/AppKit.framework |
Availability | Available in Mac OS X v10.0 and later. |
Declared in | NSSavePanel.h |
Companion guides | |
Related sample code |
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.
– accessoryView
– setAccessoryView:
– title
– setTitle:
– prompt
– setPrompt:
– nameFieldLabel
– setNameFieldLabel:
– message
– setMessage:
– canCreateDirectories
– setCanCreateDirectories:
– delegate
– setDelegate:
– isExtensionHidden
– setExtensionHidden:
– requiredFileType
– setRequiredFileType:
– canSelectHiddenExtension
– setCanSelectHiddenExtension:
– allowedFileTypes
– setAllowedFileTypes:
– allowsOtherFileTypes
– setAllowsOtherFileTypes:
– treatsFilePackagesAsDirectories
– setTreatsFilePackagesAsDirectories:
– beginSheetForDirectory:file:modalForWindow:modalDelegate:didEndSelector:contextInfo:
– runModal
– runModalForDirectory:file:
– panel:compareFilename:with:caseSensitive:
delegate method
– panel:isValidFilename:
delegate method
– panel:userEnteredFilename:confirmed:
delegate method
– validateVisibleColumns
– panel:shouldShowFilename:
delegate method
– panel:willExpand:
delegate method
– panel:directoryDidChange:
delegate method
– panelSelectionDidChange:
delegate method
– selectText:
Deprecated in Mac OS X v10.3
Returns a Save panel that has been initialized with default values.
+ (NSSavePanel *)savePanel
The initialized Save panel.
NSSavePanel.h
Returns the custom accessory view for the current application.
- (NSView *)accessoryView
The custom accessory view for the current application.
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.
NSSavePanel.h
Returns an array of the allowed file types.
- (NSArray *)allowedFileTypes
An array of the allowed file types.
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.
NSSavePanel.h
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
YES
if the panel allows the user to save files with an extension that’s not in the list of allowed types; NO
otherwise.
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
.
NSSavePanel.h
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
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.
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.
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.
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.
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
.
Context information passed to modalDelegate in the didEndSelector message.
NSSavePanel.h
This action method is invoked when the user clicks the panel’s Cancel button.
- (IBAction)cancel:(id)sender
The NSSavePanel
object whose Cancel button was clicked.
NSSavePanel.h
Returns a Boolean value that indicates whether the panel allows the user to create directories.
- (BOOL)canCreateDirectories
YES
when the panel allows the user to create directories; NO
otherwise.
The default value is YES
.
NSSavePanel.h
Returns a Boolean value that indicates whether the panel allows the user to hide or show extensions.
- (BOOL)canSelectHiddenExtension
YES
when the panel allows the user to hide or show extensions; NO
otherwise.
NSSavePanel.h
Returns the panel’s delegate.
- (id)delegate
The panel’s delegate.
NSSavePanel.h
Returns the absolute pathname of the directory currently shown in the panel.
- (NSString *)directory
The absolute pathname of the directory currently shown in the panel.
NSSavePanel.h
Returns the absolute pathname of the file currently shown in the panel.
- (NSString *)filename
The absolute pathname of the file.
NSSavePanel.h
Returns a Boolean value that indicates whether the panel is expanded.
- (BOOL)isExpanded
YES
if the panel is expanded; NO
otherwise.
NSSavePanel.h
Returns a Boolean value that indicates whether the extension-hiding checkbox is visible and checked.
- (BOOL)isExtensionHidden
YES
when the extension-hiding checkbox is visible and checked; NO
otherwise.
NSSavePanel.h
Returns the message displayed in the save panel.
- (NSString *)message
The message displayed in the save panel.
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.
NSSavePanel.h
Returns the string displayed in front of the filename text field.
- (NSString *)nameFieldLabel
The string displayed in front of the filename text field.
By default the label is “Save As:”.
NSSavePanel.h
This action method is invoked when the user clicks the panel’s OK button.
- (IBAction)ok:(id)sender
The NSSavePanel
object whose OK button was clicked.
NSSavePanel.h
Returns the prompt of the default button.
- (NSString *)prompt
The prompt of the default button.
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.
NSSavePanel.h
Returns the required file type (if any).
- (NSString *)requiredFileType
The required file type (if any).
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.
NSSavePanel.h
Displays the panel and begins its event loop with the current working (or last selected) directory as the default starting point.
- (NSInteger)runModal
NSFileHandlingPanelOKButton
(if the user clicks the OK button) or NSFileHandlingPanelCancelButton
(if the user clicks the Cancel button).
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.
– runModalForDirectory:file:
– runModalForWindow:
(NSApplication
)NSSavePanel.h
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
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.
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.
NSFileHandlingPanelOKButton
(if the user clicks the OK button) or NSFileHandlingPanelCancelButton
(if the user clicks the Cancel button).
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.
– runModal
– runModalForWindow:
(NSApplication
)NSSavePanel.h
Customizes the panel for the application by adding a custom view to the panel.
- (void)setAccessoryView:(NSView *)aView
View to set as the panel’s accessory view.
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.
NSSavePanel.h
Specifies the allowed file types for the panel.
- (void)setAllowedFileTypes:(NSArray *)types
Array to set as the panel’s array of allowed file types.
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.
NSSavePanel.h
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
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.
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
.
NSSavePanel.h
Sets whether the panel allows the user to create directories.
- (void)setCanCreateDirectories:(BOOL)flag
YES
specifies that the panel allows the user to create directories; NO
specifies otherwise.
NSSavePanel.h
Sets whether the panel allows the user to hide or show extensions.
- (void)setCanSelectHiddenExtension:(BOOL)flag
YES
specifies that the panel allows the user to hide or show extensions; NO
specifies otherwise.
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.
NSSavePanel.h
Sets an object as the panel’s delegate, after verifying which delegate methods are implemented.
- (void)setDelegate:(id)anObject
Object to set as the panel’s delegate.
NSSavePanel.h
Sets the current pathname in the panel’s browser.
- (void)setDirectory:(NSString *)path
String to set as the panel’s current pathname.
The path argument must be an absolute pathname.
NSSavePanel.h
Sets the value of the extension-hiding checkbox.
- (void)setExtensionHidden:(BOOL)flag
YES
specifies that the extension-hiding checkbox is visible and checked; NO
specifies otherwise.
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.
NSSavePanel.h
Sets the message text displayed in the panel.
- (void)setMessage:(NSString *)message
String to set as the panel’s message.
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.
NSSavePanel.h
Sets the text displayed in front of the text field.
- (void)setNameFieldLabel:(NSString *)label
String to set as the text displayed in front of the panel’s text field.
By default the label is “Save As:”.
NSSavePanel.h
Sets the prompt of the default button.
- (void)setPrompt:(NSString *)prompt
String to set as the prompt of the panel’s default button.
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.
NSSavePanel.h
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
String to set as the extension to be appended to any selected files that don’t already have that extension.
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
).
NSSavePanel.h
Sets the title of the panel.
- (void)setTitle:(NSString *)title
String to set as the panel’s title.
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.
NSSavePanel.h
Sets the panel’s behavior for displaying file packages (for example, MyApp.app
) to the user.
- (void)setTreatsFilePackagesAsDirectories:(BOOL)flag
YES
specifies that the panel will display file packages as directories; NO
specifies otherwise.
NSSavePanel.h
Returns the title of the panel.
- (NSString *)title
The title of the panel.
NSSavePanel.h
Returns a Boolean value that indicates whether the panel displays file packages as directories.
- (BOOL)treatsFilePackagesAsDirectories
YES
if the panel displays file packages as directories; NO
otherwise.
NSSavePanel.h
Returns the absolute pathname of the file currently shown in the panel as a URL.
- (NSURL *)URL
The absolute pathname of the file currently shown in the panel as a URL.
NSSavePanel.h
Validates and possibly reloads the browser columns visible in the panel by invoking the delegate method panel:shouldShowFilename:
.
- (void)validateVisibleColumns
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.
NSSavePanel.h
Controls the ordering of files presented by the NSSavePanel
object specified.
- (NSComparisonResult)panel:(id)sender compareFilename:(NSString *)fileName1 with:(NSString *)fileName2 caseSensitive:(BOOL)flag
Panel requesting the ordering.
String representing the first filename to order.
String representing the second filename to order.
YES
specifies that the ordering is to be case-sensitive; NO
specifies otherwise.
One of the following:
NSOrderedAscending
if fileName1 should precede fileName2
NSOrderedSame
if the two names are equivalent
NSOrderedDescending
if fileName2 should precede fileName1
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.
NSSavePanel.h
Tells the delegate that the user has changed the selected directory in the NSSavePanel
object specified.
- (void)panel:(id)sender directoryDidChange:(NSString *)path
Panel whose directory has changed.
String representing the new directory’s path.
NSSavePanel.h
Gives the delegate the opportunity to validate selected items.
- (BOOL)panel:(id)sender isValidFilename:(NSString *)filename
Panel requesting filename validation.
String representing the filename to validate.
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.
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.
NSSavePanel.h
Gives the delegate the opportunity to filter items that it doesn’t want the user to choose.
- (BOOL)panel:(id)sender shouldShowFilename:(NSString *)filename
Panel that is querying whether it should show a certain file.
String representing the name of the file to be loaded in the browser.
YES
if filename should be selectable, and NO
if the save panel should disable the file or directory.
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.
NSSavePanel.h
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
Panel reporting the user’s confirmation of a filename choice.
String representing the filename the user chose.
YES
specifies the user clicked the OK button; NO
specifies otherwise.
String representing the filename that should be used for saving.
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
.
NSSavePanel.h
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
Panel that is about to expand or collapse.
YES
specifies that the panel is expanding; NO
specifies that it is collapsing.
NSSavePanel.h
Tells the delegate that the user changed the selection in the specified Save panel.
- (void)panelSelectionDidChange:(id)sender
Panel whose selection has changed.
NSSavePanel.h
Button tags that refer to items on the panel.
enum { NSFileHandlingPanelCancelButton = NSCancelButton, NSFileHandlingPanelOKButton = NSOKButton };
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.
Available in Mac OS X v10.0 through Mac OS X v10.2.
Declared in NSSavePanel.h
.
NSFileHandlingPanelTitleField
Deleted in Mac OS X v10.3.
Available in Mac OS X v10.0 through Mac OS X v10.2.
Declared in NSSavePanel.h
.
NSFileHandlingPanelBrowser
Deleted in Mac OS X v10.3.
Available in Mac OS X v10.0 through Mac OS X v10.2.
Declared in NSSavePanel.h
.
NSFileHandlingPanelForm
Deleted in Mac OS X v10.3.
Available in Mac OS X v10.0 through Mac OS X v10.2.
Declared in NSSavePanel.h
.
NSFileHandlingPanelHomeButton
Deleted in Mac OS X v10.3.
Available in Mac OS X v10.0 through Mac OS X v10.2.
Declared in NSSavePanel.h
.
NSFileHandlingPanelDiskButton
Deleted in Mac OS X v10.3.
Available in Mac OS X v10.0 through Mac OS X v10.2.
Declared in NSSavePanel.h
.
NSFileHandlingPanelDiskEjectButton
Deleted in Mac OS X v10.3.
Available in Mac OS X v10.0 through Mac OS X v10.2.
Declared in NSSavePanel.h
.
NSSavePanel.h
© 2009 Apple Inc. All Rights Reserved. (Last updated: 2009-02-04)