Mac Developer Library

Developer

AppKit Framework Reference NSSavePanel Class Reference

Options
Deployment Target:

On This Page
Language:

NSSavePanel

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.

Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.0 and later.
  • Returns a Save panel that has been initialized with default values.

    Declaration

    Objective-C

    + (NSSavePanel *)savePanel

    Return Value

    The initialized Save panel.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

  • The custom accessory view for the current application.

    Declaration

    Swift

    var accessoryView: NSView?

    Objective-C

    @property(strong) NSView *accessoryView

    Discussion

    You can customize the panel by adding a custom 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 accessoryView. You can use this property to change the accessory view as needed. If accessoryView is nil, the Save panel removes the current accessory view.

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • title title Property

    The title of the panel.

    Declaration

    Swift

    var title: String?

    Objective-C

    @property(copy) 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • prompt prompt Property

    The prompt of the default button.

    Declaration

    Swift

    var prompt: String?

    Objective-C

    @property(copy) NSString *prompt

    Discussion

    The prompt appears on all NSSavePanel objects (or all NSOpenPanel objects if this property is on 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The string displayed in front of the filename text field.

    Declaration

    Swift

    var nameFieldLabel: String?

    Objective-C

    @property(copy) NSString *nameFieldLabel

    Discussion

    The default value of this property is “Save As:”.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • message message Property

    The message text displayed in the save panel.

    Declaration

    Swift

    var message: String?

    Objective-C

    @property(copy) NSString *message

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • A Boolean value that indicates whether the panel allows the user to create directories.

    Declaration

    Swift

    var canCreateDirectories: Bool

    Objective-C

    @property BOOL canCreateDirectories

    Discussion

    When the value of this property is YEStrue, the panel allows the user to create directories; if NOfalse, the panel does not.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • A Boolean value that indicates whether the panel displays files that are normally hidden from the user.

    Declaration

    Swift

    var showsHiddenFiles: Bool

    Objective-C

    @property BOOL showsHiddenFiles

    Discussion

    When the value of this property is YEStrue, the panel displays hidden files; if NOfalse, it does not. The default value is NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.

  • delegate delegate Property

    The panel’s delegate.

    Declaration

    Swift

    unowned(unsafe) var delegate: NSOpenSavePanelDelegate?

    Objective-C

    @property(assign) id< NSOpenSavePanelDelegate > delegate

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • A Boolean value that indicates whether the panel displays the Tags field.

    Declaration

    Swift

    var showsTagField: Bool

    Objective-C

    @property BOOL showsTagField

    Discussion

    When the value of this property is YEStrue, the panel displays the Tags field; if NOfalse, the panel doesn’t display the Tags field. The default value is YEStrue. (Note that the Tags field is appropriate only in a Save panel.)

    If you set this property to YEStrue, you are responsible for setting tag names on the resulting file after saving is complete. If you don’t set this property, 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.)

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.9 and later.

  • tagNames tagNames Property

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

    Declaration

    Swift

    var tagNames: [AnyObject]?

    Objective-C

    @property(copy) NSArray *tagNames

    Discussion

    When the value of showsTagField is YEStrue, use this property to provide an array of strings that represent the inital set of tag names to display in the panel. If you set the property to nil or an empty array, no initial tag names are displayed in the panel. (Note that the Tags field is appropriate only in a Save panel.)

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.9 and later.

  • A Boolean value that indicates whether the extension-hiding checkbox is visible and checked.

    Declaration

    Swift

    var extensionHidden: Bool

    Objective-C

    @property(getter=isExtensionHidden) BOOL extensionHidden

    Discussion

    When the value of this property is YEStrue, the extension-hiding checkbox is visible and checked. You should rarely set this property, because the state is saved on a per-application basis. Setting this property has no effect if the user has chosen to show all file extensions in Finder.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.10 and later.

  • Returns the required file type (if any).

    Deprecation Statement

    Use allowedFileTypes instead.

    Declaration

    Objective-C

    - (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 using allowedFileTypes and returning the first element of the list of allowed types, or nil if there are none.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    See Also

    allowedFileTypes

  • Specifies the file type (as an extension) or a UTI.

    Deprecation Statement

    Use allowedFileTypes instead.

    Declaration

    Objective-C

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

    If type is an extension, it 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 using allowedFileTypes with an array containing only type (unless type is nil, and then it’s equivalent to setting the property to nil).

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    See Also

    allowedFileTypes

  • The directory shown in the panel as a URL.

    Declaration

    Swift

    @NSCopying var directoryURL: NSURL?

    Objective-C

    @property(copy) NSURL *directoryURL

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.

  • Sets the current pathname in the panel’s browser.

    Deprecation Statement

    Use directoryURL instead.

    Declaration

    Objective-C

    - (void)setDirectory:(NSString *)path

    Parameters

    path

    String to set as the panel’s current pathname.

    Discussion

    The path argument must be an absolute pathname.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    See Also

    directoryURL

  • A Boolean value that indicates whether the panel allows the user to hide or show file extensions.

    Declaration

    Swift

    var canSelectHiddenExtension: Bool

    Objective-C

    @property BOOL canSelectHiddenExtension

    Discussion

    When the value of this property is YEStrue, the panel allows the user to hide or show extensions; if NOfalse, it does not. The default value is NOfalse.

    This property must be set before the panel is displayed. If set to YEStrue, the extensionHidden property can be used to get and set the value of the checkbox that hides or shows extensions.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • An array of NSString objects specifying the allowed file types for the panel.

    Declaration

    Swift

    var allowedFileTypes: [AnyObject]?

    Objective-C

    @property(copy) NSArray *allowedFileTypes

    Discussion

    The value of this property specifies the file types the user can save the file as. A file type can be a common file extension, or a UTI. The default value of this property is nil, which indicates that any file type can be used. (Note that if the array is not nil and the array contains no items, an exception is raised.)

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

    NSOpenPanel: In versions of OS X earlier 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. You should not use the deprecated methods to show the open panel (that is, the methods that take a types: parameter) because they will overwrite this value. The allowed file types can be changed while the panel is running (for example, from an accessory view). This is also known as the “enabled file types.” A nil value indicates that all files should be enabled.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • 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.

    Declaration

    Swift

    var allowsOtherFileTypes: Bool

    Objective-C

    @property BOOL allowsOtherFileTypes

    Discussion

    When the value of this property is YEStrue, the panel allows the user to save files with an extension that’s not in the list of allowed types. The default value is NOfalse.

    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 the value of this property is YEStrue, then the dialog presents the option of using the extension the user specified.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • A Boolean value that indicates whether the panel displays file packages as directories.

    Declaration

    Swift

    var treatsFilePackagesAsDirectories: Bool

    Objective-C

    @property BOOL treatsFilePackagesAsDirectories

    Discussion

    When the value of this property is YEStrue, the panel displays file packages as directories; if NOfalse, it will not.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Deprecation Statement

    Use beginSheetModalForWindow:completionHandler: instead.

    Declaration

    Objective-C

    - (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 has a weak reference to 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.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

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

    Declaration

    Swift

    func beginSheetModalForWindow(_ window: NSWindow, completionHandler handler: (Int) -> Void)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.

  • Presents the panel as a modeless window.

    Declaration

    Swift

    func beginWithCompletionHandler(_ handler: (Int) -> Void)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.

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

    Declaration

    Swift

    func runModal() -> Int

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    runModalForWindow: (NSApplication)

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

    Deprecation Statement

    Use runModal instead.

    Declaration

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    See Also

    – runModal
    runModalForWindow: (NSApplication)

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

    Deprecation Statement

    There is no replacement.

    Declaration

    Objective-C

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

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Gives the delegate the opportunity to validate selected items.

    Deprecation Statement

    Use panel:validateURL:error: (NSOpenSavePanelDelegate) instead. If both methods are implemented, the URL version will be called.

    Declaration

    Objective-C

    - (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). If the delegate refuses a filename in a multiple selection, none of the filenames in the selection is accepted.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    See Also

    panel:validateURL:error: (NSOpenSavePanelDelegate)

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

    Declaration

    Swift

    func validateVisibleColumns()

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Deprecation Statement

    Use panel:shouldEnableURL: (NSOpenSavePanelDelegate).

    Declaration

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    See Also

    panel:shouldEnableURL: (NSOpenSavePanelDelegate).

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

    Deprecation Statement

    Use panel:didChangeToDirectoryURL: (NSOpenSavePanelDelegate) instead.

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.3 and later.

    Deprecated in OS X v10.6.

    See Also

    panel:didChangeToDirectoryURL: (NSOpenSavePanelDelegate)

  • directory - directory (OS X v10.6)

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

    Deprecation Statement

    Use directoryURL instead.

    Declaration

    Objective-C

    - (NSString *)directory

    Return Value

    The absolute pathname of the directory currently shown in the panel.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    See Also

    directoryURL

  • filename - filename (OS X v10.6)

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

    Deprecation Statement

    Use URL instead.

    Declaration

    Objective-C

    - (NSString *)filename

    Return Value

    The absolute pathname of the file.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    See Also

    URL

  • URL URL Property

    The absolute pathname of the file currently shown in the panel as a URL. (read-only)

    Declaration

    Swift

    @NSCopying var URL: NSURL? { get }

    Objective-C

    @property(readonly, copy) NSURL *URL

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • expanded expanded Property

    A Boolean value that indicates whether the panel is expanded. (read-only)

    Declaration

    Swift

    var expanded: Bool { get }

    Objective-C

    @property(getter=isExpanded, readonly) BOOL expanded

    Discussion

    The value of this property is YEStrue if the panel is expanded; otherwise, NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.10 and later.

  • The user-editable filename currently shown in the name field.

    Declaration

    Swift

    var nameFieldStringValue: String

    Objective-C

    @property(copy) NSString *nameFieldStringValue

    Discussion

    The value of this property must not be nil. Note that the filename may not display an extension if the value of extensionHidden is YEStrue.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.

  • selectText: - selectText: (OS X v10.3)

    This method has been deprecated.

    Deprecation Statement

    There is no replacement.

    Declaration

    Objective-C

    - (IBAction)selectText:(id)sender

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.3.

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

    Declaration

    Swift

    @IBAction func ok(_ sender: AnyObject?)

    Objective-C

    - (IBAction)ok:(id)sender

    Parameters

    sender

    The NSSavePanel object whose OK button was clicked.

    Discussion

    Sandboxed apps cannot programmatically invoke the OK button.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – cancel:

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

    Declaration

    Swift

    @IBAction func cancel(_ sender: AnyObject?)

    Objective-C

    - (IBAction)cancel:(id)sender

    Parameters

    sender

    The NSSavePanel object whose Cancel button was clicked.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – ok:

  • Button tags that refer to items on the panel.

    Declaration

    Swift

    var NSFileHandlingPanelCancelButton: Int { get } var NSFileHandlingPanelOKButton: Int { get }

    Objective-C

    enum { NSFileHandlingPanelCancelButton = NSCancelButton, NSFileHandlingPanelOKButton = NSOKButton };

    Constants

    • NSFileHandlingPanelCancelButton

      NSFileHandlingPanelCancelButton

      The Cancel button.

      Available in OS X v10.0 and later.

    • NSFileHandlingPanelOKButton

      NSFileHandlingPanelOKButton

      The OK button.

      Available in OS X v10.0 and later.