Skip to content

native_file_dialog.md

Latest commit

 

History

History
177 lines (108 loc) · 4.51 KB

native_file_dialog.md

File metadata and controls

177 lines (108 loc) · 4.51 KB
Raw

NativeFileDialog

Description

NativeFileDialog is a dialog used to choose files and directories in the filesystem. It supports filter masks. The NativeFileDialog automatically sets its window title according to the mode. If you want to use a custom title, disable this by setting mode_overrides_title to false.

Native File Dialog

Properties

Type Name Default value
Access access 0
FileMode file_mode 3
PoolStringArray filters PoolStringArray()
bool mode_overrides_title true
String root_subfolder ""
String title "Save a File"

Methods

Returned type Declaration
void add_filter(String filter, String description="")
void clear_filters()
void hide()
void show()

Signals

dir_selected(String dir)

Emitted when the user selects a directory.

file_selected(String path)

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

files_selected(PoolStringArray paths)

Emitted when the user selects multiple files.

canceled()

Emitted when the dialog is closed.

Enumerations

enum FileMode

FileMode MODE_OPEN_FILE = 0

The dialog allows selecting one, and only one file.

FileMode MODE_OPEN_FILES = 1

The dialog allows selecting multiple files.

FileMode MODE_OPEN_DIR = 2

The dialog only allows selecting a directory, disallowing the selection of any file.

FileMode MODE_SAVE_FILE = 3

The dialog will warn when a file exists.

enum Access

Access ACCESS_RESOURCES = 0

The dialog is initiated under the Resource path (res://).

Access ACCESS_USERDATA = 1

The dialog is initiated under the user data path (user://).

Access ACCESS_FILESYSTEM = 2

The dialog allows accessing files on the whole file system.

Property Descriptions

Access access = 0

The file system access scope. See enum Access constants. Changing this value would reset root_subfolder. So when using code, you need to set access before root_subfolder.

void set_access(Access value)

Access get_access()

FileMode file_mode = 3

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

void set_file_mode(FileMode value)

FileMode get_file_mode()

PackedStringArray filters = PackedStringArray()

The available file type filters. For example, this shows only .png and .gd files: set_filters(PackedStringArray(["*.png ; PNG Images","*.gd ; GDScript Files"])). Multiple file types can also be specified in a single filter. "*.png, *.jpg, *.jpeg ; Supported Images" will show both PNG and JPEG files when selected.

void set_filters(PackedStringArray value)

PackedStringArray get_filters()

bool mode_overrides_title = true

If true, changing the Mode property will set the window title accordingly (e.g. setting mode to FILE_MODE_OPEN_FILE will change the window title to "Open a File").

void set_mode_overrides_title(bool value)

bool is_mode_overriding_title()

String root_subfolder = ""

The subfolder where the native dialog would start.

void set_root_subfolder(String value)

String get_root_subfolder()

String title = "Save a File"

The dialog's title.

void set_title(String value)

String get_title()

Method Descriptions

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

Adds a comma-delimited file name filter 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" and a description of "Images" results in filter text "Images (*.png, *.jpg)".

void clear_filters()

Clear all the added filters in the dialog.

void hide()

Hides the dialog.

void show()

Makes the dialog appear. If this dialog is already visible, it would call hide first.