FutureBasic Logo

<<    Index    >> FutureBasic 5

OSPanelOpen/OSPanelSave   function/statement



Syntax:
For Selecting a File or Directory(folder) to open
    url | array = OSPanelOpen( options, message, allowedFileTypes, prompt, directoryURL )

For Selecting a File Name and Folder where a file may be Saved
    url = OSPanelSave( options, message, allowedFileTypes, nameFieldStringValue, prompt, directoryURL )
Description:
OSPanelOpen and OSPanelSave present Open and Save panels (dialogs) to enable the user to select a file/directory to open or a file name for saving. They are an optional step in the general process to select, open, read/write and close files and are functional replacements for FB's files$, use modern methods, and, unlike files$, avoid Carbon framework use.

Parameters:
options
    _OSPanelCantChooseFiles
    _OSPanelCanChooseDirectories
    _OSPanelAllowsMultipleSelection
    _OSPanelDoesntResolveAliases
    _OSPanelCantDownloadUbiquitousContents
    _OSPanelCantResolveUbiquitousConflicts
    _OSPanelDoesntShowTagField
    _OSPanelExtensionVisible
    _OSPanelCanSelectHiddenExtension
    _OSPanelAllowsOtherFileTypes
    _OSPanelCanCreateDirectories
    _OSPanelCantCreateDirectories
    _OSPanelShowsHiddenFiles
    _OSPanelTreatsFilePackagesAsDirectories

message( CFString )
    Displayed in the panel, it offers guidance. e.g. "Pick an image file or directory"

allowedFileTypes
    A CFArray or semicolon (;) dellimited CFString of file extensions or Uniform Type Identifiers(UTIs). See Note #5 too.

nameFieldStringValue( CFString )
    The user-editable filename shown in the name field (OSPanelSave only).

prompt( CFString )
    The default button's title text.

directoryURL( CFURLRef )
    The directory shown when the panel appears

Return value(s):
    OSPanelOpen - a CFURLRef or a CFArrayRef of URLs if _OSPanelAllowsMultipleSelection option is used.
    OSPanelSave - a CFURLRef.

Exception: When a callback function is installed on the panel, NSPanelOpen or NSPanelSave will always return NULL. For more information, see OSPanelInstallHandler below.

Notes:
  1. Using OSPanelOpen or OSPanelSave 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 open panel has been given the _OSPanelAllowsMultipleSelection option, 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
  5. allowedFileTypes does NOT support/use old four character OSTypes

Ancillary Statements:
Optional statements enhance the open or save panel and should be called before the call to the main OSPanelOpen or OSPanelSave function. Note: 'string' refers to a CFStringRef or CFString constant.

    OSPanelSetTitle string
    Sets the title of the panel to the supplied CFString

    OSPanelSetNameFieldLabel string
    The string displayed in front of the filename text field (OSPanelSave only). Text size limited to less than fifteen characters by framework.

    OSPanelSetTagNames tagNames
    The tag names to set on the file (OSPanelSave only) // requires macOS 10.9 or later.
    tagNames can be an CFArray, or semicolon (;) delimited CFString of tag names.

    OSPanelInstallHandler parentWindow, callback, userData
    Installs a callback function on the panel. The function designated in the callback parameter will be called after the panel is dismissed.

      Parameters:
         parentWindow - a Cocoa or FB window reference. If this param is non-NULL, the panel will be displayed as a sheet attached to the window.
         callback          - a pointer to a function to be called after the panel is dismissed.
         userData          - optional user data which will be sent to the callback function.

      Example callback function:
         local fn MyOSPanelHandler( result as SInt32, object as CFTypeRef, userData as ptr )
               select ( result )
                     case NSOKButton
                        // user pressed the panel's default button
                     case NSCancelButton
                        // user cancelled
               end select
         end fn

   Note:
   When a callback handler is installed on the panel, OSPanelOpen or OSPanelSave will always return NULL.
   In which case, the main call can be optionally typed as a statement. e.g.:
    OSPanelOpen options, message, allowedFileTypes, prompt, directoryURL

  OSPanelSetAccessoryView accessoryView
  A custom accessory view which appears just above the OK and Cancel buttons at the bottom of the panel.
  This must be a Cocoa NSView object.

See Also:
Appendix A - File Object Specifiers; files$