Class

# SaveFileDialog

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

## Description

Used to create customized Save File dialogs. Non-customizable Save File dialogs are created by the `FolderItem<folderitem.showsavefiledialog>` function.

## Properties

<div class="rst-class">

table-centered_columns_3_and_4

</div>

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

## Methods

<div class="rst-class">

table-centered_column_4

</div>

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

## Property descriptions

<div id="savefiledialog.actionbuttoncaption">

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

</div>

<div class="rst-class">

forsearch

</div>

SaveFileDialog.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 `FolderItemDialog</api/user_interface/desktop/folderitemdialog>`.
>
> ``` xojo
> Var dlg As New SaveFileDialog
>
> 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="savefiledialog.cancelbuttoncaption">

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

</div>

<div class="rst-class">

forsearch

</div>

SaveFileDialog.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 `FolderItemDialog</api/user_interface/desktop/folderitemdialog>`.
>
> ``` xojo
> Var dlg As New SaveFileDialog
>
> 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="savefiledialog.filter">

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

</div>

<div class="rst-class">

forsearch

</div>

SaveFileDialog.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 `FolderItemDialog</api/user_interface/desktop/folderitemdialog>`.
>
> ``` xojo
> Var dlg As New SaveFileDialog
>
> dlg.Title = "Select an mp4 file"
> dlg.Filter = FileTypeGroup1.Videos ' defined in the File Type Group Editor...
>
> Var f As FolderItem = dlg.ShowModal
>
> If f <> Nil Then
>   MoviePlayer1.Movie = Movie.Open(f)
> Else
>   ' user cancelled
> End If
> ```

<div id="savefiledialog.initialfolder">

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

</div>

<div class="rst-class">

forsearch

</div>

SaveFileDialog.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 `FolderItemDialog</api/user_interface/desktop/folderitemdialog>`.
>
> ``` xojo
> Var dlg As New SaveFileDialog
>
> #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="savefiledialog.left">

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

</div>

<div class="rst-class">

forsearch

</div>

SaveFileDialog.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 `FolderItemDialog</api/user_interface/desktop/folderitemdialog>`.
>
> ``` xojo
> Var dlg As New SaveFileDialog
>
> 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="savefiledialog.prompttext">

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

</div>

<div class="rst-class">

forsearch

</div>

SaveFileDialog.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 `FolderItemDialog</api/user_interface/desktop/folderitemdialog>`.
>
> ``` xojo
> Var dlg As New SaveFileDialog
>
> 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="savefiledialog.result">

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

</div>

<div class="rst-class">

forsearch

</div>

SaveFileDialog.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 SaveFileDialog
>
> 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="savefiledialog.suggestedfilename">

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

</div>

<div class="rst-class">

forsearch

</div>

SaveFileDialog.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 `FolderItemDialog</api/user_interface/desktop/folderitemdialog>`.
>
> ``` xojo
> Var dlg As New SaveFileDialog
>
> 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="savefiledialog.title">

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

</div>

<div class="rst-class">

forsearch

</div>

SaveFileDialog.Title

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

> The string that appears in the Title bar.
>
> This example illustrates all the labelling properties of a `FolderItemDialog</api/user_interface/desktop/folderitemdialog>`.
>
> ``` xojo
> Var dlg As New SaveFileDialog
>
> 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="savefiledialog.top">

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

</div>

<div class="rst-class">

forsearch

</div>

SaveFileDialog.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 `FolderItemDialog</api/user_interface/desktop/folderitemdialog>`.
>
> ``` xojo
> Var dlg As New SaveFileDialog
>
> 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="savefiledialog.showmodal">

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

</div>

<div class="rst-class">

forsearch

</div>

SaveFileDialog.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 save-file dialog box:

- Position (Left and Top properties)
- Default Folder (Initial Folder property)
- Valid file types to show (Filter property).
- If you specify more than one file type (separate the file type names with semicolons), <span class="title-ref">SaveFileDialog</span> will add a Format pop-up menu to the dialog, allowing the user to specify the desired file type to use. Examine the extension of the file name returned to see which format was chosen.
- Default filename (SuggestedFileName 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)

On macOS 10.11 through 10.15, a Hide Filename Extension checkbox appears in the save-file dialog. The `FolderItem</api/files/folderitem>` returned has its ExtensionVisible property set according to the user's use of this checkbox.

## Sample code

The following code opens a customized save-file dialog box and displays the contents of the "Documents" directory in the browser area. It refers to the 'text/plain' common file type defined in the FileTypeGroup1 file type set.

``` 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
  ' f is the FolderItem of the file to save
Else
  ' user canceled
End If
```

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

The following code creates a pop-up menu in the Save File dialog that gives the user the option of choosing among four file types.

``` xojo
Var txtType As New FileType

txtType.Name = "Text File (*.txt)"
txtType.MacType = "TEXT"
txtType.Extensions = "txt"

Var htmlType As New FileType

htmlType.Name = "HTML File (*.htm, *.html)"
htmlType.MacType = "HTML "
htmlType.Extensions = "htm"

Var csvType As New FileType

csvType.Name = "CSV File (*.csv)"
csvType.MacType = "TEXT"
csvType.Extensions = "csv"

Var xlsType As New FileType

xlsType.Name = "Excel File (*.xls)"
xlsType.MacType = "XLS "
xlsType.Extensions = "xls"

Var dlg As New SaveFileDialog 

dlg.InitialFolder = SpecialFolder.Desktop
dlg.promptText = "Prompt Text"
dlg.SuggestedFileName = "Suggested Filename"
dlg.Title = "Title Property"
dlg.Filter = txtType + htmlType + csvType + xlsType

Var f As FolderItem = dlg.ShowModal

If f <> Nil Then
  If Right(f.Name, 3) = "txt" Then
    MessageBox("1")
  ElseIf Right(f.Name, 3) = "htm" Then
    MessageBox("2")
  ElseIf Right(f.Name, 3) = "csv" Then
    MessageBox("3")
  ElseIf Right(f.Name, 3) = "xls" Then
    MessageBox("4")
  End If
Else
  ' user canceled
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>`, `SelectFolderDialog</api/user_interface/desktop/selectfolderdialog>` classes

</div>