Class

SelectFolderDialog

Description

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

Methods

Name

Parameters

Returns

Shared

ShowModal

FolderItem

Property descriptions

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

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

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

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

SelectFolderDialog.Left

Left As Integer

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

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

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

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

SelectFolderDialog.Title

Title As String

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

SelectFolderDialog.Top

Top As Integer

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

Method descriptions

SelectFolderDialog.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 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
Else
  ' User cancelled
End If

Compatibility

All project types on all supported operating systems.