Class FileDialog

A dialog for selecting files or directories in the filesystem.

Inheritance

ConfirmationDialog

AcceptDialog

Window

Viewport

Node

Object

FileDialog

Remarks

FileDialog is a preset dialog used to choose files and directories in the filesystem. It supports filter masks. FileDialog automatically sets its window title according to the file_mode. If you want to use a custom title, disable this by setting mode_overrides_title to false.

Properties

access

The file system access scope. See Access constants.

Warning: In Web builds, FileDialog cannot access the host file system. In sandboxed Linux and macOS environments, use_native_dialog is automatically used to allow limited access to host file system.

var access : int = 0

Property Value

int

Remarks

• void set_access(int value)
• int get_access

current_dir

The current working directory of the file dialog.

Note: For native file dialogs, this property is only treated as a hint and may not be respected by specific OS implementations.

var current_dir : String

Property Value

String

Remarks

• void set_current_dir(String value)
• String get_current_dir

current_file

The currently selected file of the file dialog.

var current_file : String

Property Value

String

Remarks

• void set_current_file(String value)
• String get_current_file

current_path

The currently selected file path of the file dialog.

var current_path : String

Property Value

String

Remarks

• void set_current_path(String value)
• String get_current_path

file_mode

The dialog's open or save mode, which affects the selection behavior. See FileMode.

var file_mode : int = 4

Property Value

int

Remarks

• void set_file_mode(int value)
• int get_file_mode

filename_filter

The filter for file names (case-insensitive). When set to a non-empty string, only files that contains the substring will be shown. filename_filter can be edited by the user with the filter button at the top of the file dialog.

See also filters, which should be used to restrict the file types that can be selected instead of filename_filter which is meant to be set by the user.

var filename_filter : String = ""

Property Value

String

Remarks

• void set_filename_filter(String value)
• String get_filename_filter

filters

The available file type filters. Each filter string in the array should be formatted like this: *.png,*.jpg,*.jpeg;Image Files;image/png,image/jpeg. The description text of the filter is optional and can be omitted. Both file extensions and MIME type should be always set.

Note: Embedded file dialog and Windows file dialog support only file extensions, while Android, Linux, and macOS file dialogs also support MIME types.

var filters : PackedStringArray = PackedStringArray()

Property Value

PackedStringArray

Remarks

• void set_filters(PackedStringArray value)
• PackedStringArray get_filters

mode_overrides_title

If true, changing the file_mode property will set the window title accordingly (e.g. setting file_mode to FileDialog.FILE_MODE_OPEN_FILE will change the window title to "Open a File").

var mode_overrides_title : bool = true

Property Value

bool

Remarks

• void set_mode_overrides_title(bool value)
• bool is_mode_overriding_title

option_count

The number of additional OptionButtons and CheckBoxes in the dialog.

var option_count : int = 0

Property Value

int

Remarks

• void set_option_count(int value)
• int get_option_count

root_subfolder

If non-empty, the given sub-folder will be "root" of this FileDialog, i.e. user won't be able to go to its parent directory.

Note: This property is ignored by native file dialogs.

var root_subfolder : String = ""

Property Value

String

Remarks

• void set_root_subfolder(String value)
• String get_root_subfolder

show_hidden_files

If true, the dialog will show hidden files.

Note: This property is ignored by native file dialogs on Android and Linux.

var show_hidden_files : bool = false

Property Value

bool

Remarks

• void set_show_hidden_files(bool value)
• bool is_showing_hidden_files

use_native_dialog

If true, and if supported by the current DisplayServer, OS native dialog will be used instead of custom one.

Note: On Android, it is only supported when using FileDialog.ACCESS_FILESYSTEM. For access mode FileDialog.ACCESS_RESOURCES and FileDialog.ACCESS_USERDATA, the system will fall back to custom FileDialog.

Note: On Linux and macOS, sandboxed apps always use native dialogs to access the host file system.

Note: On macOS, sandboxed apps will save security-scoped bookmarks to retain access to the opened folders across multiple sessions. Use get_granted_permissions to get a list of saved bookmarks.

Note: Native dialogs are isolated from the base process, file dialog properties can't be modified once the dialog is shown.

var use_native_dialog : bool = false

Property Value

bool

Remarks

• void set_use_native_dialog(bool value)
• bool get_use_native_dialog

file_disabled_color

Theme Property

The color tint for disabled files (when the FileDialog is used in open folder mode).

 = ``Color(1, 1, 1, 0.25)``

Property Value

Color

file_icon_color

Theme Property

The color modulation applied to the file icon.

 = ``Color(1, 1, 1, 1)``

Property Value

Color

folder_icon_color

Theme Property

The color modulation applied to the folder icon.

 = ``Color(1, 1, 1, 1)``

Property Value

Color

back_folder

Theme Property

Custom icon for the back arrow.

Texture2D back_folder

Property Value

Texture2D

create_folder

Theme Property

Custom icon for the create folder button.

Texture2D create_folder

Property Value

Texture2D

file

Theme Property

Custom icon for files.

Texture2D file

Property Value

Texture2D

folder

Theme Property

Custom icon for folders.

Texture2D folder

Property Value

Texture2D

forward_folder

Theme Property

Custom icon for the forward arrow.

Texture2D forward_folder

Property Value

Texture2D

parent_folder

Theme Property

Custom icon for the parent folder arrow.

Texture2D parent_folder

Property Value

Texture2D

reload

Theme Property

Custom icon for the reload button.

Texture2D reload

Property Value

Texture2D

toggle_filename_filter

Theme Property

Custom icon for the toggle button for the filter for file names.

Texture2D toggle_filename_filter

Property Value

Texture2D

toggle_hidden

Theme Property

Custom icon for the toggle hidden button.

Texture2D toggle_hidden

Property Value

Texture2D

Methods

add_filter(String, String)

Adds a comma-delimited file name filter option to the FileDialog with an optional description, which restricts what files can be picked.

A filter should be of the form "filename.extension", where filename and extension can be * to match any string. Filters starting with . (i.e. empty filenames) are not allowed.

For example, a filter of "*.png, *.jpg" and a description of "Images" results in filter text "Images (*.png, *.jpg)".

void add_filter(String filter, String description)

Parameters

filter String

description String

add_option(String, PackedStringArray, int)

Adds an additional OptionButton to the file dialog. If values is empty, a CheckBox is added instead.

default_value_index should be an index of the value in the values. If values is empty it should be either 1 (checked), or 0 (unchecked).

void add_option(String name, PackedStringArray values, int default_value_index)

Parameters

name String

values PackedStringArray

default_value_index int

clear_filename_filter

Clear the filter for file names.

void clear_filename_filter

clear_filters

Clear all the added filters in the dialog.

void clear_filters

deselect_all

Clear all currently selected items in the dialog.

void deselect_all

get_line_edit

Returns the LineEdit for the selected file.

Warning: This is a required internal node, removing and freeing it may cause a crash. If you wish to hide it or any of its children, use their visible property.

LineEdit get_line_edit

get_option_default(int)

Qualifiers: const

Returns the default value index of the OptionButton or CheckBox with index option.

int get_option_default(int option)

Parameters

option int

get_option_name(int)

Qualifiers: const

Returns the name of the OptionButton or CheckBox with index option.

String get_option_name(int option)

Parameters

option int

get_option_values(int)

Qualifiers: const

Returns an array of values of the OptionButton with index option.

PackedStringArray get_option_values(int option)

Parameters

option int

get_selected_options

Qualifiers: const

Returns a Dictionary with the selected values of the additional OptionButtons and/or CheckBoxes. Dictionary keys are names and values are selected value indices.

Dictionary get_selected_options

get_vbox

Returns the vertical box container of the dialog, custom controls can be added to it.

Warning: This is a required internal node, removing and freeing it may cause a crash. If you wish to hide it or any of its children, use their visible property.

Note: Changes to this node are ignored by native file dialogs, use FileDialog.add_option to add custom elements to the dialog instead.

VBoxContainer get_vbox

invalidate

Invalidate and update the current dialog content list.

Note: This method does nothing on native file dialogs.

void invalidate

set_option_default(int, int)

Sets the default value index of the OptionButton or CheckBox with index option.

void set_option_default(int option, int default_value_index)

Parameters

option int

default_value_index int

set_option_name(int, String)

Sets the name of the OptionButton or CheckBox with index option.

void set_option_name(int option, String name)

Parameters

option int

name String

set_option_values(int, PackedStringArray)

Sets the option values of the OptionButton with index option.

void set_option_values(int option, PackedStringArray values)

Parameters

option int

values PackedStringArray

Events

dir_selected(String)

Emitted when the user selects a directory.

signal dir_selected(String dir)

Parameters

dir String

file_selected(String)

Emitted when the user selects a file by double-clicking it or pressing the OK button.

signal file_selected(String path)

Parameters

path String

filename_filter_changed(String)

Emitted when the filter for file names changes.

signal filename_filter_changed(String filter)

Parameters

filter String

files_selected(PackedStringArray)

Emitted when the user selects multiple files.

signal files_selected(PackedStringArray paths)

Parameters

paths PackedStringArray