ratatui-explorer 0.2.1

ratatui-explorer is a small, but highly customizable, file explorer widget for ratatui.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129

# ratatui-explorer

[ratatui-explorer](https://crates.io/crates/ratatui-explorer) is a simple library for creating file explorers for [ratatui](https://github.com/ratatui-org/ratatui).

Features:
- File explorer functionality.
- Input handling (from [crossterm](https://docs.rs/crossterm/latest/crossterm/), [termion](https://docs.rs/termion/latest/termion/), [termwiz](https://docs.rs/termwiz/latest/termwiz/) and your own backend).
- Customizable widget theming.

# Examples

Run `cargo run --example` to try the different example available.

## [Basic usage](examples/basic.rs)
The simplest use of [ratatui-explorer](https://crates.io/crates/ratatui-explorer) with the [crossterm](https://docs.rs/crossterm/latest/crossterm/) backend.


```shell
cargo run --example basic
```

![basic usage demonstration](https://raw.githubusercontent.com/tatounee/ratatui-explorer/master/assets/basic.gif)

---

## [Light and dark theme](examples/light_and_dark_theme.rs)
Switching custom themes while running.

```shell
cargo run --example light_and_dark_theme
```

![theme switching demonstration](https://raw.githubusercontent.com/tatounee/ratatui-explorer/master/assets/light_and_dark_theme.gif)

---

## [File preview](examples/file_preview.rs)
Adapt the interface depending on the selected file.

```shell
cargo run --example file_preview
```

![file preview demonstration](https://raw.githubusercontent.com/tatounee/ratatui-explorer/master/assets/file_preview.gif)


# Basic usage
Install the libraries in your `Cargo.toml` file:
```plaintext
cargo add ratatui ratatui-explorer crossterm
```
Then inside your `main.rs` file:
```rust no_run
use std::io::{self, stdout};

use crossterm::{
    event::{read, Event, KeyCode},
    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
    ExecutableCommand,
};
use ratatui::prelude::*;

use ratatui_explorer::{FileExplorer, Theme};

fn main() -> io::Result<()> {
    enable_raw_mode()?;
    stdout().execute(EnterAlternateScreen)?;

    let mut terminal = Terminal::new(CrosstermBackend::new(stdout()))?;

    // Create a new file explorer with the default theme and title.
    let theme = Theme::default().add_default_title();
    let mut file_explorer = FileExplorer::with_theme(theme)?;

    loop {
        // Render the file explorer widget.
        terminal.draw(|f| {
            f.render_widget(&file_explorer.widget(), f.area());
        })?;

        // Read the next event from the terminal.
        let event = read()?;
        if let Event::Key(key) = event {
            if key.code == KeyCode::Char('q') {
                break;
            }
        }
        // Handle the event in the file explorer.
        file_explorer.handle(&event)?;
    }

    disable_raw_mode()?;
    stdout().execute(LeaveAlternateScreen)?;
    Ok(())
}
```

## Customizing the theme
You can customize the theme of the file explorer widget by using the `Theme` struct.
```rust
use ratatui::{prelude::*, widgets::*};
use ratatui_explorer::Theme;

let theme = Theme::default()
    .add_default_title()
    .with_title_bottom(|fe| format!("[{} files]", fe.files().len()).into())
    .with_block(Block::default().borders(Borders::ALL).border_type(BorderType::Rounded))
    .with_highlight_item_style(Style::default().fg(Color::Yellow).add_modifier(Modifier::BOLD))
    .with_highlight_dir_style(Style::default().fg(Color::Red).add_modifier(Modifier::BOLD))
    .with_highlight_symbol("> ".into());
```

# Bindings

The following bindings are used by default for [crossterm](https://docs.rs/crossterm/latest/crossterm/),
[termion](https://docs.rs/termion/latest/termion/) and [termwiz](https://docs.rs/termwiz/latest/termwiz/).

| Binding                           | Action                     |
|-----------------------------------|----------------------------|
| `j`, `<DownArrow>`                | Move the selection down    |
| `k`, `<UpArrow>`                  | Move the selection up      |
| `h`, `<LeftArrow>`, `<Backspace>` | Go to the parent directory |
| `l`, `<RightArrow>`, `<Enter>`    | Go to the child directory* |
| `Home`                            | Select the first entry     |
| `End`                             | Select the last entry      |
| `PageUp`                          | Scroll the selection up    |
| `PageDown`                        | Scroll the selection down  |

_*if the selected item is a directory_