7bc78bca1b
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))?;
```
63 lines
2.6 KiB
Rust
63 lines
2.6 KiB
Rust
/// A Ratatui example that demonstrates a basic hello world application.
|
|
///
|
|
/// This example runs with the Ratatui library code in the branch that you are currently
|
|
/// reading. See the [`latest`] branch for the code which works with the most recent Ratatui
|
|
/// release.
|
|
///
|
|
/// [`latest`]: https://github.com/ratatui/ratatui/tree/latest
|
|
use std::time::Duration;
|
|
|
|
use color_eyre::Result;
|
|
use color_eyre::eyre::Context;
|
|
use crossterm::event::{self, KeyCode};
|
|
use ratatui::widgets::Paragraph;
|
|
use ratatui::{DefaultTerminal, Frame};
|
|
|
|
/// This is a bare minimum example. There are many approaches to running an application loop, so
|
|
/// this is not meant to be prescriptive. It is only meant to demonstrate the basic setup and
|
|
/// teardown of a terminal application.
|
|
///
|
|
/// This example does not handle events or update the application state. It just draws a greeting
|
|
/// and exits when the user presses 'q'.
|
|
fn main() -> Result<()> {
|
|
color_eyre::install()?; // augment errors / panics with easy to read messages
|
|
ratatui::run(run).context("failed to run app")
|
|
}
|
|
|
|
/// Run the application loop. This is where you would handle events and update the application
|
|
/// state. This example exits when the user presses 'q'. Other styles of application loops are
|
|
/// possible, for example, you could have multiple application states and switch between them based
|
|
/// on events, or you could have a single application state and update it based on events.
|
|
fn run(terminal: &mut DefaultTerminal) -> Result<()> {
|
|
loop {
|
|
terminal.draw(render)?;
|
|
if should_quit()? {
|
|
break;
|
|
}
|
|
}
|
|
Ok(())
|
|
}
|
|
|
|
/// Render the application. This is where you would draw the application UI. This example draws a
|
|
/// greeting.
|
|
fn render(frame: &mut Frame) {
|
|
let greeting = Paragraph::new("Hello World! (press 'q' to quit)");
|
|
frame.render_widget(greeting, frame.area());
|
|
}
|
|
|
|
/// Check if the user has pressed 'q'. This is where you would handle events. This example just
|
|
/// checks if the user has pressed 'q' and returns true if they have. It does not handle any other
|
|
/// events. There is a 250ms timeout on the event poll to ensure that the terminal is rendered at
|
|
/// least once every 250ms. This allows you to do other work in the application loop, such as
|
|
/// updating the application state, without blocking the event loop for too long.
|
|
fn should_quit() -> Result<bool> {
|
|
if event::poll(Duration::from_millis(250)).context("event poll failed")? {
|
|
let q_pressed = event::read()
|
|
.context("event read failed")?
|
|
.as_key_press_event()
|
|
.is_some_and(|key| key.code == KeyCode::Char('q'));
|
|
return Ok(q_pressed);
|
|
}
|
|
Ok(false)
|
|
}
|