FileDialog

Hereda: ConfirmationDialog < AcceptDialog < Window < Viewport < Node < Object

Heredado por: EditorFileDialog

Un diálogo para seleccionar archivos o directorios en el sistema de archivos.

Descripción

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

Propiedades

Access

access

0

String

current_dir

String

current_file

String

current_path

bool

deleting_enabled

true

bool

dialog_hide_on_ok

false (overrides AcceptDialog)

DisplayMode

display_mode

0

bool

favorites_enabled

true

bool

file_filter_toggle_enabled

true

FileMode

file_mode

4

bool

file_sort_options_enabled

true

String

filename_filter

""

PackedStringArray

filters

PackedStringArray()

bool

folder_creation_enabled

true

bool

hidden_files_toggle_enabled

true

bool

layout_toggle_enabled

true

bool

mode_overrides_title

true

int

option_count

0

bool

overwrite_warning_enabled

true

bool

recent_list_enabled

true

String

root_subfolder

""

bool

show_hidden_files

false

Vector2i

size

Vector2i(640, 360) (overrides Window)

String

title

"Save a File" (overrides Window)

bool

use_native_dialog

false

Métodos

void

add_filter(filter: String, description: String = "", mime_type: String = "")

void

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

void

clear_filename_filter()

void

clear_filters()

void

deselect_all()

PackedStringArray

get_favorite_list() static

LineEdit

get_line_edit()

int

get_option_default(option: int) const

String

get_option_name(option: int) const

PackedStringArray

get_option_values(option: int) const

PackedStringArray

get_recent_list() static

Dictionary

get_selected_options() const

VBoxContainer

get_vbox()

void

invalidate()

bool

is_customization_flag_enabled(flag: Customization) const

void

popup_file_dialog()

void

set_customization_flag_enabled(flag: Customization, enabled: bool)

void

set_favorite_list(favorites: PackedStringArray) static

void

set_get_icon_callback(callback: Callable) static

void

set_get_thumbnail_callback(callback: Callable) static

void

set_option_default(option: int, default_value_index: int)

void

set_option_name(option: int, name: String)

void

set_option_values(option: int, values: PackedStringArray)

void

set_recent_list(recents: PackedStringArray) static

Propiedades del Tema

Color

file_disabled_color

Color(1, 1, 1, 0.25)

Color

file_icon_color

Color(1, 1, 1, 1)

Color

folder_icon_color

Color(1, 1, 1, 1)

int

thumbnail_size

64

Texture2D

back_folder

Texture2D

create_folder

Texture2D

favorite

Texture2D

favorite_down

Texture2D

favorite_up

Texture2D

file

Texture2D

file_thumbnail

Texture2D

folder

Texture2D

folder_thumbnail

Texture2D

forward_folder

Texture2D

list_mode

Texture2D

parent_folder

Texture2D

reload

Texture2D

sort

Texture2D

thumbnail_mode

Texture2D

toggle_filename_filter

Texture2D

toggle_hidden

Señales

dir_selected(dir: String) 🔗

Emitida cuando el usuario selecciona un directorio.

file_selected(path: String) 🔗

Emitida cuando el usuario selecciona un archivo haciendo doble clic en él o pulsando el botón OK.

filename_filter_changed(filter: String) 🔗

Emitida cuando el filtro de nombres de archivos cambia.

files_selected(paths: PackedStringArray) 🔗

Emitida cuando el usuario selecciona múltiples archivos.

Enumeraciones

enum FileMode: 🔗

FileMode FILE_MODE_OPEN_FILE = 0

El diálogo permite seleccionar uno, y sólo un archivo.

FileMode FILE_MODE_OPEN_FILES = 1

El diálogo permite seleccionar varios archivos.

FileMode FILE_MODE_OPEN_DIR = 2

El diálogo sólo permite seleccionar un directorio, no permitiendo la selección de ningún archivo.

FileMode FILE_MODE_OPEN_ANY = 3

El diálogo permite seleccionar un archivo o directorio.

FileMode FILE_MODE_SAVE_FILE = 4

El diálogo avisará cuando exista un archivo.

enum Access: 🔗

Access ACCESS_RESOURCES = 0

El diálogo sólo permite acceder a los archivos bajo la ruta Resource (res://).

Access ACCESS_USERDATA = 1

El diálogo sólo permite acceder a los archivos bajo la ruta de datos del usuario (user://).

Access ACCESS_FILESYSTEM = 2

El diálogo permite acceder a los archivos de todo el sistema de archivos.

enum DisplayMode: 🔗

DisplayMode DISPLAY_THUMBNAILS = 0

El diálogo muestra los archivos como una cuadrícula de miniaturas. Usa thumbnail_size para ajustar su tamaño.

DisplayMode DISPLAY_LIST = 1

El diálogo muestra los archivos como una lista de nombres de archivo.

enum Customization: 🔗

Customization CUSTOMIZATION_HIDDEN_FILES = 0

Alterna la visibilidad del botón de favoritos y la lista de favoritos en el lado izquierdo del diálogo.

Equivalente a hidden_files_toggle_enabled.

Customization CUSTOMIZATION_CREATE_FOLDER = 1

Si está habilitado, muestra el botón para crear nuevos directorios (cuando se usa FILE_MODE_OPEN_DIR, FILE_MODE_OPEN_ANY o FILE_MODE_SAVE_FILE).

Equivalente a folder_creation_enabled.

Customization CUSTOMIZATION_FILE_FILTER = 2

Si está habilitado, muestra el botón para alternar el filtro de archivos.

Equivalente a file_filter_toggle_enabled.

Customization CUSTOMIZATION_FILE_SORT = 3

Si está habilitado, muestra el botón de opciones para ordenar archivos.

Equivalente a file_sort_options_enabled.

Customization CUSTOMIZATION_FAVORITES = 4

Si está habilitado, muestra el botón de alternar favoritos y la lista de favoritos en el lado izquierdo del diálogo.

Equivalente a favorites_enabled.

Customization CUSTOMIZATION_RECENT = 5

Si está habilitado, muestra la lista de directorios recientes en el lado izquierdo del diálogo.

Equivalente a recent_list_enabled.

Customization CUSTOMIZATION_LAYOUT = 6

Si está habilitado, muestra los botones de cambio de diseño (lista/miniaturas).

Equivalente a layout_toggle_enabled.

Customization CUSTOMIZATION_OVERWRITE_WARNING = 7

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

Equivalent to overwrite_warning_enabled.

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

Descripciones de Propiedades

Access access = 0 🔗

El ámbito de acceso al sistema de archivos.

Advertencia: En compilaciones para la web, FileDialog no puede acceder al sistema de archivos del anfitrión. En entornos de sandboxed de Linux y macOS, use_native_dialog se utiliza automáticamente para permitir un acceso limitado al sistema de archivos del anfitrión.

String current_dir 🔗

  • void set_current_dir(value: String)

  • String get_current_dir()

El directorio de trabajo actual del diálogo de archivo.

Nota: Para los diálogos de archivo nativos, esta propiedad sólo se trata como una sugerencia y puede no ser respetada por implementaciones específicas del sistema operativo.

String current_file 🔗

  • void set_current_file(value: String)

  • String get_current_file()

El archivo actualmente seleccionado del diálogo de archivos.

String current_path 🔗

  • void set_current_path(value: String)

  • String get_current_path()

La ruta de archivo actualmente seleccionada del diálogo de archivo.

bool deleting_enabled = true 🔗

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

DisplayMode display_mode = 0 🔗

Modo de visualización de la lista de archivos del diálogo.

bool favorites_enabled = true 🔗

Si es true, muestra el botón para alternar favoritos y la lista de favoritos en el lado izquierdo del diálogo.

bool file_filter_toggle_enabled = true 🔗

Si es true, muestra el botón para alternar el filtro de archivos.

FileMode file_mode = 4 🔗

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

bool file_sort_options_enabled = true 🔗

Si es true, muestra el botón de opciones para ordenar archivos.

String filename_filter = "" 🔗

  • void set_filename_filter(value: String)

  • String get_filename_filter()

El filtro para nombres de archivo (no distingue entre mayúsculas y minúsculas). Cuando se establece en una string no vacía, solo se mostrarán los archivos que contengan la substring. El usuario puede editar filename_filter con el botón de filtro en la parte superior del diálogo de archivo.

Véase también filters, que debería usarse para restringir los tipos de archivo que se pueden seleccionar en lugar de filename_filter, que está destinado a ser establecido por el usuario.

PackedStringArray filters = 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.

Note: The returned array is copied and any changes to it will not update the original property value. See PackedStringArray for more details.

bool folder_creation_enabled = 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.

bool hidden_files_toggle_enabled = true 🔗

Si es true, muestra el botón para alternar la visibilidad de archivos ocultos.

bool layout_toggle_enabled = true 🔗

Si es true, muestra los botones para cambiar el diseño (lista/miniaturas).

bool mode_overrides_title = true 🔗

  • void set_mode_overrides_title(value: bool)

  • bool is_mode_overriding_title()

Si es true, cambiar la propiedad file_mode establecerá el título de la ventana en consecuencia (p. ej., establecer file_mode en FILE_MODE_OPEN_FILE cambiará el título de la ventana a "Abrir un archivo").

int option_count = 0 🔗

  • void set_option_count(value: int)

  • int get_option_count()

The number of additional OptionButtons and CheckBoxes in the dialog.

bool overwrite_warning_enabled = true 🔗

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

bool recent_list_enabled = true 🔗

Si es true, muestra la lista de directorios recientes en el lado izquierdo del diálogo.

String root_subfolder = "" 🔗

  • void set_root_subfolder(value: String)

  • String get_root_subfolder()

Si no está vacío, la subcarpeta dada será la "raíz" de este FileDialog, es decir, el usuario no podrá ir a su directorio padre.

Nota: Esta propiedad es ignorada por los diálogos de archivo nativos.

bool show_hidden_files = false 🔗

  • void set_show_hidden_files(value: bool)

  • bool is_showing_hidden_files()

Si es true, el diálogo mostrará los archivos ocultos.

Nota: Esta propiedad es ignorada por los diálogos de archivo nativos en Android y Linux.

bool use_native_dialog = false 🔗

  • void set_use_native_dialog(value: bool)

  • bool get_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 for Android 10+ devices and 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.

Descripciones de Métodos

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.

void add_option(name: String, values: PackedStringArray, 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).

void clear_filename_filter() 🔗

Limpiar el filtro de nombres de archivos.

void clear_filters() 🔗

Borra todos los filtros añadidos en el diálogo.

void deselect_all() 🔗

Borra los elementos actualmente seleccionados en el diálogo.

PackedStringArray get_favorite_list() static 🔗

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.

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.

PackedStringArray get_recent_list() static 🔗

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.

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() 🔗

Devuelve el contenedor de caja vertical del diálogo, se le pueden añadir controles personalizados.

Advertencia: Este es un nodo interno requerido, eliminarlo y liberarlo puede causar un fallo. Si deseas ocultarlo o cualquiera de sus hijos, usa su propiedad CanvasItem.visible.

Nota: Los diálogos de archivo nativos ignoran los cambios en este nodo, usa add_option() para añadir elementos personalizados al diálogo en su lugar.

void invalidate() 🔗

Invalidates and updates this dialog's content list.

Note: This method does nothing on native file dialogs.

bool is_customization_flag_enabled(flag: Customization) const 🔗

Devuelve true si la flag proporcionada está habilitada.

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.

void set_customization_flag_enabled(flag: Customization, enabled: bool) 🔗

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

void set_favorite_list(favorites: PackedStringArray) static 🔗

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.

void set_get_icon_callback(callback: Callable) static 🔗

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.

void set_get_thumbnail_callback(callback: Callable) static 🔗

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

void set_option_default(option: int, default_value_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.

void set_recent_list(recents: PackedStringArray) static 🔗

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.

Descripciones de las propiedades del tema

Color file_disabled_color = Color(1, 1, 1, 0.25) 🔗

El tinte de color para los archivos desactivados (cuando se utiliza FileDialog en el modo de carpeta abierta).

Color file_icon_color = Color(1, 1, 1, 1) 🔗

La modulación del color aplicada al icono del archivo.

Color folder_icon_color = Color(1, 1, 1, 1) 🔗

La modulación del color aplicada al icono de la carpeta.

int thumbnail_size = 64 🔗

El tamaño de los iconos de miniatura cuando DISPLAY_THUMBNAILS está habilitado.

Texture2D back_folder 🔗

Icono personalizado para la flecha de retroceso.

Texture2D create_folder 🔗

Icono personalizado para el botón de crear carpeta.

Texture2D favorite 🔗

Icono personalizado para el botón de carpeta favorita.

Texture2D favorite_down 🔗

Icono personalizado para el botón de mover hacia abajo una entrada favorita.

Texture2D favorite_up 🔗

Icono personalizado para el botón de mover hacia arriba una entrada favorita.

Texture2D file 🔗

Icono personalizado para los archivos.

Texture2D file_thumbnail 🔗

Icono para los archivos cuando está en modo de miniaturas.

Texture2D folder 🔗

Icono personalizado para las carpetas.

Texture2D folder_thumbnail 🔗

Icono para carpetas en modo miniatura.

Texture2D forward_folder 🔗

Icono personalizado para la flecha de avance.

Texture2D list_mode 🔗

Icono para el botón que habilita el modo de lista.

Texture2D parent_folder 🔗

Icono personalizado para la flecha de la carpeta principal.

Texture2D reload 🔗

Icono personalizado para el botón de recarga.

Texture2D sort 🔗

Icono personalizado para el menú de opciones de ordenación.

Texture2D thumbnail_mode 🔗

Icono para el botón que habilita el modo de miniaturas.

Texture2D toggle_filename_filter 🔗

Icono personalizado para el botón de conmutación del filtro de nombres de archivo.

Texture2D toggle_hidden 🔗

Icono personalizado para el botón oculto de commutación.