Class

# FolderItemDialog

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

## Description

The base class for the `OpenFileDialog</api/user_interface/desktop/openfiledialog>`, `SaveFileDialog</api/user_interface/desktop/savefiledialog>`, and `SelectFolderDialog</api/user_interface/desktop/selectfolderdialog>` classes, which allow you to create customized open, save, and select folder dialog boxes.

## Properties

<div class="rst-class">

table-centered_columns_3_and_4

</div>

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

## Methods

<div class="rst-class">

table-centered_column_4

</div>

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

## Property descriptions

<div id="folderitemdialog.actionbuttoncaption">

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

</div>

<div class="rst-class">

forsearch

</div>

FolderItemDialog.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.
>
> This example illustrates all the labelling properties of a <span class="title-ref">FolderItemDialog</span>.
>
> ``` xojo
> Var dlg As OpenFileDialog
>
> dlg = New OpenFileDialog
> 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
>
> Var f As FolderItem = dlg.ShowModal
>
> If f <> Nil Then
>   MessageBox("You selected: " + f.NativePath)
> Else
>   ' User Cancelled
> End If
> ```

<div id="folderitemdialog.cancelbuttoncaption">

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

</div>

<div class="rst-class">

forsearch

</div>

FolderItemDialog.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.
>
> This example illustrates all the labelling properties of a <span class="title-ref">FolderItemDialog</span>.
>
> ``` xojo
> Var dlg As OpenFileDialog
>
> dlg = New OpenFileDialog
> 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
>
> Var f As FolderItem = dlg.ShowModal
>
> If f <> Nil Then
>   MessageBox("You selected: " + f.NativePath)
> Else
>   ' User Cancelled
> End If
> ```

<div id="folderitemdialog.filter">

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

</div>

<div class="rst-class">

forsearch

</div>

FolderItemDialog.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.
>
> This example illustrates all the labelling properties of a <span class="title-ref">FolderItemDialog</span>.
>
> ``` xojo
> Var dlg As New OpenFileDialog
>
> 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
> ```

<div id="folderitemdialog.initialfolder">

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

</div>

<div class="rst-class">

forsearch

</div>

FolderItemDialog.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.
>
> This example illustrates all the labelling properties of a <span class="title-ref">FolderItemDialog</span>.
>
> ``` xojo
> Var dlg As New OpenFileDialog
>
> #If Not (TargetLinux) then
>   dlg.InitialFolder = SpecialFolder.Documents
> #Else //open Home directory on linux
>   dlg.InitialFolder = SpecialFolder.home
> #EndIf
>
> Var f As FolderItem = dlg.ShowModal
> ```

<div id="folderitemdialog.left">

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

</div>

<div class="rst-class">

forsearch

</div>

FolderItemDialog.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.
>
> This code illustrates all the labelling properties of a <span class="title-ref">FolderItemDialog</span>.
>
> ``` xojo
> Var dlg As New OpenFileDialog
>
> dlg.Left = 50
> dlg.Top = 50
>
> Var f As FolderItem = dlg.ShowModal
>
> If f <> Nil Then
>   MessageBox("You selected: " + f.NativePath)
> Else
>   ' User Cancelled
> End If
> ```

<div id="folderitemdialog.prompttext">

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

</div>

<div class="rst-class">

forsearch

</div>

FolderItemDialog.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 `SelectFolderDialog</api/user_interface/desktop/selectfolderdialog>`.
>
> This example illustrates all the labelling properties of a <span class="title-ref">FolderItemDialog</span>.
>
> ``` xojo
> Var dlg As New OpenFileDialog
>
> dlg.PromptText = "Select a file"
>
> Var f As FolderItem = dlg.ShowModal
>
> If f <> Nil Then
>   MessageBox("You selected: " + f.NativePath)
> Else
>   ' User Cancelled
> End If
> ```

<div id="folderitemdialog.result">

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

</div>

<div class="rst-class">

forsearch

</div>

FolderItemDialog.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>`.
>
> This example displays the NativePath to the mp4 file that the user selects using the Result property.
>
> ``` xojo
> Var dlg As New OpenFileDialog
>
> dlg.PromptText = "Select a file"
>
> Var f As FolderItem = dlg.ShowModal
>
> If dlg.Result <> Nil Then
>   MessageBox("You selected: " + dlg.Result.NativePath)
> Else
>   ' User Cancelled
> End If
> ```

<div id="folderitemdialog.suggestedfilename">

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

</div>

<div class="rst-class">

forsearch

</div>

FolderItemDialog.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.
>
> This example illustrates all the labelling properties of a <span class="title-ref">FolderItemDialog</span>.
>
> ``` xojo
> Var dlg As New SaveAsDialog
>
> dlg.SuggestedFileName = "SaveFile.txt"
>
> Var f As FolderItem = dlg.ShowModal
>
> If f <> Nil Then
>   MessageBox("You selected: " + f.NativePath)
> Else
>   ' User Cancelled
> End If
> ```

<div id="folderitemdialog.title">

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

</div>

<div class="rst-class">

forsearch

</div>

FolderItemDialog.Title

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

> The string that appears in the Title bar. This property is ignored on macOS.
>
> This example illustrates all the labelling properties of a <span class="title-ref">FolderItemDialog</span>.
>
> ``` xojo
> Var dlg As New OpenFileDialog
>
> dlg.Title = "Choose a File"
>
> Var f As FolderItem = dlg.ShowModal
>
> If f <> Nil Then
>   MessageBox("You selected: " + f.NativePath)
> Else
>   ' User Cancelled
> End If
> ```

<div id="folderitemdialog.top">

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

</div>

<div class="rst-class">

forsearch

</div>

FolderItemDialog.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.
>
> This code illustrates all the labelling properties of a <span class="title-ref">FolderItemDialog</span>.
>
> ``` xojo
> Var dlg As New OpenFileDialog
>
> dlg.Left = 50
> dlg.Top = 50
>
> Var f As FolderItem = dlg.ShowModal
>
> If f <> Nil Then
>   MessageBox("You selected: " + f.NativePath)
> Else
>   ' User Cancelled
> End If
> ```

## Method descriptions

<div id="folderitemdialog.showmodal">

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

</div>

<div class="rst-class">

forsearch

</div>

FolderItemDialog.ShowModal

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

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

> Displays the <span class="title-ref">FolderItemDialog</span> as a Sheet window on macOS within the window specified by *parent*.

## Notes

Not all properties are available for all three subclasses of <span class="title-ref">FolderItemDialog</span> 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</api/files/filetype>` class.

``` xojo
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 = 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.

``` xojo
Var dlg As New SaveFileDialog

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

Var f As FolderItem = 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:

``` xojo
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 = 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">

`Object</api/data_types/additional_types/object>` parent class; `OpenFileDialog</api/user_interface/desktop/openfiledialog>`, `SaveFileDialog</api/user_interface/desktop/savefiledialog>`, `SelectFolderDialog</api/user_interface/desktop/selectfolderdialog>` classes.

</div>