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)?;
```
This introduces a new `ratatui::run()` method which runs a closure with
a terminal initialized with reasonable defaults for most applications.
This calls `ratatui::init()` before running the closure and
`ratatui::restore()` after the closure completes, and returns the result
of the closure.
A minimal hello world example using the new `ratatui::run()` method:
```rust
fn main() -> Result<(), Box<dyn std::error::Error>> {
ratatui::run(|terminal| {
loop {
terminal.draw(|frame| frame.render_widget("Hello World!", frame.area()))?;
if crossterm::event::read()?.is_key_press() {
break Ok(());
}
}
})
}
```
Of course, this also works both with apps that use free methods and
structs:
```rust
fn run(terminal: &mut DefaultTerminal) -> Result<(), AppError> { ... }
ratatui::run(run)?;
```
```rust
struct App { ... }
impl App {
fn new() -> Self { ... }
fn run(mut self, terminal: &mut DefaultTerminal) -> Result<(), AppError> { ... }
}
ratatui::run(|terminal| App::new().run(terminal))?;
```
Crossterm 0.29 introduced methods to easily check / extract the event
type. E.g. as_key_press_event() and is_key_press(). This commit
updates the examples to use these methods instead of matching on
the event type. This makes the code cleaner and easier to read.
Also does a general cleanup of the event handling code in the examples.
I was swayed by the arguments about this made by the compiler team In
<https://github.com/rust-lang/compiler-team/issues/750> and decided to
look at how this organization affects ratatui. I found this reduces the
number of lines across the codebase by about 350 and makes the imports
more readable and definitely more greppable as you usually only have
to read a single line. I've found in the past that maintaining imports
regularly leads to merge conflicts which have to be resolved by hand
and this change should reduce the likelihood of that happening.
Main change is in rustfmt.toml, and the rest is just the result of
running `cargo xtask format`.
While implementing this, cargo machete brings up that the various
backend crates are unused by the example crates.
The re-export of each backend crate under ratatui is to make it possible
for libs that rely on a specific version of ratatui to use the same
version of the backend crate. Apps in general should use the backend
crate directly rather than through ratatui as this is less confusing.
- Removes all usages of `ratatui::{crossterm, termion, termwiz}`` in the
examples.
- Adds the backend crate to the dependencies of the examples that use
the backend crate directly.
Bumps [time](https://github.com/time-rs/time) from 0.3.37 to 0.3.39.
<details>
<summary>Release notes</summary>
<p><em>Sourced from <a
href="https://github.com/time-rs/time/releases">time's
releases</a>.</em></p>
<blockquote>
<h2>v0.3.39</h2>
<p>See the <a
href="https://github.com/time-rs/time/blob/main/CHANGELOG.md">changelog</a>
for details.</p>
<h2>v0.3.38</h2>
<p>See the <a
href="https://github.com/time-rs/time/blob/main/CHANGELOG.md">changelog</a>
for details.</p>
</blockquote>
</details>
<details>
<summary>Changelog</summary>
<p><em>Sourced from <a
href="https://github.com/time-rs/time/blob/main/CHANGELOG.md">time's
changelog</a>.</em></p>
<blockquote>
<h2>0.3.39 [2025-03-06]</h2>
<h3>Fixed</h3>
<ul>
<li>Doc tests run successfully with the default feature set.</li>
<li>wasm builds work again.</li>
</ul>
<p>Both of these were regressions in v0.3.38 and are now checked in
CI.</p>
<h2>0.3.38 [2025-03-05]</h2>
<h3>Added</h3>
<ul>
<li>
<p>The <code>[year]</code> component (in format descriptions) now
supports a <code>range</code> modifier, which can be
either <code>standard</code> or <code>extended</code>. The default is
<code>extended</code> for backwards compatibility. This is
intended as a manner to opt <em>out</em> of the extended range when the
<code>large-dates</code> feature is enabled.
When the <code>large-dates</code> feature is not enabled, the modifier
has no effect.</p>
</li>
<li>
<p><code>UtcDateTime</code>, which is semantically equivalent to an
<code>OffsetDateTime</code> with UTC as its offset. The
advantage is that it is the same size as a
<code>PrimitiveDateTime</code> and has improved operability with
well-known formats.</p>
<p>As part of this, there were some other additions:</p>
<ul>
<li><code>utc_datetime!</code> macro, which is similar to the
<code>datetime!</code> macro but constructs a
<code>UtcDateTime</code>.</li>
<li><code>PrimitiveDateTime::as_utc</code></li>
<li><code>OffsetDateTime::to_utc</code></li>
<li><code>OffsetDateTime::checked_to_utc</code></li>
</ul>
</li>
<li>
<p><code>time::serde::timestamp::milliseconds_i64</code>, which is a
module to serialize/deserialize timestamps
as the Unix timestamp. The pre-existing module does this as an
<code>i128</code> where an <code>i64</code> would
suffice. This new module should be preferred.</p>
</li>
</ul>
<h3>Changed</h3>
<ul>
<li><code>error::Format</code> has had its <code>source()</code>
implementation changed to no longer return a boxed value
from the <code>ComponentRange</code> variant. If you were explicitly
expecting this, you will need to update
your code. The method API remains unchanged.</li>
<li><code>[year repr:century]</code> supports single-digit values.</li>
<li>All <code>format_into</code> methods accept <code>?Sized</code>
references.</li>
</ul>
<h3>Miscellaneous</h3>
<ul>
<li>Some non-exhaustive enum variants that are no longer used have been
modified to be statically
proven as uninhabited. The relevant fields are doc-hidden and not
semver-guaranteed to remain as
such, though it is unlikely to change.</li>
<li>An unnecessary check when parsing RFC 2822 has been removed.</li>
<li>Various methods have had their implementations changed, resulting in
significant performance
gains. Among the methods changed are
<ul>
<li><code>util::is_leap_year</code></li>
<li><code>util::weeks_in_year</code></li>
<li><code>Month::length</code></li>
<li><code>Date::to_calendar_date</code></li>
</ul>
</li>
</ul>
<!-- raw HTML omitted -->
</blockquote>
<p>... (truncated)</p>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="7949d2c2e8"><code>7949d2c</code></a>
v0.3.39 release</li>
<li><a
href="f51623b653"><code>f51623b</code></a>
Fix breakage from v0.3.38</li>
<li><a
href="1a31c0595b"><code>1a31c05</code></a>
v0.3.38 release</li>
<li><a
href="addf231ef5"><code>addf231</code></a>
Permit unsized writers for <code>format_into</code></li>
<li><a
href="338f84f545"><code>338f84f</code></a>
Allow clippy::ref_option lint for serde::format_description.</li>
<li><a
href="f8ecd81e8f"><code>f8ecd81</code></a>
feat: timestamp::milliseconds_i64 serializer</li>
<li><a
href="ce03bcab8f"><code>ce03bca</code></a>
Update Unicode license for cargo-audit</li>
<li><a
href="3d0b981381"><code>3d0b981</code></a>
Add parentheses for clarity</li>
<li><a
href="3096301eb3"><code>3096301</code></a>
Remove specific year from license</li>
<li><a
href="ec327a26db"><code>ec327a2</code></a>
Optimize Julian day calculations</li>
<li>Additional commits viewable in <a
href="https://github.com/time-rs/time/compare/v0.3.37...v0.3.39">compare
view</a></li>
</ul>
</details>
<br />
[](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores)
Dependabot will resolve any conflicts with this PR as long as you don't
alter it yourself. You can also trigger a rebase manually by commenting
`@dependabot rebase`.
[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)
---
<details>
<summary>Dependabot commands and options</summary>
<br />
You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits
that have been made to it
- `@dependabot merge` will merge this PR after your CI passes on it
- `@dependabot squash and merge` will squash and merge this PR after
your CI passes on it
- `@dependabot cancel merge` will cancel a previously requested merge
and block automerging
- `@dependabot reopen` will reopen this PR if it is closed
- `@dependabot close` will close this PR and stop Dependabot recreating
it. You can achieve the same result by closing it manually
- `@dependabot show <dependency name> ignore conditions` will show all
of the ignore conditions of the specified dependency
- `@dependabot ignore this major version` will close this PR and stop
Dependabot creating any more for this major version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this minor version` will close this PR and stop
Dependabot creating any more for this minor version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this dependency` will close this PR and stop
Dependabot creating any more for this dependency (unless you reopen the
PR or upgrade to it yourself)
</details>
Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Related to #1512
As discussed, this moves the calendar example from ratatui to app
examples as an "explorer" example. It also adds interactivity where you
can press s to toggle between different styles of calendars.
---------
Co-authored-by: Josh McKinney <joshka@users.noreply.github.com>
