6dcd53bc6b
This commit introduces new methods for the `Rect` struct that simplify
the process of splitting a `Rect` into sub-rects according to a given
`Layout`. By putting these methods on the `Rect` struct, we make it a
bit more natural that a layout is applied to the `Rect` itself, rather
than passing a `Rect` to the `Layout` struct to be split.
Adds:
- `Rect::layout` and `Rect::try_layout` methods that allow splitting a
`Rect` into an array of sub-rects according to a given `Layout`.
- `Rect::layout_vec` method that returns a `Vec` of sub-rects.
- `Layout::try_areas` method that returns an array of sub-rects, with
compile-time checks for the number of constraints. This is added
mainly for consistency with the new `Rect` methods.
```rust
use ratatui_core::layout::{Layout, Constraint, Rect};
let area = Rect::new(0, 0, 10, 10);
let layout = Layout::vertical([Constraint::Fill(1); 2]);
// Rect::layout() infers the number of constraints at compile time:
let [top, main] = area.layout(&layout);
// Rect::try_layout() and Layout::try_areas() do the same, but return a
// Result:
let [top, main] = area.try_layout(&layout)?;
let [top, main] = layout.try_areas(area)?;
// Rect::layout_vec() returns a Vec of sub-rects:
let areas_vec = area.layout_vec(&layout);
// you can also explicitly specify the number of constraints:
let areas = area.layout::<2>(&layout);
let areas = area.try_layout::<2>(&layout)?;
let areas = layout.try_areas::<2>(area)?;
```
Ratatui Widgets
ratatui-widgets contains all the widgets that were previously part of the Ratatui crate.
It is meant to be used in conjunction with ratatui, which provides the core functionality for
building terminal user interfaces.
Most applications shouldn't need to depend directly on ratatui-widgets, ratatui crate
re-exports all the widgets from this crate. However, if you are building a widget library that
internally uses these widgets, or if you prefer finer grained dependencies, you may want to
depend on this crate rather than transitively through the ratatui crate.
Previously, a crate named ratatui-widgets was published with some formative ideas about an
eventual Ratatui framework. That crate has now moved to tui-framework-experiment, pending a
new name.
Installation
Run the following command to add this crate to your project:
cargo add ratatui-widgets
Available Widgets
BarChart: displays multiple datasets as bars with optional grouping.Block: a basic widget that draws a block with optional borders, titles, and styles.calendar::Monthly: displays a single month.Canvas: draws arbitrary shapes using drawing characters.Chart: displays multiple datasets as lines or scatter graphs.Clear: clears the area it occupies. Useful to render over previously drawn widgets.Gauge: displays progress percentage using block characters.LineGauge: displays progress as a line.List: displays a list of items and allows selection.RatatuiLogo: displays the Ratatui logo.RatatuiMascot: displays the Ratatui mascot.Paragraph: displays a paragraph of optionally styled and wrapped text.Scrollbar: displays a scrollbar.Sparkline: displays a single dataset as a sparkline.Table: displays multiple rows and columns in a grid and allows selection.Tabs: displays a tab bar and allows selection.
All these widgets are re-exported directly under ratatui::widgets in the ratatui crate.
Crate Organization
ratatui-widgets is part of the Ratatui workspace that was modularized in version 0.30.0.
This crate contains all the built-in widget implementations that were previously part of the
main ratatui crate.
When to use ratatui-widgets:
- Building widget libraries that need to compose with built-in widgets
- You want finer-grained dependencies and only need specific widgets
- Creating custom widgets that extend or wrap the built-in ones
When to use the main ratatui crate:
- Building applications (recommended - includes everything you need)
- You want the convenience of having all widgets available
For detailed information about the workspace organization, see ARCHITECTURE.md.
Contributing
Contributions are welcome! Please open an issue or submit a pull request on GitHub. For more details on contributing, please see the CONTRIBUTING document.
License
This project is licensed under the MIT License. See the LICENSE file for details.