FileDialog

Наследует: ConfirmationDialog < AcceptDialog < Window < Viewport < Node < Object

Наследуется от: EditorFileDialog

Диалоговое окно для выбора файлов или каталогов в файловой системе.

Описание

FileDialog — это предустановленный диалог, используемый для выбора файлов и каталогов в файловой системе. Он поддерживает маски фильтров. FileDialog автоматически устанавливает заголовок окна в соответствии с file_mode. Если вы хотите использовать пользовательский заголовок, отключите эту функцию, установив mode_overrides_title в false.

Примечание: FileDialog по умолчанию невидим. Чтобы сделать его видимым, вызовите один из методов popup_* из Window узла, например, Window.popup_centered_clamped().

Свойства

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`

Методы

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

Свойства темы

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

Сигналы

dir_selected(dir: String) 🔗

Выдается, когда пользователь выбирает каталог.

file_selected(path: String) 🔗

Генерируется, когда пользователь выбирает файл двойным щелчком или нажимает кнопку ОК.

filename_filter_changed(filter: String) 🔗

Выдается при изменении фильтра имен файлов.

files_selected(paths: PackedStringArray) 🔗

Выдается, когда пользователь выбирает несколько файлов.

Перечисления

enum FileMode: 🔗

FileMode FILE_MODE_OPEN_FILE = 0

Диалоговое окно позволяет выбрать один и только один файл.

FileMode FILE_MODE_OPEN_FILES = 1

Диалоговое окно позволяет выбрать несколько файлов.

FileMode FILE_MODE_OPEN_DIR = 2

В диалоговом окне можно выбрать только каталог, но не файл.

FileMode FILE_MODE_OPEN_ANY = 3

Диалог позволяет выбрать один файл или каталог.

FileMode FILE_MODE_SAVE_FILE = 4

Диалоговое окно выдаст предупреждение, если файл уже существует.

enum Access: 🔗

Access ACCESS_RESOURCES = 0

Диалоговое окно позволяет получить доступ только к файлам, находящимся по пути Resource (res://).

Access ACCESS_USERDATA = 1

Диалоговое окно позволяет получить доступ только к файлам, находящимся по пути к данным пользователя (user://).

Access ACCESS_FILESYSTEM = 2

Диалоговое окно позволяет получить доступ к файлам во всей файловой системе.

enum DisplayMode: 🔗

DisplayMode DISPLAY_THUMBNAILS = 0

Диалог отображает файлы в виде сетки миниатюр. Используйте thumbnail_size для настройки их размера.

DisplayMode DISPLAY_LIST = 1

В диалоговом окне файлы отображаются в виде списка имен файлов.

enum Customization: 🔗

Customization CUSTOMIZATION_HIDDEN_FILES = 0

Включает/выключает видимость кнопки «Избранное» и списка избранного в левой части диалогового окна.

Эквивалентно hidden_files_toggle_enabled.

Customization CUSTOMIZATION_CREATE_FOLDER = 1

Если включено, отображает кнопку для создания новых каталогов (при использовании FILE_MODE_OPEN_DIR, FILE_MODE_OPEN_ANY или FILE_MODE_SAVE_FILE).

Эквивалентно folder_creation_enabled.

Customization CUSTOMIZATION_FILE_FILTER = 2

Если включено, отображается кнопка переключения фильтра файлов.

Эквивалентно file_filter_toggle_enabled.

Customization CUSTOMIZATION_FILE_SORT = 3

Если включено, отображает кнопку параметров сортировки файлов.

Эквивалентно file_sort_options_enabled.

Customization CUSTOMIZATION_FAVORITES = 4

Если включено, в левой части диалогового окна отображается кнопка переключения избранного и список избранного.

Эквивалентно favorites_enabled.

Customization CUSTOMIZATION_RECENT = 5

Если включено, отображает список последних каталогов в левой части диалогового окна.

Эквивалентно recent_list_enabled.

Customization CUSTOMIZATION_LAYOUT = 6

Если включено, отображаются кнопки переключения макета (список/миниатюры).

Эквивалентно layout_toggle_enabled.

Customization CUSTOMIZATION_OVERWRITE_WARNING = 7

Если включено, FileDialog предупредит пользователя перед перезаписью файлов в режиме сохранения.

Эквивалентно overwrite_warning_enabled.

Customization CUSTOMIZATION_DELETE = 8

Если эта опция включена, в контекстном меню отобразится пункт «Удалить», позволяющий перемещать файлы и папки в корзину.

Эквивалентно deleting_enabled.

Описания свойств

Access access = 0 🔗

void set_access(value: Access)
Access get_access()

Область доступа к файловой системе.

Предупреждение: В веб-сборках FileDialog не может получить доступ к файловой системе хоста. В изолированных средах Linux и macOS use_native_dialog автоматически используется для разрешения ограниченного доступа к файловой системе хоста.

String current_dir 🔗

void set_current_dir(value: String)
String get_current_dir()

Текущий рабочий каталог диалога файлов.

Примечание: Для собственных диалогов файлов это свойство рассматривается только как подсказка и может не учитываться определенными реализациями ОС.

String current_file 🔗

void set_current_file(value: String)
String get_current_file()

Текущий выбранный файл в диалоговом окне.

String current_path 🔗

void set_current_path(value: String)
String get_current_path()

Текущий выбранный путь к файлу в диалоговом окне.

bool deleting_enabled = true 🔗

void set_customization_flag_enabled(flag: Customization, enabled: bool)
bool is_customization_flag_enabled(flag: Customization) const

Если true, в контекстном меню отобразится опция «Удалить», позволяющая перемещать файлы и папки в корзину.

DisplayMode display_mode = 0 🔗

void set_display_mode(value: DisplayMode)
DisplayMode get_display_mode()

Режим отображения списка файлов диалога.

bool favorites_enabled = true 🔗

void set_customization_flag_enabled(flag: Customization, enabled: bool)
bool is_customization_flag_enabled(flag: Customization) const

Если true, то на левой стороне диалогового окна отображаются кнопка переключения избранного и список избранного.

bool file_filter_toggle_enabled = true 🔗

void set_customization_flag_enabled(flag: Customization, enabled: bool)
bool is_customization_flag_enabled(flag: Customization) const

Если true, отображается кнопка переключения фильтра файлов.

FileMode file_mode = 4 🔗

void set_file_mode(value: FileMode)
FileMode get_file_mode()

Режим открытия или сохранения диалогового окна, который влияет на поведение выбора.

bool file_sort_options_enabled = true 🔗

void set_customization_flag_enabled(flag: Customization, enabled: bool)
bool is_customization_flag_enabled(flag: Customization) const

Если true, показывает кнопку параметров сортировки файлов.

String filename_filter = "" 🔗

void set_filename_filter(value: String)
String get_filename_filter()

Фильтр для имен файлов (без учета регистра). Если задана непустая строка, будут показаны только файлы, содержащие подстроку. filename_filter может редактироваться пользователем с помощью кнопки фильтра в верхней части диалогового окна файла.

См. также filters, которые следует использовать для ограничения типов файлов, которые можно выбрать, вместо filename_filter, который должен устанавливаться пользователем.

PackedStringArray filters = PackedStringArray() 🔗

void set_filters(value: PackedStringArray)
PackedStringArray get_filters()

Доступные фильтры по типам файлов. Каждая строка фильтра в массиве должна быть отформатирована следующим образом: *.png,*.jpg,*.jpeg;Файлы изображений;image/png,image/jpeg. Текст описания фильтра является необязательным и может быть опущен. Расширения файлов и MIME-типы всегда должны быть указаны.

Примечание: Встроенные диалоговые окна выбора файлов и диалоговые окна выбора файлов Windows поддерживают только расширения файлов, в то время как диалоговые окна выбора файлов Android, Linux и macOS также поддерживают MIME-типы.

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 🔗

void set_customization_flag_enabled(flag: Customization, enabled: bool)
bool is_customization_flag_enabled(flag: Customization) const

Если true, отобразится кнопка для создания новых каталогов (при использовании FILE_MODE_OPEN_DIR, FILE_MODE_OPEN_ANY или FILE_MODE_SAVE_FILE), а в контекстном меню появится опция "Новая папка...".

bool hidden_files_toggle_enabled = true 🔗

void set_customization_flag_enabled(flag: Customization, enabled: bool)
bool is_customization_flag_enabled(flag: Customization) const

Если true, отображается кнопка переключения скрытых файлов.

bool layout_toggle_enabled = true 🔗

void set_customization_flag_enabled(flag: Customization, enabled: bool)
bool is_customization_flag_enabled(flag: Customization) const

Если true, отображаются кнопки переключения макета (список/миниатюры).

bool mode_overrides_title = true 🔗

void set_mode_overrides_title(value: bool)
bool is_mode_overriding_title()

Если true, изменение свойства file_mode соответствующим образом установит заголовок окна (например, установка file_mode на FILE_MODE_OPEN_FILE изменит заголовок окна на «Открыть файл»).

int option_count = 0 🔗

void set_option_count(value: int)
int get_option_count()

Количество дополнительных OptionButton и CheckBox-ов в диалоговом окне.

bool overwrite_warning_enabled = true 🔗

void set_customization_flag_enabled(flag: Customization, enabled: bool)
bool is_customization_flag_enabled(flag: Customization) const

Если true, то FileDialog предупредит пользователя перед перезаписью файлов в режиме сохранения.

bool recent_list_enabled = true 🔗

void set_customization_flag_enabled(flag: Customization, enabled: bool)
bool is_customization_flag_enabled(flag: Customization) const

Если true, отображает список последних каталогов в левой части диалогового окна.

String root_subfolder = "" 🔗

void set_root_subfolder(value: String)
String get_root_subfolder()

Если не пусто, указанная подпапка будет «корневой» для этого FileDialog, т. е. пользователь не сможет перейти в ее родительский каталог.

Примечание: Это свойство игнорируется для собственных файловых диалогов.

bool show_hidden_files = false 🔗

void set_show_hidden_files(value: bool)
bool is_showing_hidden_files()

Если true, диалоговое окно покажет скрытые файлы.

Примечание: Это свойство игнорируется собственными диалоговыми окнами файлов на Android и Linux.

bool use_native_dialog = false 🔗

void set_use_native_dialog(value: bool)
bool get_use_native_dialog()

Если true и если это поддерживается текущим DisplayServer, вместо пользовательского диалогового окна будет использоваться собственное диалоговое окно ОС.

Примечание: На Android это поддерживается только для устройств Android 10+ и при использовании ACCESS_FILESYSTEM. Для режимов доступа ACCESS_RESOURCES и ACCESS_USERDATA система будет использовать пользовательское диалоговое окно FileDialog.

Примечание: В Linux и macOS изолированные приложения всегда используют собственные диалоговые окна для доступа к файловой системе хоста.

Примечание: В macOS изолированные приложения сохраняют закладки с ограниченным доступом, чтобы сохранить доступ к открытым папкам в нескольких сессиях. Используйте OS.get_granted_permissions(), чтобы получить список сохраненных закладок.

Примечание: Нативные диалоговые окна изолированы от базового процесса, свойства диалогового окна выбора файла нельзя изменить после его отображения.

Примечание: Это свойство игнорируется в EditorFileDialog.

Описания метода

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

Добавляет в FileDialog параметр расширения файла, разделённого запятыми filter, и параметр MIME-типа, разделённого запятыми mime_type, с необязательным параметром description, который ограничивает выбор файлов.

Параметр filter должен иметь вид "filename.extension", где имя файла и расширение могут быть * для соответствия любой строке. Фильтры, начинающиеся с . (т.е. пустые имена файлов), не допускаются.

Например, filter со значением "*.png, *.jpg", mime_type со значением image/png, image/jpeg и description со значением "Images" приведёт к тексту фильтра "Images (*.png, *.jpg)".

Примечание: Встроенные диалоговые окна выбора файлов и диалоговые окна выбора файлов Windows поддерживают только расширения файлов, в то время как диалоговые окна выбора файлов Android, Linux и macOS также поддерживают типы MIME.

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

Добавляет дополнительный OptionButton в диалоговое окно файла. Если values пусто, вместо него добавляется CheckBox.

default_value_index должен быть индексом значения в values. Если values пусто, он должен быть либо 1 (отмечено), либо 0 (не отмечено).

void clear_filename_filter() 🔗

Очистить фильтр по именам файлов.

void clear_filters() 🔗

Очистите все добавленные фильтры в диалоговом окне.

void deselect_all() 🔗

Очистить все выбранные элементы в диалоговом окне.

PackedStringArray get_favorite_list() static 🔗

Возвращает список избранных каталогов, который используется всеми узлами FileDialog. Полезен для хранения списка избранных каталогов между сессиями проекта. Этот метод может быть вызван только из основного потока.

LineEdit get_line_edit() 🔗

Возвращает LineEdit для выбранного файла.

Предупреждение: Это обязательный внутренний узел, его удаление и освобождение может привести к сбою. Если вы хотите скрыть его или любой из его дочерних элементов, используйте их свойство CanvasItem.visible.

int get_option_default(option: int) const 🔗

Возвращает индекс значения по умолчанию для OptionButton или CheckBox с индексом option.

String get_option_name(option: int) const 🔗

Возвращает имя OptionButton или CheckBox с индексом option.

PackedStringArray get_option_values(option: int) const 🔗

Возвращает массив значений OptionButton с индексом option.

PackedStringArray get_recent_list() static 🔗

Возвращает список недавно открытых каталогов, который используется всеми узлами FileDialog. Полезен для хранения списка недавно открытых каталогов между сессиями проекта. Этот метод может быть вызван только из основного потока.

Dictionary get_selected_options() const 🔗

Возвращает Dictionary с выбранными значениями дополнительных OptionButton и/или CheckBox. Ключи Dictionary — это имена, а значения — это выбранные индексы значений.

VBoxContainer get_vbox() 🔗

Возвращает вертикальный контейнер диалога, в него можно добавлять пользовательские элементы управления.

Предупреждение: Это обязательный внутренний узел, его удаление и освобождение может привести к сбою. Если вы хотите скрыть его или любой из его дочерних элементов, используйте их свойство CanvasItem.visible.

Примечание: Изменения этого узла игнорируются собственными файловыми диалогами, используйте add_option() для добавления пользовательских элементов в диалог.

void invalidate() 🔗

Аннулирует и обновляет список содержимого этого диалогового окна.

Примечание: Этот метод ничего не делает с собственными диалоговыми окнами выбора файла.

bool is_customization_flag_enabled(flag: Customization) const 🔗

Возвращает true, если указанный flag включен.

Отображает диалоговое окно выбора файла (FileDialog) с использованием размера и положения по умолчанию для диалоговых окон выбора файлов и выбирает имя файла, если есть текущий файл.

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

Устанавливает указанный параметр настройки flag, позволяющий настраивать функции, доступные в этом FileDialog.

void set_favorite_list(favorites: PackedStringArray) static 🔗

Задает список избранных каталогов, который используется всеми узлами FileDialog. Полезен для восстановления списка избранных, сохраненного с помощью get_favorite_list(). Этот метод можно вызывать только из основного потока.

Примечание: FileDialog будет обновлять свой внутренний ItemList избранных каталогов при изменении его видимости. Обязательно вызовите этот метод раньше, если хотите, чтобы ваши изменения вступили в силу.

void set_get_icon_callback(callback: Callable) static 🔗

Задает функцию обратного вызова, используемую узлами FileDialog для получения значка файла при использовании режима DISPLAY_LIST. Функция обратного вызова должна принимать один аргумент String (путь к файлу) и возвращать объект Texture2D. Если возвращается недопустимая текстура, вместо нее будет использоваться значок из файла .

void set_get_thumbnail_callback(callback: Callable) static 🔗

Задает функцию обратного вызова, используемую узлами FileDialog для получения значка файла при использовании режима DISPLAY_THUMBNAILS. Функция обратного вызова должна принимать один аргумент String (путь к файлу) и возвращать Texture2D. Если возвращается недопустимая текстура, вместо нее будет использоваться значок file_thumbnail.

Миниатюры обычно более сложные и могут загружаться некоторое время. Чтобы избежать задержки приложения, можно использовать ImageTexture для асинхронного создания миниатюры.

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) # Метод, генерирующий миниатюру.
    image_texture.set_image(thumbnail_texture.get_image())

void set_option_default(option: int, default_value_index: int) 🔗

Устанавливает индекс значения по умолчанию для OptionButton или CheckBox с индексом option.

void set_option_name(option: int, name: String) 🔗

Задает имя OptionButton или CheckBox с индексом option.

void set_option_values(option: int, values: PackedStringArray) 🔗

Устанавливает значения параметров OptionButton с индексом option.

void set_recent_list(recents: PackedStringArray) static 🔗

Задает список недавно открытых каталогов, который используется всеми узлами FileDialog. Полезно для восстановления списка недавно открытых каталогов, сохраненного с помощью set_recent_list(). Этот метод можно вызывать только из основного потока.

Примечание: FileDialog будет обновлять свой внутренний ItemList недавно открытых каталогов при изменении его видимости. Обязательно вызовите этот метод раньше, если хотите, чтобы ваши изменения вступили в силу.

Описания свойств темы

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

Цветовой оттенок для отключенных файлов (когда FileDialog используется в режиме открытой папки).

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

Цветовая модуляция, примененная к значку файла.

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

Цветовая модуляция, примененная к значку папки.

int thumbnail_size = 64 🔗

Размер миниатюрных значков, когда включен DISPLAY_THUMBNAILS.

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 🔗

Пользовательский значок для кнопки переключения скрытой информации.