Class

OpenFileDialog

Description

Creates a customizable Open-file dialog box. The non-customizable version of this dialog is displayed by the FolderItem function.

Methods

Name

Parameters

Returns

Shared

SelectedFiles

resolveAlias As Boolean

Iterable

ShowModal

FolderItem

Property descriptions

OpenFileDialog.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.

OpenFileDialog.AllowMultipleSelections

AllowMultipleSelections As Boolean

If True, the dialog supports multiple file selections. The default is False.

ShowModal still returns a FolderItem, but in the case of a AllowMultipleSelections OpenFileDialog, the FolderItem returned will be the first selection. To obtain a list of all the selected FolderItem to iterate through them.

In this example the user can choose multiple files which are then displayed in a Listbox:

Var dlg As New OpenFileDialog
dlg.ActionButtonCaption = "Select Files"
dlg.CancelButtonCaption = "Cancel"
dlg.SuggestedFileName = ""
dlg.Title = "Select Files"
dlg.PromptText = "Select one or more files"
dlg.InitialFolder = SpecialFolder.Documents
dlg.AllowMultipleSelections = True
Var f As FolderItem = dlg.ShowModal

For Each file As Folderitem In dlg.SelectedFiles
  Listbox1.AddRow(file.Name)
Next

OpenFileDialog.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.

OpenFileDialog.Count

Count As Integer

The number of items selected by the user in the OpenFileDialog. If AllowMultipleSelections is True, the number can be greater than 1.

The following gets the number of items the user selected. In this case, it will be 1 since AllowMultipleSelections is not selected.

Var f As FolderItem = dlg.ShowModal
Var i As Integer = dlg.Count

OpenFileDialog.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 setting the Filter property to show only MP4 videos:

Var dlg As New OpenFileDialog
dlg.Title = "Select an mp4 file"
dlg.Filter = FileTypes1.VideoMp4.Extensions ' defined in the File Types Editor...

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

OpenFileDialog.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 setting the intial folder to the Home folder/directory on Linux and the Documents folder/directory macOS and Windows:

Var dlg As OpenFileDialog
Var f As FolderItem
dlg = New OpenFileDialog

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

OpenFileDialog.Left

Left As Integer

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

OpenFileDialog.PromptText

PromptText As String

The Help text that appears within the dialog.

This example illustrates setting the PromptText to "Select a file":

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

OpenFileDialog.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 of whatever file the user selects:

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

OpenFileDialog.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.

OpenFileDialog.Title

Title As String

The string that appears in the Title bar. This property is ignored on Macintosh.

OpenFileDialog.Top

Top As Integer

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

Method descriptions

OpenFileDialog.SelectedFiles

SelectedFiles(resolveAlias As Boolean) As Iterable

Allow you to iterate through all the files the user selected in the open file dialog box.

Let user choose multiple files and displays them in a Listbox:

Var dlg As New OpenFileDialog
dlg.ActionButtonCaption = "Select Files"
dlg.CancelButtonCaption = "Cancel"
dlg.SuggestedFileName = ""
dlg.Title = "Select Files"
dlg.PromptText = "Select one or more files"
dlg.InitialFolder = SpecialFolder.Documents
dlg.AllowMultipleSelections = True
Var f As FolderItem = dlg.ShowModal

For Each file As Folderitem In dlg.SelectedFiles
  Listbox1.AddRow(file.Name)
Next

OpenFileDialog.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 OpenFileDialog class, you can customize the following aspects of an open-file dialog box:

  • Position (Left and Top properties)

  • Default directory (Initial Directory property)

  • Valid file types to show (Filter 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 inside the dialog (PromptText property)

Sample code

This example illustrates all the labelling properties of a OpenItemDialog.

Var dlg As OpenFileDialog
Var f As FolderItem
dlg = New OpenFileDialog
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

The following code opens a customizable open-file dialog box and presents the Documents or Home directory in the file browser. Only text files are listed. The file type passed to the Filter parameter was previously defined in a File Type Set called "TextTypes" in the File Type Sets Editor or via the FileType class.

Var dlg As OpenFileDialog
Var f As FolderItem
dlg = New OpenFileDialog
#If Not TargetLinux Then
  dlg.InitialFolder = SpecialFolder.Documents
#Else //open Home directory on linux
  dlg.InitialFolder = SpecialFolder.Home
#Endif

dlg.Title = "Select a Text file"
dlg.Filter = FileTypes1.Text  ' "text/plain" file type defined in FileTypes1 set
f = dlg.ShowModal
If f <> Nil Then
  //proceed normally
Else
   //User Cancelled
End If

Compatibility

All project types on all supported operating systems.