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 panelIsValidFilename 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 true if the file name is valid, or false 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
- runModalInDirectory
- Getting user selections
- directory
- filename
- Action methods
- cancel
- ok
- Responding to user input
- selectText
- Setting the delegate
- setDelegate
public NSSavePanel(NSRect aRect, int anInt, int anInt, boolean flag)
public NSSavePanel(NSRect aRect, int anInt, int anInt, boolean aBoolean, NSScreen aScreen)
public static NSSavePanel savePanel()
public NSView accessoryView()
See Also: setAccessoryView
public void cancel(Object sender)
public String directory()
See Also: setDirectory
public String filename()
public void ok(Object sender)
public String prompt()
See Also: setPrompt
public String requiredFileType()
See Also: setRequiredFileType
public int runModal()
OKButton
(if
the user clicks the OK button) or CancelButton
(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: runModalInDirectory, - runModalForWindow: (NSApplication)
public int runModalInDirectory(String path, String filename)
null
. The
method invokes NSApplication's runModalForWindow: method
with this as the argument. Returns OKButton
(if
the user clicks the OK button) or CancelButton
(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)
public void selectText(Object sender)
public void setAccessoryView(NSView aView)
null
,
the NSSavePanel removes the current accessory view.See Also: accessoryView
public void setDelegate(Object anObject)
public void setDirectory(String path)
See Also: directory
public void setPrompt(String prompt)
See Also: prompt
public void setRequiredFileType(String type)
See Also: requiredFileType
public void setTreatsFilePackagesAsDirectories(boolean flag)
true
,
the user is shown files and subdirectories within a file package.
If false
, the NSSavePanel shows each file
package as a file, thereby giving no indication that it is a directory.See Also: treatsFilePackagesAsDirectories
public void setTitle(String title)
See Also: title
public String title()
See Also: setTitle:
public boolean treatsFilePackagesAsDirectories()
See Also: setTreatsFilePackagesAsDirectories:
public void validateVisibleColumns()
public java.net.URL URL()
public abstract int panelCompareFilenames(Object sender, String fileName1, String fileName2, boolean flag)
OrderedAscending
if fileName1 should
precede fileName2OrderedSame
if the two names
are equivalentOrderedDescending
if fileName2 should
precede fileName1The flag argument,
if true
, 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.
public abstract boolean panelShouldShowFilename (Object sender, String filename)
true
if filename should
be displayed, and false
if the NSSavePanel
should ignore the file or directory.public abstract boolean panelIsValidFilename (Object sender, String filename)
true
if the file name
is valid, or false
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.