Used to create and present customized Select Folder dialog boxes. The non-customized version of this function is provided by the FolderItem function.








Property descriptions


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.


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.


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.


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.


Left As Integer

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


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.


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.


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.


Title As String

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


Top As Integer

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

Method descriptions


ShowModal As FolderItem

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


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

  • Position (Left and Top properties)

  • Default directory (InitialFolder 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 in the body of the dialog (PromptText property)

Sample code

The following example opens a select folder dialog box and presents the contents of the "Documents" 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"
dlg.InitialFolder = SpecialFolder.Documents

Var f As FolderItem
f = dlg.ShowModal
If f <> Nil Then
  ' Use the folderitem here
  ' User cancelled
End If


All project types on all supported operating systems.