Add customization examples

CHANGELOG.md

@@ -35,6 +35,7 @@
 ### 📚 Documentation
 - Added downloads and total lines badge to `README.md` [#71](https://github.com/fluxxcode/egui-file-dialog/pull/71)
 - Updated project description, features and planned features in `README.md` [#78](https://github.com/fluxxcode/egui-file-dialog/pull/78)
+- Added customization example to `README.md` and `lib.rs` [#83](https://github.com/fluxxcode/egui-file-dialog/pull/83)
 - Added multilingual example to `README.md`, `lib.rs` and an interactive example in `examples/` [#81](https://github.com/fluxxcode/egui-file-dialog/pull/81)
 
 ## 2024-02-20 - v0.3.1 - Bug fixes

README.md

@@ -25,10 +25,11 @@ The latest changes included in the next release can be found in the [CHANGELOG.m
 - Navigation buttons to open the parent or previous directories
 - Search for items in a directory
 - Shortcut for user directories (Home, Documents, ...) and system disks
-- Customization:
+- Customization highlights:
   - Customize which areas and functions of the dialog are visible
   - Multilingual support: Customize the text labels that the dialog uses
   - Customize file and folder icons
+  - _More options can be found in the documentation on [docs.rs](https://docs.rs/egui-file-dialog/latest/egui_file_dialog/index.html)_
 
 ## Planned features
 The following lists some of the features that are currently missing but are planned for the future!
@@ -100,6 +101,65 @@ fn main() -> eframe::Result<()> {
 }
 ```
 
+## Customization
+Many things can be customized so that the dialog can be used in different situations. \
+A few highlights of the customization are listed below. For all possible customization options, see the documentation on [docs.rs](https://docs.rs/egui-file-dialog/latest/egui_file_dialog/struct.FileDialog.html). (More customization will be implemented in the future!)
+
+- Set which areas and functions of the dialog are visible using `FileDialog::show_*` methods
+- Update the text labels that the dialog uses. See [Multilingual support](#multilingual-support)
+- Customize file and folder icons using `FileDialog::set_file_icon` (Currently only unicode is supported)
+
+Since the dialog uses the egui style to look like the rest of the application, the appearance can be customized with `egui::Style`.
+
+The following example shows how a file dialog can be customized. If you need to configure multiple file dialog objects with the same or almost the same options, it is a good idea to use `FileDialogConfig` and `FileDialog::with_config` (See `FileDialogConfig` on [docs.rs](https://docs.rs/egui-file-dialog/latest/egui_file_dialog/struct.FileDialogConfig.html)).
+```rust
+use std::path::PathBuf;
+use std::sync::Arc;
+
+use egui_file_dialog::FileDialog;
+
+FileDialog::new()
+    .initial_directory(PathBuf::from("/path/to/app"))
+    .default_file_name("app.cfg")
+    .default_size([600.0, 400.0])
+    .resizable(false)
+    .show_new_folder_button(false)
+    .show_search(false)
+    // Markdown and text files should use the "document with text (U+1F5B9)" icon
+    .set_file_icon(
+        "🖹",
+        Arc::new(|path| {
+            match path
+                .extension()
+                .unwrap_or_default()
+                .to_str()
+                .unwrap_or_default()
+            {
+                "md" => true,
+                "txt" => true,
+                _ => false,
+            }
+        }),
+    )
+    // .gitignore files should use the "web-github (U+E624)" icon
+    .set_file_icon(
+        "",
+        Arc::new(|path| path.file_name().unwrap_or_default() == ".gitignore"),
+    );
+```
+With the options the dialog then looks like this:
+<img src="media/customization_demo.png">
+
+The smallest possible dialog can be generated with the following configuration:
+
+```rust
+FileDialog::new()
+    .title_bar(false)
+    .show_top_panel(false)
+    .show_left_panel(false)
+```
+<img src="media/customization_demo_2.png">
+
 ## Multilingual support
 For desktop applications it is often necessary to offer different languages. While the dialog currently only offers English labels by default, the labels are fully customizable. This makes it possible to adapt the labels to different languages.
 
@@ -114,7 +174,7 @@ enum Language {
     German,
 }
 
-fn get_german_labels() -> FileDialogLabels {
+fn get_labels_german() -> FileDialogLabels {
     FileDialogLabels {
         title_select_directory: "📁 Ordner Öffnen".to_string(),
         title_select_file: "📂 Datei Öffnen".to_string(),
@@ -133,7 +193,7 @@ fn update_labels(language: &Language, file_dialog: &mut FileDialog) {
         // English labels are used by default
         Language::English => FileDialogLabels::default(),
         // Use custom labels for German
-        Language::German => get_german_labels(),
+        Language::German => get_labels_german(),
     };
 }
 ```

examples/multilingual/src/main.rs

@@ -9,7 +9,7 @@ enum Language {
     German,
 }
 
-fn gen_german_labels() -> FileDialogLabels {
+fn get_labels_german() -> FileDialogLabels {
     FileDialogLabels {
         title_select_directory: "📁 Ordner Öffnen".to_string(),
         title_select_file: "📂 Datei Öffnen".to_string(),
@@ -64,7 +64,7 @@ impl MyApp {
     fn update_labels(&mut self) {
         *self.file_dialog.labels_mut() = match self.language {
             Language::English => FileDialogLabels::default(),
-            Language::German => gen_german_labels(),
+            Language::German => get_labels_german(),
         };
     }
 }

src/lib.rs

@@ -17,7 +17,7 @@
 //! - Navigation buttons to open the parent or previous directories
 //! - Search for items in a directory
 //! - Shortcut for user directories (Home, Documents, ...) and system disks
-//! - Customization:
+//! - Customization highlights:
 //!   - Customize which areas and functions of the dialog are visible
 //!   - Multilingual support: Customize the text labels that the dialog uses
 //!   - Customize file and folder icons
@@ -59,6 +59,60 @@
 //! }
 //! ```
 //!
+//! ### Customization
+//!
+//! Many things can be customized so that the dialog can be used in different situations. \
+//! A few highlights of the customization are listed below.
+//! (More customization will be implemented in the future!)
+//!
+//! - Set which areas and functions of the dialog are visible using `FileDialog::show_*` methods
+//! - Update the text labels that the dialog uses. See [Multilingual support](#multilingual-support)
+//! - Customize file and folder icons using `FileDialog::set_file_icon`
+//!   (Currently only unicode is supported)
+//!
+//! Since the dialog uses the egui style to look like the rest of the application,
+//! the appearance can be customized with `egui::Style`.
+//!
+//! The following example shows how a file dialog can be customized. If you need to
+//! configure multiple file dialog objects with the same or almost the same options,
+//! it is a good idea to use `FileDialogConfig` and `FileDialog::with_config`
+//!
+//! ```
+//! use std::path::PathBuf;
+//! use std::sync::Arc;
+//!
+//! use egui_file_dialog::FileDialog;
+//!
+//! FileDialog::new()
+//!     .initial_directory(PathBuf::from("/path/to/app"))
+//!     .default_file_name("app.cfg")
+//!     .default_size([600.0, 400.0])
+//!     .resizable(false)
+//!     .show_new_folder_button(false)
+//!     .show_search(false)
+//!     // Markdown and text files should use the "document with text (U+1F5B9)" icon
+//!     .set_file_icon(
+//!         "🖹",
+//!         Arc::new(|path| {
+//!             match path
+//!                 .extension()
+//!                 .unwrap_or_default()
+//!                 .to_str()
+//!                 .unwrap_or_default()
+//!             {
+//!                 "md" => true,
+//!                 "txt" => true,
+//!                 _ => false,
+//!             }
+//!         }),
+//!     )
+//!     // .gitignore files should use the "web-github (U+E624)" icon
+//!     .set_file_icon(
+//!         "",
+//!         Arc::new(|path| path.file_name().unwrap_or_default() == ".gitignore"),
+//!     );
+//! ```
+//!
 //! ### Multilingual support
 //! For desktop applications it is often necessary to offer different languages.
 //! While the dialog currently only offers English labels by default, the labels are
@@ -75,7 +129,7 @@
 //!     German,
 //! }
 //!
-//! fn get_german_labels() -> FileDialogLabels {
+//! fn get_labels_german() -> FileDialogLabels {
 //!     FileDialogLabels {
 //!         title_select_directory: "📁 Ordner Öffnen".to_string(),
 //!         title_select_file: "📂 Datei Öffnen".to_string(),
@@ -94,7 +148,7 @@
 //!         // English labels are used by default
 //!         Language::English => FileDialogLabels::default(),
 //!         // Use custom labels for German
-//!         Language::German => get_german_labels(),
+//!         Language::German => get_labels_german(),
 //!     };
 //! }
 //! ```