Attention: Here be dragons
This is the latest
(unstable) version of this documentation, which may document features
not available in or compatible with released stable versions of Godot.
Checking the stable version of the documentation...
FileDialog¶
Inherits: ConfirmationDialog < AcceptDialog < Window < Viewport < Node < Object
A dialog for selecting files or directories in the filesystem.
Description¶
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¶
|
||
dialog_hide_on_ok |
|
|
|
||
|
||
|
||
|
||
|
||
|
||
title |
|
|
|
Methods¶
void |
add_filter(filter: String, description: String = "") |
void |
add_option(name: String, values: PackedStringArray, index: int) |
void |
|
void |
|
get_option_default(option: int) const |
|
get_option_name(option: int) const |
|
get_option_values(option: int) const |
|
get_selected_options() const |
|
get_vbox() |
|
void |
|
void |
set_option_default(option: int, index: int) |
void |
set_option_name(option: int, name: String) |
void |
set_option_values(option: int, values: PackedStringArray) |
Theme Properties¶
|
||
|
||
|
||
Signals¶
dir_selected(dir: String)
Emitted when the user selects a directory.
file_selected(path: String)
Emitted when the user selects a file by double-clicking it or pressing the OK button.
files_selected(paths: PackedStringArray)
Emitted when the user selects multiple files.
Enumerations¶
enum FileMode:
FileMode FILE_MODE_OPEN_FILE = 0
The dialog allows selecting one, and only one file.
FileMode FILE_MODE_OPEN_FILES = 1
The dialog allows selecting multiple files.
FileMode FILE_MODE_OPEN_DIR = 2
The dialog only allows selecting a directory, disallowing the selection of any file.
FileMode FILE_MODE_OPEN_ANY = 3
The dialog allows selecting one file or directory.
FileMode FILE_MODE_SAVE_FILE = 4
The dialog will warn when a file exists.
enum Access:
Access ACCESS_RESOURCES = 0
The dialog only allows accessing files under the Resource path (res://
).
Access ACCESS_USERDATA = 1
The dialog only allows accessing files under user data path (user://
).
Access ACCESS_FILESYSTEM = 2
The dialog allows accessing files on the whole file system.
Property Descriptions¶
Access access = 0
The file system access scope. See Access constants.
Warning: Currently, in sandboxed environments such as Web builds or sandboxed macOS apps, FileDialog cannot access the host file system. See godot-proposals#1123.
String current_dir
The current working directory of the file dialog.
String current_file
The currently selected file of the file dialog.
String current_path
The currently selected file path of the file dialog.
FileMode file_mode = 4
The dialog's open or save mode, which affects the selection behavior. See FileMode.
PackedStringArray filters = PackedStringArray()
void set_filters(value: PackedStringArray)
PackedStringArray get_filters()
The available file type filters. Each filter string in the array should be formatted like this: *.txt,*.doc;Text Files
. The description text of the filter is optional and can be omitted.
bool mode_overrides_title = true
If true
, changing the file_mode property will set the window title accordingly (e.g. setting file_mode to FILE_MODE_OPEN_FILE will change the window title to "Open a File").
int option_count = 0
The number of additional OptionButtons and CheckBoxes in the dialog.
String 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.
If true
, the dialog will show hidden files.
bool use_native_dialog = false
If true
, access is set to ACCESS_FILESYSTEM, and it is supported by the current DisplayServer, OS native dialog will be used instead of custom one.
Note: On macOS, sandboxed apps always use native dialogs to access host filesystem.
Method Descriptions¶
void add_filter(filter: String, description: 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_option(name: String, values: PackedStringArray, index: int)
Adds an additional OptionButton to the file dialog. If values
is empty, a CheckBox is added instead.
void clear_filters()
Clear all the added filters in the dialog.
void deselect_all()
Clear all currently selected items in the dialog.
LineEdit 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 CanvasItem.visible property.
int get_option_default(option: int) const
Returns the default value index of the OptionButton or CheckBox with index option
.
String get_option_name(option: int) const
Returns the name of the OptionButton or CheckBox with index option
.
PackedStringArray get_option_values(option: int) const
Returns an array of values of the OptionButton with index option
.
Dictionary get_selected_options() 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.
VBoxContainer 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 CanvasItem.visible property.
void invalidate()
Invalidate and update the current dialog content list.
void set_option_default(option: int, index: int)
Sets the default value index of the OptionButton or CheckBox with index option
.
void set_option_name(option: int, name: String)
Sets the name of the OptionButton or CheckBox with index option
.
void set_option_values(option: int, values: PackedStringArray)
Sets the option values of the OptionButton with index option
.
Theme Property Descriptions¶
Color file_disabled_color = Color(1, 1, 1, 0.25)
The color tint for disabled files (when the FileDialog is used in open folder mode).
Color file_icon_color = Color(1, 1, 1, 1)
The color modulation applied to the file icon.
Color folder_icon_color = Color(1, 1, 1, 1)
The color modulation applied to the folder icon.
Texture2D back_folder
Custom icon for the back arrow.
Texture2D create_folder
Custom icon for the create folder button.
Texture2D file
Custom icon for files.
Texture2D folder
Custom icon for folders.
Texture2D forward_folder
Custom icon for the forward arrow.
Texture2D parent_folder
Custom icon for the parent folder arrow.
Texture2D reload
Custom icon for the reload button.
Custom icon for the toggle hidden button.