All notable changes to this project will be documented in this file.
0.25.0 - 2023-12-18
We are thrilled to announce the new version of ratatui
- a Rust library that's all about cooking up TUIs 🐭
In this version, we made improvements on widgets such as List, Table and Layout and changed some of the defaults for a better user experience.
Also, we renewed our website and updated our documentation/tutorials to get started with ratatui
: https://ratatui.rs 🚀
✨ Release highlights: https://ratatui.rs/highlights/v025/
💖 We also enabled GitHub Sponsors for our organization, consider sponsoring us if you like ratatui
: https://github.com/sponsors/ratatui-org
-
aef4956 (list)
List::new
now acceptsIntoIterator<Item = Into<ListItem>>
(#672) [breaking]This allows to build list like ``` List::new(["Item 1", "Item 2"]) ```
-
8bfd666 (paragraph) Add
line_count
andline_width
unstable helper methodsThis is an unstable feature that may be removed in the future
-
1229b96 (rect) Add
offset
method (#533)The offset method creates a new Rect that is moved by the amount specified in the x and y direction. These values can be positive or negative. This is useful for manual layout tasks. ```rust let rect = area.offset(Offset { x: 10, y -10 }); ```
-
edacaf7 (buffer) Deprecate
Cell::symbol
field (#624)The Cell::symbol field is now accessible via a getter method (`symbol()`). This will allow us to make future changes to the Cell internals such as replacing `String` with `compact_str`.
-
6b2efd0 (layout) Accept IntoIterator for constraints (#663)
Layout and Table now accept IntoIterator for constraints with an Item that is AsRef<Constraint>. This allows pretty much any collection of constraints to be passed to the layout functions including arrays, vectors, slices, and iterators (without having to call collect() on them).
-
753e246 (layout) Allow configuring layout fill (#633)
The layout split will generally fill the remaining area when `split()` is called. This change allows the caller to configure how any extra space is allocated to the `Rect`s. This is useful for cases where the caller wants to have a fixed size for one of the `Rect`s, and have the other `Rect`s fill the remaining space. For now, the method and enum are marked as unstable because the exact name is still being bikeshedded. To enable this functionality, add the `unstable-segment-size` feature flag in your `Cargo.toml`. To configure the layout to fill the remaining space evenly, use `Layout::segment_size(SegmentSize::EvenDistribution)`. The default behavior is `SegmentSize::LastTakesRemainder`, which gives the last segment the remaining space. `SegmentSize::None` will disable this behavior. See the docs for `Layout::segment_size()` and `layout::SegmentSize` for more information. Fixes https://github.com/ratatui-org/ratatui/issues/536
-
1e2f0be (layout) Add parameters to Layout::new() (#557) [breaking]
Adds a convenience function to create a layout with a direction and a list of constraints which are the most common parameters that would be generally configured using the builder pattern. The constraints can be passed in as any iterator of constraints. ```rust let layout = Layout::new(Direction::Horizontal, [ Constraint::Percentage(50), Constraint::Percentage(50), ]); ```
-
c862aa5 (list) Support line alignment (#599)
The `List` widget now respects the alignment of `Line`s and renders them as expected.
-
ebf1f42 (style) Implement
From
trait for crossterm toStyle
related structs (#686) -
e49385b (table) Add a Table::segment_size method (#660)
It controls how to distribute extra space to an underconstrained table. The default, legacy behavior is to leave the extra space unused. The new options are LastTakesRemainder which gets all space to the rightmost column that can used it, and EvenDistribution which divides it amongst all columns.
-
b8f71c0 (widgets/chart) Add option to set the position of legend (#378)
-
5bf4f52 (uncategorized) Implement
From
trait for termion toStyle
related structs (#692)* feat(termion): implement from termion color * feat(termion): implement from termion style * feat(termion): implement from termion `Bg` and `Fg`
-
d19b266 (uncategorized) Add Constraint helpers (e.g. from_lengths) (#641)
Adds helper methods that convert from iterators of u16 values to the specific Constraint type. This makes it easy to create constraints like: ```rust // a fixed layout let constraints = Constraint::from_lengths([10, 20, 10]); // a centered layout let constraints = Constraint::from_ratios([(1, 4), (1, 2), (1, 4)]); let constraints = Constraint::from_percentages([25, 50, 25]); // a centered layout with a minimum size let constraints = Constraint::from_mins([0, 100, 0]); // a sidebar / main layout with maximum sizes let constraints = Constraint::from_maxes([30, 200]); ```
-
f69d57c (rect) Fix underflow in the
Rect::intersection
method (#678) -
56fc410 (block) Make
inner
aware of title positions (#657)Previously, when computing the inner rendering area of a block, all titles were assumed to be positioned at the top, which caused the height of the inner area to be miscalculated.
-
ec7b387 (doc) Do not access deprecated
Cell::symbol
field in doc example (#626) -
37c70db (table) Add widths parameter to new() (#664) [breaking]
This prevents creating a table that doesn't actually render anything.
-
1f88da7 (table) Fix new clippy lint which triggers on table widths tests (#630)
* fix(table): new clippy lint in 1.74.0 triggers on table widths tests
-
36d8c53 (table) Widths() now accepts AsRef<[Constraint]> (#628)
This allows passing an array, slice or Vec of constraints, which is more ergonomic than requiring this to always be a slice. The following calls now all succeed: ```rust Table::new(rows).widths([Constraint::Length(5), Constraint::Length(5)]); Table::new(rows).widths(&[Constraint::Length(5), Constraint::Length(5)]); // widths could also be computed at runtime let widths = vec![Constraint::Length(5), Constraint::Length(5)]; Table::new(rows).widths(widths.clone()); Table::new(rows).widths(&widths); ```
-
34d099c (tabs) Fixup tests broken by semantic merge conflict (#665)
Two changes without any line overlap caused the tabs tests to break
-
e4579f0 (tabs) Set the default highlight_style (#635) [breaking]
Previously the default highlight_style was set to `Style::default()`, which meant that the highlight style was the same as the normal style. This change sets the default highlight_style to reversed text.
-
28ac55b (tabs) Tab widget now supports custom padding (#629)
The Tab widget now contains padding_left and and padding_right properties. Those values can be set with functions `padding_left()`, `padding_right()`, and `padding()` which all accept `Into<Line>`. Fixes issue https://github.com/ratatui-org/ratatui/issues/502
-
df0eb1f (terminal) Insert_before() now accepts lines > terminal height and doesn't add an extra blank line (#596)
Fixes issue with inserting content with height>viewport_area.height and adds the ability to insert content of height>terminal_height - Adds TestBackend::append_lines() and TestBackend::clear_region() methods to support testing the changes
-
aaeba27 (uncategorized) Truncate table when overflow (#685)
This prevents a panic when rendering an empty right aligned and rightmost table cell
-
ffa78aa (uncategorized) Add #[must_use] to Style-moving methods (#600)
-
f767ea7 (list)
start_corner
is nowdirection
(#673)The previous name `start_corner` did not communicate clearly the intent of the method. A new method `direction` and a new enum `ListDirection` were added. `start_corner` is now deprecated
-
0576a8a (layout) To natural reading order (#681)
Structs and enums at the top of the file helps show the interaction between the types without having to find each type in between longer impl sections. Also moved the try_split function into the Layout impl as an associated function and inlined the `layout::split()` which just called try_split. This makes the code a bit more contained.
-
4be18ab (readme) Reference awesome-ratatui instead of wiki (#689)
* refactor(readme): link awesome-ratatui instead of wiki The apps wiki moved to awesome-ratatui * docs(readme): Update README.md
-
7ef0afc (widgets) Remove unnecessary dynamic dispatch and heap allocation (#597)
-
b282a06 (uncategorized) Remove items deprecated since 0.10 (#691) [breaking]
Remove `Axis::title_style` and `Buffer::set_background` which are deprecated since 0.10
-
7ced7c0 (uncategorized) Define struct WrappedLine instead of anonymous tuple (#608)
It makes the type easier to document, and more obvious for users
-
1b8b626 (examples) Add animation and FPS counter to colors_rgb (#583)
-
2169a0d (examples) Add example of half block rendering (#687)
This is a fun example of how to render big text using half blocks
-
91c67eb (github) Update code owners (#666)
onboard @Valentin271 as maintainer
-
3ec4e24 (list) Add documentation to the List widget (#669)
Adds documentation to the List widget and all its sub components like `ListState` and `ListItem`
-
9f37100 (readme) Update README.md and fix the bug that demo2 cannot run (#595)
Fixes https://github.com/ratatui-org/ratatui/issues/594
-
2a87251 (security) Add security policy (#676)
* docs: Create SECURITY.md * Update SECURITY.md
-
a15c3b2 (uncategorized) Remove deprecated table constructor from breaking changes (#698)
-
113b4b7 (uncategorized) Rename template links to remove ratatui from name 📚 (#690)
-
211160c (uncategorized) Remove simple-tui-rs (#651)
This has not been recently and doesn't lead to good code
-
910ad00 (rustfmt) Enable format_code_in_doc_comments (#695)
This enables more consistently formatted code in doc comments, especially since ratatui heavily uses fluent setters. See https://rust-lang.github.io/rustfmt/?version=v1.6.0#format_code_in_doc_comments
-
d118565 (table) Cleanup docs and builder methods (#638)
- Refactor the `table` module for better top to bottom readability by putting types first and arranging them in a logical order (Table, Row, Cell, other). - Adds new methods for: - `Table::rows` - `Row::cells` - `Cell::new` - `Cell::content` - `TableState::new` - `TableState::selected_mut` - Makes `HighlightSpacing::should_add` pub(crate) since it's an internal detail. - Adds tests for all the new methods and simple property tests for all the other setter methods.
-
dd22e72 (uncategorized) Correct "builder methods" in docs and add
must_use
on widgets setters (#655) -
18e19f6 (uncategorized) Fix breaking changes doc versions (#639)
Moves the layout::new change to unreleasedd section and adds the table change
-
a58cce2 (uncategorized) Disable default benchmarking (#598)
Disables the default benchmarking behaviour for the lib target to fix unrecognized criterion benchmark arguments. See https://bheisler.github.io/criterion.rs/book/faq.html#cargo-bench-gives-unrecognized-option-errors-for-valid-command-line-options for details
-
59b9c32 (codecov) Adjust threshold and noise settings (#615)
Fixes https://github.com/ratatui-org/ratatui/issues/612
-
03401cd (uncategorized) Fix untrusted input in pr check workflow (#680)
Thank you so much to everyone that contributed to this release!
Here is the list of contributors who have contributed to ratatui
for the first time!
- @rikonaka
- @danny-burrows
- @SOF3
- @jan-ferdinand
- @rhaskia
- @asomers
- @progval
- @TylerBloom
- @YeungKC
- @lyuha
0.24.0 - 2023-10-23
We are excited to announce the new version of ratatui
- a Rust library that's all about cooking up TUIs 🐭
In this version, we've introduced features like window size API, enhanced chart rendering, and more.
The list of *breaking changes* can be found here
✨ Release highlights: https://ratatui.rs/highlights/v024
-
c6c3f88 (backend) Implement common traits for
WindowSize
(#586) -
d077903 (backend) Backend provides window_size, add Size struct (#276)
For image (sixel, iTerm2, Kitty...) support that handles graphics in terms of `Rect` so that the image area can be included in layouts. For example: an image is loaded with a known pixel-size, and drawn, but the image protocol has no mechanism of knowing the actual cell/character area that been drawn on. It is then impossible to skip overdrawing the area. Returning the window size in pixel-width / pixel-height, together with columns / rows, it can be possible to account the pixel size of each cell / character, and then known the `Rect` of a given image, and also resize the image so that it fits exactly in a `Rect`. Crossterm and termwiz also both return both sizes from one syscall, while termion does two. Add a `Size` struct for the cases where a `Rect`'s `x`/`y` is unused (always zero). `Size` is not "clipped" for `area < u16::max_value()` like `Rect`. This is why there are `From` implementations between the two.
-
301366c (barchart) Render charts smaller than 3 lines (#532)
The bar values are not shown if the value width is equal the bar width and the bar is height is less than one line Add an internal structure `LabelInfo` which stores the reserved height for the labels (0, 1 or 2) and also whether the labels will be shown. Fixes ratatui-org#513
-
32e4619 (block) Allow custom symbols for borders (#529) [breaking]
Adds a new `Block::border_set` method that allows the user to specify the symbols used for the border. Added two new border types: `BorderType::QuadrantOutside` and `BorderType::QuadrantInside`. These are used to draw borders using the unicode quadrant characters (which look like half block "pixels"). ``` ▛▀▀▜ ▌ ▐ ▙▄▄▟ ▗▄▄▖ ▐ ▌ ▝▀▀▘ ``` Fixes: https://github.com/ratatui-org/ratatui/issues/528 BREAKING CHANGES: - BorderType::to_line_set is renamed to to_border_set - BorderType::line_symbols is renamed to border_symbols
-
4541336 (canvas) Implement half block marker (#550)
* feat(canvas): implement half block marker A useful technique for the terminal is to use half blocks to draw a grid of "pixels" on the screen. Because we can set two colors per cell, and because terminal cells are about twice as tall as they are wide, we can draw a grid of half blocks that looks like a grid of square pixels. This commit adds a new `HalfBlock` marker that can be used in the Canvas widget and the associated HalfBlockGrid. Also updated demo2 to use the new marker as it looks much nicer. Adds docs for many of the methods and structs on canvas. Changes the grid resolution method to return the pixel count rather than the index of the last pixel. This is an internal detail with no user impact.
-
082cbcb (frame) Remove generic Backend parameter (#530) [breaking]
This change simplifies UI code that uses the Frame type. E.g.: ```rust fn draw<B: Backend>(frame: &mut Frame<B>) { // ... } ``` Frame was generic over Backend because it stored a reference to the terminal in the field. Instead it now directly stores the viewport area and current buffer. These are provided at creation time and are valid for the duration of the frame. BREAKING CHANGE: Frame is no longer generic over Backend. Code that accepted a Frame<Backend> will now need to accept a Frame.
-
d67fa2c (line) Add
Line::raw
constructor (#511)* feat(line): add `Line::raw` constructor There is already `Span::raw` and `Text::raw` methods and this commit simply adds `Line::raw` method for symmetry. Multi-line content is converted to multiple spans with the new line removed
-
cbf86da (rect) Add is_empty() to simplify some common checks (#534)
- add `Rect::is_empty()` that checks whether either height or width == 0 - refactored `Rect` into layout/rect.rs from layout.rs. No public API change as the module is private and the type is re-exported under the `layout` module.
-
15641c8 (uncategorized) Add
buffer_mut
method onFrame
✨ (#548)
-
638d596 (layout) Use LruCache for layout cache (#487)
The layout cache now uses a LruCache with default size set to 16 entries. Previously the cache was backed by a HashMap, and was able to grow without bounds as a new entry was added for every new combination of layout parameters. - Added a new method (`layout::init_cache(usize)`) that allows the cache size to be changed if necessary. This will only have an effect if it is called prior to any calls to `layout::split()` as the cache is wrapped in a `OnceLock`
-
8d507c4 (backend) Add feature flag for underline-color (#570)
Windows 7 doesn't support the underline color attribute, so we need to make it optional. This commit adds a feature flag for the underline color attribute - it is enabled by default, but can be disabled by passing `--no-default-features` to cargo. We could specically check for Windows 7 and disable the feature flag automatically, but I think it's better for this check to be done by the crossterm crate, since it's the one that actually knows about the underlying terminal. To disable the feature flag in an application that supports Windows 7, add the following to your Cargo.toml: ```toml ratatui = { version = "0.24.0", default-features = false, features = ["crossterm"] } ``` Fixes https://github.com/ratatui-org/ratatui/issues/555
-
c3155a2 (barchart) Add horizontal labels(#518)
Labels were missed in the initial implementation of the horizontal mode for the BarChart widget. This adds them. Fixes https://github.com/ratatui-org/ratatui/issues/499
-
c9b8e7c (barchart) Render value labels with unicode correctly (#515)
An earlier change introduced a bug where the width of value labels with unicode characters was incorrectly using the string length in bytes instead of the unicode character count. This reverts the earlier change.
-
c8ab2d5 (chart) Use graph style for top line (#462)
A bug in the rendering caused the top line of the chart to be rendered using the style of the chart, instead of the dataset style. This is fixed by only setting the style for the width of the text, and not the entire row.
-
0c7d547 (docs) Don't fail rustdoc due to termion (#503)
Windows cannot compile termion, so it is not included in the docs. Rustdoc will fail if it cannot find a link, so the docs fail to build on windows. This replaces the link to TermionBackend with one that does not fail during checks. Fixes https://github.com/ratatui-org/ratatui/issues/498
-
0c52ff4 (gauge) Fix gauge widget colors (#572)
The background colors of the gauge had a workaround for the issue we had with VHS / TTYD rendering the background color of the gauge. This workaround is no longer necessary in the updated versions of VHS / TTYD. Fixes https://github.com/ratatui-org/ratatui/issues/501
-
11076d0 (rect) Fix arithmetic overflow edge cases (#543)
Fixes https://github.com/ratatui-org/ratatui/issues/258
-
21303f2 (rect) Prevent overflow in inner() and area() (#523)
-
ebd3680 (stylize) Add Stylize impl for String (#466) [breaking]
Although the `Stylize` trait is already implemented for `&str` which extends to `String`, it is not implemented for `String` itself. This commit adds an impl of Stylize that returns a Span<'static> for `String` so that code can call Stylize methods on temporary `String`s. E.g. the following now compiles instead of failing with a compile error about referencing a temporary value: let s = format!("hello {name}!", "world").red(); BREAKING CHANGE: This may break some code that expects to call Stylize methods on `String` values and then use the String value later. This will now fail to compile because the String is consumed by set_style instead of a slice being created and consumed. This can be fixed by cloning the `String`. E.g.: let s = String::from("hello world"); let line = Line::from(vec![s.red(), s.green()]); // fails to compile let line = Line::from(vec![s.clone().red(), s.green()]); // works Fixes https://discord.com/channels/1070692720437383208/1072907135664529508/1148229700821450833
-
2fd85af (barchart) Simplify internal implementation (#544)
Replace `remove_invisible_groups_and_bars` with `group_ticks` `group_ticks` calculates the visible bar length in ticks. (A cell contains 8 ticks). It is used for 2 purposes: 1. to get the bar length in ticks for rendering 2. since it delivers only the values of the visible bars, If we zip these values with the groups and bars, then we will filter out the invisible groups and bars
-
27c5637 (readme) Fix links to CONTRIBUTING.md and BREAKING-CHANGES.md (#577)
-
e098731 (barchart) Add documentation to
BarChart
(#449)Add documentation to the `BarChart` widgets and its sub-modules.
-
3cf0b83 (color) Document true color support (#477)
* refactor(style): move Color to separate color mod * docs(color): document true color support
-
e5caf17 (custom_widget) Make button sticky when clicking with mouse (#561)
-
ad2dc56 (examples) Update examples readme (#576)
remove VHS bug info, tweak colors_rgb image, update some of the instructions. add demo2
-
b61f65b (examples) Update theme to Aardvark Blue (#574)
This is a nicer theme that makes the colors pop
-
61af0d9 (examples) Make custom widget example into a button (#539)
The widget also now supports mouse
-
5c785b2 (examples) Move example gifs to github (#460)
- A new orphan branch named "images" is created to store the example images
-
ca9bcd3 (examples) Add descriptions and update theme (#460)
- Use the OceanicMaterial consistently in examples
-
1e20475 (stylize) Improve docs for style shorthands (#491)
The Stylize trait was introduced in 0.22 to make styling less verbose. This adds a bunch of documentation comments to the style module and types to make this easier to discover.
-
dd9a8df (table) Add documentation for
block
andheader
methods of theTable
widget (#505) -
42f8169 (terminal) Add docs for terminal module (#486)
- moves the impl Terminal block up to be closer to the type definition
-
51fdcbe (title) Add documentation to title (#443)
This adds documentation for Title and Position
-
d4976d4 (widgets) Update the list of available widgets (#496)
-
6c7bef8 (uncategorized) Replace colons with dashes in README.md for consistency (#566)
-
88ae348 (uncategorized) Update
Frame
docstring to remove reference to generic backend (#564) -
089f8ba (uncategorized) Add double quotes to instructions for features (#560)
-
346e7b4 (uncategorized) Add summary to breaking changes (#549)
-
401a7a7 (uncategorized) Improve clarity in documentation for
Frame
andTerminal
📚 (#545) -
9cfb133 (uncategorized) Document alpha release process (#542)
Fixes https://github.com/ratatui-org/ratatui/issues/412
-
4548a9b (uncategorized) Add BREAKING-CHANGES.md (#538)
Document the breaking changes in each version. This document is manually curated by summarizing the breaking changes in the changelog.
-
c0991cc (uncategorized) Make library and README consistent (#526)
* docs: make library and README consistent Generate the bulk of the README from the library documentation, so that they are consistent using cargo-rdme. - Removed the Contributors section, as it is redundant with the github contributors list. - Removed the info about the other backends and replaced it with a pointer to the documentation. - add docsrs example, vhs tape and images that will end up in the README
-
1414fbc (uncategorized) Import prelude::* in doc examples (#490)
This commit adds `prelude::*` all doc examples and widget::* to those that need it. This is done to highlight the use of the prelude and simplify the examples. - Examples in Type and module level comments show all imports and use `prelude::*` and `widget::*` where possible. - Function level comments hide imports unless there are imports other than `prelude::*` and `widget::*`.
-
74c5244 (uncategorized) Add logo and favicon to docs.rs page (#473)
-
927a5d8 (uncategorized) Fix documentation lint warnings (#450)
-
94af2a2 (buffer) Allow with_lines to accept Vec<Into> (#494)
This allows writing unit tests without having to call set_style on the expected buffer.
-
1278131 (changelog) Make the scopes lowercase in the changelog (#479)
-
82b40be (ci) Improve checking the PR title (#464)
- Use [`action-semantic-pull-request`](https://github.com/amannn/action-semantic-pull-request) - Allow only reading the PR contents - Enable merge group
-
a20bd6a (deps) Update lru requirement from 0.11.1 to 0.12.0 (#581)
Updates the requirements on [lru](https://github.com/jeromefroe/lru-rs) to permit the latest version. - [Changelog](https://github.com/jeromefroe/lru-rs/blob/master/CHANGELOG.md) - [Commits](https://github.com/jeromefroe/lru-rs/compare/0.11.1...0.12.0) --- updated-dependencies: - dependency-name: lru dependency-type: direct:production ...
-
5213f78 (deps) Bump actions/checkout from 3 to 4 (#580)
Bumps [actions/checkout](https://github.com/actions/checkout) from 3 to 4. - [Release notes](https://github.com/actions/checkout/releases) - [Changelog](https://github.com/actions/checkout/blob/main/CHANGELOG.md) - [Commits](https://github.com/actions/checkout/compare/v3...v4) --- updated-dependencies: - dependency-name: actions/checkout dependency-type: direct:production update-type: version-update:semver-major ...
-
6cbdb06 (examples) Refactor some examples (#578)
* chore(examples): Simplify timeout calculation with `Duration::saturating_sub`
-
12f9291 (github) Create dependabot.yml (#575)
* chore: Create dependabot.yml * Update .github/dependabot.yml
-
5498a88 (spans) Remove deprecated
Spans
type (#426)The `Spans` type (plural, not singular) was replaced with a more ergonomic `Line` type in Ratatui v0.21.0 and marked deprecated byt left for backwards compatibility. This is now removed. - `Line` replaces `Spans` - `Buffer::set_line` replaces `Buffer::set_spans`
-
fbf1a45 (uncategorized) Simplify constraints (#556)
Use bare arrays rather than array refs / Vecs for all constraint examples.
-
a7bf4b3 (uncategorized) Use modern modules syntax (#492)
Move xxx/mod.rs to xxx.rs
-
af36282 (uncategorized) Only run check pr action on pull_request_target events (#485)
-
322e46f (uncategorized) Prevent PR merge with do not merge labels ♻️ (#484)
-
983ea7f (uncategorized) Fix check for if breaking change label should be added ♻️ (#483)
-
384e616 (uncategorized) Add a check for if breaking change label should be added ♻️ (#481)
-
47ae602 (uncategorized) Check that PR title matches conventional commit guidelines ♻️ (#459)
-
343c6cd (lint) Move formatting and doc checks first (#465)
Putting the formatting and doc checks first to ensure that more critical errors are caught first (e.g. a conventional commit error or typo should not prevent the formatting and doc checks from running).
-
c95a75c (makefile) Remove termion dependency from doc lint (#470)
Only build termion on non-windows targets
-
b996102 (makefile) Add format target (#468)
- add format target to Makefile.toml that actually fixes the formatting - rename fmt target to lint-format - rename style-check target to lint-style - rename typos target to lint-typos - rename check-docs target to lint-docs - add section to CONTRIBUTING.md about formatting
-
572df75 (uncategorized) Put commit id first in changelog (#463)
-
878b6fc (uncategorized) Ignore benches from code coverage (#461)
Thank you so much to everyone that contributed to this release!
Here is the list of contributors who have contributed to ratatui
for the first time!
v0.23.0 - 2023-08-28
We are thrilled to release the new version of ratatui
🐭, the official successor* of tui-rs
.
In this version, we improved the existing widgets such as Barchart
and Scrollbar
. We also made improvmements in the testing/internal APIs to provide a smoother testing/development experience. Additionally, we have addressed various bugs and implemented enhancements.
Here is a blog post that highlights the new features and breaking changes along with a retrospective about the project: https://blog.orhun.dev/ratatui-0-23-0
-
(barchart) Add direction attribute. (horizontal bars support) (#325) (0dca6a6)
* feat(barchart): Add direction attribute Enable rendering the bars horizontally. In some cases this allow us to make more efficient use of the available space.
-
(cell) Add voluntary skipping capability for sixel (#215) (e4bcf78)
> Sixel is a bitmap graphics format supported by terminals. > "Sixel mode" is entered by sending the sequence ESC+Pq. > The "String Terminator" sequence ESC+\ exits the mode. The graphics are then rendered with the top left positioned at the cursor position. It is actually possible to render sixels in ratatui with just `buf.get_mut(x, y).set_symbol("^[Pq ... ^[\")`. But any buffer covering the "image area" will overwrite the graphics. This is most likely the same buffer, even though it consists of empty characters `' '`, except for the top-left character that starts the sequence. Thus, either the buffer or cells must be specialized to avoid drawing over the graphics. This patch specializes the `Cell` with a `set_skip(bool)` method, based on James' patch: https://github.com/TurtleTheSeaHobo/tui-rs/tree/sixel-support I unsuccessfully tried specializing the `Buffer`, but as far as I can tell buffers get merged all the way "up" and thus skipping must be set on the Cells. Otherwise some kind of "skipping area" state would be required, which I think is too complicated. Having access to the buffer now it is possible to skip all cells but the first one which can then `set_symbol(sixel)`. It is up to the user to deal with the graphics size and buffer area size. It is possible to get the terminal's font size in pixels with a syscall. An image widget for ratatui that uses this `skip` flag is available at https://github.com/benjajaja/ratatu-image.
-
(list) Add option to always allocate the "selection" column width (#394) (4d70169)
* feat(list): add option to always allocate the "selection" column width Before this option was available, selecting a item in a list when nothing was selected previously made the row layout change (the same applies to unselecting) by adding the width of the "highlight symbol" in the front of the list, this option allows to configure this behavior. * style: change "highlight_spacing" doc comment to use inline code-block for reference
-
(release) Add automated nightly releases (#359) (aad164a)
* feat(release): add automated nightly releases * refactor(release): rename the alpha workflow * refactor(release): simplify the release calculation
-
(scrollbar) Add optional track symbol (#360) (1727fa5) [breaking]
The track symbol is now optional, simplifying composition with other widgets.
-
(table) Add support for line alignment in the table widget (#392) (7748720)
* feat(table): enforce line alignment in table render * test(table): add table alignment render test
-
(widgets::table) Add option to always allocate the "selection" constraint (#375) (f63ac72)
* feat(table): add option to configure selection layout changes Before this option was available, selecting a row in the table when no row was selected previously made the tables layout change (the same applies to unselecting) by adding the width of the "highlight symbol" in the front of the first column, this option allows to configure this behavior. * refactor(table): refactor "get_columns_widths" to return (x, width) and "render" to make use of that * refactor(table): refactor "get_columns_widths" to take in a selection_width instead of a boolean also refactor "render" to make use of this change * fix(table): rename "highlight_set_selection_space" to "highlight_spacing" * style(table): apply doc-comment suggestions from code review
-
(uncategorized) Expand serde attributes for
TestBuffer
(#389) (57ea871) -
(uncategorized) Add weak constraints to make rects closer to each other in size ✨ (#395) (6153371)
Also make `Max` and `Min` constraints MEDIUM strength for higher priority over equal chunks
-
(barchart) Empty groups causes panic (#333) (9c95673)
This unlikely to happen, since nobody wants to add an empty group. Even we fix the panic, things will not render correctly. So it is better to just not add them to the BarChart.
-
(block) Fixed title_style not rendered (#349) (#363) (49a82e0)
-
(cargo) Adjust minimum paste version (#348) (8db9fb4)
ratatui is using features that are currently only available in paste 1.0.2; specifying the minimum version to be 1.0 will consequently cause a compilation error if cargo is only able to use a version less than 1.0.2.
-
(example) Fix typo (#337) (daf5890)
the existential feels
-
(layout) Don't leave gaps between chunks (#408) (56455e0)
Previously the layout used the floor of the calculated start and width as the value to use for the split Rects. This resulted in gaps between the split rects. This change modifies the layout to round to the nearest column instead of taking the floor of the start and width. This results in the start and end of each rect being rounded the same way and being strictly adjacent without gaps. Because there is a required constraint that ensures that the last end is equal to the area end, there is no longer the need to fixup the last item width when the fill (as e.g. width = x.99 now rounds to x+1 not x). The colors example has been updated to use Ratio(1, 8) instead of Percentage(13), as this now renders without gaps for all possible sizes, whereas previously it would have left odd gaps between columns.
-
(layout) Ensure left <= right (#410) (f4ed3b7)
The recent refactor missed the positive width constraint
-
(release) Fix the last tag retrieval for alpha releases (#416) (b6b2da5)
-
(release) Set the correct permissions for creating alpha releases (#400) (778c320)
-
(scrollbar) Move symbols to symbols module (#330) (7539f77) [breaking]
The symbols and sets are moved from `widgets::scrollbar` to `symbols::scrollbar`. This makes it consistent with the other symbol sets and allows us to make the scrollbar module private rather than re-exporting it.
-
(table) Fix unit tests broken due to rounding (#419) (dc55211)
The merge of the table unit tests after the rounding layout fix was not rebased correctly, this addresses the broken tests, makes them more concise while adding comments to help clarify that the rounding behavior is working as expected.
-
(uncategorized) Correct minor typos in documentation (#331) (13fb11a)
-
(barchart) Reduce some calculations (#430) (fc727df)
Calculating the label_offset is unnecessary, if we just render the group label after rendering the bars. We can just reuse bar_y.
-
(layout) Simplify and doc split() (#405) (de25de0)
* test(layout): add tests for split() * refactor(layout): simplify and doc split() This is mainly a reduction in density of the code with a goal of improving mainatainability so that the algorithm is clear.
-
(layout) Simplify split() function (#396) (5195099)
Removes some unnecessary code and makes the function more readable. Instead of creating a temporary result and mutating it, we just create the result directly from the list of changes.
-
(examples) Fix the instructions for generating demo GIF (#442) (7a70602)
-
(examples) Show layout constraints (#393) (10dbd6f)
Shows the way that layout constraints interact visually ![example](https://vhs.charm.sh/vhs-1ZNoNLNlLtkJXpgg9nCV5e.gif)
-
(examples) Add color and modifiers examples (#345) (6ad4bd4)
The intent of these examples is to show the available colors and modifiers. - added impl Display for Color ![colors](https://vhs.charm.sh/vhs-2ZCqYbTbXAaASncUeWkt1z.gif) ![modifiers](https://vhs.charm.sh/vhs-2ovGBz5l3tfRGdZ7FCw0am.gif)
-
(examples) Update block example (#351) (554805d)
![Block example](https://vhs.charm.sh/vhs-5X6hpReuDBKjD6hLxmDQ6F.gif)
-
(examples) Add examples readme with gifs (#303) (add578a)
This commit adds a readme to the examples directory with gifs of each example. This should make it easier to see what each example does without having to run it. I modified the examples to fit better in the gifs. Mostly this was just removing the margins, but for the block example I cleaned up the code a bit to make it more readable and changed it so the background bug is not triggered. For the table example, the combination of Min, Length, and Percent constraints was causing the table to panic when the terminal was too small. I changed the example to use the Max constraint instead of the Length constraint. The layout example now shows information about how the layout is constrained on each block (which is now a paragraph with a block).
-
(layout::Constraint) Add doc-comments for all variants (#371) (c8ddc16)
-
(lib) Extract feature documentation from Cargo.toml (#438) (8b36683)
* docs(lib): extract feature documentation from Cargo.toml * chore(deps): make `document-features` optional dependency * docs(lib): document the serde feature from features section
-
(project) Make the project description cooler (#441) (47fe4ad)
* docs(project): make the project description cooler * docs(lib): simplify description
-
(readme) Fix widget docs links (#346) (2920e04)
Add scrollbar, clear. Fix Block link. Sort
-
(uncategorized) Improve scrollbar doc comment (#329) (c3f87f2)
-
(bench) Used
iter_batched
to clone widgets in setup function (#383) (149d489)Replaced `Bencher::iter` by `Bencher::iter_batched` to clone the widget in the setup function instead of in the benchmark timing.
-
(paragraph) Add documentation for "scroll"'s "offset" (#355) (ab5e616)
* style(paragraph): add documentation for "scroll"'s "offset" * style(paragraph): add more text to the scroll doc-comment
-
(block) Add benchmarks (#368) (e18393d)
Added benchmarks to the block widget to uncover eventual performance issues
-
(canvas) Add unit tests for line (#437) (ad3413e)
Also add constructor to simplify creating lines
-
(list) Added benchmarks (#377) (664fb4c)
Added benchmarks for the list widget (render and render half scrolled)
-
(sparkline) Added benchmark (#384) (3293c6b)
Added benchmark for the `sparkline` widget testing a basic render with different amount of data
-
(styled_grapheme) Test StyledGrapheme methods (#433) (292a11d)
-
(table) Add test for consistent table-column-width (#404) (4cd843e)
-
(test_backend) Add tests for TestBackend coverage (#434) (b35f19e)
These are mostly to catch any future bugs introduced in the test backend
-
(changelog) Show full commit message (#423) (a937500)
This allows someone reading the changelog to search for information about breaking changes or implementation of new functionality. - refactored the commit template part to a macro instead of repeating it - added a link to the commit and to the release - updated the current changelog for the alpha and unreleased changes - Automatically changed the existing * lists to - lists
-
(codecov) Fix yaml syntax (#407) (ea48af1)
a yaml file cannot contain tabs outside of strings
-
(docs) Add doc comment bump to release documentation (#382) (8b28672)
-
(github) Rename
tui-rs-revival
references toratatui-org
(#340) (964190a) -
(make) Add task descriptions to Makefile.toml (#398) (268bbed)
-
(toolchain) Bump msrv to 1.67 (#361) (8cd3205) [breaking]
* chore(toolchain)!: bump msrv to 1.67
-
(traits) Add Display and FromStr traits (#425) (98155dc)
Use strum for most of these, with a couple of manual implementations, and related tests
-
(uncategorized) Use vhs to create demo.gif (#390) (8c55158)
The bug that prevented braille rendering is fixed, so switch to VHS for rendering the demo gif ![Demo of Ratatui](https://vhs.charm.sh/vhs-tF0QbuPbtHgUeG0sTVgFr.gif)
-
(uncategorized) Implement
Hash
common traits (#381) (8c4a2e0)Reorder the derive fields to be more consistent: Debug, Default, Clone, Copy, Eq, PartialEq, Ord, PartialOrd, Hash Hash trait won't be impl in this PR due to rust std design. If we need hash trait for f64 related structs in the future, we should consider wrap f64 into a new type.
-
(uncategorized) Implement
Eq & PartialEq
common traits (#357) (181706c)Reorder the derive fields to be more consistent: Debug, Default, Clone, Copy, Eq, PartialEq, Ord, PartialOrd, Hash
-
(uncategorized) Implement
Clone & Copy
common traits (#350) (440f62f)Implement `Clone & Copy` common traits for most structs in src. Only implement `Copy` for structs that are simple and trivial to copy. Reorder the derive fields to be more consistent: Debug, Default, Clone, Copy, Eq, PartialEq, Ord, PartialOrd, Hash
-
(uncategorized) Implement
Debug & Default
common traits (#339) (bf49446)Implement `Debug & Default` common traits for most structs in src. Reorder the derive fields to be more consistent: Debug, Default, Clone, Copy, Eq, PartialEq, Ord, PartialOrd, Hash
-
(examples) Fix cargo make run-examples (#327) (e2cb11c)
Enables the all-widgets feature so that the calendar example runs correctly
-
(uncategorized) Forbid unsafe code (#332) (0fb1ed8)
This indicates good (high level) code and is used by tools like cargo-geiger.
-
(coverage) Exclude examples directory from coverage (#373) (de9f52f)
-
(uncategorized) Don't fail fast (#364) (9191ad6)
Run all the tests rather than canceling when one test fails. This allows us to see all the failures, rather than just the first one if there are multiple. Specifically this is useful when we have an issue in one toolchain or backend.
Thank you so much to everyone that contributed to this release!
Here is the list of contributors who have contributed to ratatui
for the first time!
- @EdJoPaTo
- @mhovd
- @joshrotenberg
- @t-nil
- @ndd7xv
- @TieWay59
- @Valentin271
- @hasezoey
- @jkcdarunday
- @stappersg
- @benjajaja
- (barchart) Set custom text value in the bar (#309)
- (barchart) Enable barchart groups (#288)
- (block) Support for having more than one title (#232)
- (examples) User_input example cursor movement (#302)
- (misc) Make builder fn const (#275) (#275)
- (prelude) Add a prelude (#304)
- (style) Enable setting the underline color for crossterm (#308) (#310)
- (style) Allow Modifiers add/remove in const (#287)
- (stylize) Allow all widgets to be styled (#289)
- (terminal) Expose 'swap_buffers' method
- (uncategorized) Stylization shorthands (#283)
- (uncategorized) Add scrollbar widget (#228)
- (clippy) Unused_mut lint for layout (#285)
- (examples) Correct progress label in gague example (#263)
- (layout) Cap Constraint::apply to 100% length (#264)
- (lint) Suspicious_double_ref_op is new in 1.71 (#311)
- (prelude) Remove widgets module from prelude (#317)
- (title) Remove default alignment and position (#323)
- (typos) Configure typos linter (#233)
- (uncategorized) Rust-tui-template became a revival project (#320)
- (uncategorized) Revert removal of WTFPL from deny.toml (#266)
- (color) Parse more color formats and add docs (#306)
- (lib) Add
tui-term
a pseudoterminal library (#268) - (lib) Fixup tui refs in widgets/mod.rs (#216)
- (lib) Add backend docs (#213)
- (readme) Remove duplicated mention of tui-rs-tree-widgets (#223)
- (uncategorized) Improve CONTRIBUTING.md (#277)
- (uncategorized) Fix scrollbar ascii illustrations and calendar doc paths (#272)
- (uncategorized) README tweaks (#225)
- (uncategorized) Add CODEOWNERS file (#212)
- (uncategorized) Update README.md and add hello_world example (#204)
- (comments) Set comment length to wrap at 100 chars (#218)
- (config) Apply formatting to config files (#238)
- (manifest) Apply formatting to Cargo.toml (#237)
- (readme) Update the style of badges in README.md (#299)
- (widget) Inline format arguments (#279)
- (uncategorized) Fix formatting (#292)
- (uncategorized) Reformat imports (#219)
- (barchart) Add unit tests (#301)
- (paragraph) Simplify paragraph benchmarks (#282)
- (uncategorized) Add benchmarks for paragraph (#262)
- (ci) Bump cargo-make version (#239)
- (ci) Enable merge queue for builds (#235)
- (ci) Integrate cargo-deny for linting dependencies (#221)
- (commitizen) Add commitizen config (#222)
- (demo) Update demo gif (#234)
- (demo) Update demo gif with a fixed unicode gauge (#227)
- (features) Enable building with all-features (#286)
- (github) Add EditorConfig config (#300)
- (github) Simplify the CODEOWNERS file (#271)
- (github) Add pull request template (#269)
- (github) Fix the syntax in CODEOWNERS file (#236)
- (license) Add Ratatui developers to license (#297)
- (tests) Add coverage job to bacon (#312)
- (uncategorized) Lint and doc cleanup (#191)
- (deps) Upgrade bitflags to 2.3 (#205) [breaking]
- (uncategorized) Add git pre-push hooks using cargo-husky (#274)
- (makefile) Split CI jobs (#278)
- (uncategorized) Parallelize CI jobs (#318)
- (uncategorized) Add feat-wrapping on push and on pull request ci triggers (#267)
- (uncategorized) Add code coverage action (#209)
Thank you so much to everyone that contributed to this release!
Here is the list of contributors who have contributed to ratatui
for the first time!
- @Nydragon
- @snpefk
- @Philipp-M
- @mrbcmorris
- @endepointe
- @kdheepak
- @samyosm
- @SLASHLogin
- @karthago1
- @BoolPurist
- @Nogesma
- (backend) Add termwiz backend and example (#5)
- (block) Support placing the title on bottom (#36)
- (border) Add border! macro for easy bitflag manipulation (#11)
- (calendar) Add calendar widget (#138)
- (color) Add
FromStr
implementation forColor
(#180) - (list) Add len() to List (#24)
- (paragraph) Allow Lines to be individually aligned (#149)
- (sparkline) Finish #1 Sparkline directions PR (#134)
- (terminal) Add inline viewport (#114) [breaking]
- (test) Expose test buffer (#160)
- (text) Add
Masked
to display secure data (#168) [breaking] - (widget) Add circle widget (#159)
- (widget) Add style methods to Span, Spans, Text (#148)
- (widget) Support adding padding to Block (#20)
- (widget) Add offset() and offset_mut() for table and list state (#12)
- (canvas) Use full block for Marker::Block (#133) [breaking]
- (example) Update input in examples to only use press events (#129)
- (uncategorized) Cleanup doc example (#145)
- (reflow) Remove debug macro call (#198)
- (example) Remove redundant
vec![]
inuser_input
example (#26) - (example) Refactor paragraph example (#152)
- (style) Mark some Style fns const so they can be defined globally (#115)
- (text) Replace
Spans
withLine
(#178)
- (apps) Fix rsadsb/adsb_deku radar link (#140)
- (apps) Add tenere (#141)
- (apps) Add twitch-tui (#124)
- (apps) Add oxycards (#113)
- (apps) Re-add trippy to APPS.md (#117)
- (block) Add example for block.inner (#158)
- (changelog) Update the empty profile link in contributors (#112)
- (readme) Fix small typo in readme (#186)
- (readme) Add termwiz demo to examples (#183)
- (readme) Add acknowledgement section (#154)
- (readme) Update project description (#127)
- (uncategorized) Scrape example code from examples/* (#195)
- (apps) Update the style of application list (#184)
- (readme) Update project introduction in README.md (#153)
- (uncategorized) Clippy's variable inlining in format macros
- (buffer) Add
assert_buffer_eq!
and Debug implementation (#161) - (list) Add characterization tests for list (#167)
- (widget) Add unit tests for Paragraph (#156)
- (uncategorized) Bump MSRV to 1.65.0 (#171)
- (uncategorized) Add ci, build, and revert to allowed commit types
Thank you so much to everyone that contributed to this release!
Here is the list of contributors who have contributed to ratatui
for the first time!
- @kpcyrd
- @fujiapple852
- @BrookJeynes
- @Ziqi-Yang
- @Xithrius
- @lesleyrs
- @pythops
- @wcampbell0x2a
- @sophacles
- @Eyesonjune18
- @a-kenji
- @TimerErTim
- @Mehrbod2002
- @thomas-mauran
- @nyurik
- (style) Bold needs a bit (#104)
Thank you so much to everyone that contributed to this release!
This marks the first release of ratatui
, a community-maintained fork of tui.
The purpose of this release is to include bug fixes and small changes into the repository thus no new features are added. We have transferred all the pull requests from the original repository and worked on the low hanging ones to incorporate them in this "maintenance" release.
Here is a list of changes:
- (cd) Add continuous deployment workflow (#93)
- (ci) Add MacOS to CI (#60)
- (widget) Add
offset()
toTableState
(#10) - (widget) Add
width()
to ListItem (#17)
- (ci) Test MSRV compatibility on CI (#85)
- (ci) Bump Rust version to 1.63.0 (#80)
- (ci) Use env for the cargo-make version (#76)
- (ci) Fix deprecation warnings on CI (#58)
- (doc) Add 3rd party libraries accidentally removed at #21 (#61)
- (widget) List should not ignore empty string items (#42) [breaking]
- (uncategorized) Cassowary/layouts: add extra constraints for fixing Min(v)/Max(v) combination. (#31)
- (uncategorized) Fix user_input example double key press registered on windows
- (uncategorized) Ignore zero-width symbol on rendering
Paragraph
- (uncategorized) Fix typos (#45)
- (uncategorized) Fix typos (#47)
- (style) Make bitflags smaller (#13)
- (apps) Move 'apps using ratatui' to dedicated file (#98) (#99)
- (canvas) Add documentation for x_bounds, y_bounds (#35)
- (contributing) Specify the use of unsafe for optimization (#67)
- (github) Remove pull request template (#68)
- (readme) Update crate status badge (#102)
- (readme) Small edits before first release (#101)
- (readme) Add install instruction and update title (#100)
- (readme) Add systeroid to application list (#92)
- (readme) Add glicol-cli to showcase list (#95)
- (readme) Add oxker to application list (#74)
- (readme) Add app kubectl-watch which uses tui (#73)
- (readme) Add poketex to 'apps using tui' in README (#64)
- (readme) Update README.md (#39)
- (readme) Update README.md (#40)
- (readme) Clarify README.md fork status update
- (uncategorized) Fix: fix typos (#90)
- (uncategorized) Update to build more backends (#81)
- (uncategorized) Expand "Apps" and "Third-party" sections (#21)
- (uncategorized) Add tui-input and update xplr in README.md
- (uncategorized) Add hncli to list of applications made with tui-rs (#41)
- (uncategorized) Updated readme and contributing guide with updates about the fork (#46)
- (layout) Better safe shared layout cache (#62)
- (cargo) Update project metadata (#94)
- (ci) Integrate
typos
for checking typos (#91) - (ci) Change the target branch to main (#79)
- (ci) Re-enable clippy on CI (#59)
- (uncategorized) Integrate
committed
for checking conventional commits (#77) - (uncategorized) Update
rust-version
to 1.59 in Cargo.toml (#57) - (uncategorized) Update deps (#51)
- (uncategorized) Fix typo in layout.rs (#619)
- (uncategorized) Add apps using
tui
Thank you so much to everyone that contributed to this release!
- @orhun
- @mindoodoo
- @sayanarijit
- @Owletti
- @UncleScientist
- @rhysd
- @ckaznable
- @imuxin
- @mrjackwills
- @conradludgate
- @kianmeng
- @chaosprint
And most importantly, special thanks to Florian Dehau for creating this awesome library 💖 We look forward to building on the strong foundations that the original crate laid out.
- Bump
crossterm
to0.25
- Update
crossterm
to0.23
- Add option to
widgets::List
to repeat the highlight symbol for each line of multi-line items (#533). - Add option to control the alignment of
Axis
labels in theChart
widget (#568).
- The minimum supported rust version is now
1.56.1
.
crossterm
is now the default backend. If you are already using thecrossterm
backend, you can simplify your dependency specification inCargo.toml
:
- tui = { version = "0.16", default-features = false, features = ["crossterm"] }
+ tui = "0.17"
If you are using the termion
backend, your Cargo
is now a bit more verbose:
- tui = "0.16"
+ tui = { version = "0.17", default-features = false, features = ["termion"] }
crossterm
has also been bumped to version 0.22
.
Because of their apparent low usage, curses
and rustbox
backends have been removed.
If you are using one of them, you can import their last implementation in your own project:
- Labels of the
Canvas
widget are nowtext::Spans
. The signature ofwidgets::canvas::Context::print
has thus been updated:
- ctx.print(x, y, "Some text", Color::Yellow);
+ ctx.print(x, y, Span::styled("Some text", Style::default().fg(Color::Yellow)))
- Update
crossterm
to0.20
. - Add
From<Cow<str>>
implementation fortext::Text
(#471). - Add option to right or center align the title of a
widgets::Block
(#462).
- Apply label style in
widgets::Gauge
and avoid panics because of overflows with long labels (#494). - Avoid panics because of overflows with long axis labels in
widgets::Chart
(#512). - Fix computation of column widths in
widgets::Table
(#514). - Fix panics because of invalid offset when input changes between two frames in
widgets::List
andwidgets::Chart
(#516).
- Update
crossterm
to0.19
. - Update
rand
to0.8
. - Add a read-only view of the terminal state after the draw call (#440).
- Remove compile warning in
TestBackend::assert_buffer
(#466).
The Table
widget got a lot of improvements that should make it easier to work with:
- It should not longer panic when rendered on small areas.
Row
s are now a collection ofCell
s, themselves wrapping aText
. This means you can style the entireTable
, an entireRow
, an entireCell
and rely on the styling capabilities ofText
to get full control over the look of yourTable
.Row
s can have multiple lines.- The header is now optional and is just another
Row
always visible at the top. Row
s can have a bottom margin.- The header alignment is no longer off when an item is selected.
Taking the example of the code in examples/demo/ui.rs
, this is what you may have to change:
let failure_style = Style::default()
.fg(Color::Red)
.add_modifier(Modifier::RAPID_BLINK | Modifier::CROSSED_OUT);
- let header = ["Server", "Location", "Status"];
let rows = app.servers.iter().map(|s| {
let style = if s.status == "Up" {
up_style
} else {
failure_style
};
- Row::StyledData(vec![s.name, s.location, s.status].into_iter(), style)
+ Row::new(vec![s.name, s.location, s.status]).style(style)
});
- let table = Table::new(header.iter(), rows)
+ let table = Table::new(rows)
+ .header(
+ Row::new(vec!["Server", "Location", "Status"])
+ .style(Style::default().fg(Color::Yellow))
+ .bottom_margin(1),
+ )
.block(Block::default().title("Servers").borders(Borders::ALL))
- .header_style(Style::default().fg(Color::Yellow))
.widths(&[
Constraint::Length(15),
Constraint::Length(15),
Here, we had to:
- Change the way we construct
Row
which is no longer anenum
but astruct
. It accepts anything that can be converted to an iterator of things that can be converted to aCell
- The header is no longer a required parameter so we use
Table::header
to set it.Table::header_style
has been removed since the style can be directly set usingRow::style
. In addition, we want to preserve the old margin between the header and the rest of the rows so we add a bottom margin to the header usingRow::bottom_margin
.
You may want to look at the documentation of the different types to get a better understanding:
- Fix handling of Non Breaking Space (NBSP) in wrapped text in
Paragraph
widget.
- Add
Style::reset
to create aStyle
resetting all styling properties when applied. - Add an option to render the
Gauge
widget with unicode blocks. - Manage common project tasks with
cargo-make
rather thanmake
for easier on-boarding.
- Add
LineGauge
widget which is a more compact variant of the existingGauge
. - Bump
crossterm
to 0.18
- Take into account the borders of the
Table
widget when the widths of columns is controlled byPercentage
andRatio
constraints.
- Make it easier to work with string with multiple lines in
Text
(#361).
- Fix a style leak in
Graph
so components drawn on top of the plotted data (i.e legend and axis titles) are not affected by the style of theDataset
s (#388). - Make sure
BarChart
shows bars with the max height only when the plotted data is actually equal to the max (#383).
- Add the dot character as a new type of canvas marker (#350).
- Support more style modifiers on Windows (#368).
- Clearing the terminal through
Terminal::clear
will cause the whole UI to be redrawn (#380). - Fix incorrect output when the first diff to draw is on the second cell of the terminal (#347).
A new method has been added to Frame
called set_cursor
. It lets you specify where the cursor
should be placed after the draw call. Furthermore like any other widgets, if you do not set a cursor
position during a draw call, the cursor is automatically hidden.
For example:
fn draw_input(f: &mut Frame, app: &App) {
if app.editing {
let input_width = app.input.width() as u16;
// The cursor will be placed just after the last character of the input
f.set_cursor((input_width + 1, 0));
} else {
// We are no longer editing, the cursor does not have to be shown, set_cursor is not called and
// thus automatically hidden.
}
}
In order to make this possible, the draw closure takes in input &mut Frame
instead of mut Frame
.
It has been reported several times that the text styling capabilities were somewhat limited in many places of the crate. To solve the issue, this release includes a new set of text primitives that are now used by a majority of widgets to provide flexible text styling.
Text
is replaced by the following types:
Span
: a string with a unique style.Spans
: a string with multiple styles.Text
: a multi-lines string with multiple styles.
However, you do not always need this complexity so the crate provides From
implementations to
let you use simple strings as a default and switch to the previous primitives when you need
additional styling capabilities.
For example, the title of a Block
can be set in the following ways:
// A title with no styling
Block::default().title("My title");
// A yellow title
Block::default().title(Span::styled("My title", Style::default().fg(Color::Yellow)));
// A title where "My" is bold and "title" is a simple string
Block::default().title(vec![
Span::styled("My", Style::default().add_modifier(Modifier::BOLD)),
Span::from("title")
]);
Buffer::set_spans
andBuffer::set_span
were added.Paragraph::new
expects an input that can be converted to aText
.Block::title_style
is deprecated.Block::title
expects aSpans
.Tabs
expects a list ofSpans
.Gauge
custom label is now aSpan
.Axis
title and labels areSpans
(as a consequenceChart
no longer has generic bounds).
Previously Style
was used to represent an exhaustive set of style rules to be applied to an UI
element. It implied that whenever you wanted to change even only one property you had to provide the
complete style. For example, if you had a Block
where you wanted to have a green background and
a title in bold, you had to do the following:
let style = Style::default().bg(Color::Green);
Block::default()
.style(style)
.title("My title")
// Here we reused the style otherwise the background color would have been reset
.title_style(style.modifier(Modifier::BOLD));
In this new release, you may now write this as:
Block::default()
.style(Style::default().bg(Color::Green))
// The style is not overridden anymore, we simply add new style rule for the title.
.title(Span::styled("My title", Style::default().add_modifier(Modifier::BOLD)))
In addition, the crate now provides a method patch
to combine two styles into a new set of style
rules:
let style = Style::default().modifier(Modifier::BOLD);
let style = style.patch(Style::default().add_modifier(Modifier::ITALIC));
// style.modifier == Modifier::BOLD | Modifier::ITALIC, the modifier has been enriched not overridden
Style::modifier
has been removed in favor ofStyle::add_modifier
andStyle::remove_modifier
.Buffer::set_style
has been added.Buffer::set_background
is deprecated.BarChart::style
no longer set the style of the bars. UseBarChart::bar_style
in replacement.Gauge::style
no longer set the style of the gauge. UseGauge::gauge_style
in replacement.
The List
widget has been refactored once again to support items with variable heights and complex
styling.
List::new
expects an input that can be converted to aVec<ListItem>
whereListItem
is a wrapper around the item content to provide additional styling capabilities.ListItem
contains aText
.List::items
has been removed.
// Before
let items = vec![
"Item1",
"Item2",
"Item3"
];
List::default().items(items.iters());
// After
let items = vec![
ListItem::new("Item1"),
ListItem::new("Item2"),
ListItem::new("Item3"),
];
List::new(items);
See the examples for more advanced usages.
Paragraph::wrap
expects Wrap
instead of bool
to let users decided whether they want to trim
whitespaces when the text is wrapped.
// before
Paragraph::new(text).wrap(true)
// after
Paragraph::new(text).wrap(Wrap { trim: true }) // to have the same behavior
Paragraph::new(text).wrap(Wrap { trim: false }) // to use the new behavior
You can now scroll horizontally in Paragraph
. The argument of Paragraph::scroll
has thus be
changed from u16
to (u16, u16)
.
You can now serialize and de-serialize Style
using the optional serde
feature.
- Fix out of bounds panic in
widgets::Tabs
when the widget is rendered on small areas.
- Ignore zero-width graphemes in
Buffer::set_stringn
.
- Fix usize overflows in
widgets::Chart
when a dataset is empty.
- Fix usize overflows in
widgets::canvas::Line
drawing algorithm.
- The
List
widget now takes into account the width of thehighlight_symbol
when calculating the total width of its items. It prevents items to overflow outside of the widget area.
- Introduce stateful widgets, i.e widgets that can take advantage of keeping some state around between two draw calls (#210 goes a bit more into the details).
- Allow a
Table
row to be selected.
// State initialization
let mut state = TableState::default();
// In the terminal.draw closure
let header = ["Col1", "Col2", "Col"];
let rows = [
Row::Data(["Row11", "Row12", "Row13"].into_iter())
];
let table = Table::new(header.into_iter(), rows.into_iter());
f.render_stateful_widget(table, area, &mut state);
// In response to some event:
state.select(Some(1));
-
Add a way to choose the type of border used to draw a block. You can now choose from plain, rounded, double and thick lines.
-
Add a
graph_type
property on theDataset
of aChart
widget. By default it will beScatter
where the points are drawn as is. An other option isLine
where a line will be draw between each consecutive points of the dataset. -
Style methods are now const, allowing you to initialize const
Style
objects. -
Improve control over whether the legend in the
Chart
widget is shown or not. You can now set custom constraints usingChart::hidden_legend_constraints
. -
Add
Table::header_gap
to add some space between the header and the first row. -
Remove
log
from the dependencies -
Add a way to use a restricted set of unicode symbols in several widgets to improve portability in exchange of a degraded output. (see
BarChart::bar_set
,Sparkline::bar_set
andCanvas::marker
). You can check how the--enhanced-graphics
flag is used in the demos.
Widget::render
has been deleted. You should now useFrame::render_widget
to render a widget on the correspondingFrame
. This makes theWidget
implementation totally decoupled from theFrame
.
// Before
Block::default().render(&mut f, size);
// After
let block = Block::default();
f.render_widget(block, size);
Widget::draw
has been renamed toWidget::render
and the signature has been updated to reflect that widgets are consumable objects. Thus the method takesself
instead of&mut self
.
// Before
impl Widget for MyWidget {
fn draw(&mut self, area: Rect, buf: &mut Buffer) {
}
}
/// After
impl Widget for MyWidget {
fn render(self, arera: Rect, buf: &mut Buffer) {
}
}
Widget::background
has been replaced byBuffer::set_background
// Before
impl Widget for MyWidget {
fn render(self, arera: Rect, buf: &mut Buffer) {
self.background(area, buf, self.style.bg);
}
}
// After
impl Widget for MyWidget {
fn render(self, arera: Rect, buf: &mut Buffer) {
buf.set_background(area, self.style.bg);
}
}
-
Update the
Shape
trait for objects that can be draw on aCanvas
widgets. Instead of returning an iterator over its points, aShape
is given aPainter
object that provides apaint
as well as aget_point
method. This gives theShape
more information about the surface it will be drawn to. In particular, this change allows theLine
shape to use a more precise and efficient drawing algorithm (Bresenham's line algorithm). -
SelectableList
has been deleted. You can now take advantage of the associatedListState
of theList
widget to select an item.
// Before
List::new(&["Item1", "Item2", "Item3"])
.select(Some(1))
.render(&mut f, area);
// After
// State initialization
let mut state = ListState::default();
// In the terminal.draw closure
let list = List::new(&["Item1", "Item2", "Item3"]);
f.render_stateful_widget(list, area, &mut state);
// In response to some events
state.select(Some(1));
widgets::Marker
has been moved tosymbols::Marker
- Bump crossterm to 0.14.
- Add cross symbol to the symbols list.
- Use the value of
title_style
to style the title ofAxis
.
- Use
Constraint
instead of integers to specify the widths of theTable
widget's columns. This will allow more responsive tables.
Table::new(header, row)
.widths(&[15, 15, 10])
.render(f, chunk);
becomes:
Table::new(header, row)
.widths(&[
Constraint::Length(15),
Constraint::Length(15),
Constraint::Length(10),
])
.render(f, chunk);
- Bump crossterm to 0.13.
- Use Github Actions for CI (Travis and Azure Pipelines integrations have been deleted).
- Add support for horizontal and vertical margins in
Layout
.
Text
implements PartialEq
- Avoid overflow errors in canvas
- Avoid a division by zero when all values in a barchart are equal to 0.
- Fix the inverted cursor position in the curses backend.
- Ensure that the correct terminal size is returned when using the crossterm backend.
- Avoid highlighting the separator after the selected item in the Tabs widget.
- Update crossterm backend
- Fix a panic in the Sparkline widget
- Add a new curses backend (with Windows support thanks to
pancurses
). - Add
Backend::get_cursor
andBackend::set_cursor
methods to query and set the position of the cursor. - Add more constructors to the
Crossterm
backend. - Add a demo for all backends using a shared UI and application state.
- Add
Ratio
as a new variant of layoutConstraint
. It can be used to define exact ratios constraints.
- Add support for multiple modifiers on the same
Style
by changingModifier
from an enum to a bitflags struct.
So instead of writing:
let style = Style::default().add_modifier(Modifier::Italic);
one should use:
let style = Style::default().add_modifier(Modifier::ITALIC);
// or
let style = Style::default().add_modifier(Modifier::ITALIC | Modifier::BOLD);
- Ensure correct behavior of the alternate screens with the
Crossterm
backend. - Fix out of bounds panic when two
Buffer
are merged.
- Add a new canvas shape:
Rectangle
. - Official support of
Crossterm
backend. - Make it possible to choose the divider between
Tabs
. - Add word wrapping on Paragraph.
- The gauge widget accepts a ratio (f64 between 0 and 1) in addition of a percentage.
- Upgrade to Rust 2018 edition.
- Fix rendering of double-width characters.
- Fix race condition on the size of the terminal and expose a size that is
safe to use when drawing through
Frame::size
. - Prevent unsigned int overflow on large screens.
- Add experimental test backend
show_cursor
is called whenTerminal
is dropped if the cursor is hidden.
- Remove custom
termion
backends. This is motivated by the fact thattermion
structs are meant to be combined/wrapped to provide additional functionalities to the terminal (e.g AlternateScreen, Mouse support, ...). Thus providing exclusive types do not make a lot of sense and give a false hint that additional features cannot be used together. The recommended approach is now to create your own version ofstdout
:
let stdout = io::stdout().into_raw_mode()?;
let stdout = MouseTerminal::from(stdout);
let stdout = AlternateScreen::from(stdout);
and then to create the corresponding termion
backend:
let backend = TermionBackend::new(stdout);
The resulting code is more verbose but it works with all combinations of
additional termion
features.
- Replace
Item
by a generic and flexibleText
that can be used in bothParagraph
andList
widgets. - Remove unnecessary borrows on
Style
.
- Add a basic
Crossterm
backend
- Remove
Group
and introduceLayout
in its placeTerminal
is no longer required to compute a layoutSize
has been renamedConstraint
- Widgets are rendered on a
Frame
instead of aTerminal
in order to avoid mixingdraw
andrender
calls draw
onTerminal
expects a closure where the UI is built by rendering widgets on the givenFrame
- Update
Widget
traitdraw
takes area by valuerender
takes aFrame
instead of aTerminal
- All widgets use the consumable builder pattern
SelectableList
can have no selected item and the highlight symbol is hidden in this case- Remove markup language inside
Paragraph
.Paragraph
now expects an iterator ofText
items
- Add
start_corner
option forList
- Add more text alignment options for
Paragraph
Terminal
implementsDebug
- Use
FnOnce
instead ofFnMut
in Group::render
- Add
AlternateScreenBackend
intermion
backend - Add
TermionBackend::with_stdout
in order to let an user of the library provides its own termion struct - Add tests and documentation for
Buffer::pos_of
- Remove leading whitespaces when wrapping text
- Fix
debug_assert
inBuffer::pos_of
- Pass the style of
SelectableList
to the underlyingList
- Fix missing character when wrapping text
- Fix panic when specifying layout constraints
- Add
MouseBackend
intermion
backend to handle scroll and mouse events - Add generic
Item
for items in aList
- Drop
log4rs
as a dev-dependencies in favor ofstderrlog
- Rename
TermionBackend
toRawBackend
(to distinguish it from theMouseBackend
) - Generic parameters for
List
to allow passing iterators as items - Generic parameters for
Table
to allow using iterators as rows and header - Generic parameters for
Tabs
- Rename
border
bitflags toBorders