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<folderitem.showselectfolderdialog>` function.

## Properties

<div class="rst-class">

table-centered_columns_3_and_4

</div>

| Name                                                          | Type                                | Read-Only | Shared |
|---------------------------------------------------------------|-------------------------------------|-----------|--------|
| `ActionButtonCaption<selectfolderdialog.actionbuttoncaption>` | `String</api/data_types/string>`    |           |        |
| `CancelButtonCaption<selectfolderdialog.cancelbuttoncaption>` | `String</api/data_types/string>`    |           |        |
| `Filter<selectfolderdialog.filter>`                           | `String</api/data_types/string>`    |           |        |
| `InitialFolder<selectfolderdialog.initialfolder>`             | `FolderItem</api/files/folderitem>` |           |        |
| `Left<selectfolderdialog.left>`                               | `Integer</api/data_types/integer>`  |           |        |
| `PromptText<selectfolderdialog.prompttext>`                   | `String</api/data_types/string>`    |           |        |
| `Result<selectfolderdialog.result>`                           | `FolderItem</api/files/folderitem>` | ✓         |        |
| `SuggestedFileName<selectfolderdialog.suggestedfilename>`     | `String</api/data_types/string>`    |           |        |
| `Title<selectfolderdialog.title>`                             | `String</api/data_types/string>`    |           |        |
| `Top<selectfolderdialog.top>`                                 | `Integer</api/data_types/integer>`  |           |        |

## Methods

<div class="rst-class">

table-centered_column_4

</div>

| Name                                      | Parameters                                                           | Returns                             | Shared |
|-------------------------------------------|----------------------------------------------------------------------|-------------------------------------|--------|
| `ShowModal<selectfolderdialog.showmodal>` |                                                                      | `FolderItem</api/files/folderitem>` |        |
|                                           | parent As `DesktopWindow</api/user_interface/desktop/desktopwindow>` | `FolderItem</api/files/folderitem>` |        |

## Property descriptions

<div id="selectfolderdialog.actionbuttoncaption">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

SelectFolderDialog.ActionButtonCaption

**ActionButtonCaption** As `String</api/data_types/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.

<div id="selectfolderdialog.cancelbuttoncaption">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

SelectFolderDialog.CancelButtonCaption

**CancelButtonCaption** As `String</api/data_types/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.

<div id="selectfolderdialog.filter">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

SelectFolderDialog.Filter

**Filter** As `String</api/data_types/string>`

> One or more File Types, separated by semicolons, previously defined via the `FileType</api/files/filetype>` class or in the File Type Sets Editor in the IDE.
>
> *Filter* controls which files within *InitialDirectory* are visible.

<div id="selectfolderdialog.initialfolder">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

SelectFolderDialog.InitialFolder

**InitialFolder** As `FolderItem</api/files/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</api/files/folderitem>` is specified.

<div id="selectfolderdialog.left">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

SelectFolderDialog.Left

**Left** As `Integer</api/data_types/integer>`

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

<div id="selectfolderdialog.prompttext">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

SelectFolderDialog.PromptText

**PromptText** As `String</api/data_types/string>`

> The Help text that appears within the dialog.
>
> PromptText is displayed on macOS for all dialog types and on Windows for <span class="title-ref">SelectFolderDialog</span>.

<div id="selectfolderdialog.result">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

SelectFolderDialog.Result

**Result** As `FolderItem</api/files/folderitem>`

> Holds the result of calling ShowModal or ShowModalWithin.
>
> This property is read-only.
>
> If the user validates the dialog, *Result* contains the `FolderItem</api/files/folderitem>` corresponding to the selection; otherwise, *Result* is `Nil</api/language/nil>`.

<div id="selectfolderdialog.suggestedfilename">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

SelectFolderDialog.SuggestedFileName

**SuggestedFileName** As `String</api/data_types/string>`

> The default name of the file; it appears as the default text in the filename enterable area.
>
> `OpenFileDialog</api/user_interface/desktop/openfiledialog>` displays this value on Windows, but not other platforms.

<div id="selectfolderdialog.title">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

SelectFolderDialog.Title

**Title** As `String</api/data_types/string>`

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

<div id="selectfolderdialog.top">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

SelectFolderDialog.Top

**Top** As `Integer</api/data_types/integer>`

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

## Method descriptions

<div id="selectfolderdialog.showmodal">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

SelectFolderDialog.ShowModal

**ShowModal** As `FolderItem</api/files/folderitem>`

**ShowModal**(parent As `DesktopWindow</api/user_interface/desktop/desktopwindow>`) As `FolderItem</api/files/folderitem>`

> Displays the FolderItemDialog as a Sheet window on macOS within the window specified by *parent*.

## Notes

Using the properties of the `FolderItemDialog</api/user_interface/desktop/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:

``` xojo
Var dlg As New SelectFolderDialog

dlg.ActionButtonCaption = "Select"
dlg.Title = "Title Property"
dlg.PromptText = "Prompt Text"
dlg.InitialFolder = SpecialFolder.Documents

Var f As FolderItem = dlg.ShowModal

If f <> Nil Then
  ' Use the folderitem here
Else
  ' User cancelled
End If
```

## Compatibility

|                       |         |
|-----------------------|---------|
| **Project Types**     | Desktop |
| **Operating Systems** | All     |

<div class="seealso">

`FolderItemDialog</api/user_interface/desktop/folderitemdialog>` parent class; `FileType</api/files/filetype>`, `FolderItem</api/files/folderitem>`, `FolderItemDialog</api/user_interface/desktop/folderitemdialog>`, `OpenFileDialog</api/user_interface/desktop/openfiledialog>`, `SaveFileDialog</api/user_interface/desktop/savefiledialog>`, classes; `FolderItem.ShowSelectFolderDialog<folderitem.showselectfolderdialog>` function.

</div>