Inherits From:
Windows: NSObject
Mach: NSPanel : NSWindow : NSResponder : NSObject
Conforms To:
Windows: NSObject (NSObject)
Mach: NSCoding (NSResponder)
NSObject (NSObject)
Declared In:
AppKit/NSSavePanel.h
Delegate | Browser | |
Form | Prompt | |
Title | File name | |
Directory | Accessory view |
runModal | Displays the panel and begins the event loop. |
filename | Returns the selected or entered file name. |
directory | Returns the full path of the selected file. |
ok: | Invoked when users click OK. |
When the user decides on a file name, the message panel:isValidFilename:
is sent to the NSSavePanel's delegate. If it responds to that message, the delegate can determine whether the specified file name can be used; it returns YES if the file name is valid, or NO if the Save panel should stay up and wait for the user to type in a different file name.
Typically, you access an NSSavePanel by invoking the savePanel
method. When the class receives a savePanel
message, it tries to reuse an existing panel rather than create a new one. When a panel is reused its attributes are reset to the default values so that the effect is the same as receiving a new panel. Because a Save panel may be reused, you shouldn't modify the instance returned by savePanel
except through the methods listed below. For example, you can set the panel's title and required file type, but not the arrangement of the buttons within the panel. If you must modify the Save panel substantially, create and manage your own instance using the alloc...
and init...
methods rather than the savePanel
method.
A typical programmatic use of NSavePanel requires you to:
savePanel.
newView
and textData
, are assumed to be defined and created elsewhere.)
NSSavePanel *sp;
int runResult;
/* create or get the shared instance of NSSavePanel */
sp = [NSSavePanel savePanel];
/* set up new attributes */
[sp setAccessoryView:newView];
[sp setRequiredFileType:@"txt"];
/* display the NSSavePanel */
runResult = [sp runModalForDirectory:NSHomeDirectory() file:@""];
/* if successful, save file under designated name */
if (runResult == NSOKButton) {
if (![textData writeToFile:[sp filename] atomically:YES])
NSBeep();
}
)savePanel
Returns an instance of NSSavePanel, creating one if necessary. Otherwise, the instance is a recycled NSSavePanel object. The method sets the attributes of the instance to the default values:
current working directory as starting point
prompt of "Name"
no required file types
file packages not treated as directories
no delegate
no accessory view
Returns the custom accessory view for the current application. This view is set by setAccessoryView:
.
See also:
- setAccessoryView:
Invoked when the user clicks the panel's Cancel button.
directory
Returns the absolute pathname of the directory currently shown in the panel. Do not invoke this method within a modal session (runModal
or runModalForDirectory:file:
) because the directory information is only updated just before the modal session ends.
See also:
- setDirectory:
encodeWithCoder:
(NSCoder *)coder
Overrides the superclass implementation of this NSCoding protocol method to raise an exception. The NSSavePanel does not get encoded.
See also:
- initWithCoder:
filename
Returns the absolute path name of the file currently shown in the panel. Do not invoke this method within a modal session (runModal
or runModalForDirectory:file:
) because the filename information is only updated just before the modal session ends.
initWithCoder:
(NSCoder *)coder
Overrides the superclass implementation of this NSCoding protocol method to raise an exception. The NSSavePanel does not get decoded.
See also:
- encodeWithCoder:
Invoked when the user clicks the panel's OK button.
prompt
Returns the prompt of the Save panel field that holds the current pathname or file name. By default this prompt is "Name:".
See also:
- setPrompt:
requiredFileType
Returns the required file type (if any). A file specified in the Save panel is saved with the designated file name and this file type as an extension. Examples of common file types are "rtf", "tiff", and "ps". An empty NSString return value indicates that the user can save to any ASCII file.
See also:
- setRequiredFileType:
runModal
Displays the panel and begins its event loop with the current working (or last selected) directory as the default starting point. Invokes runModalForDirectory:file:
(file argument is an empty NSString), which in turn performs NSApplication's 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). Do not invoke filename
or directory
within a modal loop because the information that these methods fetch is updated only upon return.
See also:
- runModalForDirectory:file:
, - runModalForWindow:
(NSApplication)
runModalForDirectory:
(NSString *)path file:
(NSString *)filename
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, but cannot be nil
. The method invokes Application's 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). Do not invoke filename
or directory
within a modal loop because the information that these methods fetch is updated only upon return.
See also:
- runModal
, - runModalForWindow:
(Application)
Advances the current browser selection one line when Tab or the up-arrow key is pressed, and goes back one line when Shift-Tab or the down-arrow key is pressed; after it makes the new selection it writes the selected item in the field after the prompt. The argument sender identifies the object invoking this method. This method is primarily of interest to those who want to override it to get different behavior.
setAccessoryView:
(NSView *)aView
Customizes the panel for the application by adding a custom NSView (aView) to the panel. The custom NSView that's added appears just above the OK and Cancel buttons at the bottom of the panel. The NSSavePanel automatically resizes itself to accommodate aView. You can invoke this method repeatedly to change the accessory view as needed. If aView is nil
, the NSSavePanel removes the current accessory view.
See also:
- accessoryView
setDelegate:
(id)anObject
Makes anObject the NSSavePanel's delegate, after verifying which delegate methods are implemented. Use NSWindow's delegate
method to retrieve the NSSavePanel's delegate.
setDirectory:
(NSString *)path
Sets the current path name in the Save panel's browser. The path argument must be an absolute path name.
See also:
- directory
setPrompt:
(NSString *)prompt
Sets the prompt of the field that holds the current pathname or file name. This prompt appears on all NSSavePanels (or all NSOpenPanels if the receiver of this message is an NSOpenPanel) in your application. "Name:" is the default prompt string.
See also:
- prompt
setRequiredFileType:
(NSString *)type
Specifies the type, a file name extension to be appended to any selected files that don't already have that extension; "nib" and "rtf" are examples. The argument type should not include the period that begins the extension. You need to invoke this method each time the Save panel is used for another file type within the application.
See also:
- requiredFileType
setTreatsFilePackagesAsDirectories:
(BOOL)flag
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
setTitle:
(NSString *)title
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
title
<< Description forthcoming >>
See also:
- setTitle:
treatsFilePackagesAsDirectories
Use to determine whether the Save panel displays file packages to the user as directories. Returns YES if the user is shown files and subdirectories within a file package; returns NO (the default) if the user is shown only file-package names, with no indication that they are directories.
See also:
- setTreatsFilePackagesAsDirectories:
validateVisibleColumns
Validates and possibly reloads the browser columns 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 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.