Legacy Document
Important: The information in this document is obsolete and should not be used for new development.
NSOpenPanel
| Inherits from | |
| Implements | |
| Package | com.apple.cocoa.application |
| Companion guides |
Overview
NSOpenPanel provides the Open panel for the Cocoa user interface. Applications use the Open panel as a convenient way to query the user for the name of a file to open. The Open panel can only be run modally.
Tasks
Constructors
Obtaining
Running the Panel
Getting the User Selection
Specifying the File Types
Allowing Browser Selections
-
setCanChooseFiles
-
canChooseFiles
-
setCanChooseDirectories
-
canChooseDirectories
-
setResolvesAliases
-
resolvesAliases
Allowing Multiple Selections
Constructors
NSOpenPanel
Creates an empty NSOpenPanel.
public NSOpenPanel()
Creates a new NSOpenPanel.
public NSOpenPanel(NSRect contentRect, int styleMask, int backingType, boolean flag)
Discussion
The contentRect argument specifies the location and size of the panel’s content area in screen coordinates. Note that the Window Server limits window position coordinates to ±16,000 and sizes to 10,000.
The styleMask argument specifies the panel’s style. Either it can be NSWindow.BorderlessWindowMask, or it can contain any of the options described in NSWindow’s “Constants,” combined using the C bitwise OR operator.
Borderless windows display none of the usual peripheral elements and are generally useful only for display or caching purposes; you should normally not need to create them. Also, note that an NSWindow’s style mask should include NSWindow.TitledWindowMask if it includes any of the others.
The backingType argument specifies how the drawing done in the panel is buffered by the object’s window device, and possible values are described in NSWindow’s “Constants.”
The flag argument determines whether the window server creates a window device for the new panel immediately. If flag is true, it defers creating the window until the panel is moved onscreen. All display messages sent are postponed until the panel is created, just before it’s moved onscreen. Deferring the creation of the window improves launch time and minimizes the virtual memory load on the window server.
The new panel creates an instance of NSView to be its default content view. You can replace it with your own object by using the setContentView method.
Creates a new NSOpenPanel.
public NSOpenPanel(NSRect contentRect, int styleMask, int backingType, boolean flag, NSScreen aScreen)
Discussion
This constructor is equivalent to NSOpenPanel except contentRect is specified relative to the lower-left corner of aScreen.
If aScreen is null, contentRect is interpreted relative to the lower-left corner of the main screen. The main screen is the one that contains the current key window or, if there is no key window, the one that contains the main menu. If there’s neither a key window nor a main menu (if there’s no active application), the main screen is the one where the origin of the screen coordinate system is located.
Static Methods
openPanel
Creates and returns a new NSOpenPanel object.
public static NSOpenPanel openPanel()
Discussion
The open panel has been initialized with default values.
Instance Methods
allowedFileTypes
Returns an array of the allowed file types.
public NSArray allowedFileTypes()
Discussion
File type strings encoding HFS file types are valid values for this attribute. A null return value, which is the default, indicates that all file types are allowed.
Availability
- Available in Mac OS X v10.3 and later.
See Also
allowsMultipleSelection
Returns whether the receiver’s browser allows the user to open multiple files (and directories) at a time.
public boolean allowsMultipleSelection()
Discussion
If multiple files or directories are allowed, then the filename method—inherited from NSSavePanel—returns a non-null 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
beginForDirectory
Presents a modeless Open panel.
public void beginForDirectory(String path, String filename, NSArray fileTypes, Object modelessDelegate, NSSelector didEndSelector, Object contextInfo)
Discussion
Similar to beginSheetForDirectory, but allows for modeless operation of the panel.
The receiver displays the files in directory (an absolute directory path), and allows selections of ones that match the types in fileTypes (an NSArray of file extensions and/or HFS file types). If directory is null the directory is the same directory used in the previous invocation of the panel. Passing null for directory is probably the best choice for most situations. If all files in a directory should be selectable in the browser, fileTypes should be null. The filename argument specifies a particular file in directory that is selected when the Open panel is presented to the user; otherwise, filename should be null. When the panel operation is ended, didEndSelector is invoked on the modelessDelegate, passing contextInfo as an argument. modelessDelegate is not the same as a delegate assigned to the panel. This delegate is temporary and the relationship only lasts until the panel is dismissed.
didEndSelector should have the following signature:
void openPanelDidEnd(NSOpenPanel panel, int returnCode, void contextInfo) |
The value passed as returnCode will be either NSPanel.CancelButton or NSPanel.OKButton.
Availability
- Available in Mac OS X v10.3 and later.
beginSheetForDirectory
Presents a sheet Open panel on a given window, docWindow.
public void beginSheetForDirectory(String directory, String filename, NSArray fileTypes, NSWindow docWindow, Object modalDelegate, NSSelector didEndSelector, Object contextInfo)
Discussion
The receiver displays the files in directory (an absolute directory path), and allows selection of ones that match the types in fileTypes (an NSArray of file extensions and/or HFS file types). If directory is null the directory is the same directory used in the previous invocation of the panel. Passing null for directory is probably the best choice for most situations. If all files in a directory should be selectable in the browser, fileTypes should be null. The filename argument specifies a particular file in directory that is selected when the Open panel is presented to the user; otherwise, filename should be null. When the modal session is ended, didEndSelector is invoked on the modalDelegate, passing contextInfo as an argument. modalDelegate is not the same as a delegate assigned to the panel. Modal delegates in sheets are temporary and the relationship only lasts until the sheet is dismissed.
didEndSelector should have the following signature:
public void openPanelDidEnd (NSOpenPanel sheet, int returnCode, Object contextInfo) |
The value passed as returnCode will be either NSPanel.CancelButton or NSPanel.OKButton.
canChooseDirectories
Returns whether the receiver allows the user to choose directories to open.
public boolean canChooseDirectories()
See Also
canChooseFiles
Returns whether the receiver allows the user to choose files to open.
public boolean canChooseFiles()
See Also
filenames
Returns an array containing the absolute paths (as String objects) of the selected files and directories.
public NSArray filenames()
Discussion
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.
See Also
resolvesAliases
Returns whether the receiver resolves aliases.
public boolean resolvesAliases()
Discussion
If true, the effect is that dropping an alias on the receiver or asking for filenames or URLs returns the resolved aliases. The default is true.
See Also
runModalForTypes
Invokes the runModalInDirectory method, using null for both the filename and directory arguments.
public int runModalForTypes(NSArray fileTypes)
Discussion
See the description of runModalInDirectory for details. The fileTypes argument is an NSArray containing the extensions of files to be selectable in the browser. Returns NSPanel.OKButton (if the user clicks the OK button) or NSPanel.CancelButton (if the user clicks the Cancel button).
runModalInDirectory
Displays the receiver and begins a modal event loop that is terminated when the user clicks either OK or Cancel, resulting in the return of NSPanel.OKButton or NSPanel.CancelButton, respectively.
public int runModalInDirectory(String directory, String filename, NSArray fileTypes)
Discussion
The receiver displays the files in directory (an absolute directory path), and allows selection of ones that match the types in fileTypes (an NSArray of file extensions and/or HFS file types). If directory is null the directory is the same directory used in the previous invocation of the panel. Passing null for directory is probably the best choice for most situations. If all files in a directory should be selectable in the browser, fileTypes should be null. 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 panel is presented to the user; otherwise, filename should be null.
If window is not null, the Open panel slides down as a sheet running as a document modal window. If window is null, the behavior defaults to a standalone modal panel.
public int runModalInDirectory(String directory, String filename, NSArray fileTypes, NSWindow window)
See Also
setAllowedFileTypes
Specifies the allowed file types for the receiver.
public void setAllowedFileTypes(NSArray types)
Discussion
types may not be empty. The items in types should not include the period that begins the extension. File type strings encoding HFS file types are valid values. Pass null, to allow any file type, which is the default.
Availability
- Available in Mac OS X v10.3 and later.
See Also
setAllowsMultipleSelection
Sets whether the user can select multiple files (and directories) at one time for opening to flag.
public void setAllowsMultipleSelection(boolean flag)
See Also
setCanChooseDirectories
Sets whether the user can select directories in the receiver’s browser.
public void setCanChooseDirectories(boolean flag)
Discussion
When a directory is selected, the OK button is enabled only if flag is true.
See Also
setCanChooseFiles
Sets whether the user can select files in the receiver’s browser.
public void setCanChooseFiles(boolean flag)
See Also
setResolvesAliases
Sets whether the receiver resolves aliases to resolvesAliases.
public void setResolvesAliases(boolean resolvesAliases)
Discussion
If true, the effect is that dropping an alias on the receiver or asking for filenames or URLs returns the resolved aliases. Set this value to false to allow selection of aliases without resolving.
See Also
URLs
Returns an array containing the absolute paths of the selected files and directories as URLs.
public NSArray URLs()
Discussion
If multiple selections aren’t allowed, the array contains a single name.
See Also
© 1997, 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-02-01)