Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

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

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. The Open panel can only be run modally.

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

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 when the panel operation ends. The corresponding method should have the 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 a sheet Open panel on a given window.

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

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 when the panel operation ends. The corresponding method should have the 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
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
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.

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
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 in absoluteDirectoryPath selectable by the user.

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
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
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
Declared In
NSOpenPanel.h

setCanChooseFiles:

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

- (void)setCanChooseFiles:(BOOL)flag

Availability
See Also
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
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
Declared In
NSOpenPanel.h

Next Page > Hide TOC

Last updated: 2007-04-03

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.
Get information on Apple products.
Visit the Apple Store online or at retail locations.
1-800-MY-APPLE

Copyright © 2007 Apple Inc.
All rights reserved. | Terms of use | Privacy Notice