Mac Developer Library

Developer

AppKit Framework Reference NSOpenPanel Class Reference

Options
Deployment Target:

On This Page
Language:

NSOpenPanel

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.

In a sandboxed environment, Open panels are drawn in a separate process by the powerbox, not by AppKit itself. When the user chooses a file to open, OS X adds that file to the app’s sandbox.

Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.0 and later.
  • Creates and returns a NSOpenPanel object.

    Declaration

    Objective-C

    + (NSOpenPanel *)openPanel

    Return Value

    The initialized Open panel.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

  • Returns whether the panel allows the user to choose files to open.

    Declaration

    Swift

    var canChooseFiles: Bool

    Objective-C

    @property BOOL canChooseFiles

    Return Value

    YEStrue if the panel allows the user to choose files; otherwise, NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var canChooseFiles: Bool

    Objective-C

    @property BOOL canChooseFiles

    Parameters

    flag

    If YEStrue, the panel allows the user to choose files; if NOfalse, it does not.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns whether the panel allows the user to choose directories to open.

    Declaration

    Swift

    var canChooseDirectories: Bool

    Objective-C

    @property BOOL canChooseDirectories

    Return Value

    YEStrue if the panel allows the user to choose directories; otherwise, NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var canChooseDirectories: Bool

    Objective-C

    @property BOOL canChooseDirectories

    Parameters

    flag

    If YEStrue, the panel allows the user to choose directories; if NOfalse, it does not.

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns whether the panel resolves aliases.

    Declaration

    Swift

    var resolvesAliases: Bool

    Objective-C

    @property BOOL resolvesAliases

    Return Value

    YEStrue if the panel resolves aliases; otherwise, NOfalse.

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.1 and later.

  • Sets whether the panel resolves aliases.

    Declaration

    Swift

    var resolvesAliases: Bool

    Objective-C

    @property BOOL resolvesAliases

    Parameters

    resolvesAliases

    If YEStrue, the panel resolves aliases; if NOfalse, it does not.

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.1 and later.

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

    Declaration

    Swift

    var allowsMultipleSelection: Bool

    Objective-C

    @property BOOL allowsMultipleSelection

    Return Value

    YEStrue if the panel’s browser allows multiple selection; otherwise, NOfalse.

    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 URLs method always returns the URLs of the selected files, even if only one file is selected.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var allowsMultipleSelection: Bool

    Objective-C

    @property BOOL allowsMultipleSelection

    Parameters

    flag

    If YEStrue, the panel’s browser allows multiple selection; if NOfalse, it does not.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Presents a modeless Open panel.

    Deprecation Statement

    Use beginWithCompletionHandler: instead. You can set absoluteDirectoryPath using setDirectoryURL:, and you can set fileTypes using setAllowedFileTypes:.

    Declaration

    Objective-C

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

    Parameters

    absoluteDirectoryPath

    The 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

    An 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

    The 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

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

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

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

    Deprecation Statement

    Use beginSheetModalForWindow:completionHandler: instead. You can set absoluteDirectoryPath using setDirectoryURL:, and you can set fileTypes using setAllowedFileTypes:.

    Declaration

    Objective-C

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

    Parameters

    absoluteDirectoryPath

    The 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

    An 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

    The 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

    The 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

    Any context information passed to modalDelegate in the didEndSelector message.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

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

    Deprecation Statement

    Use runModal instead. You can set path using setDirectoryURL:, and you can set fileTypes using setAllowedFileTypes:.

    Declaration

    Objective-C

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

    Parameters

    absoluteDirectoryPath

    The 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

    An 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

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

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    See Also

    runModal

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

    Deprecation Statement

    Use runModal instead. You can set fileTypes using setAllowedFileTypes:.

    Declaration

    Objective-C

    - (NSInteger)runModalForTypes:(NSArray *)fileTypes

    Parameters

    fileTypes

    An 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

    The 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 panel. See runModalForDirectory:file:types: for additional details.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    See Also

    runModal

  • filenames - filenames (OS X v10.6)

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

    Deprecation Statement

    Use URLs instead.

    Declaration

    Objective-C

    - (NSArray *)filenames

    Return Value

    The array of 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.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    See Also

    – URLs

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

    Declaration

    Swift

    var URLs: [AnyObject] { get }

    Objective-C

    @property(readonly, copy) NSArray *URLs

    Return Value

    The array of URLs.

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.