[Previous] [Class List] [Next]

NSOpenPanel


Inherits from: NSSavePanel : NSObject
Conforms to: NSObject
(NSObject)
Declared in: AppKit/NSOpenPanel.h




Class Description




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:

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



openPanel

+ (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



allowsMultipleSelection

- (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:



canChooseDirectories

- (BOOL)canChooseDirectories

Returns whether the Open dialog or panel allows the user to choose directories to open.

See Also: - setCanChooseDirectories:



canChooseFiles

- (BOOL)canChooseFiles

Returns whether the Open dialog or panel allows the user to choose files to open.

See Also: - setCanChooseFiles:



filenames

- (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.

runModalForDirectory:file:types:

- (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:



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).

setAllowsMultipleSelection:

- (void)setAllowsMultipleSelection:(BOOL)flag

Sets whether the user can select multiple files (and directories) at one time for opening.

See Also: - allowsMultipleSelection



setCanChooseDirectories:

- (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



setCanChooseFiles:

- (void)setCanChooseFiles:(BOOL)flag

Sets whether the user can select files in the NSOpenPanel's browser.

See Also: - canChooseFiles



URLs

- (NSArray *)URLs

<<Documentation forthcoming>>


[Previous][Next]
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.