Struct FileDialog

pub struct FileDialog { /* private fields */ }

Represents a file dialog instance.

The FileDialog instance can be used multiple times and for different actions.

Examples

use egui_file_dialog::FileDialog;

struct MyApp {
    file_dialog: FileDialog,
}

impl MyApp {
    fn update(&mut self, ctx: &egui::Context, ui: &mut egui::Ui) {
        if ui.button("Pick a file").clicked() {
            self.file_dialog.pick_file();
        }

        if let Some(path) = self.file_dialog.update(ctx).picked() {
            println!("Picked file: {:?}", path);
        }
    }
}

Implementations

impl FileDialog

pub fn new() -> Self

Creates a new file dialog instance with default values.

pub fn with_config(config: FileDialogConfig) -> Self

Creates a new file dialog object and initializes it with the specified configuration.

pub fn with_file_system(file_system: Arc<dyn FileSystem + Send + Sync>) -> Self

Uses the given file system instead of the native file system.

pub fn open( &mut self, mode: DialogMode, show_files: bool, operation_id: Option<&str>, )

👎Deprecated since 0.10.0: Use pick_file / pick_directory / pick_multiple in combination with set_operation_id instead

Opens the file dialog in the given mode with the given options. This function resets the file dialog and takes care for the variables that need to be set when opening the file dialog.

Returns the result of the operation to load the initial directory.

If you don’t need to set the individual parameters, you can also use the shortcut methods select_directory, select_file and save_file.

Arguments

• mode - The mode in which the dialog should be opened
• show_files - If files should also be displayed to the user in addition to directories. This is ignored if the mode is DialogMode::SelectFile.
• operation_id - Sets an ID for which operation the dialog was opened. This is useful when the dialog can be used for various operations in a single view. The ID can then be used to check which action the user selected an item for.

Examples

The following example shows how the dialog can be used for multiple actions using the operation_id.

use std::path::PathBuf;

use egui_file_dialog::{DialogMode, FileDialog};

struct MyApp {
    file_dialog: FileDialog,

    picked_file_a: Option<PathBuf>,
    picked_file_b: Option<PathBuf>,
}

impl MyApp {
    fn update(&mut self, ctx: &egui::Context, ui: &mut egui::Ui) {
        if ui.button("Pick file a").clicked() {
            let _ = self.file_dialog.open(DialogMode::PickFile, true, Some("pick_a"));
        }

        if ui.button("Pick file b").clicked() {
            let _ = self.file_dialog.open(DialogMode::PickFile, true, Some("pick_b"));
        }

        self.file_dialog.update(ctx);

        if let Some(path) = self.file_dialog.picked() {
            if self.file_dialog.operation_id() == Some("pick_a") {
                self.picked_file_a = Some(path.to_path_buf());
            }
            if self.file_dialog.operation_id() == Some("pick_b") {
                self.picked_file_b = Some(path.to_path_buf());
            }
        }
    }
}

pub fn pick_directory(&mut self)

Shortcut function to open the file dialog to prompt the user to pick a directory. If used, no files in the directories will be shown to the user. Use the open() method instead, if you still want to display files to the user. This function resets the file dialog. Configuration variables such as initial_directory are retained.

The function ignores the result of the initial directory loading operation.

pub fn pick_file(&mut self)

Shortcut function to open the file dialog to prompt the user to pick a file. This function resets the file dialog. Configuration variables such as initial_directory are retained.

The function ignores the result of the initial directory loading operation.

pub fn pick_multiple(&mut self)

Shortcut function to open the file dialog to prompt the user to pick multiple files and folders. This function resets the file dialog. Configuration variables such as initial_directory are retained.

The function ignores the result of the initial directory loading operation.

pub fn save_file(&mut self)

Shortcut function to open the file dialog to prompt the user to save a file. This function resets the file dialog. Configuration variables such as initial_directory are retained.

The function ignores the result of the initial directory loading operation.

pub fn update(&mut self, ctx: &Context) -> &Self

The main update method that should be called every frame if the dialog is to be visible.

This function has no effect if the dialog state is currently not DialogState::Open.

pub fn set_right_panel_width(&mut self, width: f32)

Sets the width of the right panel.

pub fn clear_right_panel_width(&mut self)

Clears the width of the right panel by setting it to None.

pub fn update_with_right_panel_ui( &mut self, ctx: &Context, f: &mut (dyn FnMut(&mut Ui, &mut FileDialog) + '_), ) -> &Self

Do an update with a custom right panel ui.

Example use cases:

• Show custom information for a file (size, MIME type, etc.)
• Embed a preview, like a thumbnail for an image
• Add controls for custom open options, like open as read-only, etc.

See active_entry to get the active directory entry to show the information for.

This function has no effect if the dialog state is currently not DialogState::Open.

pub fn config_mut(&mut self) -> &mut FileDialogConfig

Mutably borrow internal config.

pub fn storage(self, storage: FileDialogStorage) -> Self

Sets the storage used by the file dialog. Storage includes all data that is persistently stored between multiple file dialog instances.

pub fn storage_mut(&mut self) -> &mut FileDialogStorage

Mutably borrow internal storage.

pub fn keybindings(self, keybindings: FileDialogKeyBindings) -> Self

Sets the keybindings used by the file dialog.

pub fn labels(self, labels: FileDialogLabels) -> Self

Sets the labels the file dialog uses.

Used to enable multiple language support.

See FileDialogLabels for more information.

pub fn labels_mut(&mut self) -> &mut FileDialogLabels

Mutably borrow internal config.labels.

pub const fn opening_mode(self, opening_mode: OpeningMode) -> Self

Sets which directory is loaded when opening the file dialog.

pub const fn as_modal(self, as_modal: bool) -> Self

If the file dialog window should be displayed as a modal.

If the window is displayed as modal, the area outside the dialog can no longer be interacted with and an overlay is displayed.

pub const fn modal_overlay_color(self, modal_overlay_color: Color32) -> Self

Sets the color of the overlay when the dialog is displayed as a modal window.

pub fn initial_directory(self, directory: PathBuf) -> Self

Sets the first loaded directory when the dialog opens. If the path is a file, the file’s parent directory is used. If the path then has no parent directory or cannot be loaded, the user will receive an error. However, the user directories and system disk allow the user to still select a file in the event of an error.

Since fs::canonicalize is used, both absolute paths and relative paths are allowed. See FileDialog::canonicalize_paths for more information.

pub fn default_file_name(self, name: &str) -> Self

Sets the default file name when opening the dialog in DialogMode::SaveFile mode.

pub const fn allow_file_overwrite(self, allow_file_overwrite: bool) -> Self

Sets if the user is allowed to select an already existing file when the dialog is in DialogMode::SaveFile mode.

If this is enabled, the user will receive a modal asking whether the user really wants to overwrite an existing file.

pub const fn allow_path_edit_to_save_file_without_extension( self, allow: bool, ) -> Self

Sets if the path edit is allowed to select the path as the file to save if it does not have an extension.

This can lead to confusion if the user wants to open a directory with the path edit, types it incorrectly and the dialog tries to select the incorrectly typed folder as the file to be saved.

This only affects the DialogMode::SaveFile mode.

pub fn directory_separator(self, separator: &str) -> Self

Sets the separator of the directories when displaying a path. Currently only used when the current path is displayed in the top panel.

pub const fn canonicalize_paths(self, canonicalize: bool) -> Self

Sets if the paths in the file dialog should be canonicalized before use.

By default, all paths are canonicalized. This has the advantage that the paths are all brought to a standard and are therefore compatible with each other.

On Windows, however, this results in the namespace prefix \\?\ being set in front of the path, which may not be compatible with other applications. In addition, canonicalizing converts all relative paths to absolute ones.

See: Rust docs for more information.

In general, it is only recommended to disable canonicalization if you know what you are doing and have a reason for it. Disabling canonicalization can lead to unexpected behavior, for example if an already canonicalized path is then set as the initial directory.

pub const fn load_via_thread(self, load_via_thread: bool) -> Self

If the directory content should be loaded via a separate thread. This prevents the application from blocking when loading large directories or from slow hard drives.

pub const fn truncate_filenames(self, truncate_filenames: bool) -> Self

Sets if long filenames should be truncated in the middle. The extension, if available, will be preserved.

Warning! If this is disabled, the scroll-to-selection might not work correctly and have an offset for large directories.

pub fn err_icon(self, icon: &str) -> Self

Sets the icon that is used to display errors.

pub fn default_file_icon(self, icon: &str) -> Self

Sets the default icon that is used to display files.

pub fn default_folder_icon(self, icon: &str) -> Self

Sets the default icon that is used to display folders.

pub fn device_icon(self, icon: &str) -> Self

Sets the icon that is used to display devices in the left panel.

pub fn removable_device_icon(self, icon: &str) -> Self

Sets the icon that is used to display removable devices in the left panel.

pub fn add_file_filter( self, name: &str, filter: Arc<dyn Fn(&Path) -> bool + Send + Sync>, ) -> Self

Adds a new file filter the user can select from a dropdown widget.

NOTE: The name must be unique. If a filter with the same name already exists, it will be overwritten.

Arguments

• name - Display name of the filter
• filter - Sets a filter function that checks whether a given Path matches the criteria for this filter.

Examples

use std::sync::Arc;
use egui_file_dialog::FileDialog;

FileDialog::new()
    .add_file_filter(
        "PNG files",
        Arc::new(|path| path.extension().unwrap_or_default() == "png"))
    .add_file_filter(
        "JPG files",
        Arc::new(|path| path.extension().unwrap_or_default() == "jpg"));

pub fn add_file_filter_extensions( self, name: &str, extensions: Vec<&'static str>, ) -> Self

Shortctut method to add a file filter that matches specific extensions.

Arguments

• name - Display name of the filter
• extensions - The extensions of the files to be filtered

Examples

use egui_file_dialog::FileDialog;

FileDialog::new()
    .add_file_filter_extensions("Pictures", vec!["png", "jpg", "dds"])
    .add_file_filter_extensions("Rust files", vec!["rs", "toml", "lock"]);

pub fn default_file_filter(self, name: &str) -> Self

Name of the file filter to be selected by default.

No file filter is selected if there is no file filter with that name.

pub fn add_save_extension(self, name: &str, file_extension: &str) -> Self

Adds a new file extension that the user can select in a dropdown widget when saving a file.

NOTE: The name must be unique. If an extension with the same name already exists, it will be overwritten.

Arguments

• name - Display name of the save extension.
• file_extension - The file extension to use.

Examples

use std::sync::Arc;
use egui_file_dialog::FileDialog;

let config = FileDialog::default()
    .add_save_extension("PNG files", "png")
    .add_save_extension("JPG files", "jpg");

pub fn default_save_extension(self, name: &str) -> Self

Name of the file extension to be selected by default when saving a file.

No file extension is selected if there is no extension with that name.

pub fn set_file_icon( self, icon: &str, filter: Arc<dyn Fn(&Path) -> bool + Send + Sync>, ) -> Self

Sets a new icon for specific files or folders.

Arguments

• icon - The icon that should be used.
• filter - Sets a filter function that checks whether a given Path matches the criteria for this icon.

Examples

use std::sync::Arc;
use egui_file_dialog::FileDialog;

FileDialog::new()
    // .png files should use the "document with picture (U+1F5BB)" icon.
    .set_file_icon("🖻", Arc::new(|path| path.extension().unwrap_or_default() == "png"))
    // .git directories should use the "web-github (U+E624)" icon.
    .set_file_icon("", Arc::new(|path| path.file_name().unwrap_or_default() == ".git"));

pub fn add_quick_access( self, heading: &str, builder: impl FnOnce(&mut QuickAccess), ) -> Self

Adds a new custom quick access section to the left panel.

Examples

use egui_file_dialog::FileDialog;

FileDialog::new()
    .add_quick_access("My App", |s| {
        s.add_path("Config", "/app/config");
        s.add_path("Themes", "/app/themes");
        s.add_path("Languages", "/app/languages");
    });

pub fn title(self, title: &str) -> Self

Overwrites the window title.

By default, the title is set dynamically, based on the DialogMode the dialog is currently in.

pub fn id(self, id: impl Into<Id>) -> Self

Sets the ID of the window.

pub fn default_pos(self, default_pos: impl Into<Pos2>) -> Self

Sets the default position of the window.

pub fn fixed_pos(self, pos: impl Into<Pos2>) -> Self

Sets the window position and prevents it from being dragged around.

pub fn default_size(self, size: impl Into<Vec2>) -> Self

Sets the default size of the window.

pub fn max_size(self, max_size: impl Into<Vec2>) -> Self

Sets the maximum size of the window.

pub fn min_size(self, min_size: impl Into<Vec2>) -> Self

Sets the minimum size of the window.

Specifying a smaller minimum size than the default can lead to unexpected behavior.

pub fn anchor(self, align: Align2, offset: impl Into<Vec2>) -> Self

Sets the anchor of the window.

pub const fn resizable(self, resizable: bool) -> Self

Sets if the window is resizable.

pub const fn movable(self, movable: bool) -> Self

Sets if the window is movable.

Has no effect if an anchor is set.

pub const fn title_bar(self, title_bar: bool) -> Self

Sets if the title bar of the window is shown.

pub const fn show_top_panel(self, show_top_panel: bool) -> Self

Sets if the top panel with the navigation buttons, current path display and search input should be visible.

pub const fn show_parent_button(self, show_parent_button: bool) -> Self

Sets whether the parent folder button should be visible in the top panel.

Has no effect when FileDialog::show_top_panel is disabled.

pub const fn show_back_button(self, show_back_button: bool) -> Self

Sets whether the back button should be visible in the top panel.

Has no effect when FileDialog::show_top_panel is disabled.

pub const fn show_forward_button(self, show_forward_button: bool) -> Self

Sets whether the forward button should be visible in the top panel.

Has no effect when FileDialog::show_top_panel is disabled.

pub const fn show_new_folder_button(self, show_new_folder_button: bool) -> Self

Sets whether the button to create a new folder should be visible in the top panel.

Has no effect when FileDialog::show_top_panel is disabled.

pub const fn show_current_path(self, show_current_path: bool) -> Self

Sets whether the current path should be visible in the top panel.

Has no effect when FileDialog::show_top_panel is disabled.

pub const fn show_path_edit_button(self, show_path_edit_button: bool) -> Self

Sets whether the button to text edit the current path should be visible in the top panel.

has no effect when FileDialog::show_top_panel is disabled.

pub const fn show_menu_button(self, show_menu_button: bool) -> Self

Sets whether the menu with the reload button and other options should be visible inside the top panel.

Has no effect when FileDialog::show_top_panel is disabled.

pub const fn show_reload_button(self, show_reload_button: bool) -> Self

Sets whether the reload button inside the top panel menu should be visible.

Has no effect when FileDialog::show_top_panel or FileDialog::show_menu_button is disabled.

pub const fn show_working_directory_button( self, show_working_directory_button: bool, ) -> Self

Sets if the “Open working directory” button should be visible in the hamburger menu. The working directory button opens to the currently returned working directory from std::env::current_dir().

Has no effect when FileDialog::show_top_panel or FileDialog::show_menu_button is disabled.

pub const fn show_hidden_option(self, show_hidden_option: bool) -> Self

Sets whether the show hidden files and folders option inside the top panel menu should be visible.

Has no effect when FileDialog::show_top_panel or FileDialog::show_menu_button is disabled.

pub const fn show_system_files_option( self, show_system_files_option: bool, ) -> Self

Sets whether the show system files option inside the top panel menu should be visible.

Has no effect when FileDialog::show_top_panel or FileDialog::show_menu_button is disabled.

pub const fn show_search(self, show_search: bool) -> Self

Sets whether the search input should be visible in the top panel.

Has no effect when FileDialog::show_top_panel is disabled.

pub const fn show_left_panel(self, show_left_panel: bool) -> Self

Sets if the sidebar with the shortcut directories such as “Home”, “Documents” etc. should be visible.

pub const fn show_pinned_folders(self, show_pinned_folders: bool) -> Self

Sets if pinned folders should be listed in the left sidebar. Disabling this will also disable the functionality to pin a folder.

pub const fn show_places(self, show_places: bool) -> Self

Sets if the “Places” section should be visible in the left sidebar. The Places section contains the user directories such as Home or Documents.

Has no effect when FileDialog::show_left_panel is disabled.

pub const fn show_devices(self, show_devices: bool) -> Self

Sets if the “Devices” section should be visible in the left sidebar. The Devices section contains the non removable system disks.

Has no effect when FileDialog::show_left_panel is disabled.

pub const fn show_removable_devices(self, show_removable_devices: bool) -> Self

Sets if the “Removable Devices” section should be visible in the left sidebar. The Removable Devices section contains the removable disks like USB disks.

Has no effect when FileDialog::show_left_panel is disabled.

pub fn picked(&self) -> Option<&Path>

Returns the directory or file that the user picked, or the target file if the dialog is in DialogMode::SaveFile mode.

None is returned when the user has not yet selected an item.

pub fn take_picked(&mut self) -> Option<PathBuf>

Returns the directory or file that the user picked, or the target file if the dialog is in DialogMode::SaveFile mode. Unlike FileDialog::picked, this method returns the picked path only once and sets the dialog’s state to DialogState::Closed.

None is returned when the user has not yet picked an item.

pub fn picked_multiple(&self) -> Option<Vec<&Path>>

Returns a list of the files and folders the user picked, when the dialog is in DialogMode::PickMultiple mode.

None is returned when the user has not yet picked an item.

pub fn take_picked_multiple(&mut self) -> Option<Vec<PathBuf>>

Returns a list of the files and folders the user picked, when the dialog is in DialogMode::PickMultiple mode. Unlike FileDialog::picked_multiple, this method returns the picked paths only once and sets the dialog’s state to DialogState::Closed.

None is returned when the user has not yet picked an item.

pub const fn selected_entry(&self) -> Option<&DirectoryEntry>

Returns the currently active directory entry.

This is either the currently highlighted entry, or the currently active directory if nothing is being highlighted.

For the [DialogMode::SelectMultiple] counterpart, see [FileDialog::active_selected_entries].

pub fn selected_entries(&self) -> impl Iterator<Item = &DirectoryEntry>

Returns an iterator over the currently selected entries in SelectMultiple mode.

For the counterpart in single selection modes, see [FileDialog::active_entry].

pub fn operation_id(&self) -> Option<&str>

Returns the ID of the operation for which the dialog is currently being used.

See FileDialog::open for more information.

pub fn set_operation_id(&mut self, operation_id: &str)

Sets the ID of the operation for which the dialog is currently being used.

See FileDialog::open for more information.

pub const fn mode(&self) -> DialogMode

Returns the mode the dialog is currently in.

pub fn state(&self) -> DialogState

Returns the state the dialog is currently in.

pub const fn get_window_id(&self) -> Id

Get the window Id

Trait Implementations

impl Debug for FileDialog

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for FileDialog

fn default() -> Self

Creates a new file dialog instance with default values.