FutureBasic Logo

 <<    Index    >> FutureBasic
SavePanel   statement / function


Statement syntax
savepanel tag, msg, fileTypes, nameFldString, prompt, dirURL, sheetFlag

Function syntax
url = savepanel tag, msg, fileTypes, nameFldString, prompt, dirURL

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

    • Parameters
    Parameter
    		 Description
    tag A number (1 through 1000000) that you assign when you create the savepanel 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 save 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 save the file as. The default value of this property is nil, which indicates that any file type can be used.
    Note: old four character OSTypes are not supported.
    nameFldString The user-editable filename currently shown in the name field.
    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 savepanel statement, but instead posts an _savePanelDidEnd event to the user on dialog function.
     
    Return value (non-sheet dialog only)
    The URL of the saved file. Returns NULL if the dialog was cancelled.
     
    Ancillary functions
    The following optional functions enhance the savepanel and should be called before the savepanel statement.
    SavePanelSetAccessoryView
    SavePanelSetTitle
    SavePanelSetNameFieldLabel
    SavePanelSetCanCreateDirectories
    SavePanelSetShowsHiddenFiles
    SavePanelSetShowsTagField
    SavePanelSetTagNames
    SavePanelSetExtensionHidden
    SavePanelSetCanSelectHiddenExtension
    SavePanelSetAllowsOtherFileTypes
    SavePanelSetTreatsFilePackagesAsDirectories
    SavePanelSetShowsContentTypes // macOS 15.0+
    SavePanelSetCurrentContentType // macOS 15.0+
      
    Notes
    1. Using savepanel to specify a filename does not actually save the file. Use the open statement if you need to save 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. The returned CFURLRef object will need to be retained if not used immediately.

    Dialog events
    _savePanelDidEnd
    _savePanelUserEnteredFilename
    _savePanelSelectionDidChange
    _savePanelDidChangeToDirectoryURL
    _savePanelWillExpand
    _savePanelShouldEnableURL
    _savePanelValidateURL
    _savePanelDisplayNameForType // macOS 15.0+
    _savePanelDidSelectType // macOS 15.0+
      

    See also
    openpanel
     
    Apple documentation
    NSSavePanel