Skip to content

Commit

Permalink
chore: cleanup examples (#213)
Browse files Browse the repository at this point in the history
* rework examples

---------

Co-authored-by: Jannis <[email protected]>
  • Loading branch information
bircni and fluxxcode authored Dec 4, 2024
1 parent 7664483 commit 42f0210
Show file tree
Hide file tree
Showing 35 changed files with 135 additions and 185 deletions.
29 changes: 11 additions & 18 deletions Cargo.toml
Original file line number Diff line number Diff line change
@@ -1,13 +1,3 @@
[workspace]
members = ["examples/*"]

[workspace.dependencies]
eframe = { version = "0.29.1", default-features = false, features = [
"glow",
"persistence",
] }
egui-file-dialog = { path = "." }

[package]
name = "egui-file-dialog"
description = "An easy-to-use file dialog for egui"
Expand All @@ -23,18 +13,21 @@ license = "MIT"

[dependencies]
egui = { version = "0.29.1", default-features = false }

# Used to fetch user folders
# fetch user folders
directories = "5.0"

# Used to fetch disks
# canonicalize paths
dunce = "1.0.5"
# fetch disks
sysinfo = { version = "0.32", default-features = false, features = ["disk"] }

# Used for persistent storage
# persistent storage
serde = { version = "1", features = ["derive"], optional = true }

# Used to canonicalize paths
dunce = "1.0.5"
[dev-dependencies]
eframe = { version = "0.29.1", default-features = false, features = [
"glow",
"persistence",
] }
egui-file-dialog = { path = "." }

[features]
default = ["serde", "default_fonts"]
Expand Down
51 changes: 37 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
# egui-file-dialog

[![Latest version](https://img.shields.io/crates/v/egui-file-dialog.svg)](https://crates.io/crates/egui-file-dialog)
[![Documentation](https://img.shields.io/docsrs/egui-file-dialog)](https://docs.rs/egui-file-dialog)
[![Dependency status](https://deps.rs/repo/github/fluxxcode/egui-file-dialog/status.svg)](https://deps.rs/repo/github/fluxxcode/egui-file-dialog)
Expand Down Expand Up @@ -27,6 +28,7 @@ The file dialog is intended for use by desktop applications, allowing the use of
The latest changes included in the next release can be found in the [CHANGELOG.md](https://github.com/fluxxcode/egui-file-dialog/blob/develop/CHANGELOG.md) file on the develop branch.

## Features

- Select a file or a directory
- Save a file (Prompt user for a destination path)
- Dialog to ask the user if the existing file should be overwritten
Expand All @@ -51,18 +53,21 @@ The latest changes included in the next release can be found in the [CHANGELOG.m
- Add a right panel with custom UI using

## Example

Detailed examples that can be run can be found in the [examples](https://github.com/fluxxcode/egui-file-dialog/tree/develop/examples) folder.

The following example shows the basic use of the file dialog with [eframe](https://github.com/emilk/egui/tree/master/crates/eframe) to select a file.

Cargo.toml:

```toml
[dependencies]
eframe = "0.29.1"
egui-file-dialog = "0.7.0"
```

main.rs:

```rust
use std::path::PathBuf;

Expand Down Expand Up @@ -114,25 +119,33 @@ fn main() -> eframe::Result<()> {
}
```

## Examples

The examples can be found in the [examples](examples) folder.
Further descriptions can be found in the [EXAMPLES.](examples/README.md) file.

## Keybindings

Keybindings can be used in the file dialog for easier navigation. All keybindings can be configured from the backend with `FileDialogKeyBindings` and `FileDialog::keybindings`. \
The following table lists all available keybindings and their default values.
| Name | Description | Default |
| --- | --- | --- |
| submit | Submit the current action or open the currently selected folder | `Enter` |
| cancel | Cancel the current action | `Escape` |
| parent | Open the parent directory | `ALT` + `` |
| back | Go back | `Mouse button 1` <br/> `ALT` + `` <br/> `Backspace` |
| forward | Go forward | `Mouse button 2` <br/> `ALT` + `` |
| reload | Reload the file dialog data and the currently open directory | `F5` |
| new_folder | Open the dialog to create a new folder | `CTRL` + `N` on linux/windows or `CMD` + `N` on macOS |
| edit_path | Text edit the current path | `/` |
| home_edit_path | Open the home directory and start text editing the path | `~` |
| selection_up | Move the selection one item up | `` |
| selection_down | Move the selection one item down | `` |
| select_all | Select every item in the directory when using the file dialog to select multiple files and folders | `CTRL` + `A` on linux/windows or `CMD` + `A` on macOS |

| Name | Description | Default |
| -------------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| submit | Submit the current action or open the currently selected folder | `Enter` |
| cancel | Cancel the current action | `Escape` |
| parent | Open the parent directory | `ALT` + `` |
| back | Go back | `Mouse button 1` <br/> `ALT` + `` <br/> `Backspace` |
| forward | Go forward | `Mouse button 2` <br/> `ALT` + `` |
| reload | Reload the file dialog data and the currently open directory | `F5` |
| new_folder | Open the dialog to create a new folder | `CTRL` + `N` on linux/windows or `CMD` + `N` on macOS |
| edit_path | Text edit the current path | `/` |
| home_edit_path | Open the home directory and start text editing the path | `~` |
| selection_up | Move the selection one item up | `` |
| selection_down | Move the selection one item down | `` |
| select_all | Select every item in the directory when using the file dialog to select multiple files and folders | `CTRL` + `A` on linux/windows or `CMD` + `A` on macOS |

## 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).

Expand All @@ -146,6 +159,7 @@ Since the dialog uses the egui style to look like the rest of the application, t

The following example shows how a single 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;
Expand Down Expand Up @@ -186,12 +200,14 @@ FileDialog::new()
Arc::new(|p| p.extension().unwrap_or_default() == "rs"),
);
```

With the options the dialog then looks like this:
<img src="media/customization_demo.png">

If you want to display your own information in the file dialog, you can update the file dialog with
`update_with_right_panel_ui` instead of `update`. This allows e.g. to display custom image previews or further
information about the selected item. See [custom-right-panel](https://github.com/fluxxcode/egui-file-dialog/tree/develop/examples/custom-right-panel) for the full example.

```rust
fn update(&mut self, ctx: &egui::Context, _frame: &mut eframe::Frame) {
// Update the dialog with a custom right panel
Expand All @@ -202,9 +218,11 @@ fn update(&mut self, ctx: &egui::Context, _frame: &mut eframe::Frame) {
});
}
```

<img src="media/right_panel_demo.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.

The following example shows how the labels can be changed to display the file dialog in English or German. \
Expand Down Expand Up @@ -243,6 +261,7 @@ fn update_labels(language: &Language, file_dialog: &mut FileDialog) {
```

## Persistent data

The file dialog currently requires the following persistent data to be stored across multiple file dialog objects:

- Folders the user pinned to the left sidebar (`FileDialog::show_pinned_folders`)
Expand Down Expand Up @@ -292,3 +311,7 @@ impl eframe::App for MyApp {
}
}
```

## Development

Feel free to contribute to the project. If you have any questions or need help, please open an issue.
78 changes: 78 additions & 0 deletions examples/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
# Examples

## Multi Selection

Example showing how to select multiple files and folders at once.

```shell
cargo run --example multi_selection
```

![Screenshot](../media/examples/multi-selection.png)

## Multilingual

Example that shows how the dialog can be displayed and used in different languages.

```shell
cargo run --example multilingual
```

![Screenshot](../media/examples/multilingual.png)

## Multiple Actions

This example shows how you can query multiple files from the user in one view.

```shell
cargo run --example multiple_actions
```

![Screenshot](../media/examples/multiple_actions.png)

## Persistence

This example uses eframe to show how the persistent data of the file dialog can be saved. \
The example uses the `serde` feature to serialize the required data.

```shell
cargo run --example persistence
```

## Pick Directory

Example showing how to select a directory using the file dialog.

```shell
cargo run --example pick_directory
```

![Screenshot](../media/examples/pick_directory.png)

## Pick File

Example showing how to select a file using the file dialog.

```shell
cargo run --example pick_file
```

![Screenshot](../media/examples/pick_file.png)

## Sandbox

Sandbox app used during development of the file dialog.

```shell
cargo run --example sandbox
```

## Save File

Example showing how to save a file using the file dialog.

```shell
cargo run --example save_file
```

![Screenshot](../media/examples/save_file.png)
Original file line number Diff line number Diff line change
Expand Up @@ -31,15 +31,15 @@ impl eframe::App for MyApp {

if let Some(items) = &self.picked_items {
for item in items {
ui.label(format!("{:?}", item));
ui.label(format!("{item:?}"));
}
} else {
ui.label("None");
}

self.file_dialog
.update_with_right_panel_ui(ctx, &mut |ui, dia| match dia.mode() {
DialogMode::SelectMultiple => {
.update_with_right_panel_ui(ctx, &mut |ui, dia| {
if dia.mode() == DialogMode::SelectMultiple {
ui.heading("Selected items");
ui.separator();
egui::ScrollArea::vertical()
Expand All @@ -50,8 +50,7 @@ impl eframe::App for MyApp {
ui.separator();
}
});
}
_ => {
} else {
ui.heading("Active item");
ui.small(format!("{:#?}", dia.active_entry()));
}
Expand Down
10 changes: 0 additions & 10 deletions examples/custom-right-panel/Cargo.toml

This file was deleted.

Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ impl eframe::App for MyApp {

if let Some(items) = &self.picked_items {
for item in items {
ui.label(format!("{:?}", item));
ui.label(format!("{item:?}"));
}
} else {
ui.label("None");
Expand Down
10 changes: 0 additions & 10 deletions examples/multi_selection/Cargo.toml

This file was deleted.

7 changes: 0 additions & 7 deletions examples/multi_selection/README.md

This file was deleted.

File renamed without changes.
10 changes: 0 additions & 10 deletions examples/multilingual/Cargo.toml

This file was deleted.

7 changes: 0 additions & 7 deletions examples/multilingual/README.md

This file was deleted.

File renamed without changes.
10 changes: 0 additions & 10 deletions examples/multiple_actions/Cargo.toml

This file was deleted.

7 changes: 0 additions & 7 deletions examples/multiple_actions/README.md

This file was deleted.

Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ impl MyApp {
// Alternatively, you can also use the `FileDialog::storage` builder method.
if let Some(storage) = cc.storage {
*file_dialog.storage_mut() =
eframe::get_value(storage, "file_dialog_storage").unwrap_or_default()
eframe::get_value(storage, "file_dialog_storage").unwrap_or_default();
}

Self {
Expand Down
10 changes: 0 additions & 10 deletions examples/persistence/Cargo.toml

This file was deleted.

6 changes: 0 additions & 6 deletions examples/persistence/README.md

This file was deleted.

File renamed without changes.
Loading

0 comments on commit 42f0210

Please sign in to comment.