Struct egui_file_dialog::FileDialog

source ·

pub struct FileDialog { /* private fields */ }

Expand description

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§

source §

impl FileDialog

source

pub fn new() -> Self

Creates a new file dialog instance with default values.

source

pub fn with_config(config: FileDialogConfig) -> Self

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

source

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

source

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.

source

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.

source

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.

source

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.

source

pub fn overwrite_config(self, config: FileDialogConfig) -> Self

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"),
        }
    }
}

source

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

Mutably borrow internal config.

source

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.

source

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

Mutably borrow internal config.labels.

source

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.

source

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

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

source

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.

source

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.

source

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

Sets the icon that is used to display errors.

source

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

Sets the default icon that is used to display files.

source

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

Sets the default icon that is used to display folders.

source

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

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

source

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

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

source

pub fn set_file_icon( self, icon: &str, filter: Arc<dyn Fn(&Path) -> bool> ) -> 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"));

source

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");
    });

source

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.

source

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

Sets the ID of the window.

source

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

Sets the default position of the window.

source

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

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

source

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

Sets the default size of the window.

source

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

Sets the maximum size of the window.

source

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.

source

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

Sets the anchor of the window.

source

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

Sets if the window is resizable.

source

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

Sets if the window is movable.

Has no effect if an anchor is set.

source

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

Sets if the title bar of the window is shown.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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

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

Has no effect when FileDialog::show_top_panel is disabled.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source