Compare commits
5 Commits
v0.27.0-al
...
v0.27.0
| Author | SHA1 | Date | |
|---|---|---|---|
|
0a18dcb329 | ||
|
|
7ef2daee06 | ||
|
|
46977d8851 | ||
|
|
38bb196404 | ||
|
|
1908b06b4a |
@@ -10,12 +10,15 @@ GitHub with a [breaking change] label.
|
||||
|
||||
This is a quick summary of the sections below:
|
||||
|
||||
- [Unreleased](#unreleased)
|
||||
- [v0.27.0](#v0270)
|
||||
- List no clamps the selected index to list
|
||||
- Prelude items added / removed
|
||||
- 'termion' updated to 4.0
|
||||
- `Rect::inner` takes `Margin` directly instead of reference
|
||||
- `Buffer::filled` takes `Cell` directly instead of reference
|
||||
- `Stylize::bg()` now accepts `Into<Color>`
|
||||
- Removed deprecated `List::start_corner`
|
||||
- `LineGauge::gauge_style` is deprecated
|
||||
- [v0.26.0](#v0260)
|
||||
- `Flex::Start` is the new default flex mode for `Layout`
|
||||
- `patch_style` & `reset_style` now consume and return `Self`
|
||||
@@ -53,7 +56,17 @@ This is a quick summary of the sections below:
|
||||
- MSRV is now 1.63.0
|
||||
- `List` no longer ignores empty strings
|
||||
|
||||
## Unreleased
|
||||
## [v0.27.0](https://github.com/ratatui-org/ratatui/releases/tag/v0.27.0)
|
||||
|
||||
### List no clamps the selected index to list ([#1159])
|
||||
|
||||
[#1149]: https://github.com/ratatui-org/ratatui/pull/1149
|
||||
|
||||
The `List` widget now clamps the selected index to the bounds of the list when navigating with
|
||||
`first`, `last`, `previous`, and `next`, as well as when setting the index directly with `select`.
|
||||
|
||||
Previously selecting an index past the end of the list would show treat the list as having a
|
||||
selection which was not visible. Now the last item in the list will be selected instead.
|
||||
|
||||
### Prelude items added / removed ([#1149])
|
||||
|
||||
@@ -100,8 +113,6 @@ To update your app:
|
||||
+ let position: some_crate::Position = ...;
|
||||
```
|
||||
|
||||
[#1149]: https://github.com/ratatui-org/ratatui/pull/1149
|
||||
|
||||
### Termion is updated to 4.0 [#1106]
|
||||
|
||||
Changelog: <https://gitlab.redox-os.org/redox-os/termion/-/blob/master/CHANGELOG.md>
|
||||
@@ -167,6 +178,19 @@ flexible types from calling scopes, though it can break some type inference in t
|
||||
|
||||
`layout::Corner` was removed entirely.
|
||||
|
||||
### `LineGauge::gauge_style` is deprecated ([#565])
|
||||
|
||||
[#565]: https://github.com/ratatui-org/ratatui/pull/1148
|
||||
|
||||
`LineGauge::gauge_style` is deprecated and replaced with `LineGauge::filled_style` and `LineGauge::unfilled_style`:
|
||||
|
||||
```diff
|
||||
let gauge = LineGauge::default()
|
||||
- .gauge_style(Style::default().fg(Color::Red).bg(Color::Blue)
|
||||
+ .filled_style(Style::default().fg(Color::Green))
|
||||
+ .unfilled_style(Style::default().fg(Color::White));
|
||||
```
|
||||
|
||||
## [v0.26.0](https://github.com/ratatui-org/ratatui/releases/tag/v0.26.0)
|
||||
|
||||
### `Flex::Start` is the new default flex mode for `Layout` ([#881])
|
||||
|
||||
373
CHANGELOG.md
373
CHANGELOG.md
@@ -2,6 +2,379 @@
|
||||
|
||||
All notable changes to this project will be documented in this file.
|
||||
|
||||
## [0.27.0](https://github.com/ratatui-org/ratatui/releases/tag/v0.27.0) - 2024-06-24
|
||||
|
||||
In this version, we have focused on enhancing usability and functionality with new features like
|
||||
background styles for LineGauge, palette colors, and various other improvements including
|
||||
improved performance. Also, we added brand new examples for tracing and creating hyperlinks!
|
||||
|
||||
✨ **Release highlights**: <https://ratatui.rs/highlights/v027/>
|
||||
|
||||
⚠️ List of breaking changes can be found [here](https://github.com/ratatui-org/ratatui/blob/main/BREAKING-CHANGES.md).
|
||||
|
||||
### Features
|
||||
|
||||
- [eef1afe](https://github.com/ratatui-org/ratatui/commit/eef1afe9155089dca489a9159c368a5ac07e7585) _(linegauge)_ Allow LineGauge background styles by @nowNick in [#565](https://github.com/ratatui-org/ratatui/pull/565)
|
||||
|
||||
```text
|
||||
This PR deprecates `gauge_style` in favor of `filled_style` and
|
||||
`unfilled_style` which can have it's foreground and background styled.
|
||||
|
||||
`cargo run --example=line_gauge --features=crossterm`
|
||||
```
|
||||
|
||||
https://github.com/ratatui-org/ratatui/assets/5149215/5fb2ce65-8607-478f-8be4-092e08612f5b
|
||||
|
||||
Implements:<https://github.com/ratatui-org/ratatui/issues/424>
|
||||
|
||||
- [1365620](https://github.com/ratatui-org/ratatui/commit/13656206064b53c7f86f179b570c7769399212a3) _(borders)_ Add FULL and EMPTY border sets by @joshka in [#1182](https://github.com/ratatui-org/ratatui/pull/1182)
|
||||
|
||||
`border::FULL` uses a full block symbol, while `border::EMPTY` uses an
|
||||
empty space. This is useful for when you need to allocate space for the
|
||||
border and apply the border style to a block without actually drawing a
|
||||
border. This makes it possible to style the entire title area or a block
|
||||
rather than just the title content.
|
||||
|
||||
```rust
|
||||
use ratatui::{symbols::border, widgets::Block};
|
||||
let block = Block::bordered().title("Title").border_set(border::FULL);
|
||||
let block = Block::bordered().title("Title").border_set(border::EMPTY);
|
||||
```
|
||||
|
||||
- [7a48c5b](https://github.com/ratatui-org/ratatui/commit/7a48c5b11b3d51b915ccc187d0499b6e0e88b89d) _(cell)_ Add EMPTY and (const) new method by @EdJoPaTo in [#1143](https://github.com/ratatui-org/ratatui/pull/1143)
|
||||
|
||||
```text
|
||||
This simplifies calls to `Buffer::filled` in tests.
|
||||
```
|
||||
|
||||
- [3f2f2cd](https://github.com/ratatui-org/ratatui/commit/3f2f2cd6abf67a04809ff314025a462a3c2e2446) _(docs)_ Add tracing example by @joshka in [#1192](https://github.com/ratatui-org/ratatui/pull/1192)
|
||||
|
||||
```text
|
||||
Add an example that demonstrates logging to a file for:
|
||||
```
|
||||
|
||||
<https://forum.ratatui.rs/t/how-do-you-println-debug-your-tui-programs/66>
|
||||
|
||||
```shell
|
||||
cargo run --example tracing
|
||||
RUST_LOG=trace cargo run --example=tracing
|
||||
cat tracing.log
|
||||
```
|
||||
|
||||
|
||||
|
||||
- [1520ed9](https://github.com/ratatui-org/ratatui/commit/1520ed9d106f99580a9e529212e43dac06a2f6d2) _(layout)_ Impl Display for Position and Size by @joshka in [#1162](https://github.com/ratatui-org/ratatui/pull/1162)
|
||||
|
||||
- [46977d8](https://github.com/ratatui-org/ratatui/commit/46977d88519d28ccac1c94e171af0c9cca071dbc) _(list)_ Add list navigation methods (first, last, previous, next) by @joshka in [#1159](https://github.com/ratatui-org/ratatui/pull/1159) [**breaking**]
|
||||
|
||||
```text
|
||||
Also cleans up the list example significantly (see also
|
||||
<https://github.com/ratatui-org/ratatui/issues/1157>)
|
||||
```
|
||||
|
||||
Fixes:<https://github.com/ratatui-org/ratatui/pull/1159>
|
||||
|
||||
BREAKING CHANGE:The `List` widget now clamps the selected index to the
|
||||
bounds of the list when navigating with `first`, `last`, `previous`, and
|
||||
`next`, as well as when setting the index directly with `select`.
|
||||
|
||||
- [10d7788](https://github.com/ratatui-org/ratatui/commit/10d778866edea55207ff3f03d063c9fec619b9c9) _(style)_ Add conversions from the palette crate colors by @joshka in [#1172](https://github.com/ratatui-org/ratatui/pull/1172)
|
||||
|
||||
````text
|
||||
This is behind the "palette" feature flag.
|
||||
|
||||
```rust
|
||||
use palette::{LinSrgb, Srgb};
|
||||
use ratatui::style::Color;
|
||||
|
||||
let color = Color::from(Srgb::new(1.0f32, 0.0, 0.0));
|
||||
let color = Color::from(LinSrgb::new(1.0f32, 0.0, 0.0));
|
||||
```
|
||||
````
|
||||
|
||||
- [7ef2dae](https://github.com/ratatui-org/ratatui/commit/7ef2daee060a7fe964a8de64eafcb6062228e035) _(text)_ support conversion from Display to Span, Line and Text by @orhun in [#1167](https://github.com/ratatui-org/ratatui/pull/1167)
|
||||
|
||||
````text
|
||||
Now you can create `Line` and `Text` from numbers like so:
|
||||
|
||||
```rust
|
||||
let line = 42.to_line();
|
||||
let text = 666.to_text();
|
||||
```
|
||||
````
|
||||
|
||||
- [74a32af](https://github.com/ratatui-org/ratatui/commit/74a32afbaef8851f9462b27094d88d518e56addf) _(uncategorized)_ Re-export backends from the ratatui crate by @joshka in [#1151](https://github.com/ratatui-org/ratatui/pull/1151)
|
||||
|
||||
```text
|
||||
`crossterm`, `termion`, and `termwiz` can now be accessed as
|
||||
`ratatui::{crossterm, termion, termwiz}` respectively. This makes it
|
||||
possible to just add the Ratatui crate as a dependency and use the
|
||||
backend of choice without having to add the backend crates as
|
||||
dependencies.
|
||||
|
||||
To update existing code, replace all instances of `crossterm::` with
|
||||
`ratatui::crossterm::`, `termion::` with `ratatui::termion::`, and
|
||||
`termwiz::` with `ratatui::termwiz::`.
|
||||
```
|
||||
|
||||
- [3594180](https://github.com/ratatui-org/ratatui/commit/35941809e11ab43309dd83a8f67bb375f5e7ff2b) _(uncategorized)_ Make Stylize's `.bg(color)` generic by @kdheepak in [#1103](https://github.com/ratatui-org/ratatui/pull/1103) [**breaking**]
|
||||
|
||||
- [0b5fd6b](https://github.com/ratatui-org/ratatui/commit/0b5fd6bf8eb64662df96900faea3608d4cbb3984) _(uncategorized)_ Add writer() and writer_mut() to termion and crossterm backends by @enricozb in [#991](https://github.com/ratatui-org/ratatui/pull/991)
|
||||
|
||||
```text
|
||||
It is sometimes useful to obtain access to the writer if we want to see
|
||||
what has been written so far. For example, when using &mut [u8] as a
|
||||
writer.
|
||||
```
|
||||
|
||||
### Bug Fixes
|
||||
|
||||
- [efa965e](https://github.com/ratatui-org/ratatui/commit/efa965e1e806c60cb1bdb2d1715f960db0857704) _(line)_ Remove newlines when converting strings to Lines by @joshka in [#1191](https://github.com/ratatui-org/ratatui/pull/1191)
|
||||
|
||||
`Line::from("a\nb")` now returns a line with two `Span`s instead of 1
|
||||
|
||||
Fixes:https://github.com/ratatui-org/ratatui/issues/1111
|
||||
|
||||
- [d370aa7](https://github.com/ratatui-org/ratatui/commit/d370aa75af99da3e0c41ceb28e2d02ee81cd2538) _(span)_ Ensure that zero-width characters are rendered correctly by @joshka in [#1165](https://github.com/ratatui-org/ratatui/pull/1165)
|
||||
|
||||
- [127d706](https://github.com/ratatui-org/ratatui/commit/127d706ee4876a58230f42f4a730b18671eae167) _(table)_ Ensure render offset without selection properly by @joshka in [#1187](https://github.com/ratatui-org/ratatui/pull/1187)
|
||||
|
||||
Fixes:<https://github.com/ratatui-org/ratatui/issues/1179>
|
||||
|
||||
- [4bfdc15](https://github.com/ratatui-org/ratatui/commit/4bfdc15b80ba14489d359ab1f88564c3bd016c19) _(uncategorized)_ Render of &str and String doesn't respect area.width by @thscharler in [#1177](https://github.com/ratatui-org/ratatui/pull/1177)
|
||||
|
||||
- [e6871b9](https://github.com/ratatui-org/ratatui/commit/e6871b9e21c25acf1e203f4860198c37aa9429a1) _(uncategorized)_ Avoid unicode-width breaking change in tests by @joshka in [#1171](https://github.com/ratatui-org/ratatui/pull/1171)
|
||||
|
||||
```text
|
||||
unicode-width 0.1.13 changed the width of \u{1} from 0 to 1.
|
||||
Our tests assumed that \u{1} had a width of 0, so this change replaces
|
||||
the \u{1} character with \u{200B} (zero width space) in the tests.
|
||||
|
||||
Upstream issue (closed as won't fix):
|
||||
https://github.com/unicode-rs/unicode-width/issues/55
|
||||
```
|
||||
|
||||
- [7f3efb0](https://github.com/ratatui-org/ratatui/commit/7f3efb02e6f846fc72079f0921abd2cee09d2d83) _(uncategorized)_ Pin unicode-width crate to 0.1.13 by @joshka in [#1170](https://github.com/ratatui-org/ratatui/pull/1170)
|
||||
|
||||
```text
|
||||
semver breaking change in 0.1.13
|
||||
<https://github.com/unicode-rs/unicode-width/issues/55>
|
||||
|
||||
<!-- Please read CONTRIBUTING.md before submitting any pull request. -->
|
||||
```
|
||||
|
||||
- [42cda6d](https://github.com/ratatui-org/ratatui/commit/42cda6d28706bf83308787ca784f374f6c286a02) _(uncategorized)_ Prevent panic from string_slice by @EdJoPaTo in [#1140](https://github.com/ratatui-org/ratatui/pull/1140)
|
||||
|
||||
<https://rust-lang.github.io/rust-clippy/master/index.html#string_slice>
|
||||
|
||||
### Refactor
|
||||
|
||||
- [73fd367](https://github.com/ratatui-org/ratatui/commit/73fd367a740924ce80ef7a0cd13a66b5094f7a54) _(block)_ Group builder pattern methods by @EdJoPaTo in [#1134](https://github.com/ratatui-org/ratatui/pull/1134)
|
||||
|
||||
- [257db62](https://github.com/ratatui-org/ratatui/commit/257db6257f392a07ee238b439344d91566beb740) _(cell)_ Must_use and simplify style() by @EdJoPaTo in [#1124](https://github.com/ratatui-org/ratatui/pull/1124)
|
||||
|
||||
```text
|
||||
<!-- Please read CONTRIBUTING.md before submitting any pull request. -->
|
||||
```
|
||||
|
||||
- [bf20369](https://github.com/ratatui-org/ratatui/commit/bf2036987f04d83f4f2b8338fab1b4fd7f4cc81d) _(cell)_ Reset instead of applying default by @EdJoPaTo in [#1127](https://github.com/ratatui-org/ratatui/pull/1127)
|
||||
|
||||
```text
|
||||
Using reset is clearer to me what actually happens. On the other case a
|
||||
struct is created to override the old one completely which basically
|
||||
does the same in a less clear way.
|
||||
```
|
||||
|
||||
- [7d175f8](https://github.com/ratatui-org/ratatui/commit/7d175f85c1905c08adf547dd37cc89c63039f480) _(lint)_ Fix new lint warnings by @EdJoPaTo in [#1178](https://github.com/ratatui-org/ratatui/pull/1178)
|
||||
|
||||
- [cf67ed9](https://github.com/ratatui-org/ratatui/commit/cf67ed9b884347cef034b09e0e9f9d4aff74ab0a) _(lint)_ Use clippy::or_fun_call by @EdJoPaTo in [#1138](https://github.com/ratatui-org/ratatui/pull/1138)
|
||||
|
||||
<https://rust-lang.github.io/rust-clippy/master/index.html#or_fun_call>
|
||||
|
||||
- [4770e71](https://github.com/ratatui-org/ratatui/commit/4770e715819475cdca2f2ccdbac00cba203cd6d2) _(list)_ Remove deprecated `start_corner` and `Corner` by @Valentin271 in [#759](https://github.com/ratatui-org/ratatui/pull/759) [**breaking**]
|
||||
|
||||
`List::start_corner` was deprecated in v0.25. Use `List::direction` and
|
||||
`ListDirection` instead.
|
||||
|
||||
```diff
|
||||
- list.start_corner(Corner::TopLeft);
|
||||
- list.start_corner(Corner::TopRight);
|
||||
// This is not an error, BottomRight rendered top to bottom previously
|
||||
- list.start_corner(Corner::BottomRight);
|
||||
// all becomes
|
||||
+ list.direction(ListDirection::TopToBottom);
|
||||
```
|
||||
|
||||
```diff
|
||||
- list.start_corner(Corner::BottomLeft);
|
||||
// becomes
|
||||
+ list.direction(ListDirection::BottomToTop);
|
||||
```
|
||||
|
||||
`layout::Corner` is removed entirely.
|
||||
|
||||
- [4f77910](https://github.com/ratatui-org/ratatui/commit/4f7791079edd16b54dc8cdfc95bb72b282a09576) _(padding)_ Add Padding::ZERO as a constant by @EdJoPaTo in [#1133](https://github.com/ratatui-org/ratatui/pull/1133)
|
||||
|
||||
```text
|
||||
Deprecate Padding::zero()
|
||||
```
|
||||
|
||||
- [8061813](https://github.com/ratatui-org/ratatui/commit/8061813f324c08e11196e62fca22c2f6b9216b7e) _(uncategorized)_ Expand glob imports by @joshka in [#1152](https://github.com/ratatui-org/ratatui/pull/1152)
|
||||
|
||||
```text
|
||||
Consensus is that explicit imports make it easier to understand the
|
||||
example code. This commit removes the prelude import from all examples
|
||||
and replaces it with the necessary imports, and expands other glob
|
||||
imports (widget::*, Constraint::*, KeyCode::*, etc.) everywhere else.
|
||||
Prelude glob imports not in examples are not covered by this PR.
|
||||
|
||||
See https://github.com/ratatui-org/ratatui/issues/1150 for more details.
|
||||
```
|
||||
|
||||
- [d929971](https://github.com/ratatui-org/ratatui/commit/d92997105bde15a1fd43829466ec8cc46bffe121) _(uncategorized)_ Dont manually impl Default for defaults by @EdJoPaTo in [#1142](https://github.com/ratatui-org/ratatui/pull/1142)
|
||||
|
||||
```text
|
||||
Replace `impl Default` by `#[derive(Default)]` when its implementation
|
||||
equals.
|
||||
```
|
||||
|
||||
- [8a60a56](https://github.com/ratatui-org/ratatui/commit/8a60a561c95691912cbf41d55866abafcba0127d) _(uncategorized)_ Needless_pass_by_ref_mut by @EdJoPaTo in [#1137](https://github.com/ratatui-org/ratatui/pull/1137)
|
||||
|
||||
<https://rust-lang.github.io/rust-clippy/master/index.html#needless_pass_by_ref_mut>
|
||||
|
||||
- [1de9a82](https://github.com/ratatui-org/ratatui/commit/1de9a82b7a871a83995d224785cae139c6f4787b) _(uncategorized)_ Simplify if let by @EdJoPaTo in [#1135](https://github.com/ratatui-org/ratatui/pull/1135)
|
||||
|
||||
```text
|
||||
While looking through lints
|
||||
[`clippy::option_if_let_else`](https://rust-lang.github.io/rust-clippy/master/index.html#option_if_let_else)
|
||||
found these. Other findings are more complex so I skipped them.
|
||||
```
|
||||
|
||||
### Documentation
|
||||
|
||||
- [1908b06](https://github.com/ratatui-org/ratatui/commit/1908b06b4a497ff1cfb2c8d8c165d2a241ee1864) _(borders)_ Add missing closing code blocks by @orhun in [#1195](https://github.com/ratatui-org/ratatui/pull/1195)
|
||||
|
||||
- [38bb196](https://github.com/ratatui-org/ratatui/commit/38bb19640449c7a3eee3a2fba6450071395e5e06) _(breaking-changes)_ Mention `LineGauge::gauge_style` by @orhun in [#1194](https://github.com/ratatui-org/ratatui/pull/1194)
|
||||
|
||||
see #565
|
||||
|
||||
- [07efde5](https://github.com/ratatui-org/ratatui/commit/07efde5233752e1bcb7ae94a91b9e36b7fadb01b) _(examples)_ Add hyperlink example by @joshka in [#1063](https://github.com/ratatui-org/ratatui/pull/1063)
|
||||
|
||||
- [7fdccaf](https://github.com/ratatui-org/ratatui/commit/7fdccafd52f4ddad1a3c9dda59fada59af21ecfa) _(examples)_ Add vhs tapes for constraint-explorer and minimal examples by @joshka in [#1164](https://github.com/ratatui-org/ratatui/pull/1164)
|
||||
|
||||
- [4f307e6](https://github.com/ratatui-org/ratatui/commit/4f307e69db058891675d0f12d75ef49006c511d6) _(examples)_ Simplify paragraph example by @joshka in [#1169](https://github.com/ratatui-org/ratatui/pull/1169)
|
||||
|
||||
Related:https://github.com/ratatui-org/ratatui/issues/1157
|
||||
|
||||
- [f429f68](https://github.com/ratatui-org/ratatui/commit/f429f688da536a52266144e63a1a7897ec6b7f26) _(examples)_ Remove lifetimes from the List example by @matta in [#1132](https://github.com/ratatui-org/ratatui/pull/1132)
|
||||
|
||||
```text
|
||||
Simplify the List example by removing lifetimes not strictly necessary
|
||||
to demonstrate how Ratatui lists work. Instead, the sample strings are
|
||||
copied into each `TodoItem`. To further simplify, I changed the code to
|
||||
use a new TodoItem::new function, rather than an implementation of the
|
||||
`From` trait.
|
||||
```
|
||||
|
||||
- [308c1df](https://github.com/ratatui-org/ratatui/commit/308c1df6495ee4373f808007a1566ca7e9279933) _(readme)_ Add links to forum by @joshka in [#1188](https://github.com/ratatui-org/ratatui/pull/1188)
|
||||
|
||||
- [2f8a936](https://github.com/ratatui-org/ratatui/commit/2f8a9363fc6c54fe2b10792c9f57fbb40b06bc0f) _(uncategorized)_ Fix links on docs.rs by @EdJoPaTo in [#1144](https://github.com/ratatui-org/ratatui/pull/1144)
|
||||
|
||||
```text
|
||||
This also results in a more readable Cargo.toml as the locations of the
|
||||
things are more obvious now.
|
||||
|
||||
Includes rewording of the underline-color feature.
|
||||
|
||||
Logs of the errors: https://docs.rs/crate/ratatui/0.26.3/builds/1224962
|
||||
Also see #989
|
||||
```
|
||||
|
||||
### Performance
|
||||
|
||||
- [4ce67fc](https://github.com/ratatui-org/ratatui/commit/4ce67fc84e3bc472e9ae97aece85f8ffae091834) _(buffer)_ Filled moves the cell to be filled by @EdJoPaTo in [#1148](https://github.com/ratatui-org/ratatui/pull/1148) [**breaking**]
|
||||
|
||||
- [8b447ec](https://github.com/ratatui-org/ratatui/commit/8b447ec4d6276c3110285e663417487ff18dafc1) _(rect)_ `Rect::inner` takes `Margin` directly instead of reference by @EdJoPaTo in [#1008](https://github.com/ratatui-org/ratatui/pull/1008) [**breaking**]
|
||||
|
||||
BREAKING CHANGE:Margin needs to be passed without reference now.
|
||||
|
||||
```diff
|
||||
-let area = area.inner(&Margin {
|
||||
+let area = area.inner(Margin {
|
||||
vertical: 0,
|
||||
horizontal: 2,
|
||||
});
|
||||
```
|
||||
|
||||
### Styling
|
||||
|
||||
- [df4b706](https://github.com/ratatui-org/ratatui/commit/df4b706674de806bdf2a1fb8c04d0654b6b0b891) _(uncategorized)_ Enable more rustfmt settings by @EdJoPaTo in [#1125](https://github.com/ratatui-org/ratatui/pull/1125)
|
||||
|
||||
### Testing
|
||||
|
||||
- [d6587bc](https://github.com/ratatui-org/ratatui/commit/d6587bc6b0db955aeac6af167e1b8ef81a3afcc9) _(style)_ Use rstest by @EdJoPaTo in [#1136](https://github.com/ratatui-org/ratatui/pull/1136)
|
||||
|
||||
```text
|
||||
<!-- Please read CONTRIBUTING.md before submitting any pull request. -->
|
||||
```
|
||||
|
||||
### Miscellaneous Tasks
|
||||
|
||||
- [7b45f74](https://github.com/ratatui-org/ratatui/commit/7b45f74b719ff18329ddbf9f05a9ac53bf06f71d) _(prelude)_ Add / remove items by @joshka in [#1149](https://github.com/ratatui-org/ratatui/pull/1149) [**breaking**]
|
||||
|
||||
```text
|
||||
his PR removes the items from the prelude that don't form a coherent
|
||||
common vocabulary and adds the missing items that do.
|
||||
|
||||
Based on a comment at
|
||||
<https://www.reddit.com/r/rust/comments/1cle18j/comment/l2uuuh7/>
|
||||
```
|
||||
|
||||
BREAKING CHANGE:The following items have been removed from the prelude:
|
||||
|
||||
- `style::Styled` - this trait is useful for widgets that want to
|
||||
support the Stylize trait, but it adds complexity as widgets have two
|
||||
`style` methods and a `set_style` method.
|
||||
- `symbols::Marker` - this item is used by code that needs to draw to
|
||||
the `Canvas` widget, but it's not a common item that would be used by
|
||||
most users of the library.
|
||||
- `terminal::{CompletedFrame, TerminalOptions, Viewport}` - these items
|
||||
are rarely used by code that needs to interact with the terminal, and
|
||||
they're generally only ever used once in any app.
|
||||
|
||||
The following items have been added to the prelude:
|
||||
|
||||
- `layout::{Position, Size}` - these items are used by code that needs
|
||||
to interact with the layout system. These are newer items that were
|
||||
added in the last few releases, which should be used more liberally.
|
||||
|
||||
- [cd64367](https://github.com/ratatui-org/ratatui/commit/cd64367e244a1588206f653fd79678ce62a86a2f) _(symbols)_ Add tests for line symbols by @joshka in [#1186](https://github.com/ratatui-org/ratatui/pull/1186)
|
||||
|
||||
- [8cfc316](https://github.com/ratatui-org/ratatui/commit/8cfc316bccb48e88660d14cd18c0df2264c4d6ce) _(uncategorized)_ Alphabetize examples in Cargo.toml by @joshka in [#1145](https://github.com/ratatui-org/ratatui/pull/1145)
|
||||
|
||||
### Build
|
||||
|
||||
- [70df102](https://github.com/ratatui-org/ratatui/commit/70df102de0154cdfbd6508659cf6ed649f820bc8) _(bench)_ Improve benchmark consistency by @EdJoPaTo in [#1126](https://github.com/ratatui-org/ratatui/pull/1126)
|
||||
|
||||
```text
|
||||
Codegen units are optimized on their own. Per default bench / release
|
||||
have 16 codegen units. What ends up in a codeget unit is rather random
|
||||
and can influence a benchmark result as a code change can move stuff
|
||||
into a different codegen unit → prevent / allow LLVM optimizations
|
||||
unrelated to the actual change.
|
||||
|
||||
More details: https://doc.rust-lang.org/cargo/reference/profiles.html
|
||||
```
|
||||
|
||||
### New Contributors
|
||||
|
||||
- @thscharler made their first contribution in [#1177](https://github.com/ratatui-org/ratatui/pull/1177)
|
||||
- @matta made their first contribution in [#1132](https://github.com/ratatui-org/ratatui/pull/1132)
|
||||
- @nowNick made their first contribution in [#565](https://github.com/ratatui-org/ratatui/pull/565)
|
||||
- @enricozb made their first contribution in [#991](https://github.com/ratatui-org/ratatui/pull/991)
|
||||
|
||||
**Full Changelog**: https://github.com/ratatui-org/ratatui/compare/v0.26.3...v0.27.0
|
||||
|
||||
## [0.26.3](https://github.com/ratatui-org/ratatui/releases/tag/v0.26.3) - 2024-05-19
|
||||
|
||||
We are happy to announce a brand new [**Ratatui Forum**](https://forum.ratatui.rs) 🐭 for Rust & TUI enthusiasts.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "ratatui"
|
||||
version = "0.26.3" # crate version
|
||||
version = "0.27.0" # crate version
|
||||
authors = ["Florian Dehau <work@fdehau.com>", "The Ratatui Developers"]
|
||||
description = "A library that's all about cooking up terminal user interfaces"
|
||||
documentation = "https://docs.rs/ratatui/latest/ratatui/"
|
||||
|
||||
508
examples/list.rs
508
examples/list.rs
@@ -13,19 +13,19 @@
|
||||
//! [examples]: https://github.com/ratatui-org/ratatui/blob/main/examples
|
||||
//! [examples readme]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
|
||||
|
||||
use std::{error::Error, io, io::stdout};
|
||||
use std::{error::Error, io};
|
||||
|
||||
use color_eyre::config::HookBuilder;
|
||||
use crossterm::event::KeyEvent;
|
||||
use ratatui::{
|
||||
backend::{Backend, CrosstermBackend},
|
||||
backend::Backend,
|
||||
buffer::Buffer,
|
||||
crossterm::{
|
||||
event::{self, Event, KeyCode, KeyEventKind},
|
||||
terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
|
||||
ExecutableCommand,
|
||||
crossterm::event::{self, Event, KeyCode, KeyEventKind},
|
||||
layout::{Constraint, Layout, Rect},
|
||||
style::{
|
||||
palette::tailwind::{BLUE, GREEN, SLATE},
|
||||
Color, Modifier, Style, Stylize,
|
||||
},
|
||||
layout::{Alignment, Constraint, Layout, Rect},
|
||||
style::{palette::tailwind, Color, Modifier, Style, Stylize},
|
||||
symbols,
|
||||
terminal::Terminal,
|
||||
text::Line,
|
||||
widgets::{
|
||||
@@ -34,342 +34,302 @@ use ratatui::{
|
||||
},
|
||||
};
|
||||
|
||||
const TODO_HEADER_BG: Color = tailwind::BLUE.c950;
|
||||
const NORMAL_ROW_COLOR: Color = tailwind::SLATE.c950;
|
||||
const ALT_ROW_COLOR: Color = tailwind::SLATE.c900;
|
||||
const SELECTED_STYLE_FG: Color = tailwind::BLUE.c300;
|
||||
const TEXT_COLOR: Color = tailwind::SLATE.c200;
|
||||
const COMPLETED_TEXT_COLOR: Color = tailwind::GREEN.c500;
|
||||
const TODO_HEADER_STYLE: Style = Style::new().fg(SLATE.c100).bg(BLUE.c800);
|
||||
const NORMAL_ROW_BG: Color = SLATE.c950;
|
||||
const ALT_ROW_BG_COLOR: Color = SLATE.c900;
|
||||
const SELECTED_STYLE: Style = Style::new().bg(SLATE.c800).add_modifier(Modifier::BOLD);
|
||||
const TEXT_FG_COLOR: Color = SLATE.c200;
|
||||
const COMPLETED_TEXT_FG_COLOR: Color = GREEN.c500;
|
||||
|
||||
#[derive(Copy, Clone)]
|
||||
enum Status {
|
||||
Todo,
|
||||
Completed,
|
||||
fn main() -> Result<(), Box<dyn Error>> {
|
||||
tui::init_error_hooks()?;
|
||||
let terminal = tui::init_terminal()?;
|
||||
|
||||
let mut app = App::default();
|
||||
app.run(terminal)?;
|
||||
|
||||
tui::restore_terminal()?;
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// This struct holds the current state of the app. In particular, it has the `todo_list` field
|
||||
/// which is a wrapper around `ListState`. Keeping track of the state lets us render the
|
||||
/// associated widget with its state and have access to features such as natural scrolling.
|
||||
///
|
||||
/// Check the event handling at the bottom to see how to change the state on incoming events. Check
|
||||
/// the drawing logic for items on how to specify the highlighting style for selected items.
|
||||
struct App {
|
||||
should_exit: bool,
|
||||
todo_list: TodoList,
|
||||
}
|
||||
|
||||
struct TodoList {
|
||||
items: Vec<TodoItem>,
|
||||
state: ListState,
|
||||
}
|
||||
|
||||
#[derive(Debug)]
|
||||
struct TodoItem {
|
||||
todo: String,
|
||||
info: String,
|
||||
status: Status,
|
||||
}
|
||||
|
||||
impl TodoItem {
|
||||
fn new(todo: &str, info: &str, status: Status) -> Self {
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
|
||||
enum Status {
|
||||
Todo,
|
||||
Completed,
|
||||
}
|
||||
|
||||
impl Default for App {
|
||||
fn default() -> Self {
|
||||
Self {
|
||||
todo: todo.to_string(),
|
||||
info: info.to_string(),
|
||||
status,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
struct TodoList {
|
||||
state: ListState,
|
||||
items: Vec<TodoItem>,
|
||||
last_selected: Option<usize>,
|
||||
}
|
||||
|
||||
/// This struct holds the current state of the app. In particular, it has the `items` field which is
|
||||
/// a wrapper around `ListState`. Keeping track of the items state let us render the associated
|
||||
/// widget with its state and have access to features such as natural scrolling.
|
||||
///
|
||||
/// Check the event handling at the bottom to see how to change the state on incoming events.
|
||||
/// Check the drawing logic for items on how to specify the highlighting style for selected items.
|
||||
struct App {
|
||||
items: TodoList,
|
||||
}
|
||||
|
||||
fn main() -> Result<(), Box<dyn Error>> {
|
||||
// setup terminal
|
||||
init_error_hooks()?;
|
||||
let terminal = init_terminal()?;
|
||||
|
||||
// create app and run it
|
||||
App::new().run(terminal)?;
|
||||
|
||||
restore_terminal()?;
|
||||
|
||||
Ok(())
|
||||
}
|
||||
|
||||
fn init_error_hooks() -> color_eyre::Result<()> {
|
||||
let (panic, error) = HookBuilder::default().into_hooks();
|
||||
let panic = panic.into_panic_hook();
|
||||
let error = error.into_eyre_hook();
|
||||
color_eyre::eyre::set_hook(Box::new(move |e| {
|
||||
let _ = restore_terminal();
|
||||
error(e)
|
||||
}))?;
|
||||
std::panic::set_hook(Box::new(move |info| {
|
||||
let _ = restore_terminal();
|
||||
panic(info);
|
||||
}));
|
||||
Ok(())
|
||||
}
|
||||
|
||||
fn init_terminal() -> color_eyre::Result<Terminal<impl Backend>> {
|
||||
enable_raw_mode()?;
|
||||
stdout().execute(EnterAlternateScreen)?;
|
||||
let backend = CrosstermBackend::new(stdout());
|
||||
let terminal = Terminal::new(backend)?;
|
||||
Ok(terminal)
|
||||
}
|
||||
|
||||
fn restore_terminal() -> color_eyre::Result<()> {
|
||||
disable_raw_mode()?;
|
||||
stdout().execute(LeaveAlternateScreen)?;
|
||||
Ok(())
|
||||
}
|
||||
|
||||
impl App {
|
||||
fn new() -> Self {
|
||||
Self {
|
||||
items: TodoList::with_items(&[
|
||||
("Rewrite everything with Rust!", "I can't hold my inner voice. He tells me to rewrite the complete universe with Rust", Status::Todo),
|
||||
("Rewrite all of your tui apps with Ratatui", "Yes, you heard that right. Go and replace your tui with Ratatui.", Status::Completed),
|
||||
("Pet your cat", "Minnak loves to be pet by you! Don't forget to pet and give some treats!", Status::Todo),
|
||||
("Walk with your dog", "Max is bored, go walk with him!", Status::Todo),
|
||||
("Pay the bills", "Pay the train subscription!!!", Status::Completed),
|
||||
("Refactor list example", "If you see this info that means I completed this task!", Status::Completed),
|
||||
should_exit: false,
|
||||
todo_list: TodoList::from_iter([
|
||||
(Status::Todo, "Rewrite everything with Rust!", "I can't hold my inner voice. He tells me to rewrite the complete universe with Rust"),
|
||||
(Status::Completed, "Rewrite all of your tui apps with Ratatui", "Yes, you heard that right. Go and replace your tui with Ratatui."),
|
||||
(Status::Todo, "Pet your cat", "Minnak loves to be pet by you! Don't forget to pet and give some treats!"),
|
||||
(Status::Todo, "Walk with your dog", "Max is bored, go walk with him!"),
|
||||
(Status::Completed, "Pay the bills", "Pay the train subscription!!!"),
|
||||
(Status::Completed, "Refactor list example", "If you see this info that means I completed this task!"),
|
||||
]),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Changes the status of the selected list item
|
||||
fn change_status(&mut self) {
|
||||
if let Some(i) = self.items.state.selected() {
|
||||
self.items.items[i].status = match self.items.items[i].status {
|
||||
Status::Completed => Status::Todo,
|
||||
Status::Todo => Status::Completed,
|
||||
}
|
||||
impl FromIterator<(Status, &'static str, &'static str)> for TodoList {
|
||||
fn from_iter<I: IntoIterator<Item = (Status, &'static str, &'static str)>>(iter: I) -> Self {
|
||||
let items = iter
|
||||
.into_iter()
|
||||
.map(|(status, todo, info)| TodoItem::new(status, todo, info))
|
||||
.collect();
|
||||
let state = ListState::default();
|
||||
Self { items, state }
|
||||
}
|
||||
}
|
||||
|
||||
impl TodoItem {
|
||||
fn new(status: Status, todo: &str, info: &str) -> Self {
|
||||
Self {
|
||||
status,
|
||||
todo: todo.to_string(),
|
||||
info: info.to_string(),
|
||||
}
|
||||
}
|
||||
|
||||
fn go_top(&mut self) {
|
||||
self.items.state.select(Some(0));
|
||||
}
|
||||
|
||||
fn go_bottom(&mut self) {
|
||||
self.items.state.select(Some(self.items.items.len() - 1));
|
||||
}
|
||||
}
|
||||
|
||||
impl App {
|
||||
fn run(&mut self, mut terminal: Terminal<impl Backend>) -> io::Result<()> {
|
||||
loop {
|
||||
self.draw(&mut terminal)?;
|
||||
|
||||
while !self.should_exit {
|
||||
terminal.draw(|f| f.render_widget(&mut *self, f.size()))?;
|
||||
if let Event::Key(key) = event::read()? {
|
||||
if key.kind == KeyEventKind::Press {
|
||||
match key.code {
|
||||
KeyCode::Char('q') | KeyCode::Esc => return Ok(()),
|
||||
KeyCode::Char('h') | KeyCode::Left => self.items.unselect(),
|
||||
KeyCode::Char('j') | KeyCode::Down => self.items.next(),
|
||||
KeyCode::Char('k') | KeyCode::Up => self.items.previous(),
|
||||
KeyCode::Char('l') | KeyCode::Right | KeyCode::Enter => {
|
||||
self.change_status();
|
||||
}
|
||||
KeyCode::Char('g') => self.go_top(),
|
||||
KeyCode::Char('G') => self.go_bottom(),
|
||||
_ => {}
|
||||
}
|
||||
}
|
||||
self.handle_key(key);
|
||||
};
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
fn handle_key(&mut self, key: KeyEvent) {
|
||||
if key.kind != KeyEventKind::Press {
|
||||
return;
|
||||
}
|
||||
match key.code {
|
||||
KeyCode::Char('q') | KeyCode::Esc => self.should_exit = true,
|
||||
KeyCode::Char('h') | KeyCode::Left => self.select_none(),
|
||||
KeyCode::Char('j') | KeyCode::Down => self.select_next(),
|
||||
KeyCode::Char('k') | KeyCode::Up => self.select_previous(),
|
||||
KeyCode::Char('g') | KeyCode::Home => self.select_first(),
|
||||
KeyCode::Char('G') | KeyCode::End => self.select_last(),
|
||||
KeyCode::Char('l') | KeyCode::Right | KeyCode::Enter => {
|
||||
self.toggle_status();
|
||||
}
|
||||
_ => {}
|
||||
}
|
||||
}
|
||||
|
||||
fn draw(&mut self, terminal: &mut Terminal<impl Backend>) -> io::Result<()> {
|
||||
terminal.draw(|f| f.render_widget(self, f.size()))?;
|
||||
Ok(())
|
||||
fn select_none(&mut self) {
|
||||
self.todo_list.state.select(None);
|
||||
}
|
||||
|
||||
fn select_next(&mut self) {
|
||||
self.todo_list.state.select_next();
|
||||
}
|
||||
fn select_previous(&mut self) {
|
||||
self.todo_list.state.select_previous();
|
||||
}
|
||||
|
||||
fn select_first(&mut self) {
|
||||
self.todo_list.state.select_first();
|
||||
}
|
||||
|
||||
fn select_last(&mut self) {
|
||||
self.todo_list.state.select_last();
|
||||
}
|
||||
|
||||
/// Changes the status of the selected list item
|
||||
fn toggle_status(&mut self) {
|
||||
if let Some(i) = self.todo_list.state.selected() {
|
||||
self.todo_list.items[i].status = match self.todo_list.items[i].status {
|
||||
Status::Completed => Status::Todo,
|
||||
Status::Todo => Status::Completed,
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl Widget for &mut App {
|
||||
fn render(self, area: Rect, buf: &mut Buffer) {
|
||||
// Create a space for header, todo list and the footer.
|
||||
let vertical = Layout::vertical([
|
||||
let [header_area, main_area, footer_area] = Layout::vertical([
|
||||
Constraint::Length(2),
|
||||
Constraint::Min(0),
|
||||
Constraint::Length(2),
|
||||
]);
|
||||
let [header_area, rest_area, footer_area] = vertical.areas(area);
|
||||
Constraint::Fill(1),
|
||||
Constraint::Length(1),
|
||||
])
|
||||
.areas(area);
|
||||
|
||||
// Create two chunks with equal vertical screen space. One for the list and the other for
|
||||
// the info block.
|
||||
let vertical = Layout::vertical([Constraint::Percentage(50), Constraint::Percentage(50)]);
|
||||
let [upper_item_list_area, lower_item_list_area] = vertical.areas(rest_area);
|
||||
let [list_area, item_area] =
|
||||
Layout::vertical([Constraint::Fill(1), Constraint::Fill(1)]).areas(main_area);
|
||||
|
||||
render_title(header_area, buf);
|
||||
self.render_todo(upper_item_list_area, buf);
|
||||
self.render_info(lower_item_list_area, buf);
|
||||
render_footer(footer_area, buf);
|
||||
App::render_header(header_area, buf);
|
||||
App::render_footer(footer_area, buf);
|
||||
self.render_list(list_area, buf);
|
||||
self.render_selected_item(item_area, buf);
|
||||
}
|
||||
}
|
||||
|
||||
/// Rendering logic for the app
|
||||
impl App {
|
||||
fn render_todo(&mut self, area: Rect, buf: &mut Buffer) {
|
||||
// We create two blocks, one is for the header (outer) and the other is for list (inner).
|
||||
let outer_block = Block::new()
|
||||
.borders(Borders::NONE)
|
||||
.title_alignment(Alignment::Center)
|
||||
.title("TODO List")
|
||||
.fg(TEXT_COLOR)
|
||||
.bg(TODO_HEADER_BG);
|
||||
let inner_block = Block::new()
|
||||
.borders(Borders::NONE)
|
||||
.fg(TEXT_COLOR)
|
||||
.bg(NORMAL_ROW_COLOR);
|
||||
fn render_header(area: Rect, buf: &mut Buffer) {
|
||||
Paragraph::new("Ratatui List Example")
|
||||
.bold()
|
||||
.centered()
|
||||
.render(area, buf);
|
||||
}
|
||||
|
||||
// We get the inner area from outer_block. We'll use this area later to render the table.
|
||||
let outer_area = area;
|
||||
let inner_area = outer_block.inner(outer_area);
|
||||
fn render_footer(area: Rect, buf: &mut Buffer) {
|
||||
Paragraph::new("Use ↓↑ to move, ← to unselect, → to change status, g/G to go top/bottom.")
|
||||
.centered()
|
||||
.render(area, buf);
|
||||
}
|
||||
|
||||
// We can render the header in outer_area.
|
||||
outer_block.render(outer_area, buf);
|
||||
fn render_list(&mut self, area: Rect, buf: &mut Buffer) {
|
||||
let block = Block::new()
|
||||
.title(Line::raw("TODO List").centered())
|
||||
.borders(Borders::TOP)
|
||||
.border_set(symbols::border::EMPTY)
|
||||
.border_style(TODO_HEADER_STYLE)
|
||||
.bg(NORMAL_ROW_BG);
|
||||
|
||||
// Iterate through all elements in the `items` and stylize them.
|
||||
let items: Vec<ListItem> = self
|
||||
.items
|
||||
.todo_list
|
||||
.items
|
||||
.iter()
|
||||
.enumerate()
|
||||
.map(|(i, todo_item)| todo_item.to_list_item(i))
|
||||
.map(|(i, todo_item)| {
|
||||
let color = alternate_colors(i);
|
||||
ListItem::from(todo_item).bg(color)
|
||||
})
|
||||
.collect();
|
||||
|
||||
// Create a List from all list items and highlight the currently selected one
|
||||
let items = List::new(items)
|
||||
.block(inner_block)
|
||||
.highlight_style(
|
||||
Style::default()
|
||||
.add_modifier(Modifier::BOLD)
|
||||
.add_modifier(Modifier::REVERSED)
|
||||
.fg(SELECTED_STYLE_FG),
|
||||
)
|
||||
let list = List::new(items)
|
||||
.block(block)
|
||||
.highlight_style(SELECTED_STYLE)
|
||||
.highlight_symbol(">")
|
||||
.highlight_spacing(HighlightSpacing::Always);
|
||||
|
||||
// We can now render the item list
|
||||
// (look careful we are using StatefulWidget's render.)
|
||||
// ratatui::widgets::StatefulWidget::render as stateful_render
|
||||
StatefulWidget::render(items, inner_area, buf, &mut self.items.state);
|
||||
// We need to disambiguate this trait method as both `Widget` and `StatefulWidget` share the
|
||||
// same method name `render`.
|
||||
StatefulWidget::render(list, area, buf, &mut self.todo_list.state);
|
||||
}
|
||||
|
||||
fn render_info(&self, area: Rect, buf: &mut Buffer) {
|
||||
fn render_selected_item(&self, area: Rect, buf: &mut Buffer) {
|
||||
// We get the info depending on the item's state.
|
||||
let info = if let Some(i) = self.items.state.selected() {
|
||||
match self.items.items[i].status {
|
||||
Status::Completed => format!("✓ DONE: {}", self.items.items[i].info),
|
||||
Status::Todo => format!("TODO: {}", self.items.items[i].info),
|
||||
let info = if let Some(i) = self.todo_list.state.selected() {
|
||||
match self.todo_list.items[i].status {
|
||||
Status::Completed => format!("✓ DONE: {}", self.todo_list.items[i].info),
|
||||
Status::Todo => format!("☐ TODO: {}", self.todo_list.items[i].info),
|
||||
}
|
||||
} else {
|
||||
"Nothing to see here...".to_string()
|
||||
"Nothing selected...".to_string()
|
||||
};
|
||||
|
||||
// We show the list item's info under the list in this paragraph
|
||||
let outer_info_block = Block::new()
|
||||
.borders(Borders::NONE)
|
||||
.title_alignment(Alignment::Center)
|
||||
.title("TODO Info")
|
||||
.fg(TEXT_COLOR)
|
||||
.bg(TODO_HEADER_BG);
|
||||
let inner_info_block = Block::new()
|
||||
.borders(Borders::NONE)
|
||||
.padding(Padding::horizontal(1))
|
||||
.bg(NORMAL_ROW_COLOR);
|
||||
|
||||
// This is a similar process to what we did for list. outer_info_area will be used for
|
||||
// header inner_info_area will be used for the list info.
|
||||
let outer_info_area = area;
|
||||
let inner_info_area = outer_info_block.inner(outer_info_area);
|
||||
|
||||
// We can render the header. Inner info will be rendered later
|
||||
outer_info_block.render(outer_info_area, buf);
|
||||
|
||||
let info_paragraph = Paragraph::new(info)
|
||||
.block(inner_info_block)
|
||||
.fg(TEXT_COLOR)
|
||||
.wrap(Wrap { trim: false });
|
||||
let block = Block::new()
|
||||
.title(Line::raw("TODO Info").centered())
|
||||
.borders(Borders::TOP)
|
||||
.border_set(symbols::border::EMPTY)
|
||||
.border_style(TODO_HEADER_STYLE)
|
||||
.bg(NORMAL_ROW_BG)
|
||||
.padding(Padding::horizontal(1));
|
||||
|
||||
// We can now render the item info
|
||||
info_paragraph.render(inner_info_area, buf);
|
||||
Paragraph::new(info)
|
||||
.block(block)
|
||||
.fg(TEXT_FG_COLOR)
|
||||
.wrap(Wrap { trim: false })
|
||||
.render(area, buf);
|
||||
}
|
||||
}
|
||||
|
||||
fn render_title(area: Rect, buf: &mut Buffer) {
|
||||
Paragraph::new("Ratatui List Example")
|
||||
.bold()
|
||||
.centered()
|
||||
.render(area, buf);
|
||||
}
|
||||
|
||||
fn render_footer(area: Rect, buf: &mut Buffer) {
|
||||
Paragraph::new("\nUse ↓↑ to move, ← to unselect, → to change status, g/G to go top/bottom.")
|
||||
.centered()
|
||||
.render(area, buf);
|
||||
}
|
||||
|
||||
impl TodoList {
|
||||
fn with_items(items: &[(&str, &str, Status)]) -> Self {
|
||||
Self {
|
||||
state: ListState::default(),
|
||||
items: items
|
||||
.iter()
|
||||
.map(|(todo, info, status)| TodoItem::new(todo, info, *status))
|
||||
.collect(),
|
||||
last_selected: None,
|
||||
}
|
||||
const fn alternate_colors(i: usize) -> Color {
|
||||
if i % 2 == 0 {
|
||||
NORMAL_ROW_BG
|
||||
} else {
|
||||
ALT_ROW_BG_COLOR
|
||||
}
|
||||
}
|
||||
|
||||
fn next(&mut self) {
|
||||
let i = match self.state.selected() {
|
||||
Some(i) => {
|
||||
if i >= self.items.len() - 1 {
|
||||
0
|
||||
} else {
|
||||
i + 1
|
||||
}
|
||||
impl From<&TodoItem> for ListItem<'_> {
|
||||
fn from(value: &TodoItem) -> Self {
|
||||
let line = match value.status {
|
||||
Status::Todo => Line::styled(format!(" ☐ {}", value.todo), TEXT_FG_COLOR),
|
||||
Status::Completed => {
|
||||
Line::styled(format!(" ✓ {}", value.todo), COMPLETED_TEXT_FG_COLOR)
|
||||
}
|
||||
None => self.last_selected.unwrap_or(0),
|
||||
};
|
||||
self.state.select(Some(i));
|
||||
}
|
||||
|
||||
fn previous(&mut self) {
|
||||
let i = match self.state.selected() {
|
||||
Some(i) => {
|
||||
if i == 0 {
|
||||
self.items.len() - 1
|
||||
} else {
|
||||
i - 1
|
||||
}
|
||||
}
|
||||
None => self.last_selected.unwrap_or(0),
|
||||
};
|
||||
self.state.select(Some(i));
|
||||
}
|
||||
|
||||
fn unselect(&mut self) {
|
||||
let offset = self.state.offset();
|
||||
self.last_selected = self.state.selected();
|
||||
self.state.select(None);
|
||||
*self.state.offset_mut() = offset;
|
||||
ListItem::new(line)
|
||||
}
|
||||
}
|
||||
|
||||
impl TodoItem {
|
||||
fn to_list_item(&self, index: usize) -> ListItem {
|
||||
let bg_color = match index % 2 {
|
||||
0 => NORMAL_ROW_COLOR,
|
||||
_ => ALT_ROW_COLOR,
|
||||
};
|
||||
let line = match self.status {
|
||||
Status::Todo => Line::styled(format!(" ☐ {}", self.todo), TEXT_COLOR),
|
||||
Status::Completed => Line::styled(
|
||||
format!(" ✓ {}", self.todo),
|
||||
(COMPLETED_TEXT_COLOR, bg_color),
|
||||
),
|
||||
};
|
||||
mod tui {
|
||||
use std::{io, io::stdout};
|
||||
|
||||
ListItem::new(line).bg(bg_color)
|
||||
use color_eyre::config::HookBuilder;
|
||||
use ratatui::{
|
||||
backend::{Backend, CrosstermBackend},
|
||||
crossterm::{
|
||||
terminal::{
|
||||
disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen,
|
||||
},
|
||||
ExecutableCommand,
|
||||
},
|
||||
terminal::Terminal,
|
||||
};
|
||||
|
||||
pub fn init_error_hooks() -> color_eyre::Result<()> {
|
||||
let (panic, error) = HookBuilder::default().into_hooks();
|
||||
let panic = panic.into_panic_hook();
|
||||
let error = error.into_eyre_hook();
|
||||
color_eyre::eyre::set_hook(Box::new(move |e| {
|
||||
let _ = restore_terminal();
|
||||
error(e)
|
||||
}))?;
|
||||
std::panic::set_hook(Box::new(move |info| {
|
||||
let _ = restore_terminal();
|
||||
panic(info);
|
||||
}));
|
||||
Ok(())
|
||||
}
|
||||
|
||||
pub fn init_terminal() -> io::Result<Terminal<impl Backend>> {
|
||||
stdout().execute(EnterAlternateScreen)?;
|
||||
enable_raw_mode()?;
|
||||
Terminal::new(CrosstermBackend::new(stdout()))
|
||||
}
|
||||
|
||||
pub fn restore_terminal() -> io::Result<()> {
|
||||
stdout().execute(LeaveAlternateScreen)?;
|
||||
disable_raw_mode()
|
||||
}
|
||||
}
|
||||
|
||||
@@ -25,6 +25,7 @@ impl Default for Set {
|
||||
/// │xxxxx│
|
||||
/// │xxxxx│
|
||||
/// └─────┘
|
||||
/// ```
|
||||
pub const PLAIN: Set = Set {
|
||||
top_left: line::NORMAL.top_left,
|
||||
top_right: line::NORMAL.top_right,
|
||||
@@ -43,6 +44,7 @@ pub const PLAIN: Set = Set {
|
||||
/// │xxxxx│
|
||||
/// │xxxxx│
|
||||
/// ╰─────╯
|
||||
/// ```
|
||||
pub const ROUNDED: Set = Set {
|
||||
top_left: line::ROUNDED.top_left,
|
||||
top_right: line::ROUNDED.top_right,
|
||||
@@ -61,6 +63,7 @@ pub const ROUNDED: Set = Set {
|
||||
/// ║xxxxx║
|
||||
/// ║xxxxx║
|
||||
/// ╚═════╝
|
||||
/// ```
|
||||
pub const DOUBLE: Set = Set {
|
||||
top_left: line::DOUBLE.top_left,
|
||||
top_right: line::DOUBLE.top_right,
|
||||
@@ -79,6 +82,7 @@ pub const DOUBLE: Set = Set {
|
||||
/// ┃xxxxx┃
|
||||
/// ┃xxxxx┃
|
||||
/// ┗━━━━━┛
|
||||
/// ```
|
||||
pub const THICK: Set = Set {
|
||||
top_left: line::THICK.top_left,
|
||||
top_right: line::THICK.top_right,
|
||||
@@ -242,6 +246,7 @@ pub const PROPORTIONAL_TALL: Set = Set {
|
||||
/// █xx█
|
||||
/// █xx█
|
||||
/// ████
|
||||
/// ```
|
||||
pub const FULL: Set = Set {
|
||||
top_left: block::FULL,
|
||||
top_right: block::FULL,
|
||||
|
||||
@@ -48,14 +48,14 @@ mod grapheme;
|
||||
pub use grapheme::StyledGrapheme;
|
||||
|
||||
mod line;
|
||||
pub use line::Line;
|
||||
pub use line::{Line, ToLine};
|
||||
|
||||
mod masked;
|
||||
pub use masked::Masked;
|
||||
|
||||
mod span;
|
||||
pub use span::Span;
|
||||
pub use span::{Span, ToSpan};
|
||||
|
||||
#[allow(clippy::module_inception)]
|
||||
mod text;
|
||||
pub use text::Text;
|
||||
pub use text::{Text, ToText};
|
||||
|
||||
@@ -649,6 +649,29 @@ fn spans_after_width<'a>(
|
||||
})
|
||||
}
|
||||
|
||||
/// A trait for converting a value to a [`Line`].
|
||||
///
|
||||
/// This trait is automatically implemented for any type that implements the [`Display`] trait. As
|
||||
/// such, `ToLine` shouln't be implemented directly: [`Display`] should be implemented instead, and
|
||||
/// you get the `ToLine` implementation for free.
|
||||
///
|
||||
/// [`Display`]: std::fmt::Display
|
||||
pub trait ToLine {
|
||||
/// Converts the value to a [`Line`].
|
||||
fn to_line(&self) -> Line<'_>;
|
||||
}
|
||||
|
||||
/// # Panics
|
||||
///
|
||||
/// In this implementation, the `to_line` method panics if the `Display` implementation returns an
|
||||
/// error. This indicates an incorrect `Display` implementation since `fmt::Write for String` never
|
||||
/// returns an error itself.
|
||||
impl<T: fmt::Display> ToLine for T {
|
||||
fn to_line(&self) -> Line<'_> {
|
||||
Line::from(self.to_string())
|
||||
}
|
||||
}
|
||||
|
||||
impl fmt::Display for Line<'_> {
|
||||
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
||||
for span in &self.spans {
|
||||
@@ -824,6 +847,12 @@ mod tests {
|
||||
assert_eq!(line.spans, vec![Span::from("Hello"), Span::from("world!")]);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn to_line() {
|
||||
let line = 42.to_line();
|
||||
assert_eq!(vec![Span::from("42")], line.spans);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn from_vec() {
|
||||
let spans = vec![
|
||||
|
||||
@@ -406,6 +406,29 @@ impl WidgetRef for Span<'_> {
|
||||
}
|
||||
}
|
||||
|
||||
/// A trait for converting a value to a [`Span`].
|
||||
///
|
||||
/// This trait is automatically implemented for any type that implements the [`Display`] trait. As
|
||||
/// such, `ToSpan` shouln't be implemented directly: [`Display`] should be implemented instead, and
|
||||
/// you get the `ToSpan` implementation for free.
|
||||
///
|
||||
/// [`Display`]: std::fmt::Display
|
||||
pub trait ToSpan {
|
||||
/// Converts the value to a [`Span`].
|
||||
fn to_span(&self) -> Span<'_>;
|
||||
}
|
||||
|
||||
/// # Panics
|
||||
///
|
||||
/// In this implementation, the `to_span` method panics if the `Display` implementation returns an
|
||||
/// error. This indicates an incorrect `Display` implementation since `fmt::Write for String` never
|
||||
/// returns an error itself.
|
||||
impl<T: fmt::Display> ToSpan for T {
|
||||
fn to_span(&self) -> Span<'_> {
|
||||
Span::raw(self.to_string())
|
||||
}
|
||||
}
|
||||
|
||||
impl fmt::Display for Span<'_> {
|
||||
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
||||
fmt::Display::fmt(&self.content, f)
|
||||
@@ -507,6 +530,12 @@ mod tests {
|
||||
assert_eq!(span.style, Style::default());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn to_span() {
|
||||
assert_eq!(42.to_span(), Span::raw("42"));
|
||||
assert_eq!("test".to_span(), Span::raw("test"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn reset_style() {
|
||||
let span = Span::styled("test content", Style::new().green()).reset_style();
|
||||
|
||||
@@ -580,6 +580,29 @@ where
|
||||
}
|
||||
}
|
||||
|
||||
/// A trait for converting a value to a [`Text`].
|
||||
///
|
||||
/// This trait is automatically implemented for any type that implements the [`Display`] trait. As
|
||||
/// such, `ToText` shouldn't be implemented directly: [`Display`] should be implemented instead, and
|
||||
/// you get the `ToText` implementation for free.
|
||||
///
|
||||
/// [`Display`]: std::fmt::Display
|
||||
pub trait ToText<'a> {
|
||||
/// Converts the value to a [`Text`].
|
||||
fn to_text(&self) -> Text<'a>;
|
||||
}
|
||||
|
||||
/// # Panics
|
||||
///
|
||||
/// In this implementation, the `to_text` method panics if the `Display` implementation returns an
|
||||
/// error. This indicates an incorrect `Display` implementation since `fmt::Write for String` never
|
||||
/// returns an error itself.
|
||||
impl<'a, T: fmt::Display> ToText<'a> for T {
|
||||
fn to_text(&self) -> Text<'a> {
|
||||
Text::raw(self.to_string())
|
||||
}
|
||||
}
|
||||
|
||||
impl fmt::Display for Text<'_> {
|
||||
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
||||
for (position, line) in self.iter().with_position() {
|
||||
@@ -747,6 +770,24 @@ mod tests {
|
||||
assert_eq!(text.lines, vec![Line::from("The first line")]);
|
||||
}
|
||||
|
||||
#[rstest]
|
||||
#[case(42, Text::from("42"))]
|
||||
#[case("just\ntesting", Text::from("just\ntesting"))]
|
||||
#[case(true, Text::from("true"))]
|
||||
#[case(6.66, Text::from("6.66"))]
|
||||
#[case('a', Text::from("a"))]
|
||||
#[case(String::from("hello"), Text::from("hello"))]
|
||||
#[case(-1, Text::from("-1"))]
|
||||
#[case("line1\nline2", Text::from("line1\nline2"))]
|
||||
#[case(
|
||||
"first line\nsecond line\nthird line",
|
||||
Text::from("first line\nsecond line\nthird line")
|
||||
)]
|
||||
#[case("trailing newline\n", Text::from("trailing newline\n"))]
|
||||
fn to_text(#[case] value: impl fmt::Display, #[case] expected: Text) {
|
||||
assert_eq!(value.to_text(), expected);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn from_vec_line() {
|
||||
let text = Text::from(vec![
|
||||
|
||||
@@ -157,6 +157,72 @@ impl ListState {
|
||||
self.offset = 0;
|
||||
}
|
||||
}
|
||||
|
||||
/// Selects the next item or the first one if no item is selected
|
||||
///
|
||||
/// Note: until the list is rendered, the number of items is not known, so the index is set to
|
||||
/// `0` and will be corrected when the list is rendered
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```rust
|
||||
/// # use ratatui::{prelude::*, widgets::*};
|
||||
/// let mut state = ListState::default();
|
||||
/// state.select_next();
|
||||
/// ```
|
||||
pub fn select_next(&mut self) {
|
||||
let next = self.selected.map_or(0, |i| i.saturating_add(1));
|
||||
self.select(Some(next));
|
||||
}
|
||||
|
||||
/// Selects the previous item or the last one if no item is selected
|
||||
///
|
||||
/// Note: until the list is rendered, the number of items is not known, so the index is set to
|
||||
/// `usize::MAX` and will be corrected when the list is rendered
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```rust
|
||||
/// # use ratatui::{prelude::*, widgets::*};
|
||||
/// let mut state = ListState::default();
|
||||
/// state.select_previous();
|
||||
/// ```
|
||||
pub fn select_previous(&mut self) {
|
||||
let previous = self.selected.map_or(usize::MAX, |i| i.saturating_sub(1));
|
||||
self.select(Some(previous));
|
||||
}
|
||||
|
||||
/// Selects the first item
|
||||
///
|
||||
/// Note: until the list is rendered, the number of items is not known, so the index is set to
|
||||
/// `0` and will be corrected when the list is rendered
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```rust
|
||||
/// # use ratatui::{prelude::*, widgets::*};
|
||||
/// let mut state = ListState::default();
|
||||
/// state.select_first();
|
||||
/// ```
|
||||
pub fn select_first(&mut self) {
|
||||
self.select(Some(0));
|
||||
}
|
||||
|
||||
/// Selects the last item
|
||||
///
|
||||
/// Note: until the list is rendered, the number of items is not known, so the index is set to
|
||||
/// `usize::MAX` and will be corrected when the list is rendered
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```rust
|
||||
/// # use ratatui::{prelude::*, widgets::*};
|
||||
/// let mut state = ListState::default();
|
||||
/// state.select_last();
|
||||
/// ```
|
||||
pub fn select_last(&mut self) {
|
||||
self.select(Some(usize::MAX));
|
||||
}
|
||||
}
|
||||
|
||||
/// A single item in a [`List`]
|
||||
@@ -882,10 +948,20 @@ impl StatefulWidgetRef for List<'_> {
|
||||
self.block.render_ref(area, buf);
|
||||
let list_area = self.block.inner_if_some(area);
|
||||
|
||||
if list_area.is_empty() || self.items.is_empty() {
|
||||
if list_area.is_empty() {
|
||||
return;
|
||||
}
|
||||
|
||||
if self.items.is_empty() {
|
||||
state.select(None);
|
||||
return;
|
||||
}
|
||||
|
||||
// If the selected index is out of bounds, set it to the last item
|
||||
if state.selected.is_some_and(|s| s >= self.items.len()) {
|
||||
state.select(Some(self.items.len().saturating_sub(1)));
|
||||
}
|
||||
|
||||
let list_height = list_area.height as usize;
|
||||
|
||||
let (first_visible_index, last_visible_index) =
|
||||
@@ -1009,6 +1085,11 @@ mod tests {
|
||||
|
||||
use super::*;
|
||||
|
||||
#[fixture]
|
||||
fn single_line_buf() -> Buffer {
|
||||
Buffer::empty(Rect::new(0, 0, 10, 1))
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_list_state_selected() {
|
||||
let mut state = ListState::default();
|
||||
@@ -1036,6 +1117,96 @@ mod tests {
|
||||
assert_eq!(state.offset, 0);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_list_state_navigation() {
|
||||
let mut state = ListState::default();
|
||||
state.select_first();
|
||||
assert_eq!(state.selected, Some(0));
|
||||
|
||||
state.select_previous(); // should not go below 0
|
||||
assert_eq!(state.selected, Some(0));
|
||||
|
||||
state.select_next();
|
||||
assert_eq!(state.selected, Some(1));
|
||||
|
||||
state.select_previous();
|
||||
assert_eq!(state.selected, Some(0));
|
||||
|
||||
state.select_last();
|
||||
assert_eq!(state.selected, Some(usize::MAX));
|
||||
|
||||
state.select_next(); // should not go above usize::MAX
|
||||
assert_eq!(state.selected, Some(usize::MAX));
|
||||
|
||||
state.select_previous();
|
||||
assert_eq!(state.selected, Some(usize::MAX - 1));
|
||||
|
||||
state.select_next();
|
||||
assert_eq!(state.selected, Some(usize::MAX));
|
||||
|
||||
let mut state = ListState::default();
|
||||
state.select_next();
|
||||
assert_eq!(state.selected, Some(0));
|
||||
|
||||
let mut state = ListState::default();
|
||||
state.select_previous();
|
||||
assert_eq!(state.selected, Some(usize::MAX));
|
||||
}
|
||||
|
||||
#[rstest]
|
||||
fn test_list_state_empty_list(mut single_line_buf: Buffer) {
|
||||
let mut state = ListState::default();
|
||||
|
||||
let items: Vec<ListItem> = Vec::new();
|
||||
let list = List::new(items);
|
||||
state.select_first();
|
||||
StatefulWidget::render(list, single_line_buf.area, &mut single_line_buf, &mut state);
|
||||
assert_eq!(state.selected, None);
|
||||
}
|
||||
|
||||
#[rstest]
|
||||
fn test_list_state_single_item(mut single_line_buf: Buffer) {
|
||||
let mut state = ListState::default();
|
||||
|
||||
let items = vec![ListItem::new("Item 1")];
|
||||
let list = List::new(items);
|
||||
state.select_first();
|
||||
StatefulWidget::render(
|
||||
&list,
|
||||
single_line_buf.area,
|
||||
&mut single_line_buf,
|
||||
&mut state,
|
||||
);
|
||||
assert_eq!(state.selected, Some(0));
|
||||
|
||||
state.select_last();
|
||||
StatefulWidget::render(
|
||||
&list,
|
||||
single_line_buf.area,
|
||||
&mut single_line_buf,
|
||||
&mut state,
|
||||
);
|
||||
assert_eq!(state.selected, Some(0));
|
||||
|
||||
state.select_previous();
|
||||
StatefulWidget::render(
|
||||
&list,
|
||||
single_line_buf.area,
|
||||
&mut single_line_buf,
|
||||
&mut state,
|
||||
);
|
||||
assert_eq!(state.selected, Some(0));
|
||||
|
||||
state.select_next();
|
||||
StatefulWidget::render(
|
||||
&list,
|
||||
single_line_buf.area,
|
||||
&mut single_line_buf,
|
||||
&mut state,
|
||||
);
|
||||
assert_eq!(state.selected, Some(0));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_list_item_new_from_str() {
|
||||
let item = ListItem::new("Test item");
|
||||
@@ -1302,7 +1473,7 @@ mod tests {
|
||||
&single_item,
|
||||
Some(1),
|
||||
[
|
||||
" Item 0 ",
|
||||
">>Item 0 ",
|
||||
" ",
|
||||
" ",
|
||||
" ",
|
||||
@@ -1360,7 +1531,7 @@ mod tests {
|
||||
[
|
||||
" Item 0 ",
|
||||
" Item 1 ",
|
||||
" Item 2 ",
|
||||
">>Item 2 ",
|
||||
" ",
|
||||
" ",
|
||||
],
|
||||
@@ -2099,11 +2270,6 @@ mod tests {
|
||||
]);
|
||||
}
|
||||
|
||||
#[fixture]
|
||||
fn single_line_buf() -> Buffer {
|
||||
Buffer::empty(Rect::new(0, 0, 10, 1))
|
||||
}
|
||||
|
||||
/// Regression test for a bug where highlight symbol being greater than width caused a panic due
|
||||
/// to subtraction with underflow.
|
||||
///
|
||||
|
||||
@@ -186,7 +186,7 @@ fn widgets_list_should_clamp_offset_if_items_are_removed() {
|
||||
})
|
||||
.unwrap();
|
||||
terminal.backend().assert_buffer_lines([
|
||||
" Item 3 ",
|
||||
">> Item 3 ",
|
||||
" ",
|
||||
" ",
|
||||
" ",
|
||||
|
||||
Reference in New Issue
Block a user