NSSavePanel Class Reference

Overview

An NSSavePanel object creates and manages a Save panel and allows you to run the panel in a modal loop. The Save panel provides a simple way for a user to specify a file to use when saving a document or other data. It can restrict the user to files of a certain type, as specified by an extension.

An NSSavePanel object manages a panel that allows users to specify the directory and name under which a file is saved. It supports browsing of the file system, and it accommodates custom accessory views.

An NSSavePanel object may have a delegate. The methods that delegates of NSSavePanel may implement are specified by the NSOpenSavePanelDelegate protocol.

Tasks

Creating Panels

• + savePanel

Configuring Panels

• – accessoryView
• – setAccessoryView:
• – title
• – setTitle:
• – prompt
• – setPrompt:
• – nameFieldLabel
• – setNameFieldLabel:
• – message
• – setMessage:
• – canCreateDirectories
• – setCanCreateDirectories:
• – showsHiddenFiles
• – setShowsHiddenFiles:
• – delegate
• – setDelegate:

Configuring Panel Content

• – isExtensionHidden
• – setExtensionHidden:
• – canSelectHiddenExtension
• – setCanSelectHiddenExtension:
• – allowedFileTypes
• – setAllowedFileTypes:
• – allowsOtherFileTypes
• – setAllowsOtherFileTypes:
• – treatsFilePackagesAsDirectories
• – setTreatsFilePackagesAsDirectories:
• – requiredFileType Deprecated in Mac OS X v10.6
• – setRequiredFileType: Deprecated in Mac OS X v10.6

Running Panels

• – beginSheetModalForWindow:completionHandler:
• – beginWithCompletionHandler:
• – runModal
• – validateVisibleColumns
• – beginSheetForDirectory:file:modalForWindow:modalDelegate:didEndSelector:contextInfo: Deprecated in Mac OS X v10.6
• – runModalForDirectory:file: Deprecated in Mac OS X v10.6
• – panel:compareFilename:with:caseSensitive:  delegate method Deprecated in Mac OS X v10.6
• – panel:directoryDidChange:  delegate method Deprecated in Mac OS X v10.6
• – panel:isValidFilename:  delegate method Deprecated in Mac OS X v10.6
• – panel:shouldShowFilename:  delegate method Deprecated in Mac OS X v10.6

Accessing User Selection

• – directoryURL
• – setDirectoryURL:
• – URL
• – isExpanded
• – nameFieldStringValue
• – setNameFieldStringValue:
• – selectText: Deprecated in Mac OS X v10.3
• – directory Deprecated in Mac OS X v10.6
• – filename Deprecated in Mac OS X v10.6
• – setDirectory: Deprecated in Mac OS X v10.6

Handling Actions

• – ok:
• – cancel:

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

• CIVideoDemoGL
• ImageKitDemo
• QTAudioExtractionPanel
• Quartz Composer WWDC 2005 TextEdit
• WhackedTV

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 panel, the accessory view is released after the panel is closed. If you rely on the panel 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.

See Also

• – setAccessoryView:

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.

See Also

• – setAllowedFileTypes:

Declared In

NSSavePanel.h

allowsOtherFileTypes

Returns a Boolean value that indicates whether the panel allows the user to save files with an extension that’s not in the list of allowed types.

- (BOOL)allowsOtherFileTypes

Return Value

YES if the panel allows the user to save files with an extension that’s not in the list of allowed types; otherwise, NO.

Discussion

If the user tries to save a filename with a recognized extension that's not in the list of allowed types they are presented with a dialog. If this method returns YES, then the dialog presents the option of using the extension the user specified.

The default setting is NO.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – setAllowsOtherFileTypes:
• – allowedFileTypes

Declared In

NSSavePanel.h

beginSheetModalForWindow:completionHandler:

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

- (void)beginSheetModalForWindow:(NSWindow *)window completionHandler:(void (^)(NSInteger result))handler

Parameters

window

The window in which the panel will be presented.

handler

The block called after the user has closed the panel. The argument passed in will be NSFileHandlingPanelOKButton if the user chose the OK button or NSFileHandlingPanelCancelButton if the user chose the Cancel button.

Discussion

Any properties of the panel you wish to set should be set before calling this method.

Availability

• Available in Mac OS X v10.6 and later.

Related Sample Code

• Denoise
• DispatchFractal
• From A View to A Movie
• From A View to A Picture
• TextSizingExample

Declared In

NSSavePanel.h

beginWithCompletionHandler:

Presents the panel as a modeless window.

- (void)beginWithCompletionHandler:(void (^)(NSInteger result))handler

Parameters

handler

The block called after the user has closed the panel. The argument passed in will be NSFileHandlingPanelOKButton if the user chose the OK button or NSFileHandlingPanelCancelButton if the user chose the Cancel button.

Discussion

Any properties of the panel you wish to set should be set before calling this method.

Availability

• Available in Mac OS X v10.6 and later.

Declared In

NSSavePanel.h

cancel:

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

- (IBAction)cancel:(id)sender

Parameters

sender

The NSSavePanel object whose Cancel button was clicked.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – ok:

Declared In

NSSavePanel.h

canCreateDirectories

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

- (BOOL)canCreateDirectories

Return Value

YES when the panel allows the user to create directories; otherwise, NO.

Discussion

The default value is YES.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – setCanCreateDirectories:

Declared In

NSSavePanel.h

canSelectHiddenExtension

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

- (BOOL)canSelectHiddenExtension

Return Value

YES when the panel allows the user to hide or show extensions; otherwise, NO.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – setCanSelectHiddenExtension:

Declared In

NSSavePanel.h

delegate

Returns the panel’s delegate.

- (id <NSOpenSavePanelDelegate>)delegate

Return Value

The panel’s delegate.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – setDelegate:

Declared In

NSSavePanel.h

directoryURL

Returns the directory shown in the panel as a URL.

- (NSURL *)directoryURL

Return Value

The directory’s URL.

Availability

• Available in Mac OS X v10.6 and later.

See Also

• – setDirectoryURL:

Related Sample Code

• From A View to A Movie
• From A View to A Picture

Declared In

NSSavePanel.h

isExpanded

Returns a Boolean value that indicates whether the panel is expanded.

- (BOOL)isExpanded

Return Value

YES if the panel is expanded; otherwise, NO.

Availability

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

Availability

• Available in Mac OS X v10.1 and later.

See Also

• – setCanSelectHiddenExtension:
• – setExtensionHidden:

Related Sample Code

• Quartz Composer WWDC 2005 TextEdit

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.

See Also

• – setMessage:

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.

See Also

• – setNameFieldLabel:

Declared In

NSSavePanel.h

nameFieldStringValue

Returns the user-editable filename currently shown in the name field.

- (NSString *)nameFieldStringValue

Return Value

The filename currently selected.

Availability

• Available in Mac OS X v10.6 and later.

See Also

• – setNameFieldStringValue:

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.

See Also

• – cancel:

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.

See Also

• – setPrompt:

Declared In

NSSavePanel.h

runModal

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

- (NSInteger)runModal

Return Value

NSFileHandlingPanelOKButton (if the user clicks the OK button) or NSFileHandlingPanelCancelButton (if the user clicks the Cancel button).

Discussion

This method invokes NSApplication‘s runModalForWindow: method with self as the argument.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – runModalForWindow: (NSApplication)

Related Sample Code

• AudioDataOutputToAudioUnit
• QTKitProgressTester
• ThreadsExportMovie

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.

See Also

• – accessoryView

Related Sample Code

• ImageApp
• QTAudioContextInsert
• QTAudioExtractionPanel
• QTKitPlayer
• Quartz Composer WWDC 2005 TextEdit

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.

See Also

• – allowedFileTypes

Related Sample Code

• AudioDataOutputToAudioUnit
• ImageApp
• 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

If YES, the panel allows the user to save files with an extension that’s not in the list of allowed types; if NO, it does not.

Discussion

If the user tries to save a filename with a recognized extension that's not in the list of allowed types they are presented with a dialog. If allowsOtherFileTypes is YES, then the dialog presents the option of using the extension the user specified.

The default setting is NO.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – allowsOtherFileTypes
• – allowedFileTypes

Related Sample Code

• MassiveImage
• Quartz 2D Transformer
• Quartz Composer WWDC 2005 TextEdit

Declared In

NSSavePanel.h

setCanCreateDirectories:

Sets whether the panel allows the user to create directories.

- (void)setCanCreateDirectories:(BOOL)flag

Parameters

flag

If YES, the panel allows the user to create directories; if NO, the panel does not.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – canCreateDirectories

Related Sample Code

• GridCalendar
• OpenGLCaptureToMovie
• Quartz Composer QCTV
• WhackedTV

Declared In

NSSavePanel.h

setCanSelectHiddenExtension:

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

- (void)setCanSelectHiddenExtension:(BOOL)flag

Parameters

flag

If YES, the panel allows the user to hide or show extensions; if NO, it does not.

Discussion

This method must be called before the panel is displayed. If set to YES, isExtensionHidden and setExtensionHidden:, respectively, can be used to get and set the value of the checkbox that hides or shows extensions.

Availability

• Available in Mac OS X v10.1 and later.

See Also

• – canSelectHiddenExtension
• – isExtensionHidden
• – setExtensionHidden:

Related Sample Code

• AudioDataOutputToAudioUnit
• MassiveImage
• Quartz Composer QCTV
• Quartz Composer WWDC 2005 TextEdit
• WhackedTV

Declared In

NSSavePanel.h

setDelegate:

Sets an object as the panel’s delegate, after verifying which delegate methods are implemented.

- (void)setDelegate:(id <NSOpenSavePanelDelegate>)anObject

Parameters

anObject

Object to set as the panel’s delegate.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – delegate

Related Sample Code

• AudioBurn
• CIRAWFilterSample
• QTKitCreateMovie
• QTKitPlayer
• Quartz Composer WWDC 2005 TextEdit

Declared In

NSSavePanel.h

setDirectoryURL:

Sets the directory shown in the panel to the directory with the specified URL.

- (void)setDirectoryURL:(NSURL *)url

Parameters

url

The URL of the directory to set.

Availability

• Available in Mac OS X v10.6 and later.

See Also

• – directoryURL

Declared In

NSSavePanel.h

setExtensionHidden:

Sets the value of the extension-hiding checkbox.

- (void)setExtensionHidden:(BOOL)flag

Parameters

flag

If YES, the extension-hiding checkbox is visible and checked; if NO, it is not.

Discussion

This method should rarely be used because the state is saved on a per-application basis. Use this method to set whether a file’s extension should be indicated as being shown.

Availability

• Available in Mac OS X v10.1 and later.

See Also

• – setCanSelectHiddenExtension:
• – isExtensionHidden

Related Sample Code

• Fiendishthngs
• FunHouse

Declared In

NSSavePanel.h

setMessage:

Sets the message text displayed in the panel.

- (void)setMessage:(NSString *)message

Parameters

message

String to set as the panel’s message.

Discussion

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

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – message

Related Sample Code

• CustomSave
• Quartz 2D Transformer
• SBSetFinderComment
• TrackBall
• ViewController

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.

See Also

• – nameFieldLabel

Related Sample Code

• CustomSave

Declared In

NSSavePanel.h

setNameFieldStringValue:

Sets the filename in the name field to the specified value.

- (void)setNameFieldStringValue:(NSString *)value

Parameters

value

The filename to set. The value must not be nil.

Availability

• Available in Mac OS X v10.6 and later.

See Also

• – nameFieldStringValue

Declared In

NSSavePanel.h

setPrompt:

Sets the prompt of the default button.

- (void)setPrompt:(NSString *)prompt

Parameters

prompt

String to set as the prompt of the panel’s default button.

Discussion

This prompt appears on all NSSavePanel objects (or all NSOpenPanel objects if the receiver of this message is an NSOpenPanel instance) in your application. By default, the text in the default button is “Open” for an Open panel and “Save” for a Save panel.

It is intended that short words or phrases, such as “Open,” “Save,” “Set,” or “Choose,” be used on the button. The button is not resized to accommodate long prompts.

Since this method previously affected a title field, any colon at the end of prompt is removed.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – prompt

Related Sample Code

• AudioBurn
• CocoaSpeechSynthesisExample
• ContentBurn
• GridCalendar
• ObjectPath

Declared In

NSSavePanel.h

setShowsHiddenFiles:

Specifies whether the panel displays files that are normally hidden from the user.

- (void)setShowsHiddenFiles:(BOOL)flag

Parameters

flag

If YES, the panel displays hidden files; if NO, it does not.

Availability

• Available in Mac OS X v10.6 and later.

See Also

• – showsHiddenFiles

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.

See Also

• – title

Related Sample Code

• AudioBurn
• ContentBurn
• MovieAssembler
• ObjectPath
• Quartz Composer WWDC 2005 TextEdit

Declared In

NSSavePanel.h

setTreatsFilePackagesAsDirectories:

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

- (void)setTreatsFilePackagesAsDirectories:(BOOL)flag

Parameters

flag

If YES, the panel will display file packages as directories; if NO, it will not.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – treatsFilePackagesAsDirectories

Related Sample Code

• CustomSave
• MassiveImage
• Quartz 2D Transformer
• TextSizingExample

Declared In

NSSavePanel.h

showsHiddenFiles

Returns whether the panel displays files that are normally hidden from the user.

- (BOOL)showsHiddenFiles

Return Value

YES if the panel displays hidden files; otherwise, NO.

Discussion

The default value is NO.

Availability

• Available in Mac OS X v10.6 and later.

See Also

• – setShowsHiddenFiles:

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.

See Also

• – setTitle:

Declared In

NSSavePanel.h

treatsFilePackagesAsDirectories

Returns a Boolean value that indicates whether the panel displays file packages as directories.

- (BOOL)treatsFilePackagesAsDirectories

Return Value

YES if the panel displays file packages as directories; otherwise, NO.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setTreatsFilePackagesAsDirectories:

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

• CocoaSpeechSynthesisExample
• MassiveImage
• PDF Annotation Editor
• PDF Calendar
• Quartz2DBasics

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

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.

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.

Declared In

NSSavePanel.h

---