Class

FolderItemDialog

Warning

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

Description

The base class for the OpenFileDialog, SaveFileDialog, and SelectFolderDialog classes, which allow you to create customized open, save, and select folder dialog boxes.

Properties

Name	Type	Read-Only
ActionButtonCaption	String
CancelButtonCaption	String
Filter	String
InitialFolder	FolderItem
Left	Integer
PromptText	String
Result	FolderItem	✓
SuggestedFileName	String
Title	String
Top	Integer

Methods

Name	Parameters	Returns	Shared
ShowModal		FolderItem

Property descriptions

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

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

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

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

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

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

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

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

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

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

FolderItemDialog.ShowModal

ShowModal As FolderItem

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

Notes

Not all properties are available for all three subclasses of FolderItemDialog and some properties are not supported on Windows.

The following table clarifies the situation.

Property	Windows	Windows	Windows	macOS	macOS	macOS	Linux	Linux	Linux
	OpenDialog	SaveAsDialog	SelectFolder	OpenDialog	SaveAsDialog	SelectFolder	OpenDialog	SaveAsDialog	SelectFolder
Top & Left	✓	✓	✓	✓	✓	✓	✓	✓	✓
PromptText			✓	✓	✓	✓
Title	✓	✓	✓	✓	✓	✓	✓	✓	✓
ActionButtonCaption			✓	✓	✓	✓
CancelButtonCaption	✓	✓	✓
SuggestedFileName	✓	✓			✓			✓
Filter	✓	✓		✓	✓		✓	✓
InitialDirectory	✓	✓	✓	✓	✓	✓	✓	✓	✓

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.

Var dlg As 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 MIF file"
dlg.Filter = FileTypeGroup1.mif //Defined as file type in FileTypeGroup1.
Var f As FolderItem
f = dlg.ShowModal
If f <> Nil Then
  ' proceed normally
Else
  ' User Cancelled
End If

The following example opens a customized save-file dialog box and displays the contents of the "Documents" directory in the browser area.

Var dlg As New SaveFileDialog
Var f 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
f = dlg.ShowModal
If f <> Nil Then
  ' file saved
Else
  //user canceled
End If

The following example opens a select folder dialog box and presents the contents of the "Documents" or "Home" directory on the user's startup volume in the browser:

Var dlg As New SelectFolderDialog
dlg.ActionButtonCaption = "Select"
dlg.Title = "Title Property"
dlg.PromptText = "Prompt Text"
#If Not TargetLinux Then
  dlg.InitialFolder = SpecialFolder.Documents
#Else ' open Home directory on linux
dlg.InitialFolder = SpecialFolder.Home
#Endif
Var f As FolderItem
f = dlg.ShowModal
If f <> Nil Then
  ' use the folderitem here
Else
  ' user cancelled
End If

Compatibility

All project types on all supported operating systems.

FolderItemDialog

Description

Properties

Methods

Property descriptions

Method descriptions

Notes

Sample code

Compatibility

See also