The inheritance information
shown above applies only to NSOpenPanel on OpenStep for Windows.
On Mach, NSOpenPanel inherits from (in this order) NSSavePanel,
NSPanel, NSWindow, NSResponder, and NSObject. |
NSOpenPanel provides the Open dialog on OpenStep for Windows
or the Open panel on the OpenStep for Mach user interface. Applications
use the Open panel (or dialog) as a convenient way to query the
user for the name of a file to open. The Open panel can only be
run modally.
Most of this class's behavior is defined by its superclass,
NSSavePanel. NSOpenPanel adds to this behavior by:
- Letting you specify the types (by file-name extension)
of the items that will appear in the panel
- Letting the user select files, directories, or both
- Letting the user select multiple items at a time
Typically, you access an NSOpenPanel by invoking the openPanel class method.
When the class receives an openPanel message,
it tries to reuse an existing panel rather than create a new one.
If 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
Open dialogs and panels may be reused, you shouldn't modify the instance
returned by openPanel except
through the methods listed below (and those inherited from NSSavePanel).
For example, you can set the panel's title and whether it allows
multiple selection, but not the arrangement of the buttons within the
panel. If you must modify the Open panel substantially, create and
manage your own instance using the alloc... and init... methods rather
than the openPanel method.
The following code example shows the NSOpenPanel displaying
only files with extensions of ".td" and allowing multiple
selection. If the user makes a selection and clicks the OK button
(that is, runModalForDirectory:file:types: returns NSOKButton
),
this method opens each selected file:
- (void)openDoc:(id)sender
{
int result;
NSArray *fileTypes = [NSArray arrayWithObject:@"td"];
NSOpenPanel *oPanel = [NSOpenPanel openPanel];
[oPanel setAllowsMultipleSelection:YES];
result = [oPanel runModalForDirectory:NSHomeDirectory()
file:nil types:fileTypes];
if (result == NSOKButton) {
NSArray *filesToOpen = [oPanel filenames];
int i, count = [filesToOpen count];
for (i=0; i<count; i++) {
NSString *aFile = [filesToOpen objectAtIndex:i];
id currentDoc = [[ToDoDoc alloc] initWithFile:aFile];
}
}
}
Method Types
- Obtaining the shared
instance
- + openPanel
- Running the panel modally
- - runModalForDirectory:file:types:
- - runModalForTypes:
- Getting the user selection
- - filenames
- Allowing browser selections
- - setCanChooseFiles:
- - canChooseFiles
- - setCanChooseDirectories:
- - canChooseDirectories
- Allowing multiple selections
- - setAllowsMultipleSelection:
- - allowsMultipleSelection
Class
Methods
+ (NSOpenPanel *)openPanel
Returns a "recycled"
NSOpenPanel or, if one doesn't yet exist, creates it before returning
it. New and recycled NSOpenPanels are reset to
default values, which include selection of single files only.
Instance Methods
- (BOOL)allowsMultipleSelection
Returns whether the NSOpenPanel's
browser allows the user to open multiple files (and directories)
at a time. If multiple files or directories are
allowed, then the filename method-inherited
from NSSavePanel-returns a non-nil
value
only if one and only one file is selected. By contrast, NSOpenPanel's filenames method
always returns the selected files, even if only one file is selected. See
Also: - filename (NSSavePanel), - filenames, - setAllowsMultipleSelection:
- (BOOL)canChooseDirectories
Returns whether the Open dialog
or panel allows the user to choose directories to open. See
Also: - setCanChooseDirectories:
- (BOOL)canChooseFiles
Returns whether the Open dialog
or panel allows the user to choose files to open.See
Also: - setCanChooseFiles:
- (NSArray *)filenames
Returns an array containing
the absolute paths (as NSString objects) of the selected files and
directories. If multiple selections aren't allowed,
the array contains a single name. The filenames method is preferable over
NSSavePanel's filename to get the name
or names of files and directories that the user has selected.
- (int)runModalForDirectory:(NSString
*)directory file:(NSString
*)filename types:(NSArray
*)fileTypes
Displays the NSOpenPanel and
begins a modal event loop that is terminated when the user clicks
either OK or Cancel, resulting in the return of NSOKButton
or NSCancelButton
,
respectively. The NSOpenPanel displays the files
in directory (an absolute directory
path) that match the types in fileTypes (an NSArray
of file extensions). If directory is nil
the
default directory on Mach is the application directory; on Windows
the default directory is the root directory of the drive on which
the application resides. If all files in a directory should appear
in the browser, fileTypes should
be nil
. You can control whether directories
and files appear in the browser with the setCanChooseDirectories: and setCanChooseFiles: methods.
The filename argument specifies a particular
file in directory that is selected
when the Open dialog or panel is presented to the user; otherwise, filename should
be nil
. See
Also: - runModalForTypes:
- (int)runModalForTypes:(NSArray
*)fileTypes
Invokes the runModalForDirectory:file:types: method,
using nil
for both the filename and directory arguments. See
the description of runModalForDirectory:file:types: for
details. The fileTypes argument is
an NSArray containing the extensions of files to be shown in the
browser. Returns NSOKButton
(if the
user clicks the OK button) or NSCancelButton
(if
the user clicks the Cancel button).
- (void)setAllowsMultipleSelection:(BOOL)flag
Sets whether the user can select
multiple files (and directories) at one time for opening.See
Also: - allowsMultipleSelection
- (void)setCanChooseDirectories:(BOOL)flag
Sets whether the user can select
directories in the NSOpenPanel's browser. When
a directory is selected, the OK button is enabled only if flag is YES
.See
Also: - canChooseDirectories
- (void)setCanChooseFiles:(BOOL)flag
Sets whether the user can select
files in the NSOpenPanel's browser. See
Also: - canChooseFiles
- (NSArray *)URLs
<<Documentation forthcoming>>
[Previous] [Next]