Class

OpenDialog

Warning

This item was deprecated in version 2019r2. Please use OpenFileDialog as a replacement.

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

Item

zeroBasedIndex As Integer

FolderItem

ShowModal

FolderItem

Property descriptions

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

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

OpenDialog.Count

Count As Integer

The number of items selected by the user in the OpenDialog. If MultiSelect 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 MultiSelect is not selected.

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

OpenDialog.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 = 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

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

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

OpenDialog.MultiSelect

MultiSelect 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 MultiSelect OpenDialog, the FolderItem returned will be the first selection. To obtain a list of all the selected FolderItem) As FolderItem and Count As Integer properties.

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

Dim dlg As New OpenDialog
dlg.ActionButtonCaption = "Select Files"
dlg.CancelButtonCaption = "Cancel"
dlg.SuggestedFileName = ""
dlg.Title = "Select Files"
dlg.PromptText = "Select one or more files"
dlg.InitialDirectory = SpecialFolder.Documents
dlg.MultiSelect = True
Dim f As FolderItem = dlg.ShowModal
Dim fileCount As Integer = dlg.Count

For i As Integer = 0 To fileCount - 1
  Listbox1.AddRow(dlg.Item(i).Name)
Next

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

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

OpenDialog.SuggestedFileName

SuggestedFileName As String

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

OpenDialog 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

OpenDialog.Title

Title As String

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

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

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

OpenDialog.Item

Item(zeroBasedIndex As Integer) As FolderItem

The items selected by the user in the OpenDialog.

If MultiSelect is True, then this provides access to the files that were selected. You can get the number of items from the Count property and you can access an individual item by passing a value for the zeroBasedIndex parameter. Item is zero-based.

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

Dim dlg As New OpenDialog
dlg.ActionButtonCaption = "Select Files"
dlg.CancelButtonCaption = "Cancel"
dlg.SuggestedFileName = ""
dlg.Title = "Select Files"
dlg.PromptText = "Select one or more files"
dlg.InitialDirectory = SpecialFolder.Documents
dlg.MultiSelect = True
Dim f As FolderItem = dlg.ShowModal
Dim fileCount As Integer = dlg.Count

For i As Integer = 0 To fileCount - 1
  Listbox1.AddRow(dlg.Item(i).Name)
Next

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

The following code opens a customizable open-file dialog box and presents the Documents or Home directory in the file browser. Only MIF 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.

Dim dlg As OpenDialog
Dim f As FolderItem
dlg = New OpenDialog
#If Not TargetLinux Then
  dlg.InitialDirectory = SpecialFolder.Documents
#Else //open Home directory on linux
  dlg.InitialDirectory = 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.