ADC Home > Reference Library > Reference > Cocoa > User Experience > NSOpenPanel Class Reference >

Next Page > Hide TOC

NSOpenPanel Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in Mac OS X v10.0 and later.
Declared in
NSOpenPanel.h
Companion guides
Related sample code

Overview

The NSOpenPanel class 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.

Tasks

Creating Panels

Configuring Panels

Running Panels

Accessing User Selection

Class Methods

openPanel

Creates and returns a NSOpenPanel object.

+ (NSOpenPanel *)openPanel

Return Value

Initialized Open panel.

Discussion

The open panel has been initialized with default values.

Availability
Related Sample Code
Declared In
NSOpenPanel.h

Instance Methods

allowsMultipleSelection

Returns whether the receiver’s browser allows the user to open multiple files (and directories) at a time.

- (BOOL)allowsMultipleSelection

Discussion

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.

Availability
See Also
Declared In
NSOpenPanel.h

beginForDirectory:file:types:modelessDelegate:didEndSelector:contextInfo:

Presents a modeless Open panel.

- (void)beginForDirectory:(NSString *)absoluteDirectoryPath file:(NSString *)filename types:(NSArray *)fileTypes modelessDelegate:(id)modelessDelegate didEndSelector:(SEL)didEndSelector contextInfo:(void *)contextInfo

Parameters
absoluteDirectoryPath

Directory whose files the panel displays. When nil, the directory is the same directory used in the previous invocation of the panel; this is probably the best choice for most situations.

filename

Specifies a particular file in absoluteDirectoryPath that is selected when the Open panel is presented to the user. When nil, no file is initially selected.

fileTypes

Array of file extensions and/or HFS file types. Specifies the files the panel allows the user to select. nil makes all files in absoluteDirectoryPath selectable by the user. An array of types passed in here will override one set using setAllowedFileTypes:.

modelessDelegate

This 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

Message sent to modelessDelegate after the panel’s session has ended, but before dismissing the Open panel. didEndSelector may dismiss the Open panel itself; otherwise, it will be dismissed on return from the method. The corresponding method should have the following signature:

- (void)openPanelDidEnd:(NSOpenPanel *)panel returnCode:(int)returnCode  contextInfo:(void  *)contextInfo

The value passed as returnCode will be either NSCancelButton or NSOKButton.

contextInfo

Context information passed to modelessDelegate in the didEndSelector message.

Discussion

Similar to beginSheetForDirectory:file:types:modalForWindow:modalDelegate:didEndSelector:contextInfo:, but allows for modeless operation of the panel.

Availability
Declared In
NSOpenPanel.h

beginSheetForDirectory:file:types:modalForWindow:modalDelegate:didEndSelector:contextInfo:

Presents an Open panel as a sheet with the directory specified by absoluteDirectoryPath and optionally the file specified by filename selected.

- (void)beginSheetForDirectory:(NSString *)absoluteDirectoryPath file:(NSString *)filename types:(NSArray *)fileTypes modalForWindow:(NSWindow *)docWindow modalDelegate:(id)modalDelegate didEndSelector:(SEL)didEndSelector contextInfo:(void *)contextInfo

Parameters
absoluteDirectoryPath

Directory whose files the panel displays. When nil, the directory is the same directory used in the previous invocation of the panel; this is probably the best choice for most situations.

filename

Specifies a particular file in absoluteDirectoryPath that is selected when the Open panel is presented to the user. When nil, no file is initially selected.

fileTypes

Array of file extensions and/or HFS file types. Specifies the files the panel allows the user to select. nil makes all files in absoluteDirectoryPath selectable by the user. An array of types passed in here will override one set using setAllowedFileTypes:.

docWindow

Window to open the sheet on.

modalDelegate

This 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

Message sent to modalDelegate after the modal session has ended, but before dismissing the Open panel. didEndSelector may dismiss the Open panel itself; otherwise, it will be dismissed on return from the method. The corresponding method should have the following signature:

- (void)openPanelDidEnd:(NSOpenPanel *)panel returnCode:(int)returnCode  contextInfo:(void  *)contextInfo

The value passed as returnCode will be either NSCancelButton or NSOKButton.

contextInfo

Context information passed to modalDelegate in the didEndSelector message.

Availability
Related Sample Code
Declared In
NSOpenPanel.h

canChooseDirectories

Returns whether the receiver allows the user to choose directories to open.

- (BOOL)canChooseDirectories

Availability
See Also
Declared In
NSOpenPanel.h

canChooseFiles

Returns whether the receiver allows the user to choose files to open.

- (BOOL)canChooseFiles

Availability
See Also
Declared In
NSOpenPanel.h

filenames

Returns an array containing the absolute paths (as NSString objects) of the selected files and directories.

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

Availability
See Also
Related Sample Code
Declared In
NSOpenPanel.h

resolvesAliases

Returns whether the receiver resolves aliases.

- (BOOL)resolvesAliases

Discussion

If YES, the effect is that dropping an alias on the receiver or asking for filenames or URLs returns the resolved aliases. The default is YES.

Availability
See Also
Declared In
NSOpenPanel.h

runModalForDirectory:file:types:

Displays the receiver and begins a modal event loop that is terminated when the user clicks either OK or Cancel.

- (NSInteger)runModalForDirectory:(NSString *)absoluteDirectoryPath file:(NSString *)filename types:(NSArray *)fileTypes

Parameters
absoluteDirectoryPath

Directory whose files the panel displays. When nil, the directory is the same directory used in the previous invocation of the panel; this is probably the best choice for most situations.

filename

Specifies a particular file in absoluteDirectoryPath that is selected when the Open panel is presented to the user. When nil, no file is initially selected.

fileTypes

Array of file extensions and/or HFS file types. Specifies the files the panel allows the user to select. nil makes all files in absoluteDirectoryPath selectable by the user. An array of types passed in here will override one set using setAllowedFileTypes:.

Return Value

Button clicked to dismiss the dialog: NSOKButton for the OK button and NSCancelButton for the Cancel button.

Discussion

You can control whether directories and files appear in the browser with the setCanChooseDirectories: and setCanChooseFiles: methods.

Availability
See Also
Related Sample Code
Declared In
NSOpenPanel.h

runModalForTypes:

Displays the receiver and begins a modal event loop that is terminated when the user clicks either OK or Cancel.

- (NSInteger)runModalForTypes:(NSArray *)fileTypes

Parameters
fileTypes

Array of file extensions and/or HFS file types. Specifies the files the panel allows the user to select. nil makes all files selectable by the user. An array of types passed in here will override one set using setAllowedFileTypes:.

Return Value

Button used to dismiss the dialog: NSOKButton for the OK button and NSCancelButton for the Cancel button.

Discussion

This convenience method sends runModalForDirectory:nil file:nil types:fileTypes to the receiver. See runModalForDirectory:file:types: for additional details.

Availability
See Also
Related Sample Code
Declared In
NSOpenPanel.h

setAllowsMultipleSelection:

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

- (void)setAllowsMultipleSelection:(BOOL)flag

Availability
See Also
Related Sample Code
Declared In
NSOpenPanel.h

setCanChooseDirectories:

Sets whether the user can select directories in the receiver’s browser.

- (void)setCanChooseDirectories:(BOOL)flag

Discussion

When a directory is selected, the OK button is enabled only if flag is YES.

Availability
See Also
Related Sample Code
Declared In
NSOpenPanel.h

setCanChooseFiles:

Sets whether the user can select files in the receiver’s browser.

- (void)setCanChooseFiles:(BOOL)flag

Availability
See Also
Related Sample Code
Declared In
NSOpenPanel.h

setResolvesAliases:

Sets whether the receiver resolves aliases to resolvesAliases.

- (void)setResolvesAliases:(BOOL)resolvesAliases

Discussion

If YES, the effect is that dropping an alias on the receiver or asking for filenames or URLs returns the resolved aliases. Set this value to NO to allow selection of aliases without resolving.

Availability
See Also
Related Sample Code
Declared In
NSOpenPanel.h

URLs

Returns an array containing the absolute paths of the selected files and directories as URLs.

- (NSArray *)URLs

Discussion

If multiple selections aren’t allowed, the array contains a single name.

Availability
See Also
Related Sample Code
Declared In
NSOpenPanel.h

Next Page > Hide TOC

© 2009 Apple Inc. All Rights Reserved. (Last updated: 2009-02-04)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.