From Xojo Documentation

You are currently browsing the old Xojo documentation site. Please visit the new Xojo documentation site!

Class (inherits from FolderItemDialog)

New in 2019r2

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

ActionButtonCaption Left Title
CancelButtonCaption PromptText Top
Filter Result fa-lock-32.png
InitialFolder SuggestedFileName



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
// 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
ElseIf Right(f.Name, 3) = "htm" Then
ElseIf Right(f.Name, 3) = "csv" Then
ElseIf Right(f.Name, 3) = "xls" Then
End If
// user canceled
End If

See Also

FileType, FolderItem, FolderItemDialog, OpenFileDialog, SelectFolderDialog classes