FutureBasic Logo

 <<    Index    >> FutureBasic
OpenPanel   statement / function


Statement syntax
openpanel tag, msg, fileTypes, prompt, dirURL, sheetFlag

Function syntax
url | array = openpanel tag, msg, fileTypes, prompt, dirURL

Description
Use this statement/function to:
  • Create a new openpanel dialog;
  • Run an existing openpanel;
  • Alter an existing openpanel's characteristics.

    • Parameters
    Parameter
    		 Description
    tag A number (1 through 1000000) that you assign when you create the openpanel and that you refer to when altering the panel. A negative value builds the panel invisibly and doesn't run it until the statement is executed with a positive value.
    Note: Once the panel has been dismissed, its tag value is no longer valid.
    msg The message text displayed in the open panel.
    fileTypes The allowed file types/content types. This can be one of the following:
    • Semicolon-delimited string of file extensions and/or UTIs
    • An array of file extensions and/or UTIs
    • A UTType
    • An array of UTTypes
    The value of this property specifies the file types the user can open. A file type can be a common file extension, a UTI or UTType. The default value of this property is nil, which indicates that any file type can be opened.
    Note: old four character OSTypes are not supported.
    prompt The prompt of the default button.
    dirURL The URL of the initial directory shown when the panel is displayed.
    sheetFlag A boolean value to indicate if the panel will be a sheet attached to the current output window.
    Note A sheet panel does not return a value from the openpanel statement, but instead posts an _openPanelDidEnd event to the user on dialog function.
     
    Return value (non-sheet dialog only)
    A file URL (or an array of URLs when the panel's multiple selection flag is set to true). Returns NULL if the dialog was cancelled.
     
    Ancillary functions
    The following optional functions enhance the openpanel and should be called before the openpanel statement.
    OpenPanelSetCanChooseFiles
    OpenPanelSetCanChooseDirectories
    OpenPanelSetResolvesAliases
    OpenPanelSetAllowsMultipleSelection
    OpenPanelSetCanDownloadUbiquitousContents
    OpenPanelSetCanResolveUbiquitousConflicts
    OpenPanelSetAccessoryViewDisclosed
    OpenPanelSetAccessoryView
    OpenPanelSetTitle
    OpenPanelSetCanCreateDirectories
    OpenPanelSetShowsHiddenFiles
    OpenPanelSetAllowsOtherFileTypes
    OpenPanelSetTreatsFilePackagesAsDirectories
      
    Notes
    1. Using openpanel to select a file does not actually open the selected file. Use the open statement if you need to open the file.
    2. A returned CFURLRef should not be saved to refer to a file/directory at a later date (i.e. across machine restarts). If you need to keep track of a file's location over time, create and save an alias or bookmark for the file.
    3. When an openpanel has been given the multiple selection option (OpenPanelSetAllowsMultipleSelection), the returned value will be an array of selected file/directory URLs.
    4. Returned CFURLRef and/or CFArrayRef objects will need to be retained if not used immediately.

    Dialog events
    _openPanelDidEnd
    _openPanelSelectionDidChange
    _openPanelDidChangeToDirectoryURL
    _openPanelShouldEnableURL
    _openPanelValidateURL
      
    See also
    savepanel

    Apple documentation
    NSOpenPanel