Up

# NSSavePanel

### Authors

Jonathan Gapen (`jagapen@smithlab.chem.wisc.edu`)
Nicola Pero (`n.pero@mi.flashnet.it`)
Mirko Viviani (`mirko.viviani@rccr.cremona.it`)

> Standard panel for saving files

Copyright: (C) 1999, 2000 Free Software Foundation, Inc.

### Contents -

1. Software documentation for the NSSavePanel class
2. Software documentation for the NSObject(NSOpenSavePanelDelegate) informal protocol
3. Software documentation for the NSObject(NSSavePanelDelegate) informal protocol
4. Software documentation for the NSOpenSavePanelDelegate protocol

# Software documentation for the NSSavePanel class

## NSSavePanel : NSPanel

> Declared in:
>   AppKit/NSSavePanel.h

Availability: OpenStep

Implements a panel that allows the user to save a file.

There is only one save panel per application and this panel is obtained by calling the +savePanel class method. From here, you should set the required file extension using -setRequiredFileType: When ready to show the panel, use the -runModal , or a similar method to show the panel in a modal session. Other methods allow you to set the initial directory and initially choosen file. The method will return one of NSOKButton or NSCancelButton depending on which button the user pressed.

Use the -filename method to retrieve the name of the file the user choose.

Instance Variables
Method summary

- +savePanel
- -URL
- -accessoryView
- -allowedFileTypes
- -allowsOtherFileTypes
- -beginSheetForDirectory:file:modalForWindow:modalDelegate:didEndSelector:contextInfo:
- -beginSheetModalForWindow:completionHandler:
- -beginWithCompletionHandler:
- -canCreateDirectories
- -canSelectHiddenExtension
- -cancel:
- -directory
- -directoryURL
- -filename
- -isExpanded
- -isExtensionHidden
- -message
- -nameFieldLabel
- -nameFieldStringValue
- -ok:
- -prompt
- -requiredFileType
- -runModal
- -runModalForDirectory:file:
- -runModalForDirectory:file:relativeToWindow:
- -selectText:
- -setAccessoryView:
- -setAllowedFileTypes:
- -setAllowsOtherFileTypes:
- -setCanCreateDirectories:
- -setCanSelectHiddenExtension:
- -setDirectory:
- -setDirectoryURL:
- -setExtensionHidden:
- -setMessage:
- -setNameFieldLabel:
- -setNameFieldStringValue:
- -setPrompt:
- -setRequiredFileType:
- -setShowsHiddenFiles:
- -setTitle:
- -setTreatsFilePackagesAsDirectories:
- -showsHiddenFiles
- -title
- -treatsFilePackagesAsDirectories
- -validateVisibleColumns

### savePanel

+ (NSSavePanel*) savePanel;
Availability: OpenStep

Creates (if needed) and returns the shared NSSavePanel instance.

### URL

- (NSURL*) URL;
Availability: MacOS-X 10.0.0
Description forthcoming.

### accessoryView

- (NSView*) accessoryView;
Availability: OpenStep

Returns the accesory view (if any).

See Also: -setAccessoryView:

### allowedFileTypes

- (NSArray*) allowedFileTypes;
Availability: MacOS-X 10.3.0

Returns an array of the allowed file types. The default, indicated by `nil`, is any file type is allowed.

See Also: -setAllowedFileTypes:

### allowsOtherFileTypes

- (BOOL) allowsOtherFileTypes;
Availability: MacOS-X 10.3.0
Description forthcoming.

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

- (void) beginSheetForDirectory: (NSString*)path file: (NSString*)filename modalForWindow: (NSWindow*)docWindow modalDelegate: (id)delegate didEndSelector: (SEL)didEndSelector contextInfo: (void*)contextInfo;
Availability: MacOS-X 10.0.0
Description forthcoming.

### beginSheetModalForWindow: completionHandler:

- (void) beginSheetModalForWindow: (NSWindow*)window completionHandler: (GSSavePanelCompletionHandler)handler;
Availability: MacOS-X 10.6.0
Description forthcoming.

### beginWithCompletionHandler:

- (void) beginWithCompletionHandler: (GSSavePanelCompletionHandler)handler;
Availability: MacOS-X 10.6.0
Description forthcoming.

### canCreateDirectories

- (BOOL) canCreateDirectories;
Availability: MacOS-X 10.3.0
Description forthcoming.

### canSelectHiddenExtension

- (BOOL) canSelectHiddenExtension;
Availability: MacOS-X 10.2.0
Description forthcoming.

### cancel:

- (void) cancel: (id)sender;
Availability: OpenStep

Invoked by the 'Cancel' button. Saves the current directory browsed and stop the modal event loop using [NSApplication -stopModalWithCode:]

See Also: -ok:

### directory

- (NSString*) directory;
Availability: OpenStep

Returns the directory choosen by the user. Do not invoke directory within a modal loop because the information that these methods fetch is updated only upon return.

See Also: -setDirectory:

### directoryURL

- (NSURL*) directoryURL;
Availability: MacOS-X 10.6.0
Description forthcoming.

### filename

- (NSString*) filename;
Availability: OpenStep

Returns the absolute filename choosen by the user. Do not invoke filename within a modal loop because the information that these methods fetch is updated only upon return.

### isExpanded

- (BOOL) isExpanded;
Availability: MacOS-X 10.0.0
Description forthcoming.

### isExtensionHidden

- (BOOL) isExtensionHidden;
Availability: MacOS-X 10.2.0
Description forthcoming.

### message

- (NSString*) message;
Availability: MacOS-X 10.3.0
Description forthcoming.

### nameFieldLabel

- (NSString*) nameFieldLabel;
Availability: MacOS-X 10.3.0
Description forthcoming.

### nameFieldStringValue

- (NSString*) nameFieldStringValue;
Availability: MacOS-X 10.6.0
Description forthcoming.

### ok:

- (void) ok: (id)sender;
Availability: OpenStep

Invoked by the "OK" button.

See Also: -cancel:

### prompt

- (NSString*) prompt;
Availability: OpenStep

Returns the prompt used in the current path field.

See Also: -setPrompt:

### requiredFileType

- (NSString*) requiredFileType;
Availability: OpenStep

Returns the required file type. The default, indicated by an empty string, is no required file type.

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

See Also: -setRequiredFileType:

### runModal

- (NSInteger) runModal;
Availability: OpenStep

Shows the save panel for the user. This method invokes -runModalForDirectory:file: with empty strings for the filename. Returns NSOKButton (if the user clicks the OK button) or NSCancelButton (if the user clicks the Cancel button).

See Also: -runModalForDirectory:file:

### runModalForDirectory: file:

- (NSInteger) runModalForDirectory: (NSString*)path file: (NSString*)filename;
Availability: OpenStep

Initializes the panel 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. The method invokes [NSApplication:-runModalForWindow:] method with self as the argument. Returns NSOKButton (if the user clicks the OK button) or NSCancelButton (if the user clicks the Cancel button). If path is `nil` then the panel displays the last selected directory or as a last resort, the current working directory.

See Also: -runModal

### runModalForDirectory: file: relativeToWindow:

- (NSInteger) runModalForDirectory: (NSString*)path file: (NSString*)filename relativeToWindow: (NSWindow*)window;
Availability: MacOS-X 10.0.0
Description forthcoming.

### selectText:

- (void) selectText: (id)sender;
Availability: OpenStep
Description forthcoming.

### setAccessoryView:

- (void) setAccessoryView: (NSView*)aView;
Availability: OpenStep

Sets an accessory view which is shown near the bottom of the panel. The panel is automatically expanded with enough room to show the extra view. You can use this extra view to customize various characteristics of the file selection mechanism. For instance you could add a popup button which allows the user to select the format that the file is saved in (e.g. rtf or txt). See also -validateVisibleColumns .

See Also: -accessoryView

### setAllowedFileTypes:

- (void) setAllowedFileTypes: (NSArray*)types;
Availability: MacOS-X 10.3.0

Specifies the allowed types, i.e., file name extensions to be appended to any selected files that don't already have one of those extensions. The elements of the array should be strings that do not include the period that begins the extension. Invoke this method each time the Save panel is used for another file type within the application. If you do not invoke it, or set it to an empty array or `nil`, no extension will be appended, indicated by `nil` returned from -allowedFileTypes .

See Also: -allowedFileTypes

### setAllowsOtherFileTypes:

- (void) setAllowsOtherFileTypes: (BOOL)flag;
Availability: MacOS-X 10.3.0
Description forthcoming.

### setCanCreateDirectories:

- (void) setCanCreateDirectories: (BOOL)flag;
Availability: MacOS-X 10.3.0
Description forthcoming.

### setCanSelectHiddenExtension:

- (void) setCanSelectHiddenExtension: (BOOL)flag;
Availability: MacOS-X 10.2.0
Description forthcoming.

### setDirectory:

- (void) setDirectory: (NSString*)path;
Availability: OpenStep

Sets the current path name in the Save panel's browser. The path argument must be an absolute path name.

See Also: -directory

### setDirectoryURL:

- (void) setDirectoryURL: (NSURL*)url;
Availability: MacOS-X 10.6.0

Sets the current path name in the Save panel's browser. The path argument must be an absolute path name.

See Also: -directory

### setExtensionHidden:

- (void) setExtensionHidden: (BOOL)flag;
Availability: MacOS-X 10.2.0
Description forthcoming.

### setMessage:

- (void) setMessage: (NSString*)message;
Availability: MacOS-X 10.3.0
Description forthcoming.

### setNameFieldLabel:

- (void) setNameFieldLabel: (NSString*)label;
Availability: MacOS-X 10.3.0
Description forthcoming.

### setNameFieldStringValue:

- (void) setNameFieldStringValue: (NSString*)value;
Availability: MacOS-X 10.6.0
Description forthcoming.

### setPrompt:

- (void) setPrompt: (NSString*)prompt;
Availability: OpenStep

Returns the prompt of the Save panel field that holds the current pathname or file name. By default this prompt is 'Name: '.

See Also: -prompt

### setRequiredFileType:

- (void) setRequiredFileType: (NSString*)fileType;
Availability: OpenStep

Specifies the type, a file name 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. Invoke this method each time the Save panel is used for another file type within the application. If you do not invoke it, or set it to empty string or `nil`, no extension will be appended, indicated by an empty string returned from -requiredFileType .

This method is equivalent to calling -setAllowedFileTypes: with an array containing only fileType.

See Also: -requiredFileType

### setShowsHiddenFiles:

- (void) setShowsHiddenFiles: (BOOL)flag;
Availability: MacOS-X 10.6.0
Description forthcoming.

### setTitle:

- (void) setTitle: (NSString*)title;
Availability: OpenStep

Sets the title of the NSSavePanel to title. By default, 'Save' is the title string. If you adapt the NSSavePanel for other uses, its title should reflect the user action that brings it to the screen.

See Also: -title

### setTreatsFilePackagesAsDirectories:

- (void) setTreatsFilePackagesAsDirectories: (BOOL)flag;
Availability: OpenStep

Sets the NSSavePanel's behavior for displaying file packages (for example, MyApp.app) to the user. If flag is `YES`, the user is shown files and subdirectories within a file package. If `NO`, the NSSavePanel shows each file package as a file, thereby giving no indication that it is a directory.

See Also: -treatsFilePackagesAsDirectories

### showsHiddenFiles

- (BOOL) showsHiddenFiles;
Availability: MacOS-X 10.6.0
Description forthcoming.

### title

- (NSString*) title;
Availability: OpenStep

Returns the title of the save panel

See Also: -setTitle:

### treatsFilePackagesAsDirectories

- (BOOL) treatsFilePackagesAsDirectories;
Availability: OpenStep
Returns `YES` if file packages are shown as directories. The default is `NO`.

### validateVisibleColumns

- (void) validateVisibleColumns;
Availability: OpenStep

Validates and possibly reloads the browser columns that are visible in the Save panel by causing the delegate method -panel:shouldShowFilename: to be invoked. One situation in which this method would find use is whey you want the browser to show only 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.

## Instance Variables for NSSavePanel Class

### _OKButtonPressed

@protected BOOL _OKButtonPressed;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _accessoryView

@protected NSView* _accessoryView;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _allowedFileTypes

@protected NSArray* _allowedFileTypes;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _allowsOtherFileTypes

@protected BOOL _allowsOtherFileTypes;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _bottomView

@protected NSView* _bottomView;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _browser

@protected NSBrowser* _browser;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _canCreateDirectories

@protected BOOL _canCreateDirectories;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _canSelectHiddenExtension

@protected BOOL _canSelectHiddenExtension;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _completionHandler

@protected GSSavePanelCompletionHandler _completionHandler;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _delegateHasCompareFilter

@protected BOOL _delegateHasCompareFilter;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _delegateHasDirectoryDidChange

@protected BOOL _delegateHasDirectoryDidChange;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _delegateHasSelectionDidChange

@protected BOOL _delegateHasSelectionDidChange;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _delegateHasShowFilenameFilter

@protected BOOL _delegateHasShowFilenameFilter;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _delegateHasUserEnteredFilename

@protected BOOL _delegateHasUserEnteredFilename;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _delegateHasValidNameFilter

@protected BOOL _delegateHasValidNameFilter;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _directory

@protected NSString* _directory;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _form

@protected NSForm* _form;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _fullFileName

@protected NSString* _fullFileName;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _isExtensionHidden

@protected BOOL _isExtensionHidden;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _okButton

@protected NSButton* _okButton;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _originalMinSize

@protected NSSize _originalMinSize;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _originalSize

@protected NSSize _originalSize;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _showsHiddenFiles

@protected BOOL _showsHiddenFiles;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _showsHiddenFilesMenu

@protected NSMenu* _showsHiddenFilesMenu;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _titleField

@protected NSTextField* _titleField;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _topView

@protected NSView* _topView;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _treatsFilePackagesAsDirectories

@protected BOOL _treatsFilePackagesAsDirectories;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

# Software documentation for the NSObject(NSOpenSavePanelDelegate) informal protocol

## NSObject(NSOpenSavePanelDelegate)

> Declared in:
>   AppKit/NSSavePanel.h

Availability: OpenStep
Description forthcoming.
Method summary

- -panel:compareFilename:with:caseSensitive:
- -panel:didChangeToDirectoryURL:
- -panel:directoryDidChange:
- -panel:isValidFilename:
- -panel:shouldEnableURL:
- -panel:shouldShowFilename:
- -panel:userEnteredFilename:confirmed:
- -panel:validateURL:error:
- -panel:willExpand:
- -panelSelectionDidChange:

### panel: compareFilename: with: caseSensitive:

- (NSComparisonResult) panel: (id)sender compareFilename: (NSString*)name1 with: (NSString*)name2 caseSensitive: (BOOL)caseSensitive;
Availability: OpenStep
Description forthcoming.

### panel: didChangeToDirectoryURL:

- (void) panel: (id)sender didChangeToDirectoryURL: (NSURL*)url;
Availability: OpenStep
Description forthcoming.

### panel: directoryDidChange:

- (void) panel: (id)sender directoryDidChange: (NSString*)path;
Availability: OpenStep
Description forthcoming.

### panel: isValidFilename:

- (BOOL) panel: (id)sender isValidFilename: (NSString*)filename;
Availability: OpenStep
Description forthcoming.

### panel: shouldEnableURL:

- (BOOL) panel: (id)sender shouldEnableURL: (NSURL*)url;
Availability: OpenStep
Description forthcoming.

### panel: shouldShowFilename:

- (BOOL) panel: (id)sender shouldShowFilename: (NSString*)filename;
Availability: OpenStep
Description forthcoming.

### panel: userEnteredFilename: confirmed:

- (NSString*) panel: (id)sender userEnteredFilename: (NSString*)filename confirmed: (BOOL)flag;
Availability: OpenStep
Description forthcoming.

### panel: validateURL: error:

- (BOOL) panel: (id)sender validateURL: (NSURL*)url error: (NSError**)error;
Availability: OpenStep
Description forthcoming.

### panel: willExpand:

- (void) panel: (id)sender willExpand: (BOOL)expand;
Availability: OpenStep
Description forthcoming.

### panelSelectionDidChange:

- (void) panelSelectionDidChange: (id)sender;
Availability: OpenStep
Description forthcoming.

# Software documentation for the NSObject(NSSavePanelDelegate) informal protocol

## NSObject(NSSavePanelDelegate)

> Declared in:
>   AppKit/NSSavePanel.h

Availability: OpenStep
Description forthcoming.
Method summary

- -panel:compareFilename:with:caseSensitive:
- -panel:directoryDidChange:
- -panel:isValidFilename:
- -panel:shouldShowFilename:
- -panel:userEnteredFilename:confirmed:
- -panel:willExpand:
- -panelSelectionDidChange:

### panel: compareFilename: with: caseSensitive:

- (NSComparisonResult) panel: (id)sender compareFilename: (NSString*)filename1 with: (NSString*)filename2 caseSensitive: (BOOL)caseSensitive;
Availability: OpenStep
Description forthcoming.

### panel: directoryDidChange:

- (void) panel: (id)sender directoryDidChange: (NSString*)path;
Availability: MacOS-X 10.0.0
Description forthcoming.

### panel: isValidFilename:

- (BOOL) panel: (id)sender isValidFilename: (NSString*)filename;
Availability: OpenStep
The NSSavePanel sends this message just before the end of a modal session for each file name displayed or selected (including file names in multiple selections). The delegate determines whether it wants the file identified by filename; it returns `YES` if the file name is valid, or `NO` if the NSSavePanel should stay in its modal loop and wait for the user to type in or select a different file name or names. If the delegate refuses a file name in a multiple selection, none of the file names in the selection are accepted.

### panel: shouldShowFilename:

- (BOOL) panel: (id)sender shouldShowFilename: (NSString*)filename;
Availability: OpenStep
Sent by NSSavePanel to check whether a file should be displayed in the panel or not. The filename argument is the complete path to the file.

### panel: userEnteredFilename: confirmed:

- (NSString*) panel: (id)sender userEnteredFilename: (NSString*)fileName confirmed: (BOOL)okFlag;
Availability: OpenStep
Description forthcoming.

### panel: willExpand:

- (void) panel: (id)sender willExpand: (BOOL)expanding;
Availability: MacOS-X 10.0.0
Description forthcoming.

### panelSelectionDidChange:

- (void) panelSelectionDidChange: (id)sender;
Availability: MacOS-X 10.0.0
Description forthcoming.

# Software documentation for the NSOpenSavePanelDelegate protocol

## NSOpenSavePanelDelegate

> Declared in:
>   AppKit/NSSavePanel.h

> Conforms to:
>   NSObject

Availability: OpenStep
Description forthcoming.
Up