Class

SaveFileDialog

Description

Used to create customized Save File dialogs. Non-customizable Save File dialogs are created by the FolderItem function.

Methods

Name

Parameters

Returns

Shared

ShowModal

FolderItem

Property descriptions

SaveFileDialog.ActionButtonCaption

ActionButtonCaption As String

Text of the label for the Action button (e.g., Choose, Save, Open, etc., depending on context). It is not necessarily the default button for the dialog.

This property is not supported on Linux.

This example illustrates all the labelling properties of a FolderItemDialog.

Var dlg As OpenDialog
Var f As FolderItem
dlg = New OpenDialog
dlg.ActionButtonCaption = "Action Button"
dlg.CancelButtonCaption = "Cancel Button"
dlg.SuggestedFileName = "Suggested Filename"
dlg.Title = "Title bar text"
dlg.PromptText = "Prompt Text"
dlg.Left = 50
dlg.Top = 50

#If Not TargetLinux Then
  dlg.InitialFolder = SpecialFolder.Documents
#Else ' open Home folder on linux
  dlg.InitialFolder = SpecialFolder.home
#Endif
f = dlg.ShowModal
If f <> Nil Then
  MessageBox("You selected: " + f.NativePath)
Else
  ' User Cancelled
End If

SaveFileDialog.CancelButtonCaption

CancelButtonCaption As String

Text of the label for the Cancel button.

Supported only on Windows.

This property is ignored on macOS and Linux, since changing the caption is not supported on those operating systems.

This example illustrates all the labelling properties of a FolderItemDialog.

Var dlg As OpenDialog
Var f As FolderItem
dlg = New OpenDialog
dlg.ActionButtonCaption = "Action Button"
dlg.CancelButtonCaption = "Cancel Button"
dlg.SuggestedFileName = "Suggested Filename"
dlg.Title = "Title bar text"
dlg.PromptText = "Prompt Text"
dlg.Left = 50
dlg.Top = 50

#If Not TargetLinux Then
  dlg.InitialFolder = SpecialFolder.Documents
#Else ' open Home Folder on linux
  dlg.InitialFolder = SpecialFolder.home
#Endif
f = dlg.ShowModal
If f <> Nil Then
  MessageBox("You selected: " + f.NativePath)
Else
  ' User Cancelled
End If

SaveFileDialog.Filter

Filter As String

One or more File Types, separated by semicolons, previously defined via the FileType class or in the File Type Sets Editor in the IDE.

Filter controls which files within InitialDirectory are visible.

This example illustrates all the labelling properties of a FolderItemDialog.

Var dlg As New OpenDialog
dlg.Title = "Select an mp4 file"
dlg.Filter = FileTypeGroup1.Videos ' defined in the File Type Group Editor...

Var f As FolderItem = dlg.ShowModal
If f <> Nil Then
  MoviePlayer1.movie = Movie.Open(f)
Else
  ' user cancelled
End If

SaveFileDialog.InitialFolder

InitialFolder As FolderItem

Full or relative path to the folder whose contents are displayed when the dialog first appears.

The Filter property controls which files within the folder are visible. On Windows, this defaults to the My Documents directory if no FolderItem is specified.

This example illustrates all the labelling properties of a FolderItemDialog.

Var dlg As OpenDialog
Var f As FolderItem
dlg = New OpenDialog

#If Not (TargetLinux) then
  dlg.InitialFolder = SpecialFolder.Documents
#Else //open Home directory on linux
  dlg.InitialFolder = SpecialFolder.home
#Endif
f = dlg.ShowModal

SaveFileDialog.Left

Left As Integer

Distance (in points) of the left side of the dialog from the left side of the main screen.

This code illustrates all the labelling properties of a FolderItemDialog.

Var dlg As OpenDialog
Var f As FolderItem
dlg = New OpenDialog
dlg.Left = 50
dlg.Top = 50
f = dlg.ShowModal
If f <> Nil Then
  MessageBox("You selected: " + f.NativePath)
Else
  ' User Cancelled
End If

SaveFileDialog.PromptText

PromptText As String

The Help text that appears within the dialog.

PromptText is displayed on macOS for all dialog types and on Windows for SelectFolderDialog.

This example illustrates all the labelling properties of a FolderItemDialog.

Var dlg As OpenDialog
Var f As FolderItem
dlg = New OpenDialog
dlg.PromptText = "Select a file"
f = dlg.ShowModal
If f <> Nil Then
  MessageBox("You selected: " + f.NativePath)
Else
  ' User Cancelled
End If

SaveFileDialog.Result

Result As FolderItem

Holds the result of calling ShowModal() or ShowModalWithin.

This property is read-only.

If the user validates the dialog, Result contains the FolderItem corresponding to the selection; otherwise, Result is Nil.

This example displays the NativePath to the mp4 file that the user selects using the Result property.

Var dlg As OpenDialog
Var f As FolderItem
dlg = New OpenDialog
dlg.PromptText = "Select a file"
f = dlg.ShowModal
If dlg.Result <> Nil Then
  MessageBox("You selected: " + dlg.Result.NativePath)
Else
  ' User Cancelled
End If

SaveFileDialog.SuggestedFileName

SuggestedFileName As String

The default name of the file; it appears as the default text in the filename enterable area.

OpenFileDialog displays this value on Windows, but not other platforms.

This example illustrates all the labelling properties of a FolderItemDialog.

Var dlg As New SaveAsDialog
Var f As FolderItem
dlg.SuggestedFileName = "SaveFile.txt"
f = dlg.ShowModal
If f <> Nil Then
  MessageBox("You selected: " + f.NativePath)
Else
  ' User Cancelled
End If

SaveFileDialog.Title

Title As String

The string that appears in the Title bar.

This example illustrates all the labelling properties of a FolderItemDialog.

Var dlg As OpenDialog
Var f As FolderItem
dlg = New OpenDialog
dlg.Title = "Choose a File"
f = dlg.ShowModal
If f <> Nil Then
  MessageBox("You selected: " + f.NativePath)
Else
  ' User Cancelled
End If

SaveFileDialog.Top

Top As Integer

The distance (in points) of the top of the dialog from the top of the main screen.

This code illustrates all the labelling properties of a FolderItemDialog.

Var dlg As OpenDialog
Var f As FolderItem
dlg = New OpenDialog
dlg.Left = 50
dlg.Top = 50
f = dlg.ShowModal
If f <> Nil Then
  MessageBox("You selected: " + f.NativePath)
Else
  ' User Cancelled
End If

Method descriptions

SaveFileDialog.ShowModal

ShowModal As FolderItem

Displays the FolderItemDialog as a Sheet window on macOS within the window specified by Parent.

Notes

Using the properties of the FolderItemDialog class, you can customize the following aspects of a save-file dialog box:

  • Position (Left and Top properties)

  • Default Folder (Initial Folder property)

  • Valid file types to show (Filter property).

  • If you specify more than one file type (separate the file type names with semicolons), SaveFileDialog will add a Format pop-up menu to the dialog, allowing the user to specify the desired file type to use. Examine the extension of the file name returned to see which format was chosen.

  • Default filename (SuggestedFileName property)

  • Text of the Validate and Cancel buttons (ActionButtonCaption and CancelButtonCaption properties)

  • Text that appears in the Title bar of the dialog (Title property)

  • Text that appears in the body of the dialog (PromptText property)

On macOS 10.11 through 10.15, a Hide Filename Extension checkbox appears in the save-file dialog. The FolderItem returned has its ExtensionVisible property set according to the user's use of this checkbox.

Sample code

The following code opens a customized save-file dialog box and displays the contents of the "Documents" directory in the browser area. It refers to the 'text/plain' common file type defined in the FileTypeGroup1 file type set.

Var dlg As New SaveFileDialog
Var saveFile As FolderItem
dlg.InitialFolder = SpecialFolder.Documents
dlg.PromptText = "Prompt Text"
dlg.SuggestedFileName = "Suggested Filename"
dlg.Title = "Title Property"
dlg.Filter = FileTypeGroup1.Text ' defined as a file type in FileTypeGroup1 file type set
saveFile = dlg.ShowModal
If saveFile <> Nil Then
  ' saveFile is the FolderItem of the file to save
Else
  ' user canceled
End If

The following code creates a pop-up menu in the Save File dialog that gives the user the option of choosing among four file types.

Var dlg As New SaveFileDialog
Var f As FolderItem

Var txtType As New FileType
txtType.Name = "Text File (*.txt)"
txtType.MacType = "TEXT"
txtType.Extensions = "txt"

Var htmlType As New FileType
htmlType.Name = "HTML File (*.htm, *.html)"
htmlType.MacType = "HTML "
htmlType.Extensions = "htm"

Var csvType As New FileType
csvType.Name = "CSV File (*.csv)"
csvType.MacType = "TEXT"
csvType.Extensions = "csv"

Var xlsType As New FileType
xlsType.Name = "Excel File (*.xls)"
xlsType.MacType = "XLS "
xlsType.Extensions = "xls"

dlg.InitialFolder = SpecialFolder.Desktop
dlg.promptText = "Prompt Text"
dlg.SuggestedFileName = "Suggested Filename"
dlg.Title = "Title Property"
dlg.Filter = txtType + htmlType + csvType + xlsType
f = dlg.ShowModal
If f <> Nil Then
  If Right(f.Name, 3) = "txt" Then
    MessageBox("1")
  ElseIf Right(f.Name, 3) = "htm" Then
    MessageBox("2")
  ElseIf Right(f.Name, 3) = "csv" Then
    MessageBox("3")
  ElseIf Right(f.Name, 3) = "xls" Then
    MessageBox("4")
  End If
Else
  ' user canceled
End If

Compatibility

All project types on all supported operating systems.