# GradientProgressBar
A small, self-contained wrapper around [`indicatif::ProgressBar`](https://docs.rs/indicatif) that gives your program a consistent, beautiful look across every operation without repeating `ProgressStyle` boilerplate.
\
\
🔵 Human-written — Written entirely by humans. (*except for `\x1b[38;2;{};{};{}m█` and `█▉▊▋▌▍▎▏ ` visual elements, which I asked a large language model to provide.*)
> [!NOTE]
> `GradientProgressBar` was originally made for [Enkryptit](https://github.com/VRAM-RAM/Enkryptit) but went too far with gradients.
<div align="center">
<img src="./assets/gradient.gif" alt="Gradient gif as example" width="65%">
</div>
## Quick start
The most common case - you know the total size in bytes:
```rust
use gradient_bar::progress_bar::GradientProgressBar;
let bar = GradientProgressBar::with_total_bytes(total_size, "Operating...");
// ... inside your processing loop ...
bar.inc(bytes_processed); // or bar.update(position);
bar.finish();
```
That's it. A green spinner, a wide cyan/blue bar, `bytes/total`, percent and ETA are all handled for you.
## Constructors
| `new(len, msg, style, gradient, unit)` | any | Low-level: you pick the total *and* the style *and* the gradient *and* the unit yourself. |
| `new_with_bar_width(len, msg, style, gradient, bar_width, unit)` | any | Even more low-level: you pick the total *and* the style *and* the gradient *and* the bar width *and* the unit yourself. |
| `with_total_bytes(total, msg)` | `Main` | Byte-based workload (streams, single-file encrypt/decrypt). |
| `with_total_steps(total, msg)` | `Steps` | Chunk / step-based workload, e.g. multithreaded splitting. |
| `with_gradient(total, msg, gradient)` | `Main` | Byte-based workload with a specific [`Gradient`]. |
| `with_wide_bar(total, msg)` | `Main` | Byte-based workload with the classic two-tone bar (no true-color gradient). |
| `new_spinner(msg)` | `Spinner` | Indeterminate progress — you don't know the total up front. |
All constructors take the message as `impl Into<String>`, so `"Encrypting"` and `format!(...)` both work.
### Styles
`BarStyle` is a `Copy` enum with a hand-tuned style per variant:
| `Main` | spinner + msg + elapsed + wide bar + `bytes/total` + % + ETA | Default byte-based progress. |
| `Minified` | spinner + msg + `bytes/total` + % | Tight output, secondary lines. |
| `Steps` | spinner + msg + bar + `pos/len chunks` + % + elapsed | Chunk counts, not bytes. |
| `Spinner` | spinner + msg | Unknown/indeterminate totals. |
| `ClearOnFinish` | same as `Main` | When you want a pristine terminal afterwards. |
> **How clearing works:** indicatif decides "clear on finish" at finish time, not in the style.
> So for `ClearOnFinish` you must call **`finish_and_clear()`** — not `finish()` — otherwise the
> bar stays on screen. The other variants pair with `finish()`.
Every template uses colors safe on both light and dark terminals, and degrades gracefully
(plain ASCII) on terminals without unicode support.
### Gradients
`Gradient` is an enum that provides **13** *Gradients* for the progress bar.
| `Ocean` | Deep blue to Ice cyan (the signature look) |
| `Violet` | Violet to Magenta |
| `Sunset` | Warm orange to gold |
| `Mint` | Aqua green to mint |
| `Ember` | Amber to rose |
| `Ice` | Cool white to pale blue |
| `Aurora` | Blue / light Cyan geen to light purple |
| `Neon` | Cyan to light blue / purple |
| `Rose` | Pink to light Coral |
| `Forest` | Green to light green |
| `Midnight` | Dark blue to light purple |
| `Twilight` | Gray-blue to soft lavender |
| `Coral` | Deep Coral to soft peach |
*Gradients* are rendered using `std::fmt::Write`.
### Driving the bar
| `update(pos)` | Jump to an absolute position. |
| `inc(delta)` | Advance by `delta` (most common in loops). |
| `set_length(len)` | Change the total. |
| `inc_length(delta)` | Grow the total by `delta`. |
| `set_message(msg)` | Update the message text. |
| `tick()` | Redraw an indeterminate spinner. |
| `finish()` | Mark done and leave the bar on screen. |
| `finish_with_message(msg)` | Mark done, replacing the line with `msg`. |
| `finish_and_clear()` | Mark done and remove the bar entirely. |
| `set_style(style)` | Swap the layout of an existing bar. |
| `set_unit(unit)` | Set the unit of the bar (to `meters`, `liters`, `files`... for example) |
| `style()` | Read the current style back. |
| `set_gradient(gradient)` | Swap the gradient (or set `None` for the classic two-tone bar). |
| `gradient()` | Read the current gradient back. |
| `set_bar_width(width)` | Set the number of columns the gradient bar occupies. |
| `inner()` | Borrow the underlying `indicatif::ProgressBar` for advanced use. |
### Sharing across threads
`GradientProgressBar` is `Clone`, `Send` and `Sync` (its inner `ProgressBar` is). This makes it trivial to report progress from worker threads:
```rust
use gradient_bar::progress_bar::GradientProgressBar;
use std::sync::Arc;
let bar = Arc::new(GradientProgressBar::with_total_steps(num_chunks, "Splitting"));
let handles: Vec<_> = (0..8).map(|i| {
let bar = bar.clone();
std::thread::spawn(move || {
// ... do work ...
bar.inc(1);
})
}).collect();
for h in handles { h.join().unwrap(); }
bar.finish();
```
### Real-world patterns
#### Byte-based stream (like `encrypt_stream` / `decrypt_stream` in Enkryptit)
```rust
let bar = GradientProgressBar::with_total_bytes(total_size, "Encrypting");
while n > 0 {
// ... read, compress, encrypt, write ...
total_processed += n as u64;
bar.update(total_processed);
}
bar.finish();
```
#### Step-based multithreading
```rust
let bar = GradientProgressBar::with_total_steps(estimated_max_steps, "Splitting");
loop {
// ... read a chunk, submit a job ...
step += 1;
bar.update(step);
}
bar.finish();
```
> The `Steps` bar displays `pos/len chunks`. It does **not** take a byte count, so keep feeding it chunk positions, not accumulated bytes.
#### Indeterminate stage + success message
```rust
let sp = GradientProgressBar::new_spinner("Deriving key");
sp.tick();
// ... long-running work with no known total ...
sp.finish_with_message("Key ready");
```
#### Clean up afterwards
```rust
let mut bar = GradientProgressBar::new(total, "Packaging", BarStyle::ClearOnFinish, None, Some("files"));
// ... bar.update(x) ...
bar.finish_and_clear();
```
### Tips
- In a non-interactive context (piped output, CI) indicatif **automatically hides** the bar, so you get clean logs for free.
- Prefer `inc()` when you know each step's size; use `update()` to jump to precise positions.
- Run `cargo fmt` after editing files that embed these snippets.
## License
`gradient-bar` is licensed under :
- [MIT](./LICENSE-MIT)
- [CECILL](./LICENSE-CECILL-EN) (French / European law compliant)
Choose the one that best fits your needs !