Index · Object → Node → Viewport → Window → AcceptDialog → ConfirmationDialog → FileDialog

FileDialog

A dialog for selecting files or directories in the filesystem.

Inherited by (1): EditorFileDialog
Class 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 node, such as Window.popup_centered_clamped().

Properties

var access: FileDialog.Access = 0

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.

var current_dir: String

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_file: String

The currently selected file of the file dialog.

var current_path: String

The currently selected file path of the file dialog.

var deleting_enabled: bool = true

If true, the context menu will show the "Delete" option, which allows moving files and folders to trash.

var dialog_hide_on_ok: bool = false
var display_mode: FileDialog.DisplayMode = 0

Display mode of the dialog's file list.

var favorites_enabled: bool = true

If true, shows the toggle favorite button and favorite list on the left side of the dialog.

var file_filter_toggle_enabled: bool = true

If true, shows the toggle file filter button.

var file_mode: FileDialog.FileMode = 4

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

var file_sort_options_enabled: bool = true

If true, shows the file sorting options button.

var filename_filter: String = ""

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 filters: PackedStringArray = PackedStringArray()

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.

var folder_creation_enabled: bool = true

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.

var hidden_files_toggle_enabled: bool = true

If true, shows the toggle hidden files button.

var layout_toggle_enabled: bool = true

If true, shows the layout switch buttons (list/thumbnails).

var mode_overrides_title: bool = 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").

var option_count: int = 0

The number of additional OptionButtons and CheckBoxes in the dialog.

var option_{index}/default: int = 0

The default value for the option at index.

Note: index is a value in the 0 .. option_count - 1 range.

var option_{index}/name: String = ""

The name of the option at index.

Note: index is a value in the 0 .. option_count - 1 range.

var option_{index}/values: PackedStringArray = PackedStringArray()

The list of values for the option at index.

Note: index is a value in the 0 .. option_count - 1 range.

var overwrite_warning_enabled: bool = true

If true, the FileDialog will warn the user before overwriting files in save mode.

var recent_list_enabled: bool = true

If true, shows the recent directories list on the left side of the dialog.

var root_subfolder: String = ""

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 show_hidden_files: bool = false

If true, the dialog will show hidden files.

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

var size: Vector2i = Vector2i(640, 360)
var title: String = "Save a File"
var use_native_dialog: bool = false

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 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.

Inherited from ConfirmationDialog (4)
var cancel_button_text: String = "Cancel"
var min_size: Vector2i = Vector2i(200, 70)
var size: Vector2i = Vector2i(200, 100)
var title: String = "Please Confirm..."
Inherited from AcceptDialog (13)
var dialog_autowrap: bool = false
var exclusive: bool = true
var title: String = "Alert!"
var transient: bool = true
var visible: bool = false
var wrap_controls: bool = true
Inherited from Window (41)
var always_on_top: bool = false
var borderless: bool = false
var content_scale_size: Vector2i = Vector2i(0, 0)
var exclusive: bool = false
var extend_to_title: bool = false
var force_native: bool = false
var max_size: Vector2i = Vector2i(0, 0)
var maximize_disabled: bool = false
var min_size: Vector2i = Vector2i(0, 0)
var minimize_disabled: bool = false
var mode: Window.Mode = 0
var mouse_passthrough: bool = false
var mouse_passthrough_polygon: PackedVector2Array = PackedVector2Array()
var nonclient_area: Rect2i = Rect2i(0, 0, 0, 0)
var popup_window: bool = false
var popup_wm_hint: bool = false
var position: Vector2i = Vector2i(0, 0)
var sharp_corners: bool = false
var size: Vector2i = Vector2i(100, 100)
var title: String = ""
var transient: bool = false
var transparent: bool = false
var unfocusable: bool = false
var unresizable: bool = false
var visible: bool = true
var wrap_controls: bool = false
Inherited from Viewport (51)
var canvas_cull_mask: int = 4294967295
var disable_3d: bool = false
var fsr_sharpness: float = 0.2
var gui_disable_input: bool = false
var oversampling: bool = true
var own_world_3d: bool = false
var transparent_bg: bool = false
var use_debanding: bool = false
var use_hdr_2d: bool = false
var use_taa: bool = false
var use_xr: bool = false
Inherited from Node (14)
var owner: Node

Methods

func add_filter(filter: String, description: String = "", mime_type: String = "") -> void

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.

func add_option(name: String, values: PackedStringArray, default_value_index: int) -> void

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).

func clear_filename_filter() -> void

Clear the filter for file names.

func clear_filters() -> void

Clear all the added filters in the dialog.

func deselect_all() -> void

Clear all currently selected items in the dialog.

func get_favorite_list() -> PackedStringArray

Returns the list of favorite directories, which is shared by all FileDialog nodes. Useful to store the list of favorites between project sessions. This method can be called only from the main thread.

func get_line_edit() -> LineEdit

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.

func get_option_default(option: int) -> int

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

func get_option_name(option: int) -> String

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

func get_option_values(option: int) -> PackedStringArray

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

func get_recent_list() -> PackedStringArray

Returns the list of recent directories, which is shared by all FileDialog nodes. Useful to store the list of recents between project sessions. This method can be called only from the main thread.

func get_selected_options() -> Dictionary

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

func get_vbox() -> VBoxContainer

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.

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

func invalidate() -> void

Invalidates and updates this dialog's content list.

Note: This method does nothing on native file dialogs.

func is_customization_flag_enabled(flag: FileDialog.Customization) -> bool

Returns true if the provided flag is enabled.

func popup_file_dialog() -> void

Shows the FileDialog using the default size and position for file dialogs, and selects the file name if there is a current file.

func set_customization_flag_enabled(flag: FileDialog.Customization, enabled: bool) -> void

Sets the specified customization flag, allowing to customize the features available in this FileDialog.

func set_favorite_list(favorites: PackedStringArray) -> void

Sets the list of favorite directories, which is shared by all FileDialog nodes. 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.

func set_get_icon_callback(callback: Callable) -> void

Sets the callback used by the FileDialog nodes 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.

func set_get_thumbnail_callback(callback: Callable) -> void

Sets the callback used by the FileDialog nodes 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.

func _ready():
	FileDialog.set_get_thumbnail_callback(thumbnail_method)

func thumbnail_method(path):
	var image_texture = ImageTexture.new()
	make_thumbnail_async(path, image_texture)
	return image_texture

func make_thumbnail_async(path, image_texture):
	var thumbnail_texture = await generate_thumbnail(path) # Some method that generates a thumbnail.
	image_texture.set_image(thumbnail_texture.get_image())
func set_option_default(option: int, default_value_index: int) -> void

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

func set_option_name(option: int, name: String) -> void

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

func set_option_values(option: int, values: PackedStringArray) -> void

Sets the option values of the OptionButton with index option.

func set_recent_list(recents: PackedStringArray) -> void

Sets the list of recent directories, which is shared by all FileDialog nodes. 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.

Inherited from ConfirmationDialog (1)
Inherited from AcceptDialog (6)
func add_button(text: String, right: bool = false, action: String = "") -> Button
func get_label() -> Label
func register_text_enter(line_edit: LineEdit) -> void
func remove_button(button: Button) -> void
Inherited from Window (78)
func add_theme_color_override(name: StringName, color: Color) -> void
func add_theme_constant_override(name: StringName, constant: int) -> void
func add_theme_font_override(name: StringName, font: Font) -> void
func add_theme_font_size_override(name: StringName, font_size: int) -> void
func add_theme_icon_override(name: StringName, texture: Texture2D) -> void
func add_theme_stylebox_override(name: StringName, stylebox: StyleBox) -> void
func can_draw() -> bool
func child_controls_changed() -> void
func get_flag(flag: Window.Flags) -> bool
func get_theme_color(name: StringName, theme_type: StringName = &"") -> Color
func get_theme_constant(name: StringName, theme_type: StringName = &"") -> int
func get_theme_font(name: StringName, theme_type: StringName = &"") -> Font
func get_theme_font_size(name: StringName, theme_type: StringName = &"") -> int
func get_theme_icon(name: StringName, theme_type: StringName = &"") -> Texture2D
func get_theme_stylebox(name: StringName, theme_type: StringName = &"") -> StyleBox
func get_window_id() -> int
func grab_focus() -> void
func has_focus() -> bool
func has_theme_color(name: StringName, theme_type: StringName = &"") -> bool
func has_theme_constant(name: StringName, theme_type: StringName = &"") -> bool
func has_theme_font(name: StringName, theme_type: StringName = &"") -> bool
func has_theme_font_size(name: StringName, theme_type: StringName = &"") -> bool
func has_theme_icon(name: StringName, theme_type: StringName = &"") -> bool
func has_theme_stylebox(name: StringName, theme_type: StringName = &"") -> bool
func hide() -> void
func is_embedded() -> bool
func move_to_center() -> void
func move_to_foreground() -> void
func popup(rect: Rect2i = Rect2i(0, 0, 0, 0)) -> void
func popup_centered(minsize: Vector2i = Vector2i(0, 0)) -> void
func popup_centered_clamped(minsize: Vector2i = Vector2i(0, 0), fallback_ratio: float = 0.75) -> void
func popup_centered_ratio(ratio: float = 0.8) -> void
func popup_exclusive(from_node: Node, rect: Rect2i = Rect2i(0, 0, 0, 0)) -> void
func popup_exclusive_centered(from_node: Node, minsize: Vector2i = Vector2i(0, 0)) -> void
func popup_exclusive_centered_clamped(from_node: Node, minsize: Vector2i = Vector2i(0, 0), fallback_ratio: float = 0.75) -> void
func popup_exclusive_centered_ratio(from_node: Node, ratio: float = 0.8) -> void
func popup_exclusive_on_parent(from_node: Node, parent_rect: Rect2i) -> void
func popup_on_parent(parent_rect: Rect2i) -> void
func request_attention() -> void
func reset_size() -> void
func set_flag(flag: Window.Flags, enabled: bool) -> void
func set_ime_active(active: bool) -> void
func set_ime_position(position: Vector2i) -> void
func set_taskbar_progress_value(value: float) -> void
func set_unparent_when_invisible(unparent: bool) -> void
func set_use_font_oversampling(enable: bool) -> void
func show() -> void
func start_drag() -> void
Inherited from Viewport (38)
func get_embedded_subwindows() -> Window[]
func gui_cancel_drag() -> void
func gui_release_focus() -> void
func gui_set_drag_description(description: String) -> void
func notify_mouse_entered() -> void
func notify_mouse_exited() -> void
func push_input(event: InputEvent, in_local_coords: bool = false) -> void
func push_text_input(text: String) -> void
func push_unhandled_input(event: InputEvent, in_local_coords: bool = false) -> void
func set_canvas_cull_mask_bit(layer: int, enable: bool) -> void
func set_input_as_handled() -> void
func warp_mouse(position: Vector2) -> void
Inherited from Node (106)
func _enter_tree() -> void
func _exit_tree() -> void
func _input(event: InputEvent) -> void
func _physics_process(delta: float) -> void
func _process(delta: float) -> void
func _ready() -> void
func _shortcut_input(event: InputEvent) -> void
func _unhandled_input(event: InputEvent) -> void
func _unhandled_key_input(event: InputEvent) -> void
func add_child(node: Node, force_readable_name: bool = false, internal: Node.InternalMode = 0) -> void
func add_sibling(sibling: Node, force_readable_name: bool = false) -> void
func add_to_group(group: StringName, persistent: bool = false) -> void
func atr(message: String, context: StringName = "") -> String
func atr_n(message: String, plural_message: StringName, n: int, context: StringName = "") -> String
func can_process() -> bool
func duplicate(flags: int = 15) -> Node
func find_child(pattern: String, recursive: bool = true, owned: bool = true) -> Node
func find_children(pattern: String, type: String = "", recursive: bool = true, owned: bool = true) -> Node[]
func find_parent(pattern: String) -> Node
func get_child(idx: int, include_internal: bool = false) -> Node
func get_child_count(include_internal: bool = false) -> int
func get_children(include_internal: bool = false) -> Node[]
func get_groups() -> StringName[]
func get_index(include_internal: bool = false) -> int
func get_node(path: NodePath) -> Node
func get_orphan_node_ids() -> int[]
func get_parent() -> Node
func get_path() -> NodePath
func get_path_to(node: Node, use_unique_path: bool = false) -> NodePath
func get_window() -> Window
func has_node(path: NodePath) -> bool
func is_ancestor_of(node: Node) -> bool
func is_greater_than(node: Node) -> bool
func is_in_group(group: StringName) -> bool
func move_child(child_node: Node, to_index: int) -> void
func notify_deferred_thread_group(what: int) -> void
func notify_thread_safe(what: int) -> void
func print_orphan_nodes() -> void
func print_tree() -> void
func print_tree_pretty() -> void
func propagate_call(method: StringName, args: Array = [], parent_first: bool = false) -> void
func propagate_notification(what: int) -> void
func queue_free() -> void
func remove_child(node: Node) -> void
func remove_from_group(group: StringName) -> void
func reparent(new_parent: Node, keep_global_transform: bool = true) -> void
func replace_by(node: Node, keep_groups: bool = false) -> void
func request_ready() -> void
func rpc(method: StringName) -> Error
func rpc_config(method: StringName, config: Variant) -> void
func rpc_id(peer_id: int, method: StringName) -> Error
func set_deferred_thread_group(property: StringName, value: Variant) -> void
func set_display_folded(fold: bool) -> void
func set_editable_instance(node: Node, is_editable: bool) -> void
func set_multiplayer_authority(id: int, recursive: bool = true) -> void
func set_physics_process(enable: bool) -> void
func set_physics_process_internal(enable: bool) -> void
func set_process(enable: bool) -> void
func set_process_input(enable: bool) -> void
func set_process_internal(enable: bool) -> void
func set_process_shortcut_input(enable: bool) -> void
func set_process_unhandled_input(enable: bool) -> void
func set_scene_instance_load_placeholder(load_placeholder: bool) -> void
func set_thread_safe(property: StringName, value: Variant) -> void
Inherited from Object (62)
func _get(property: StringName) -> Variant
func _get_property_list() -> Dictionary[]
func _init() -> void
func _iter_get(iter: Variant) -> Variant
func _iter_init(iter: Array) -> bool
func _iter_next(iter: Array) -> bool
func _notification(what: int) -> void
func _set(property: StringName, value: Variant) -> bool
func _to_string() -> String
func _validate_property(property: Dictionary) -> void
func add_user_signal(signal: String, arguments: Array = []) -> void
func call(method: StringName) -> Variant
func callv(method: StringName, arg_array: Array) -> Variant
func cancel_free() -> void
func connect(signal: StringName, callable: Callable, flags: int = 0) -> Error
func disconnect(signal: StringName, callable: Callable) -> void
func emit_signal(signal: StringName) -> Error
func free() -> void
func get(property: StringName) -> Variant
func get_class() -> String
func get_incoming_connections() -> Dictionary[]
func get_indexed(property_path: NodePath) -> Variant
func get_meta(name: StringName, default: Variant = null) -> Variant
func get_meta_list() -> StringName[]
func get_method_list() -> Dictionary[]
func get_property_list() -> Dictionary[]
func get_signal_connection_list(signal: StringName) -> Dictionary[]
func get_signal_list() -> Dictionary[]
func has_meta(name: StringName) -> bool
func has_method(method: StringName) -> bool
func has_signal(signal: StringName) -> bool
func is_class(class: StringName) -> bool
func is_connected(signal: StringName, callable: Callable) -> bool
func notification(what: int, reversed: bool = false) -> void
func remove_meta(name: StringName) -> void
func remove_user_signal(signal: StringName) -> void
func set(property: StringName, value: Variant) -> void
func set_block_signals(enable: bool) -> void
func set_deferred(property: StringName, value: Variant) -> void
func set_indexed(property_path: NodePath, value: Variant) -> void
func set_message_translation(enable: bool) -> void
func set_meta(name: StringName, value: Variant) -> void
func set_script(script: Variant) -> void
func set_translation_domain(domain: StringName) -> void
func to_string() -> String
func tr(message: StringName, context: StringName = &"") -> String
func tr_n(message: StringName, plural_message: StringName, n: int, context: StringName = &"") -> String

Signals

signal dir_selected(dir: String)

Emitted when the user selects a directory.

signal file_selected(path: String)

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

signal filename_filter_changed(filter: String)

Emitted when the filter for file names changes.

signal files_selected(paths: PackedStringArray)

Emitted when the user selects multiple files.

Inherited from AcceptDialog (3)
signal canceled()
signal confirmed()
signal custom_action(action: StringName)
Inherited from Window (16)
signal dpi_changed()
signal focus_entered()
signal focus_exited()
signal mouse_entered()
signal mouse_exited()
signal output_max_linear_value_changed(output_max_linear_value: float)
signal theme_changed()
signal title_changed()
signal window_input(event: InputEvent)
Inherited from Viewport (2)
signal size_changed()
Inherited from Node (11)
signal child_entered_tree(node: Node)
signal child_exiting_tree(node: Node)
signal ready()
signal renamed()
signal replacing_by(node: Node)
signal tree_entered()
signal tree_exited()
signal tree_exiting()
Inherited from Object (2)

Enums & Constants

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
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
DISPLAY_THUMBNAILS = 0

The dialog displays files as a grid of thumbnails. Use thumbnail_size to adjust their size.

DISPLAY_LIST = 1

The dialog displays files as a list of filenames.

enum Customization
CUSTOMIZATION_HIDDEN_FILES = 0

Toggles visibility of the favorite button, and the favorite list on the left side of the dialog.

Equivalent to hidden_files_toggle_enabled.

CUSTOMIZATION_CREATE_FOLDER = 1

If enabled, shows the button for creating new directories (when using FILE_MODE_OPEN_DIR, FILE_MODE_OPEN_ANY, or FILE_MODE_SAVE_FILE).

Equivalent to folder_creation_enabled.

CUSTOMIZATION_FILE_FILTER = 2

If enabled, shows the toggle file filter button.

Equivalent to file_filter_toggle_enabled.

CUSTOMIZATION_FILE_SORT = 3

If enabled, shows the file sorting options button.

Equivalent to file_sort_options_enabled.

CUSTOMIZATION_FAVORITES = 4

If enabled, shows the toggle favorite button and favorite list on the left side of the dialog.

Equivalent to favorites_enabled.

CUSTOMIZATION_RECENT = 5

If enabled, shows the recent directories list on the left side of the dialog.

Equivalent to recent_list_enabled.

CUSTOMIZATION_LAYOUT = 6

If enabled, shows the layout switch buttons (list/thumbnails).

Equivalent to layout_toggle_enabled.

CUSTOMIZATION_OVERWRITE_WARNING = 7

If enabled, the FileDialog will warn the user before overwriting files in save mode.

Equivalent to overwrite_warning_enabled.

CUSTOMIZATION_DELETE = 8

If enabled, the context menu will show the "Delete" option, which allows moving files and folders to trash.

Equivalent to deleting_enabled.