Class

# OpenFileDialog

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

## Description

Creates a customizable Open-file dialog box. The non-customizable version of this dialog is displayed by the `FolderItem<folderitem.showopenfiledialog>` function.

## Properties

<div class="rst-class">

table-centered_columns_3_and_4

</div>

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

## Methods

<div class="rst-class">

table-centered_column_4

</div>

| Name                                          | Parameters                                                                     | Returns                             | Shared |
|-----------------------------------------------|--------------------------------------------------------------------------------|-------------------------------------|--------|
| `SelectedFiles<openfiledialog.selectedfiles>` | followAlias As `Boolean</api/data_types/boolean>` = `True</api/language/true>` | `Iterable</api/language/iterable>`  |        |
| `ShowModal<openfiledialog.showmodal>`         |                                                                                | `FolderItem</api/files/folderitem>` |        |
|                                               | parent As `DesktopWindow</api/user_interface/desktop/desktopwindow>`           | `FolderItem</api/files/folderitem>` |        |

## Property descriptions

<div id="openfiledialog.actionbuttoncaption">

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

</div>

<div class="rst-class">

forsearch

</div>

OpenFileDialog.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="openfiledialog.allowmultipleselections">

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

</div>

<div class="rst-class">

forsearch

</div>

OpenFileDialog.AllowMultipleSelections

**AllowMultipleSelections** As `Boolean</api/data_types/boolean>`

> If `True</api/language/true>`, the dialog supports multiple file selections. The default is `False</api/language/false>`.
>
> ShowModal still returns a `FolderItem</api/files/folderitem>`, but in the case of a AllowMultipleSelections <span class="title-ref">OpenFileDialog</span>, the `FolderItem</api/files/folderitem>` returned will be the first selection. To obtain a list of all the selected `` FolderItem</api/files/folderitem>`s, use the :ref:`SelectedFiles<openfiledialog.selectedfiles> `` to iterate through them.
>
> In this example the user can choose multiple files which are then displayed in a Listbox:
>
> ``` xojo
> Var dlg As New OpenFileDialog
>
> dlg.ActionButtonCaption = "Select Files"
> dlg.CancelButtonCaption = "Cancel"
> dlg.SuggestedFileName = ""
> dlg.Title = "Select Files"
> dlg.PromptText = "Select one or more files"
> dlg.InitialFolder = SpecialFolder.Documents
> dlg.AllowMultipleSelections = True
>
> Var f As FolderItem = dlg.ShowModal
>
> For Each file As FolderItem In dlg.SelectedFiles
>   Listbox1.AddRow(file.Name)
> Next
> ```

<div id="openfiledialog.cancelbuttoncaption">

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

</div>

<div class="rst-class">

forsearch

</div>

OpenFileDialog.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="openfiledialog.count">

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

</div>

<div class="rst-class">

forsearch

</div>

OpenFileDialog.Count

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

> The number of items selected by the user in the <span class="title-ref">OpenFileDialog</span>. If `AllowMultipleSelections<openfiledialog.allowmultipleselections>` is `True</api/language/true>`, the number can be greater than 1.
>
> The following gets the number of items the user selected. In this case, it will be 1 since `AllowMultipleSelections<openfiledialog.allowmultipleselections>` is not selected.
>
> ``` xojo
> Var f As FolderItem = dlg.ShowModal
> Var i As Integer = dlg.Count
> ```

<div id="openfiledialog.filter">

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

</div>

<div class="rst-class">

forsearch

</div>

OpenFileDialog.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 setting the Filter property to show only MP4 videos:
>
> ``` 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="openfiledialog.initialfolder">

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

</div>

<div class="rst-class">

forsearch

</div>

OpenFileDialog.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 setting the intial folder to the Home folder/directory on Linux and the Documents folder/directory macOS and Windows:
>
> ``` 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="openfiledialog.left">

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

</div>

<div class="rst-class">

forsearch

</div>

OpenFileDialog.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="openfiledialog.prompttext">

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

</div>

<div class="rst-class">

forsearch

</div>

OpenFileDialog.PromptText

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

> The Help text that appears within the dialog.
>
> This example illustrates setting the PromptText to "Select a file":
>
> ``` 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="openfiledialog.result">

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

</div>

<div class="rst-class">

forsearch

</div>

OpenFileDialog.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 of whatever file the user selects:
>
> ``` 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="openfiledialog.suggestedfilename">

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

</div>

<div class="rst-class">

forsearch

</div>

OpenFileDialog.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 displays this value on Windows, but not other platforms.

<div id="openfiledialog.title">

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

</div>

<div class="rst-class">

forsearch

</div>

OpenFileDialog.Title

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

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

<div id="openfiledialog.top">

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

</div>

<div class="rst-class">

forsearch

</div>

OpenFileDialog.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="openfiledialog.selectedfiles">

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

</div>

<div class="rst-class">

forsearch

</div>

OpenFileDialog.SelectedFiles

**SelectedFiles**(followAlias As `Boolean</api/data_types/boolean>` = `True</api/language/true>`) As `Iterable</api/language/iterable>`

> Allow you to iterate through all the files the user selected in the open file dialog box.
>
> Let user choose multiple files and displays them in a Listbox:
>
> ``` xojo
> Var dlg As New OpenFileDialog
>
> dlg.ActionButtonCaption = "Select Files"
> dlg.CancelButtonCaption = "Cancel"
> dlg.SuggestedFileName = ""
> dlg.Title = "Select Files"
> dlg.PromptText = "Select one or more files"
> dlg.InitialFolder = SpecialFolder.Documents
> dlg.AllowMultipleSelections = True
>
> Var f As FolderItem = dlg.ShowModal
>
> For Each file As FolderItem In dlg.SelectedFiles
>   Listbox1.AddRow(file.Name)
> Next
> ```

<div id="openfiledialog.showmodal">

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

</div>

<div class="rst-class">

forsearch

</div>

OpenFileDialog.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 `OpenFileDialog` class, you can customize the following aspects of an open-file dialog box:

- Position (Left and Top properties)
- Default directory (Initial Directory 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 inside the dialog (PromptText property)

## Sample code

This example illustrates all the labelling properties of a <span class="title-ref">OpenItemDialog</span>.

``` xojo
Var dlg As 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
```

The following code opens a customizable open-file dialog box and presents the Documents or Home directory in the file browser. Only text 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 Text file"
dlg.Filter = FileTypes1.Text ' "text/plain" file type defined in FileTypes1 set

Var f As FolderItem = dlg.ShowModal

If f <> Nil Then
  ' proceed normally
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>`, `SaveFileDialog</api/user_interface/desktop/savefiledialog>`, `SelectFolderDialog</api/user_interface/desktop/selectfolderdialog>` classes

</div>