Inherits from: Windows : NSObject : Mach : NSPanel : NSWindow : NSResponder : NSObject
Conforms to: Windows:
NSObject (NSObject)
Mach: NSCoding (NSResponder)
NSObject (NSObject)
Declared in: AppKit/NSSavePanel.h
+ savePanel | Returns the shared save panel instance. |
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. |
NSSavePanel 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 a file name extension.
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 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:
The following code fragment demonstrates this sequence. (Two objects in this example, 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(); }
- Creating an NSSavePanel
- + savePanel
- Customizing the NSSavePanel
- - setAccessoryView:
- - accessoryView
- - setTitle:
- - title
- - setPrompt:
- - prompt
- Setting directory and file type
- - setDirectory:
- - setRequiredFileType:
- - requiredFileType
- - treatsFilePackagesAsDirectories
- - setTreatsFilePackagesAsDirectories:
- - validateVisibleColumns
- Running the NSSavePanel
- - runModal
- - runModalForDirectory:file:
- Getting user selections
- - directory
- - filename
- Action methods
- - cancel:
- - ok:
- Responding to user input
- - selectText:
- Setting the delegate
- - setDelegate:
+ (NSSavePanel *)savePanel
’àí (NSView *)accessoryView
See Also: - setAccessoryView:
- (void)cancel:(id)sender
- (NSString *)directory
See Also: - setDirectory:
- (void)encodeWithCoder:(NSCoder
*)coder
See Also: - initWithCoder:
’àí (NSString *)filename
- (id)initWithCoder:(NSCoder
*)coder
See Also: - encodeWithCoder:
- (void)ok:(id)sender
- (NSString *)prompt
See Also: - setPrompt:
- (NSString *)requiredFileType
See Also: - setRequiredFileType:
’àí (int)runModal
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 these methods fetch is updated
only upon return.See Also: - runModalForDirectory:file:, - runModalForWindow: (NSApplication)
- (int)runModalForDirectory:(NSString
*)path file:(NSString *)filename
nil
. The
method invokes 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 these methods fetch is updated
only upon return.See Also: - runModal, - runModalForWindow: (Application)
- (void)selectText:(id)sender
- (void)setAccessoryView:(NSView
*)aView
nil
,
the NSSavePanel removes the current accessory view.See Also: - accessoryView
- (void)setDelegate:(id)anObject
- (void)setDirectory:(NSString
*)path
See Also: - directory
- (void)setPrompt:(NSString
*)prompt
See Also: - prompt
- (void)setRequiredFileType:(NSString
*)type
See Also: - requiredFileType
- (void)setTreatsFilePackagesAsDirectories:(BOOL)flag
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
- (void)setTitle:(NSString
*)title
See Also: - title
- (NSString *)title
See Also: - setTitle:
- (BOOL)treatsFilePackagesAsDirectories
See Also: - setTreatsFilePackagesAsDirectories:
- (void)validateVisibleColumns
’àí (NSURL *)URL
- (NSComparisonResult)panel:(id)sender compareFilename:(NSString
*)fileName1 with:(NSString *)fileName2 caseSensitive:(BOOL)flag
NSOrderedAscending
if fileName1 should
precede fileName2NSOrderedSame
if the two names
are equivalentNSOrderedDescending
if fileName2 should
precede fileName1The flag argument,
if YES
, indicates that the ordering
is to be case-sensitive.
Don't reorder file names 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 Workspace Manager. The default behavior of Save and Open panel is to order files as they appear in the Workspace Manager file viewer. Note also that by implementing this method you will reduce the operating performance of the panel.
- (BOOL)panel:(id)sender shouldShowFilename:(NSString *)filename
YES
if filename should
be displayed, and NO
if the NSSavePanel
should ignore the file or directory.- (BOOL)panel:(id)sender isValidFilename:(NSString *)filename
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.