FileDialog
Inherits: ConfirmationDialog < AcceptDialog < Window < Viewport < Actor < Object
Inherited by: EditorFileDialog
A dialog for selecting files or directories in the filesystem.
Description
Section titled “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.
Note: FileDialog is invisible by default. To make it visible, call one of the popup_* methods from Window on the actor, such as Window.popup_centered_clamped().
Properties
Section titled “Properties”Methods
Section titled “Methods”| Returns | Method |
|---|---|
| void | add_filter(filter, description, mime_type) |
| void | add_option(name, values, default_value_index) |
| void | clear_filename_filter() |
| void | clear_filters() |
| void | deselect_all() |
[]String | get_favorite_list() |
| LineEdit | get_line_edit() |
| int | get_option_default(option) |
| String | get_option_name(option) |
[]String | get_option_values(option) |
[]String | get_recent_list() |
| Dictionary | get_selected_options() |
| VBoxContainer | get_vbox() |
| void | invalidate() |
| bool | is_customization_flag_enabled(flag) |
| void | popup_file_dialog() |
| void | set_customization_flag_enabled(flag, enabled) |
| void | set_favorite_list(favorites) |
| void | set_get_icon_callback(callback) |
| void | set_get_thumbnail_callback(callback) |
| void | set_option_default(option, default_value_index) |
| void | set_option_name(option, name) |
| void | set_option_values(option, values) |
| void | set_recent_list(recents) |
Signals
Section titled “Signals”dir_selected
Section titled “dir_selected”dir_selected(dir: String)Emitted when the user selects a directory.
file_selected
Section titled “file_selected”file_selected(path: String)Emitted when the user selects a file by double-clicking it or pressing the OK button.
filename_filter_changed
Section titled “filename_filter_changed”filename_filter_changed(filter: String)Emitted when the filter for file names changes.
files_selected
Section titled “files_selected”files_selected(paths: PackedStringArray)Emitted when the user selects multiple files.
Enumerations and constants
Section titled “Enumerations and constants”enum FileMode
Section titled “enum FileMode”- FILE_MODE_OPEN_FILE =
0— The dialog allows selecting one, and only one file.
- FILE_MODE_OPEN_FILES =
1— The dialog allows selecting multiple files.
- FILE_MODE_OPEN_DIR =
2— The dialog only allows selecting a directory, disallowing the selection of any file.
- FILE_MODE_OPEN_ANY =
3— The dialog allows selecting one file or directory.
- FILE_MODE_SAVE_FILE =
4— The dialog will warn when a file exists.
enum Access
Section titled “enum Access”- ACCESS_RESOURCES =
0— The dialog only allows accessing files under the Resource path (res://).
- ACCESS_USERDATA =
1— The dialog only allows accessing files under user data path (user://).
- ACCESS_FILESYSTEM =
2— The dialog allows accessing files on the whole file system.
enum DisplayMode
Section titled “enum DisplayMode”- DISPLAY_THUMBNAILS =
0— The dialog displays files as a grid of thumbnails. Usethumbnail_sizeto adjust their size.
- DISPLAY_LIST =
1— The dialog displays files as a list of filenames.
enum Customization
Section titled “enum Customization”
- CUSTOMIZATION_HIDDEN_FILES =
0— Toggles visibility of the favorite button, and the favorite list on the left side of the dialog. Equivalent tohidden_files_toggle_enabled.
- CUSTOMIZATION_CREATE_FOLDER =
1— If enabled, shows the button for creating new directories (when usingFILE_MODE_OPEN_DIR,FILE_MODE_OPEN_ANY, orFILE_MODE_SAVE_FILE). Equivalent tofolder_creation_enabled.
- CUSTOMIZATION_FILE_FILTER =
2— If enabled, shows the toggle file filter button. Equivalent tofile_filter_toggle_enabled.
- CUSTOMIZATION_FILE_SORT =
3— If enabled, shows the file sorting options button. Equivalent tofile_sort_options_enabled.
- CUSTOMIZATION_FAVORITES =
4— If enabled, shows the toggle favorite button and favorite list on the left side of the dialog. Equivalent tofavorites_enabled.
- CUSTOMIZATION_RECENT =
5— If enabled, shows the recent directories list on the left side of the dialog. Equivalent torecent_list_enabled.
- CUSTOMIZATION_LAYOUT =
6— If enabled, shows the layout switch buttons (list/thumbnails). Equivalent tolayout_toggle_enabled.
- CUSTOMIZATION_OVERWRITE_WARNING =
7— If enabled, the FileDialog will warn the user before overwriting files in save mode. Equivalent tooverwrite_warning_enabled.
- CUSTOMIZATION_DELETE =
8— If enabled, the context menu will show the “Delete” option, which allows moving files and folders to trash. Equivalent todeleting_enabled.
Property descriptions
Section titled “Property descriptions”access
Section titled “access”FileDialog.Access access = 0
Setter/getter: set_access(), get_access()
The file system access scope.
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.
current_dir
Section titled “current_dir”String current_dir
Setter/getter: set_current_dir(), get_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.
current_file
Section titled “current_file”String current_file
Setter/getter: set_current_file(), get_current_file()
The currently selected file of the file dialog.
current_path
Section titled “current_path”String current_path
Setter/getter: set_current_path(), get_current_path()
The currently selected file path of the file dialog.
deleting_enabled
Section titled “deleting_enabled”bool deleting_enabled = true
Setter/getter: set_customization_flag_enabled(), is_customization_flag_enabled()
If true, the context menu will show the “Delete” option, which allows moving files and folders to trash.
dialog_hide_on_ok
Section titled “dialog_hide_on_ok”bool dialog_hide_on_ok = false
Setter/getter: set_hide_on_ok(), get_hide_on_ok()
No description yet.
display_mode
Section titled “display_mode”FileDialog.DisplayMode display_mode = 0
Setter/getter: set_display_mode(), get_display_mode()
Display mode of the dialog’s file list.
favorites_enabled
Section titled “favorites_enabled”bool favorites_enabled = true
Setter/getter: set_customization_flag_enabled(), is_customization_flag_enabled()
If true, shows the toggle favorite button and favorite list on the left side of the dialog.
file_filter_toggle_enabled
Section titled “file_filter_toggle_enabled”bool file_filter_toggle_enabled = true
Setter/getter: set_customization_flag_enabled(), is_customization_flag_enabled()
If true, shows the toggle file filter button.
file_mode
Section titled “file_mode”FileDialog.FileMode file_mode = 4
Setter/getter: set_file_mode(), get_file_mode()
The dialog’s open or save mode, which affects the selection behavior.
file_sort_options_enabled
Section titled “file_sort_options_enabled”bool file_sort_options_enabled = true
Setter/getter: set_customization_flag_enabled(), is_customization_flag_enabled()
If true, shows the file sorting options button.
filename_filter
Section titled “filename_filter”String filename_filter = ""
Setter/getter: set_filename_filter(), get_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.
filters
Section titled “filters”[]String filters = PackedStringArray()
Setter/getter: set_filters(), get_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 dialogs and Windows file dialogs support only file extensions, while Android, Linux, and macOS file dialogs also support MIME types.
folder_creation_enabled
Section titled “folder_creation_enabled”bool folder_creation_enabled = true
Setter/getter: set_customization_flag_enabled(), is_customization_flag_enabled()
If true, shows the button for creating new directories (when using FILE_MODE_OPEN_DIR, FILE_MODE_OPEN_ANY, or FILE_MODE_SAVE_FILE), and the context menu will have the “New Folder…” option.
hidden_files_toggle_enabled
Section titled “hidden_files_toggle_enabled”bool hidden_files_toggle_enabled = true
Setter/getter: set_customization_flag_enabled(), is_customization_flag_enabled()
If true, shows the toggle hidden files button.
layout_toggle_enabled
Section titled “layout_toggle_enabled”bool layout_toggle_enabled = true
Setter/getter: set_customization_flag_enabled(), is_customization_flag_enabled()
If true, shows the layout switch buttons (list/thumbnails).
mode_overrides_title
Section titled “mode_overrides_title”bool mode_overrides_title = true
Setter/getter: set_mode_overrides_title(), is_mode_overriding_title()
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”).
option_count
Section titled “option_count”int option_count = 0
Setter/getter: set_option_count(), get_option_count()
The number of additional OptionButtons and CheckBoxes in the dialog.
option_{index}/default
Section titled “option_{index}/default”int option_{index}/default = 0
The default value for the option at index.
Note: index is a value in the 0 .. option_count - 1 range.
option_{index}/name
Section titled “option_{index}/name”String option_{index}/name = ""
The name of the option at index.
Note: index is a value in the 0 .. option_count - 1 range.
option_{index}/values
Section titled “option_{index}/values”[]String option_{index}/values = PackedStringArray()
The list of values for the option at index.
Note: index is a value in the 0 .. option_count - 1 range.
overwrite_warning_enabled
Section titled “overwrite_warning_enabled”bool overwrite_warning_enabled = true
Setter/getter: set_customization_flag_enabled(), is_customization_flag_enabled()
If true, the FileDialog will warn the user before overwriting files in save mode.
recent_list_enabled
Section titled “recent_list_enabled”bool recent_list_enabled = true
Setter/getter: set_customization_flag_enabled(), is_customization_flag_enabled()
If true, shows the recent directories list on the left side of the dialog.
root_subfolder
Section titled “root_subfolder”String root_subfolder = ""
Setter/getter: set_root_subfolder(), get_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.
show_hidden_files
Section titled “show_hidden_files”bool show_hidden_files = false
Setter/getter: set_show_hidden_files(), is_showing_hidden_files()
If true, the dialog will show hidden files.
Note: This property is ignored by native file dialogs on Android and Linux.
Vector2i size = Vector2i(640, 360)
Setter/getter: set_size(), get_size()
No description yet.
String title = "Save a File"
Setter/getter: set_title(), get_title()
No description yet.
use_native_dialog
Section titled “use_native_dialog”bool use_native_dialog = false
Setter/getter: set_use_native_dialog(), get_use_native_dialog()
If true, and if supported by the current Display, OS native dialog will be used instead of custom one.
Note: On Android, it is only supported when using ACCESS_FILESYSTEM. For access mode ACCESS_RESOURCES and 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 OS.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.
Note: This property is ignored in EditorFileDialog.
Method descriptions
Section titled “Method descriptions”add_filter
Section titled “add_filter”void add_filter(filter: String, description: String = "", mime_type: String = "")
Adds a comma-separated file extension filter and comma-separated MIME type mime_type 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", a mime_type of image/png, image/jpeg, and a description of "Images" results in filter text “Images (*.png, *.jpg)”.
Note: Embedded file dialogs and Windows file dialogs support only file extensions, while Android, Linux, and macOS file dialogs also support MIME types.
add_option
Section titled “add_option”void add_option(name: String, values: []String, default_value_index: 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).
clear_filename_filter
Section titled “clear_filename_filter”void clear_filename_filter()
Clear the filter for file names.
clear_filters
Section titled “clear_filters”void clear_filters()
Clear all the added filters in the dialog.
deselect_all
Section titled “deselect_all”void deselect_all()
Clear all currently selected items in the dialog.
get_favorite_list
Section titled “get_favorite_list”[]String get_favorite_list() static
Returns the list of favorite directories, which is shared by all FileDialog actors. Useful to store the list of favorites between project sessions. This method can be called only from the main thread.
get_line_edit
Section titled “get_line_edit”LineEdit get_line_edit()
Returns the LineEdit for the selected file.
Warning: This is a required internal actor, removing and freeing it may cause a crash. If you wish to hide it or any of its children, use their CanvasItem.visible property.
get_option_default
Section titled “get_option_default”int get_option_default(option: int) const
Returns the default value index of the OptionButton or CheckBox with index option.
get_option_name
Section titled “get_option_name”String get_option_name(option: int) const
Returns the name of the OptionButton or CheckBox with index option.
get_option_values
Section titled “get_option_values”[]String get_option_values(option: int) const
Returns an array of values of the OptionButton with index option.
get_recent_list
Section titled “get_recent_list”[]String get_recent_list() static
Returns the list of recent directories, which is shared by all FileDialog actors. Useful to store the list of recents between project sessions. This method can be called only from the main thread.
get_selected_options
Section titled “get_selected_options”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.
get_vbox
Section titled “get_vbox”VBoxContainer get_vbox()
Returns the vertical box container of the dialog, custom controls can be added to it.
Warning: This is a required internal actor, removing and freeing it may cause a crash. If you wish to hide it or any of its children, use their CanvasItem.visible property.
Note: Changes to this actor are ignored by native file dialogs, use add_option() to add custom elements to the dialog instead.
invalidate
Section titled “invalidate”void invalidate()
Invalidates and updates this dialog’s content list.
Note: This method does nothing on native file dialogs.
is_customization_flag_enabled
Section titled “is_customization_flag_enabled”bool is_customization_flag_enabled(flag: FileDialog.Customization) const
Returns true if the provided flag is enabled.
popup_file_dialog
Section titled “popup_file_dialog”void popup_file_dialog()
Shows the FileDialog using the default size and position for file dialogs, and selects the file name if there is a current file.
set_customization_flag_enabled
Section titled “set_customization_flag_enabled”void set_customization_flag_enabled(flag: FileDialog.Customization, enabled: bool)
Sets the specified customization flag, allowing to customize the features available in this FileDialog.
set_favorite_list
Section titled “set_favorite_list”void set_favorite_list(favorites: []String) static
Sets the list of favorite directories, which is shared by all FileDialog actors. Useful to restore the list of favorites saved with get_favorite_list(). This method can be called only from the main thread.
Note: FileDialog will update its internal ItemList of favorites when its visibility changes. Be sure to call this method earlier if you want your changes to have effect.
set_get_icon_callback
Section titled “set_get_icon_callback”void set_get_icon_callback(callback: Callable) static
Sets the callback used by the FileDialog actors to get a file icon, when DISPLAY_LIST mode is used. The callback should take a single String argument (file path), and return a Texture2D. If an invalid texture is returned, the file icon will be used instead.
set_get_thumbnail_callback
Section titled “set_get_thumbnail_callback”void set_get_thumbnail_callback(callback: Callable) static
Sets the callback used by the FileDialog actors to get a file icon, when DISPLAY_THUMBNAILS mode is used. The callback should take a single String argument (file path), and return a Texture2D. If an invalid texture is returned, the file_thumbnail icon will be used instead.
Thumbnails are usually more complex and may take a while to load. To avoid stalling the application, you can use ImageTexture to asynchronously create the thumbnail.
fn _ready() void { FileDialog.set_get_thumbnail_callback(thumbnail_method)}
fn thumbnail_method(path: String) Texture2D { image_texture : ImageTexture = ImageTexture.new() spawn make_thumbnail_async(path, image_texture) return image_texture}
async fn make_thumbnail_async(path: String, image_texture: ImageTexture) void { thumbnail_texture : Texture2D = await generate_thumbnail(path) # Some method that generates a thumbnail. image_texture.set_image(thumbnail_texture.get_image())}
async fn generate_thumbnail(path: String) Texture2D { await next_frame() return ImageTexture.create_from_image(Image.load_from_file(path))}set_option_default
Section titled “set_option_default”void set_option_default(option: int, default_value_index: int)
Sets the default value index of the OptionButton or CheckBox with index option.
set_option_name
Section titled “set_option_name”void set_option_name(option: int, name: String)
Sets the name of the OptionButton or CheckBox with index option.
set_option_values
Section titled “set_option_values”void set_option_values(option: int, values: []String)
Sets the option values of the OptionButton with index option.
set_recent_list
Section titled “set_recent_list”void set_recent_list(recents: []String) static
Sets the list of recent directories, which is shared by all FileDialog actors. Useful to restore the list of recents saved with set_recent_list(). This method can be called only from the main thread.
Note: FileDialog will update its internal ItemList of recent directories when its visibility changes. Be sure to call this method earlier if you want your changes to have effect.