FileDialog

public FileDialog();

Creates a hidden SaveFile dialog with Resources access. Initial configuration neither creates a file nor opens an OS window.

public FileDialog.AccessEnum Access { get; set; }

Navigation scope: Resources (asset://), Userdata (user://) or Filesystem. Default Resources. Does not grant OS permissions; changing it resets RootSubfolder, so configure directory state again.

public string CurrentDir { get; set; }

Current directory rather than selected file. Prefer an explicit asset://, user:// or absolute path appropriate to Access. Setter neither creates a directory nor confirms a selection.

public string CurrentFile { get; set; }

Filename-field text, normally without a directory. Does not load/create a file or emit FileSelected. Use CurrentPath for a full path.

public string CurrentPath { get; set; }

Combination of CurrentDir and CurrentFile. A full-path setter sets directory/name; a separator-free path changes only the name, while empty input is a no-op. Does not prove the file exists.

public bool DeletingEnabled { get; set; }

Allows the built-in list’s delete action, which moves a selected item to trash when executed. The flag itself deletes nothing; false does not prohibit application FileAccess/DirAccess.

public FileDialog.DisplayModeEnum DisplayMode { get; set; }

Built-in list presentation: Thumbnails or List. Does not change FileMode, Access or file-read results. Thumbnail quality depends on the configured thumbnail provider.

public bool DriveSelectorEnabled { get; set; }

Show the drive selector where applicable to Access/platform. Does not grant access to every OS drive.

public bool FavoritesEnabled { get; set; }

Show favorites in built-in UI. Does not clear the shared SetFavoriteList list.

public bool FileFilterToggleEnabled { get; set; }

Show the filename-search-row toggle. true shows the button rather than enabling the search itself; separate from extension masks in Filters.

public FileDialog.FileModeEnum FileMode { get; set; }

Selection mode: OpenFile, OpenFiles, OpenDir, OpenAny or SaveFile. Default SaveFile. Changes standard labels/selection behavior rather than performing I/O; a custom Title is retained.

public string FileNameFilter { get; set; }

Built-in filename search text, separate from extension masks in Filters. Setter clears the query while the search row is disabled. Use Filters for persistent extension filtering. Do not trust the FileNameFilterChanged argument: installed Runtime has a type mismatch.

public bool FileSortOptionsEnabled { get; set; }

Show file-sort UI. Does not change filenames/file contents or Filters array order.

public string[] Filters { get; set; }

String array of mask ; label ; MIME, with trailing fields optional. Commas separate masks within a group. Getter returns a copy; setter replaces the list rather than validating file contents.

public bool FiltersEnabled { get; set; }

Show the extension-filter dropdown. Does not clear Filters and is not the filename-search toggle.

public bool FolderCreationEnabled { get; set; }

Allows directory-creation UI in applicable FileMode values. Assignment does not create a directory or prohibit your own DirAccess calls.

public bool HiddenFilesToggleEnabled { get; set; }

Show the hidden-file toggle. Separate from ShowHiddenFiles: hiding the button does not change the current hidden-file setting.

public bool LayoutToggleEnabled { get; set; }

Show the Thumbnails/List toggle. Does not reset current DisplayMode.

public bool ModeOverridesTitle { get; set; }

Legacy flag: setter does nothing and getter returns true. Set Title for your caption; installed SDK retains a custom Title when FileMode changes.

public bool NavigationButtonsEnabled { get; set; }

Show back/forward buttons. Does not block programmatic CurrentDir/CurrentPath.

public int OptionCount { get; set; }

Extra-setting count. Shrinking retains the list prefix; growing creates empty records needing unique names, values and defaults. Changes can rebuild the UI and reset current answers to defaults.

public bool OverwriteWarningEnabled { get; set; }

Request confirmation for an existing SaveFile destination. FileDialog does not write it; check your own save result even after confirmation.

public bool RecentListEnabled { get; set; }

Show recent directories in built-in UI. Does not clear the shared SetRecentList list.

public string RootSubfolder { get; set; }

Existing directory restricting built-in UI navigation within Access. Empty input clears the setting; changing Access resets it. Does not create the directory or provide a security boundary for your own FileAccess: validate the final path separately.

public bool ShowHiddenFiles { get; set; }

Show hidden items in the built-in list, default false. Does not switch FileMode or grant access to hidden/protected files.

public bool UseNativeDialog { get; set; }

Requests an OS dialog when the platform supports the needed features. false does not guarantee built-in UI in an OS sandbox; true does not guarantee support for arbitrary added Controls. Configure before opening.

public void AddFilter(string filter, string description);

Short overload adds a mask/label with empty MIME. Use the mimeType overload for MIME; filters do not validate file contents.

public void AddFilter(string filter, string description = "", string mimeType = "");

Adds mask group, label and optional MIME. Example mask: .png,.jpg; do not use .png without *. Does not confirm selection or prove content format.

public void AddOption(string name, ReadOnlySpan<string> values, int defaultValueIndex);

Adds an extra setting with a unique name. Empty values defines a checkbox with defaultValueIndex 0/1; nonempty values defines a choice list with index 0…Length-1. Default is clamped to that range. Built-in controls materialize when the visible dialog updates.

public void AddOption(string name, string[] values, int defaultValueIndex);

Adds an extra setting with a unique name. Empty values defines a checkbox with defaultValueIndex 0/1; nonempty values defines a choice list with index 0…Length-1. Default is clamped to that range. Built-in controls materialize when the visible dialog updates.

public void ClearFileNameFilter();

Clears filename search and updates built-in UI. Does not remove Filters masks, the chosen path or files. Account for the FileNameFilterChanged payload mismatch when observing notification.

public void ClearFilters();

Removes filter groups while retaining filename text. Does not reset the path or remove OS restrictions.

public void DeselectAll();

Deselects list items and updates confirmation availability. Does not delete files or emit successful selection.

public FileDialog.AccessEnum GetAccess();

Navigation scope: Resources (asset://), Userdata (user://) or Filesystem. Default Resources. Does not grant OS permissions; changing it resets RootSubfolder, so configure directory state again.

public string GetCurrentDir();

Current directory rather than selected file. Prefer an explicit asset://, user:// or absolute path appropriate to Access. Setter neither creates a directory nor confirms a selection.

public string GetCurrentFile();

Filename-field text, normally without a directory. Does not load/create a file or emit FileSelected. Use CurrentPath for a full path.

public string GetCurrentPath();

Combination of CurrentDir and CurrentFile. A full-path setter sets directory/name; a separator-free path changes only the name, while empty input is a no-op. Does not prove the file exists.

public FileDialog.DisplayModeEnum GetDisplayMode();

Built-in list presentation: Thumbnails or List. Does not change FileMode, Access or file-read results. Thumbnail quality depends on the configured thumbnail provider.

public static string[] GetFavoriteList();

Main thread: returns a copy of the shared favorite-directory list. Editing the array does not change the global list; use SetFavoriteList.

public FileDialog.FileModeEnum GetFileMode();

Selection mode: OpenFile, OpenFiles, OpenDir, OpenAny or SaveFile. Default SaveFile. Changes standard labels/selection behavior rather than performing I/O; a custom Title is retained.

public string GetFileNameFilter();

Built-in filename search text, separate from extension masks in Filters. Setter clears the query while the search row is disabled. Use Filters for persistent extension filtering. Do not trust the FileNameFilterChanged argument: installed Runtime has a type mismatch.

public string[] GetFilters();

String array of mask ; label ; MIME, with trailing fields optional. Commas separate masks within a group. Getter returns a copy; setter replaces the list rather than validating file contents.

public LineEdit GetLineEdit();

Shared internal filename field. Its Text is reflected in CurrentFile; not the filter field. Do not free/reparent it separately; it is not an OS-native window control.

public int GetOptionCount();

Extra-setting count. Shrinking retains the list prefix; growing creates empty records needing unique names, values and defaults. Changes can rebuild the UI and reset current answers to defaults.

public int GetOptionDefault(int option);

Returns the schema default rather than the current user answer: 0/1 for checkbox or a choice index.

public string GetOptionName(int option);

Setting name at an ordinary valid index. Used as a GetSelectedOptions key, so names should be unique and stable.

public string[] GetOptionValues(int option);

Returns a copy of choice labels. An empty array means checkbox rather than no setting. Use SetOptionValues to change them.

public static string[] GetRecentList();

Main thread: copy of the shared recent-directory list. These are navigation directories rather than a history of every opened file.

public string GetRootSubfolder();

Existing directory restricting built-in UI navigation within Access. Empty input clears the setting; changing Access resets it. Does not create the directory or provide a security boundary for your own FileAccess: validate the final path separately.

public Reckfell.Collections.Dictionary GetSelectedOptions();

Returns a shared Dictionary of name → bool/current choice index. Can be empty before controls materialize even when OptionCount > 0. Rebuilding options resets it to defaults. Copy accepted values into your model; do not treat dictionary mutation as an official setter.

public bool GetUseNativeDialog();

Requests an OS dialog when the platform supports the needed features. false does not guarantee built-in UI in an OS sandbox; true does not guarantee support for arbitrary added Controls. Configure before opening.

public VBoxContainer GetVBox();

Shared internal VBoxContainer of the built-in dialog. Add UI while retaining FileDialog ownership; an OS backend need not display those Controls.

public void Invalidate();

Schedules an update of the visible built-in list; does not immediately scan for a hidden dialog. Neither a file-existence check nor selection confirmation.

public bool IsCustomizationFlagEnabled(FileDialog.Customization flag);

Returns this instance’s Customization setting. A UI/confirmation policy rather than OS permission for a file operation.

public bool IsModeOverridingTitle();

Legacy flag: setter does nothing and getter returns true. Set Title for your caption; installed SDK retains a custom Title when FileMode changes.

public bool IsShowingHiddenFiles();

Show hidden items in the built-in list, default false. Does not switch FileMode or grant access to hidden/protected files.

public void PopupFileDialog();

Opens the dialog with standard viewport-relative sizing/constraints. Set mode, access, filters and selection handlers first. Can use an OS backend; does not itself read/write the file.

public void SetAccess(FileDialog.AccessEnum access);

Navigation scope: Resources (asset://), Userdata (user://) or Filesystem. Default Resources. Does not grant OS permissions; changing it resets RootSubfolder, so configure directory state again.

public void SetCurrentDir(string dir);

Current directory rather than selected file. Prefer an explicit asset://, user:// or absolute path appropriate to Access. Setter neither creates a directory nor confirms a selection.

public void SetCurrentFile(string file);

Filename-field text, normally without a directory. Does not load/create a file or emit FileSelected. Use CurrentPath for a full path.

public void SetCurrentPath(string path);

Combination of CurrentDir and CurrentFile. A full-path setter sets directory/name; a separator-free path changes only the name, while empty input is a no-op. Does not prove the file exists.

public void SetCustomizationFlagEnabled(FileDialog.Customization flag, bool enabled);

Changes a UI/confirmation setting. Does not perform file operations, change the application model or grant OS permissions.

public void SetDisplayMode(FileDialog.DisplayModeEnum mode);

Built-in list presentation: Thumbnails or List. Does not change FileMode, Access or file-read results. Thumbnail quality depends on the configured thumbnail provider.

public static void SetFavoriteList(ReadOnlySpan<string> favorites);

Replaces the process-wide FileDialog favorite-directory list; call on the main thread. Appends a trailing /. Not an instance-local list or automatic disk persistence. UI list refresh is separate.

public static void SetFavoriteList(string[] favorites);

Replaces the process-wide FileDialog favorite-directory list; call on the main thread. Appends a trailing /. Not an instance-local list or automatic disk persistence. UI list refresh is separate.

public void SetFileMode(FileDialog.FileModeEnum mode);

Selection mode: OpenFile, OpenFiles, OpenDir, OpenAny or SaveFile. Default SaveFile. Changes standard labels/selection behavior rather than performing I/O; a custom Title is retained.

public void SetFileNameFilter(string filter);

Built-in filename search text, separate from extension masks in Filters. Setter clears the query while the search row is disabled. Use Filters for persistent extension filtering. Do not trust the FileNameFilterChanged argument: installed Runtime has a type mismatch.

public void SetFilters(ReadOnlySpan<string> filters);

String array of mask ; label ; MIME, with trailing fields optional. Commas separate masks within a group. Getter returns a copy; setter replaces the list rather than validating file contents.

public void SetFilters(string[] filters);

String array of mask ; label ; MIME, with trailing fields optional. Commas separate masks within a group. Getter returns a copy; setter replaces the list rather than validating file contents.

public static void SetGetIconCallback(Callable callback);

Installs a shared static icon provider for built-in FileDialogs: Callable receives one path string and returns Texture2D or null for fallback. Not instance-local. Avoid capturing a short-lived dialog; manage provider lifetime at application level.

public static void SetGetThumbnailCallback(Callable callback);

Shared static thumbnail provider: one path string → Texture2D or null for default fallback. Used by built-in Thumbnails mode rather than guaranteeing native OS thumbnails. Cache prepared images and avoid blocking UI with expensive callback generation.

public void SetModeOverridesTitle(bool @override);

Legacy flag: setter does nothing and getter returns true. Set Title for your caption; installed SDK retains a custom Title when FileMode changes.

public void SetOptionCount(int count);

Extra-setting count. Shrinking retains the list prefix; growing creates empty records needing unique names, values and defaults. Changes can rebuild the UI and reset current answers to defaults.

public void SetOptionDefault(int option, int defaultValueIndex);

Sets a default clamped to 0…1 for checkbox or 0…values.Length-1 for a choice list. Accepts a negative setting index; not a silent setter for one current answer in an open dialog.

public void SetOptionName(int option, string name);

Changes the setting key/label; accepts negative indices from the end. Rebuilding controls can reset current answers: configure the schema before opening.

public void SetOptionValues(int option, ReadOnlySpan<string> values);

Replaces choices by copying the array; empty input switches the setting to a checkbox. Stored default is clamped to the new range. Accepts negative indices and can rebuild UI.

public void SetOptionValues(int option, string[] values);

Replaces choices by copying the array; empty input switches the setting to a checkbox. Stored default is clamped to the new range. Accepts negative indices and can rebuild UI.

public static void SetRecentList(ReadOnlySpan<string> recents);

Replaces the process-wide recent-directory list on the main thread, appending trailing /. Does not itself rewrite a user settings file.

public static void SetRecentList(string[] recents);

Replaces the process-wide recent-directory list on the main thread, appending trailing /. Does not itself rewrite a user settings file.

public void SetRootSubfolder(string dir);

Existing directory restricting built-in UI navigation within Access. Empty input clears the setting; changing Access resets it. Does not create the directory or provide a security boundary for your own FileAccess: validate the final path separately.

public void SetShowHiddenFiles(bool show);

Show hidden items in the built-in list, default false. Does not switch FileMode or grant access to hidden/protected files.

public void SetUseNativeDialog(bool native);

Requests an OS dialog when the platform supports the needed features. false does not guarantee built-in UI in an OS sandbox; true does not guarantee support for arbitrary added Controls. Configure before opening.

public event FileDialog.DirSelectedEventHandler DirSelected;

Directory accepted in OpenDir or as an OpenAny directory result. A directory rather than a destination filename; the signal does not mean FileDialog created it.

public event FileDialog.FileNameFilterChangedEventHandler FileNameFilterChanged;

Runtime/SDK 1.0.0 limitation: the native signal supplies an OptionButton object while the SDK declares string. Do not use filter as text. Workaround: Connect(FileDialog.SignalName.FileNameFilterChanged, Callable.From<Variant>(handler)), with a handler that ignores payload and reads the dialog’s FileNameFilter. Retain the Callable for Disconnect.

public event FileDialog.FileSelectedEventHandler FileSelected;

One path accepted: OpenFile, a file result of OpenAny, or SaveFile. In SaveFile it may not exist yet. The signal does not mean successful reading/writing; perform and check I/O separately.

public event FileDialog.FilesSelectedEventHandler FilesSelected;

Path array accepted in OpenFiles mode. Validate each path/file separately; changing settings or CurrentPath does not emit this signal.