Struct egui_file_dialog::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("Select a file").clicked() {
            self.file_dialog.select_file();
        }

        if let Some(path) = self.file_dialog.update(ctx).selected() {
            println!("Selected 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 open( &mut self, mode: DialogMode, show_files: bool, operation_id: Option<&str>, ) -> Result<()>

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,

    selected_file_a: Option<PathBuf>,
    selected_file_b: Option<PathBuf>,
}

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

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

        self.file_dialog.update(ctx);

        if let Some(path) = self.file_dialog.selected() {
            if self.file_dialog.operation_id() == Some("select_a") {
                self.selected_file_a = Some(path.to_path_buf());
            }
            if self.file_dialog.operation_id() == Some("select_b") {
                self.selected_file_b = Some(path.to_path_buf());
            }
        }
    }
}

pub fn select_directory(&mut self)

Shortcut function to open the file dialog to prompt the user to select 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 select_file(&mut self)

Shortcut function to open the file dialog to prompt the user to select 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 select_multiple(&mut self)

Shortcut function to open the file dialog to prompt the user to select 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 overwrite_config(self, config: FileDialogConfig) -> Self

👎Deprecated since 0.6.0: use FileDialog::with_config and FileDialog::config_mut instead

Overwrites the configuration of the file dialog.

This is useful when you want to configure multiple FileDialog objects with the same configuration. If you only want to configure a single object, it’s probably easier to use the setter methods like FileDialog::initial_directory or FileDialog::default_pos.

If you want to create a new FileDialog object with a config, you probably want to use FileDialog::with_config.

NOTE: Any configuration that was set before FileDialog::overwrite_config will be overwritten!
This means, for example, that the following code is invalid:

pub use egui_file_dialog::{FileDialog, FileDialogConfig};

fn create_file_dialog() -> FileDialog {
    FileDialog::new()
       .title("Hello world")
        // This will overwrite `.title("Hello world")`!
       .overwrite_config(FileDialogConfig::default())
}

Examples

use egui_file_dialog::{FileDialog, FileDialogConfig};

struct MyApp {
    file_dialog_a: FileDialog,
    file_dialog_b: FileDialog,
}

impl MyApp {
    pub fn new() -> Self {
        let config = FileDialogConfig {
            default_size: egui::Vec2::new(500.0, 500.0),
            resizable: false,
            movable: false,
            ..Default::default()
        };

        Self {
            file_dialog_a: FileDialog::new()
                .overwrite_config(config.clone())
                .title("File Dialog A")
                .id("fd_a"),

            file_dialog_b: FileDialog::new()
                .overwrite_config(config)
                .title("File Dialog B")
                .id("fd_b"),
        }
    }
}

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 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 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 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 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 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 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 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 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 fn resizable(self, resizable: bool) -> Self

Sets if the window is resizable.

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

Sets if the window is movable.

Has no effect if an anchor is set.

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

Sets if the title bar of the window is shown.

pub 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 selected(&self) -> Option<&Path>

Returns the directory or file that the user selected, 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_selected(&mut self) -> Option<PathBuf>

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

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

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

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

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

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

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

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

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 mode(&self) -> DialogMode

Returns the mode the dialog is currently in.

pub fn state(&self) -> DialogState

Returns the state the dialog is currently in.

Trait Implementations

impl Default for FileDialog

fn default() -> Self

Creates a new file dialog instance with default values.