
|
<<
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 )
- Parentheses are optional: each may be treated as a function ( using parentheses ) or a statement without parentheses
- All parameters are optional; only the keywords OSPanelOpen/OSPanelSave are required
- Commas may be used to designate missing parameters, e.g. url = OSPanelOpen( 0, @"Open file",, prompt, directoryURL )
- Trailing unused parameters don't require commas, e.g. url = OSPanelOpen( 0, @"Open file" )
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:
- 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.
- 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.
- When an open panel has been given the _OSPanelAllowsMultipleSelection option, the returned value will be an array of selected file/directory URLs
- Returned CFURLRef and/or CFArrayRef objects will need to be retained if not used immediately
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$