diff --git a/CHANGELOG.md b/CHANGELOG.md index 65ac1302..84d6c78b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,9 @@ - Added the ability to drag and drop files and folders to open their respective path [#192](https://github.com/fluxxcode/egui-file-dialog/pull/192) (thanks [@hacknus](https://github.com/hacknus)!) - Support network drives on MacOS [#194](https://github.com/fluxxcode/egui-file-dialog/pull/194) (thanks [@hacknus](https://github.com/hacknus)!) +### ☢️ Deprecated +- Deprecated all `select_*` methods and added new equivalent `pick_*` methods [207](https://github.com/fluxxcode/egui-file-dialog/pull/207) + ### 🐛 Bug Fixes - Fixed heading `Places` not being able to be updated with `FileDialogLabels` [#180](https://github.com/fluxxcode/egui-file-dialog/pull/180) - Fix display errors with path prefix on Windows [#182](https://github.com/fluxxcode/egui-file-dialog/pull/182) diff --git a/examples/custom-right-panel/src/main.rs b/examples/custom-right-panel/src/main.rs index 6293f947..b041b801 100644 --- a/examples/custom-right-panel/src/main.rs +++ b/examples/custom-right-panel/src/main.rs @@ -5,14 +5,14 @@ use egui_file_dialog::{DialogMode, FileDialog}; struct MyApp { file_dialog: FileDialog, - selected_items: Option>, + picked_items: Option>, } impl MyApp { pub fn new(_cc: &eframe::CreationContext) -> Self { Self { file_dialog: FileDialog::new(), - selected_items: None, + picked_items: None, } } } @@ -20,16 +20,16 @@ impl MyApp { impl eframe::App for MyApp { fn update(&mut self, ctx: &egui::Context, _frame: &mut eframe::Frame) { egui::CentralPanel::default().show(ctx, |ui| { - if ui.button("Select single").clicked() { - self.file_dialog.select_file(); + if ui.button("Pick single").clicked() { + self.file_dialog.pick_file(); } - if ui.button("Select multiple").clicked() { - self.file_dialog.select_multiple(); + if ui.button("Pick multiple").clicked() { + self.file_dialog.pick_multiple(); } - ui.label("Selected items:"); + ui.label("Picked items:"); - if let Some(items) = &self.selected_items { + if let Some(items) = &self.picked_items { for item in items { ui.label(format!("{:?}", item)); } @@ -59,13 +59,13 @@ impl eframe::App for MyApp { match self.file_dialog.mode() { DialogMode::SelectMultiple => { - if let Some(items) = self.file_dialog.take_selected_multiple() { - self.selected_items = Some(items); + if let Some(items) = self.file_dialog.take_picked_multiple() { + self.picked_items = Some(items); } } _ => { - if let Some(item) = self.file_dialog.take_selected() { - self.selected_items = Some(vec![item]); + if let Some(item) = self.file_dialog.take_picked() { + self.picked_items = Some(vec![item]); } } } diff --git a/examples/multi_selection/src/main.rs b/examples/multi_selection/src/main.rs index a4ffa199..ba13be33 100644 --- a/examples/multi_selection/src/main.rs +++ b/examples/multi_selection/src/main.rs @@ -5,14 +5,14 @@ use egui_file_dialog::FileDialog; struct MyApp { file_dialog: FileDialog, - selected_items: Option>, + picked_items: Option>, } impl MyApp { pub fn new(_cc: &eframe::CreationContext) -> Self { Self { file_dialog: FileDialog::new(), - selected_items: None, + picked_items: None, } } } @@ -20,13 +20,13 @@ impl MyApp { impl eframe::App for MyApp { fn update(&mut self, ctx: &egui::Context, _frame: &mut eframe::Frame) { egui::CentralPanel::default().show(ctx, |ui| { - if ui.button("Select multiple").clicked() { - self.file_dialog.select_multiple(); + if ui.button("Pick multiple").clicked() { + self.file_dialog.pick_multiple(); } - ui.label("Selected items:"); + ui.label("Picked items:"); - if let Some(items) = &self.selected_items { + if let Some(items) = &self.picked_items { for item in items { ui.label(format!("{:?}", item)); } @@ -36,8 +36,8 @@ impl eframe::App for MyApp { self.file_dialog.update(ctx); - if let Some(items) = self.file_dialog.take_selected_multiple() { - self.selected_items = Some(items); + if let Some(items) = self.file_dialog.take_picked_multiple() { + self.picked_items = Some(items); } }); } diff --git a/examples/multilingual/src/main.rs b/examples/multilingual/src/main.rs index debb0665..5d961a9a 100644 --- a/examples/multilingual/src/main.rs +++ b/examples/multilingual/src/main.rs @@ -62,7 +62,7 @@ struct MyApp { file_dialog: FileDialog, language: Language, - selected_file: Option, + picked_file: Option, } impl MyApp { @@ -71,7 +71,7 @@ impl MyApp { file_dialog: FileDialog::new().id("egui_file_dialog"), language: Language::English, - selected_file: None, + picked_file: None, } } @@ -99,15 +99,15 @@ impl eframe::App for MyApp { self.update_labels(); } - if ui.button("Select file").clicked() { - self.file_dialog.select_file(); + if ui.button("Picked file").clicked() { + self.file_dialog.pick_file(); } - ui.label(format!("Selected file: {:?}", self.selected_file)); + ui.label(format!("Picked file: {:?}", self.picked_file)); self.file_dialog.update(ctx); - if let Some(path) = self.file_dialog.take_selected() { - self.selected_file = Some(path); + if let Some(path) = self.file_dialog.take_picked() { + self.picked_file = Some(path); } }); } diff --git a/examples/multiple_actions/src/main.rs b/examples/multiple_actions/src/main.rs index a6dca507..c8c44331 100644 --- a/examples/multiple_actions/src/main.rs +++ b/examples/multiple_actions/src/main.rs @@ -6,8 +6,8 @@ use egui_file_dialog::{DialogMode, FileDialog}; struct MyApp { file_dialog: FileDialog, - selected_file_a: Option, - selected_file_b: Option, + picked_file_a: Option, + picked_file_b: Option, } impl MyApp { @@ -15,8 +15,8 @@ impl MyApp { Self { file_dialog: FileDialog::new().id("egui_file_dialog"), - selected_file_a: None, - selected_file_b: None, + picked_file_a: None, + picked_file_b: None, } } } @@ -24,30 +24,30 @@ impl MyApp { impl eframe::App for MyApp { fn update(&mut self, ctx: &egui::Context, _frame: &mut eframe::Frame) { egui::CentralPanel::default().show(ctx, |ui| { - if ui.button("Select file a").clicked() { + if ui.button("Pick file a").clicked() { let _ = self .file_dialog - .open(DialogMode::SelectFile, true, Some("select_a")); + .open(DialogMode::SelectFile, true, Some("pick_a")); } - if ui.button("Select file b").clicked() { + if ui.button("Pick file b").clicked() { let _ = self .file_dialog - .open(DialogMode::SelectFile, true, Some("select_b")); + .open(DialogMode::SelectFile, true, Some("pick_b")); } - ui.label(format!("Selected file a: {:?}", self.selected_file_a)); - ui.label(format!("Selected file b: {:?}", self.selected_file_b)); + ui.label(format!("Pick file a: {:?}", self.picked_file_a)); + ui.label(format!("Pick file b: {:?}", self.picked_file_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 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("select_b") { - self.selected_file_b = Some(path.to_path_buf()); + if self.file_dialog.operation_id() == Some("pick_b") { + self.picked_file_b = Some(path.to_path_buf()); } } }); diff --git a/examples/persistence/src/main.rs b/examples/persistence/src/main.rs index 3d180711..92fedbd8 100644 --- a/examples/persistence/src/main.rs +++ b/examples/persistence/src/main.rs @@ -5,7 +5,7 @@ use egui_file_dialog::FileDialog; struct MyApp { file_dialog: FileDialog, - selected_file: Option, + picked_file: Option, } impl MyApp { @@ -21,7 +21,7 @@ impl MyApp { Self { file_dialog, - selected_file: None, + picked_file: None, } } } @@ -38,16 +38,16 @@ impl eframe::App for MyApp { fn update(&mut self, ctx: &egui::Context, _frame: &mut eframe::Frame) { egui::CentralPanel::default().show(ctx, |ui| { - if ui.button("Select file").clicked() { - self.file_dialog.select_file(); + if ui.button("Pick file").clicked() { + self.file_dialog.pick_file(); } - ui.label(format!("Selected file: {:?}", self.selected_file)); + ui.label(format!("Picked file: {:?}", self.picked_file)); self.file_dialog.update(ctx); - if let Some(path) = self.file_dialog.take_selected() { - self.selected_file = Some(path); + if let Some(path) = self.file_dialog.take_picked() { + self.picked_file = Some(path); } }); } diff --git a/examples/select_directory/Cargo.toml b/examples/pick_directory/Cargo.toml similarity index 89% rename from examples/select_directory/Cargo.toml rename to examples/pick_directory/Cargo.toml index 6114747c..1c6ebd0d 100644 --- a/examples/select_directory/Cargo.toml +++ b/examples/pick_directory/Cargo.toml @@ -1,5 +1,5 @@ [package] -name = "select_directory" +name = "pick_directory" version = "0.1.0" edition = "2021" diff --git a/examples/select_directory/README.md b/examples/pick_directory/README.md similarity index 100% rename from examples/select_directory/README.md rename to examples/pick_directory/README.md diff --git a/examples/select_directory/screenshot.png b/examples/pick_directory/screenshot.png similarity index 100% rename from examples/select_directory/screenshot.png rename to examples/pick_directory/screenshot.png diff --git a/examples/select_directory/src/main.rs b/examples/pick_directory/src/main.rs similarity index 61% rename from examples/select_directory/src/main.rs rename to examples/pick_directory/src/main.rs index 1276f061..18ac2c9a 100644 --- a/examples/select_directory/src/main.rs +++ b/examples/pick_directory/src/main.rs @@ -5,14 +5,14 @@ use egui_file_dialog::FileDialog; struct MyApp { file_dialog: FileDialog, - selected_directory: Option, + picked_directory: Option, } impl MyApp { pub fn new(_cc: &eframe::CreationContext) -> Self { Self { file_dialog: FileDialog::new(), - selected_directory: None, + picked_directory: None, } } } @@ -20,14 +20,14 @@ impl MyApp { impl eframe::App for MyApp { fn update(&mut self, ctx: &egui::Context, _frame: &mut eframe::Frame) { egui::CentralPanel::default().show(ctx, |ui| { - if ui.button("Select directory").clicked() { - self.file_dialog.select_directory(); + if ui.button("Pick directory").clicked() { + self.file_dialog.pick_directory(); } - ui.label(format!("Selected directory: {:?}", self.selected_directory)); + ui.label(format!("Picked directory: {:?}", self.picked_directory)); - if let Some(path) = self.file_dialog.update(ctx).selected() { - self.selected_directory = Some(path.to_path_buf()); + if let Some(path) = self.file_dialog.update(ctx).picked() { + self.picked_directory = Some(path.to_path_buf()); } }); } diff --git a/examples/select_file/Cargo.toml b/examples/pick_file/Cargo.toml similarity index 91% rename from examples/select_file/Cargo.toml rename to examples/pick_file/Cargo.toml index 62583583..9aa2a6f8 100644 --- a/examples/select_file/Cargo.toml +++ b/examples/pick_file/Cargo.toml @@ -1,5 +1,5 @@ [package] -name = "select_file" +name = "pick_file" version = "0.1.0" edition = "2021" diff --git a/examples/select_file/README.md b/examples/pick_file/README.md similarity index 100% rename from examples/select_file/README.md rename to examples/pick_file/README.md diff --git a/examples/select_file/screenshot.png b/examples/pick_file/screenshot.png similarity index 100% rename from examples/select_file/screenshot.png rename to examples/pick_file/screenshot.png diff --git a/examples/select_file/src/main.rs b/examples/pick_file/src/main.rs similarity index 64% rename from examples/select_file/src/main.rs rename to examples/pick_file/src/main.rs index b8d62ec3..0ffb6ccc 100644 --- a/examples/select_file/src/main.rs +++ b/examples/pick_file/src/main.rs @@ -5,14 +5,14 @@ use egui_file_dialog::FileDialog; struct MyApp { file_dialog: FileDialog, - selected_file: Option, + picked_file: Option, } impl MyApp { pub fn new(_cc: &eframe::CreationContext) -> Self { Self { file_dialog: FileDialog::new(), - selected_file: None, + picked_file: None, } } } @@ -20,14 +20,14 @@ impl MyApp { impl eframe::App for MyApp { fn update(&mut self, ctx: &egui::Context, _frame: &mut eframe::Frame) { egui::CentralPanel::default().show(ctx, |ui| { - if ui.button("Select file").clicked() { - self.file_dialog.select_file(); + if ui.button("Picked file").clicked() { + self.file_dialog.pick_file(); } - ui.label(format!("Selected file: {:?}", self.selected_file)); + ui.label(format!("Picked file: {:?}", self.picked_file)); - if let Some(path) = self.file_dialog.update(ctx).selected() { - self.selected_file = Some(path.to_path_buf()); + if let Some(path) = self.file_dialog.update(ctx).picked() { + self.picked_file = Some(path.to_path_buf()); } }); } diff --git a/examples/sandbox/src/main.rs b/examples/sandbox/src/main.rs index f48dbeb0..ac18e77e 100644 --- a/examples/sandbox/src/main.rs +++ b/examples/sandbox/src/main.rs @@ -6,9 +6,9 @@ use egui_file_dialog::{DialogMode, FileDialog}; struct MyApp { file_dialog: FileDialog, - selected_directory: Option, - selected_file: Option, - selected_multiple: Option>, + picked_directory: Option, + picked_file: Option, + picked_multiple: Option>, saved_file: Option, } @@ -42,9 +42,9 @@ impl MyApp { Self { file_dialog, - selected_directory: None, - selected_file: None, - selected_multiple: None, + picked_directory: None, + picked_file: None, + picked_multiple: None, saved_file: None, } } @@ -66,24 +66,24 @@ impl eframe::App for MyApp { ui.add_space(5.0); - if ui.button("Select directory").clicked() { - self.file_dialog.select_directory(); + if ui.button("Pick directory").clicked() { + self.file_dialog.pick_directory(); } - ui.label(format!("Selected directory: {:?}", self.selected_directory)); + ui.label(format!("Picked directory: {:?}", self.picked_directory)); ui.add_space(5.0); - if ui.button("Select file").clicked() { - self.file_dialog.select_file(); + if ui.button("Pick file").clicked() { + self.file_dialog.pick_file(); } - ui.label(format!("Selected file: {:?}", self.selected_file)); + ui.label(format!("Selected file: {:?}", self.picked_file)); - if ui.button("Select multiple").clicked() { - self.file_dialog.select_multiple(); + if ui.button("Pick multiple").clicked() { + self.file_dialog.pick_multiple(); } - ui.label("Selected multiple:"); + ui.label("Picked multiple:"); - if let Some(items) = &self.selected_multiple { + if let Some(items) = &self.picked_multiple { for item in items { ui.label(format!("{:?}", item)); } @@ -100,17 +100,17 @@ impl eframe::App for MyApp { self.file_dialog.update(ctx); - if let Some(path) = self.file_dialog.take_selected() { + if let Some(path) = self.file_dialog.take_picked() { match self.file_dialog.mode() { - DialogMode::SelectDirectory => self.selected_directory = Some(path), - DialogMode::SelectFile => self.selected_file = Some(path), + DialogMode::SelectDirectory => self.picked_directory = Some(path), + DialogMode::SelectFile => self.picked_file = Some(path), DialogMode::SaveFile => self.saved_file = Some(path), _ => {} } } - if let Some(items) = self.file_dialog.take_selected_multiple() { - self.selected_multiple = Some(items); + if let Some(items) = self.file_dialog.take_picked_multiple() { + self.picked_multiple = Some(items); } }); } diff --git a/examples/save_file/src/main.rs b/examples/save_file/src/main.rs index 6dff005d..674a0509 100644 --- a/examples/save_file/src/main.rs +++ b/examples/save_file/src/main.rs @@ -26,7 +26,7 @@ impl eframe::App for MyApp { ui.label(format!("File to save: {:?}", self.file_path)); - if let Some(path) = self.file_dialog.update(ctx).selected() { + if let Some(path) = self.file_dialog.update(ctx).picked() { self.file_path = Some(path.to_path_buf()); } }); diff --git a/src/file_dialog.rs b/src/file_dialog.rs index 451cf73a..7b0e82b1 100644 --- a/src/file_dialog.rs +++ b/src/file_dialog.rs @@ -344,6 +344,17 @@ impl FileDialog { Ok(()) } + /// 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_directory(&mut self) { + let _ = self.open(DialogMode::SelectDirectory, false, None); + } + /// 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. @@ -351,8 +362,22 @@ impl FileDialog { /// `initial_directory` are retained. /// /// The function ignores the result of the initial directory loading operation. + #[deprecated( + since = "0.8.0", + note = "renamed to `FileDialog::pick_directory` for more consistent naming. \ + Will be removed in a future release, most likely 0.9.0." + )] pub fn select_directory(&mut self) { - let _ = self.open(DialogMode::SelectDirectory, false, None); + self.pick_directory(); + } + + /// 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_file(&mut self) { + let _ = self.open(DialogMode::SelectFile, true, None); } /// Shortcut function to open the file dialog to prompt the user to select a file. @@ -360,8 +385,23 @@ impl FileDialog { /// `initial_directory` are retained. /// /// The function ignores the result of the initial directory loading operation. + #[deprecated( + since = "0.8.0", + note = "renamed to `FileDialog::pick_file` for more consistent naming. \ + Will be removed in a future release, most likely 0.9.0." + )] pub fn select_file(&mut self) { - let _ = self.open(DialogMode::SelectFile, true, None); + self.pick_file(); + } + + /// 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 pick_multiple(&mut self) { + let _ = self.open(DialogMode::SelectMultiple, true, None); } /// Shortcut function to open the file dialog to prompt the user to select multiple @@ -370,8 +410,13 @@ impl FileDialog { /// are retained. /// /// The function ignores the result of the initial directory loading operation. + #[deprecated( + since = "0.8.0", + note = "renamed to `FileDialog::pick_multiple` for more consistent naming. \ + Will be removed in a future release, most likely 0.9.0." + )] pub fn select_multiple(&mut self) { - let _ = self.open(DialogMode::SelectMultiple, true, None); + self.pick_multiple(); } /// Shortcut function to open the file dialog to prompt the user to save a file. @@ -973,11 +1018,11 @@ impl FileDialog { // ------------------------------------------------- // Getter: - /// Returns the directory or file that the user selected, or the target file + /// 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 selected(&self) -> Option<&Path> { + pub fn picked(&self) -> Option<&Path> { match &self.state { DialogState::Selected(path) => Some(path), _ => None, @@ -986,11 +1031,24 @@ impl FileDialog { /// 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 take_selected(&mut self) -> Option { + #[deprecated( + since = "0.8.0", + note = "renamed to `FileDialog::picked` for more consistent naming. \ + Will be removed in a future release, most likely 0.9.0." + )] + pub fn selected(&self) -> Option<&Path> { + self.picked() + } + + /// 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 take_picked(&mut self) -> Option { match &mut self.state { DialogState::Selected(path) => { let path = std::mem::take(path); @@ -1001,11 +1059,26 @@ impl FileDialog { } } - /// Returns a list of the files and folders the user selected, when the dialog is in - /// `DialogMode::SelectMultiple` mode. + /// 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> { + #[deprecated( + since = "0.8.0", + note = "renamed to `FileDialog::take_picked` for more consistent naming. \ + Will be removed in a future release, most likely 0.9.0." + )] + pub fn take_selected(&mut self) -> Option { + self.take_picked() + } + + /// 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 picked_multiple(&self) -> Option> { match &self.state { DialogState::SelectedMultiple(items) => { Some(items.iter().map(std::path::PathBuf::as_path).collect()) @@ -1016,11 +1089,24 @@ impl FileDialog { /// 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 take_selected_multiple(&mut self) -> Option> { + #[deprecated( + since = "0.8.0", + note = "renamed to `FileDialog::picked_multiple` for more consistent naming. \ + Will be removed in a future release, most likely 0.9.0." + )] + pub fn selected_multiple(&self) -> Option> { + self.picked_multiple() + } + + /// 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 fn take_picked_multiple(&mut self) -> Option> { match &mut self.state { DialogState::SelectedMultiple(items) => { let items = std::mem::take(items); @@ -1031,6 +1117,21 @@ impl FileDialog { } } + /// 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. + #[deprecated( + since = "0.8.0", + note = "renamed to `FileDialog::take_picked_multiple` for more consistent naming. \ + Will be removed in a future release, most likely 0.9.0." + )] + pub fn take_selected_multiple(&mut self) -> Option> { + self.take_picked_multiple() + } + /// Returns the currently active directory entry. /// /// This is either the currently highlighted entry, or the currently active directory