FileDialog

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

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

Описание

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

Свойства

Access	access	`0`
String	current_dir
String	current_file
String	current_path
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	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 = "")
void	add_option(name: String, values: PackedStringArray, default_value_index: int)
void	clear_filename_filter()
void	clear_filters()
void	deselect_all()
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
Dictionary	get_selected_options() const
VBoxContainer	get_vbox()
void	invalidate()
bool	is_customization_flag_enabled(flag: Customization) const
void	set_customization_flag_enabled(flag: Customization, enabled: bool)
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)

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

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.

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

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

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

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 Files;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 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() для получения списка сохранённых закладок.

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

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

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

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

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

Например, filter со значением "*.png, *.jpg" и description со значением "Изображения" приведут к появлению текста фильтра "Изображения (*.png, *.jpg)".

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

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

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.

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 включен.

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

Включает/выключает указанную настройку flag, позволяя настраивать функции, доступные в этом FileDialog. См. Customization для получения информации о параметрах.

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.

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

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 🔗

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