Document not found (404)
+This URL is invalid, sorry. Please use the navigation bar or search to continue.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/concepts/application-patterns/flux-architecture.html b/pr-preview/pr-83/concepts/application-patterns/flux-architecture.html
new file mode 100644
index 000000000..f2e54dadc
--- /dev/null
+++ b/pr-preview/pr-83/concepts/application-patterns/flux-architecture.html
@@ -0,0 +1,281 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Component Architecture
+If you are interested in a more object oriented approach to organizing TUIs, you can use a
+Component based approach.
A couple of projects in the wild use this approach
+ +We also have a ratatui-async-template that has an example of this Component based approach:
We already covered TEA in the previous section. The Component
+architecture takes a slightly more object oriented trait based approach.
Each component encapsulates its own state, event handlers, and rendering logic.
+-
+
-
+
Component Initialization (
+init) - This is where a component can set up any initial state or +resources it needs. It’s a separate process from handling events or rendering.
+ -
+
Event Handling (
+handle_events,handle_key_events,handle_mouse_events) - Each component has +its own event handlers. This allows for a finer-grained approach to event handling, with each +component only dealing with the events it’s interested in. This contrasts with Elm’s single +update function that handles messages for the entire application.
+ -
+
State Update (
+update) - Components can have their own local state and can update it in response +to actions. This state is private to the component, which differs from Elm’s global model.
+ -
+
Rendering (
+render) - Each component defines its own rendering logic. It knows how to draw +itself, given a rendering context. This is similar to Elm’s view function but on a +component-by-component basis.
+
Here’s an example of the Component trait implementation you might use:
use anyhow::Result;
+use crossterm::event::{KeyEvent, MouseEvent};
+use ratatui::layout::Rect;
+
+use crate::{action::Action, event::Event, terminal::Frame};
+
+pub trait Component {
+ fn init(&mut self) -> Result<()> {
+ Ok(())
+ }
+ fn handle_events(&mut self, event: Option<Event>) -> Action {
+ match event {
+ Some(Event::Quit) => Action::Quit,
+ Some(Event::Tick) => Action::Tick,
+ Some(Event::Key(key_event)) => self.handle_key_events(key_event),
+ Some(Event::Mouse(mouse_event)) => self.handle_mouse_events(mouse_event),
+ Some(Event::Resize(x, y)) => Action::Resize(x, y),
+ Some(_) => Action::Noop,
+ None => Action::Noop,
+ }
+ }
+ fn handle_key_events(&mut self, key: KeyEvent) -> Action {
+ Action::Noop
+ }
+ fn handle_mouse_events(&mut self, mouse: MouseEvent) -> Action {
+ Action::Noop
+ }
+ fn update(&mut self, action: Action) -> Action {
+ Action::Noop
+ }
+ fn render(&mut self, f: &mut Frame<'_>, rect: Rect);
+}One advantage of this approach is that it incentivizes co-locating the handle_events, update and
+render functions on a component level.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/concepts/application-patterns/index.html b/pr-preview/pr-83/concepts/application-patterns/index.html
new file mode 100644
index 000000000..31a6816cf
--- /dev/null
+++ b/pr-preview/pr-83/concepts/application-patterns/index.html
@@ -0,0 +1,220 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Why
+
+
+
+
+
+ Flux Architecture
+Flux is a design pattern
+introduced by Facebook to address the challenges of building large scale web applications. Though
+originally designed with web applications in mind, the Flux architecture can be applied to any
+client-side project, including terminal applications. Here’s real world example of using the Flux
+architecture with ratatui: https://github.com/Yengas/rust-chat-server/tree/main/tui.
Why Flux for ratatui?
+Terminal applications often have to deal with complex user interactions, multiple views, and dynamic
+data sources. Keeping the application predictable and the logic decoupled is crucial. Flux, with
+its unidirectional data flow, allows ratatui developers to have a structured way to handle user
+input, process data, and update the views.
Flux ratatui Overview
+Dispatcher
+The dispatcher remains the central hub that manages all data flow in your application. Every action +in the application, whether it’s a user input or a response from a server, will be channeled through +the dispatcher. This ensures a unified way of handling data, and since the dispatcher has no logic +of its own, it simply ensures that all registered callbacks receive the action data.
+struct Dispatcher {
+ store: Store,
+}
+
+impl Dispatcher {
+ fn dispatch(&mut self, action: Action) {
+ self.store.update(action);
+ }
+}Stores
+Stores in Ratatui hold the application’s state and its logic. They could represent things like:
+-
+
- A list of items in a menu. +
- The content of a text editor or viewer. +
- User configurations or preferences. +
Stores listen for actions dispatched from the Dispatcher. When a relevant action is dispatched, the +store updates its state and notifies any listening components (or views) that a change has occurred.
+struct Store {
+ counter: i32,
+}
+
+impl Store {
+ fn new() -> Self {
+ Self { counter: 0 }
+ }
+
+ fn update(&mut self, action: Action) {
+ match action {
+ Action::Increment => self.counter += 1,
+ Action::Decrement => self.counter -= 1,
+ }
+ }
+
+ fn get_state(&self) -> i32 {
+ self.counter
+ }
+}
+Actions
+Actions represent any change or event in your application. For instance, when a user presses a key, +selects a menu item, or inputs text, an action is created. This action is dispatched and processed +by the relevant stores, leading to potential changes in application state.
+enum Action {
+ Increment,
+ Decrement,
+}Views / Widgets
+ratatui’s widgets display the application’s UI. They don’t hold or manage the application state,
+but they display it. When a user interacts with a widget, it can create an action that gets
+dispatched, which may lead to a change in a store, which in turn may lead to the widget being
+updated.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/concepts/application-patterns/the-elm-architecture.html b/pr-preview/pr-83/concepts/application-patterns/the-elm-architecture.html
new file mode 100644
index 000000000..4ce6d6730
--- /dev/null
+++ b/pr-preview/pr-83/concepts/application-patterns/the-elm-architecture.html
@@ -0,0 +1,574 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Application Patterns
+This page covers several patterns one can use for their application and acts as a top-level page for +the following articles where these patterns are gone into more in-depth.
+ + +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/concepts/backends/alternate-screen.html b/pr-preview/pr-83/concepts/backends/alternate-screen.html
new file mode 100644
index 000000000..656ffb6ff
--- /dev/null
+++ b/pr-preview/pr-83/concepts/backends/alternate-screen.html
@@ -0,0 +1,225 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Using The Elm Architecture (TEA) with
+Applying The Elm Architecture to
+
+
+
+
+ Using The Elm Architecture (TEA) with ratatui
+When building terminal user interfaces (TUI) with ratatui, it’s helpful to have a solid structure
+for organizing your application. One proven architecture comes from the Elm language, known simply
+as The Elm Architecture (TEA).
+
+
+
+
+If you are interested in a framework that uses ratatui that is based on The Elm Architecture,
+you should check out https://github.com/veeso/tui-realm/.
+The documentation on this page is for theoretical understanding and pedagogical purposes only.
In this section, we’ll explore how to apply The Elm Architecture principles to ratatui TUI apps.
The Elm Architecture: A Quick Overview
+At its core, TEA is split into three main components:
+-
+
- Model: This is your application’s state. It contains all the data your application works with. +
- Update: When there’s a change (like user input), the update function takes the current model +and the input, and produces a new model. +
- View: This function is responsible for displaying your model to the user. In Elm, it produces +HTML. In our case, it’ll produce terminal UI elements. +
sequenceDiagram +participant User +participant TUI Application + +User->>TUI Application: Input/Event/Message +TUI Application->>TUI Application: Update (based on Model and Message) +TUI Application->>TUI Application: Render View (from Model) +TUI Application-->>User: Display UI ++
Applying The Elm Architecture to ratatui
+Following TEA principles typically involves ensuring that you do the following things:
+-
+
- Define Your Model +
- Handling Updates +
- Rendering the View +
1. Define Your Model
+In ratatui, you’ll typically use a struct to represent your model:
struct Model {
+ //... your application's data goes here
+}For a counter app, our model may look like this:
+struct Model {
+ counter: i32,
+ should_quit: bool,
+}2. Handling Updates
+Updates in TEA are actions triggered by events, such as user inputs. The core idea is to map each of +these actions or events to a message. This can be achieved by creating an enum to keep track of +messages. Based on the received message, the current state of the model is used to determine the +next state.
+Defining a Message enum
enum Message {
+ //... various inputs or actions that your app cares about
+ // e.g., ButtonPressed, TextEntered, etc.
+}For a counter app, our Message enum may look like this:
enum Message {
+ Increment,
+ Decrement,
+ Reset,
+ Quit,
+}update() function
The update function is at the heart of this process. It takes the current model and a message, and +decides how the model should change in response to that message.
+A key feature of TEA is immutability. Hence, the update function should avoid direct mutation of the +model. Instead, it should produce a new instance of the model reflecting the desired changes.
+fn update(model: &Model, msg: Message) -> Model {
+ match msg {
+ // Match each possible message and decide how the model should change
+ // Return a new model reflecting those changes
+ }
+}In TEA, it’s crucial to maintain a clear separation between the data (model) and the logic that +alters it (update). This immutability principle ensures predictability and makes the application +easier to reason about.
+
+
+
+
+
+Hence, while immutability is emphasized in TEA, Rust developers can choose the most +suitable approach based on performance and their application’s needs.
+For example, it would be perfectly valid to do the following:
+fn update(model: &mut Model, msg: Message) {
+ match msg {
+ // Match each possible message and decide how the model should change
+ // Modify existing mode reflecting those changes
+ };
+}In TEA, the update() function can not only modify the model based on the Message, but it can
+also return another Message. This design can be particularly useful if you want to chain messages
+or have an update lead to another update.
For example, this is what the update() function may look like for a counter app:
fn update(model: &mut Model, msg: Message) -> Option<Message> {
+ match msg {
+ Message::Increment => {
+ model.counter += 1;
+ if model.counter > 50 {
+ return Some(Message::Reset);
+ }
+ },
+ Message::Decrement => {
+ model.counter -= 1;
+ if model.counter < -50 {
+ return Some(Message::Reset);
+ }
+ },
+ Message::Reset => {
+ model.counter = 0;
+ },
+ Message::Quit => {
+ model.should_quit = true;
+ },
+ _ => {},
+ }
+ None // Default return value if no specific message is to be returned
+}
+
+
+
+
+Remember that this design choice means that the main loop will need to handle the
+returned message, calling update() again based on that returned message.
Returning a Message from the update() function allows a developer to reason about their code as
+a “Finite State Machine”. Finite State Machines operate on defined states and transitions, where an
+initial state and an event (in our case, a Message) lead to a subsequent state. This cascading
+approach ensures that the system remains in a consistent and predictable state after handling a
+series of interconnected events.
Here’s a state transition diagram of the counter example from above:
+stateDiagram-v2
+ state Model {
+ counter : counter = 0
+ should_quit : should_quit = false
+ }
+
+ Model --> Increment
+ Model --> Decrement
+ Model --> Reset
+ Model --> Quit
+
+ Increment --> Model: counter += 1
+ Increment --> Reset: if > 50
+
+ Decrement --> Model: counter -= 1
+ Decrement --> Reset: if < -50
+
+ Reset --> Model: counter = 0
+
+ Quit --> break: should_quit = true
+
+While TEA doesn’t use the Finite State Machine terminology or strictly enforce that paradigm, +thinking of your application’s state as a state machine can allow developers to break down intricate +state transitions into smaller, more manageable steps. This can make designing the application’s +logic clearer and improve code maintainability.
+3. Rendering the View
+The view function in the Elm Architecture is tasked with taking the current model and producing a +visual representation for the user. In the case of ratatui, it translates the model into terminal UI +elements. It’s essential that the view function remains a pure function: for a given state of the +model, it should always produce the same UI representation.
+fn view(model: &Model) {
+ //... use `ratatui` functions to draw your UI based on the model's state
+}Every time the model is updated, the view function should be capable of reflecting those changes +accurately in the terminal UI.
+In TEA, you are expected to ensure that your view function is side-effect free. The view()
+function shouldn’t modify global state or perform any other actions. Its sole job is to map the
+model to a visual representation.
For a given state of the model, the view function should always produce the same visual output. This +predictability makes your TUI application easier to reason about and debug.
+
+
+
+
+
+With immediate mode rendering you may run into an issue: the view function is only aware of the
+area available to draw in at render time.
This limitation is a recognized constraint of immediate mode GUIs. Overcoming it often involves +trade-offs. One common solution is to store the drawable size and reference it in the subsequent +frame, although this can introduce a frame delay in layout adjustments, leading to potential +flickering during the initial rendering when changes in screen size occur.
+An alternative would be using the Resize event from crossterm and to clear the UI and force
+redraw everything during that event.
In ratatui, there are
+StatefulWidgets which
+require a mutable reference to state during render.
For this reason, you may choose to forego the view immutability principle. For example, if you
+were interested in rendering a List, your view function may look like this:
fn view(model: &mut Model, f: &mut Frame) {
+ let items = app.items.items.iter().map(|element| ListItem::new(element)).collect();
+ f.render_stateful_widget(List::new(items), f.size(), &mut app.items.state);
+}
+
+fn main() {
+ loop {
+ ...
+ terminal
+ .draw(|f| {
+ view(&mut model, f);
+ })?;
+ ...
+ }
+}Another advantage of having access to the Frame in the view() function is that you have access
+to setting the cursor position, which is useful for displaying text fields. For example, if you
+wanted to draw an input field using tui-input, you
+might have a view that looks like this:
fn view(model: &mut Model, f: &mut Frame) {
+ let area = f.size();
+ let input = Paragraph::new(app.input.value());
+ f.render_widget(input, area);
+ if app.mode == Mode::Insert {
+ f.set_cursor(
+ (area.x + 1 + self.input.cursor() as u16).min(area.x + area.width - 2),
+ area.y + 1
+ )
+ }
+}Putting it all together
+When you put it all together, your main application loop might look something like:
+-
+
- Listen for user input. +
- Map input to a
Message
+ - Pass that message to the update function. +
- Draw the UI with the view function. +
This cycle repeats, ensuring your TUI is always up-to-date with user interactions.
+As an illustrative example, here’s the Counter App +refactored using TEA.
+The notable difference from before is that we have an Model struct that captures the app state,
+and a Message enum that captures the various actions your app can take.
// cargo add anyhow ratatui crossterm
+use anyhow::Result;
+use ratatui::{
+ prelude::{CrosstermBackend, Terminal},
+ widgets::Paragraph,
+};
+
+pub type Frame<'a> = ratatui::Frame<'a, ratatui::backend::CrosstermBackend<std::io::Stderr>>;
+
+// MODEL
+struct Model {
+ counter: i32,
+ should_quit: bool,
+}
+
+// MESSAGES
+#[derive(PartialEq)]
+enum Message {
+ Increment,
+ Decrement,
+ Reset,
+ Quit,
+}
+
+// UPDATE
+fn update(model: &mut Model, msg: Message) -> Option<Message> {
+ match msg {
+ Message::Increment => {
+ model.counter += 1;
+ if model.counter > 50 {
+ return Some(Message::Reset);
+ }
+ },
+ Message::Decrement => {
+ model.counter -= 1;
+ if model.counter < -50 {
+ return Some(Message::Reset);
+ }
+ },
+ Message::Reset => model.counter = 0,
+ Message::Quit => model.should_quit = true, // You can handle cleanup and exit here
+ };
+ None
+}
+
+// VIEW
+fn view(model: &mut Model, f: &mut Frame) {
+ f.render_widget(Paragraph::new(format!("Counter: {}", model.counter)), f.size());
+}
+
+// Convert Event to Message
+// We don't need to pass in a `model` to this function in this example
+// but you might need it as your project evolves
+fn handle_event(_: &Model) -> Result<Option<Message>> {
+ let message = if crossterm::event::poll(std::time::Duration::from_millis(250))? {
+ if let crossterm::event::Event::Key(key) = crossterm::event::read()? {
+ match key.code {
+ crossterm::event::KeyCode::Char('j') => Message::Increment,
+ crossterm::event::KeyCode::Char('k') => Message::Decrement,
+ crossterm::event::KeyCode::Char('q') => Message::Quit,
+ _ => return Ok(None),
+ }
+ } else {
+ return Ok(None);
+ }
+ } else {
+ return Ok(None);
+ };
+ Ok(Some(message))
+}
+
+pub fn initialize_panic_handler() {
+ let original_hook = std::panic::take_hook();
+ std::panic::set_hook(Box::new(move |panic_info| {
+ crossterm::execute!(std::io::stderr(), crossterm::terminal::LeaveAlternateScreen).unwrap();
+ crossterm::terminal::disable_raw_mode().unwrap();
+ original_hook(panic_info);
+ }));
+}
+
+fn main() -> Result<()> {
+ initialize_panic_handler();
+
+ // Startup
+ crossterm::terminal::enable_raw_mode()?;
+ crossterm::execute!(std::io::stderr(), crossterm::terminal::EnterAlternateScreen)?;
+
+ let mut terminal = Terminal::new(CrosstermBackend::new(std::io::stderr()))?;
+ let mut model = Model { counter: 0, should_quit: false };
+
+ loop {
+ // Render the current view
+ terminal.draw(|f| {
+ view(&mut model, f);
+ })?;
+
+ // Handle events and map to a Message
+ let mut current_msg = handle_event(&model)?;
+
+ // Process updates as long as they return a non-None message
+ while current_msg != None {
+ current_msg = update(&mut model, current_msg.unwrap());
+ }
+
+ // Exit loop if quit flag is set
+ if model.should_quit {
+ break;
+ }
+ }
+
+ // Shutdown
+ crossterm::execute!(std::io::stderr(), crossterm::terminal::LeaveAlternateScreen)?;
+ crossterm::terminal::disable_raw_mode()?;
+ Ok(())
+}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/concepts/backends/comparison.html b/pr-preview/pr-83/concepts/backends/comparison.html
new file mode 100644
index 000000000..b988dea1c
--- /dev/null
+++ b/pr-preview/pr-83/concepts/backends/comparison.html
@@ -0,0 +1,253 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Alternate Screen
+The alternate screen is a separate buffer that some terminals provide, distinct from the main +screen. When activated, the terminal will display the alternate screen, hiding the current content +of the main screen. Applications can write to this screen as if it were the regular terminal +display, but when the application exits, the terminal will switch back to the main screen, and the +contents of the alternate screen will be cleared. This is useful for applications like text editors +or terminal games that want to use the full terminal window without disrupting the command line or +other terminal content.
+This creates a seamless transition between the application and the regular terminal session, as the +content displayed before launching the application will reappear after the application exits.
+Note that not all terminal emulators support the alternate screen, and even those that do may handle +it differently. As a result, the behavior may vary depending on the backend being used. Always +consult the specific backend’s documentation to understand how it implements the alternate screen.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/concepts/backends/index.html b/pr-preview/pr-83/concepts/backends/index.html
new file mode 100644
index 000000000..19cd5cae5
--- /dev/null
+++ b/pr-preview/pr-83/concepts/backends/index.html
@@ -0,0 +1,230 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Comparison of Backends
+
+
+
+
+
+Choose Crossterm for most tasks.
+Ratatui interfaces with the terminal emulator through its “backends”. These are powerful libraries
+that grant ratatui the ability to capture keypresses, maneuver the cursor, style the text with
+colors and other features. As of now, ratatui supports three backends:
Selecting a backend does influence your project’s structure, but the core functionalities remain +consistent across all options. Here’s a flowchart that can help you make your decision.
+graph TD; + Q1[Is the TUI only for Wezterm users?] + Q2[Is Windows compatibility important?] + Q3[Are you familiar with Crossterm?] + Q4[Are you familiar with Termion?] + Crossterm + Termwiz + Termion + + Q1 -->|Yes| Termwiz + Q1 -->|No| Q2 + Q2 -->|Yes| Crossterm + Q2 -->|No| Q3 + Q3 -->|Yes| Crossterm + Q3 -->|No| Q4 + Q4 -->|Yes| Termion + Q4 -->|No| Crossterm ++
Though we try to make sure that all backends are fully-supported, the most commonly-used backend is +Crossterm. If you have no particular reason to use Termion or Termwiz, you will find it easiest to +learn Crossterm simply due to its popularity.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/concepts/backends/mouse-capture.html b/pr-preview/pr-83/concepts/backends/mouse-capture.html
new file mode 100644
index 000000000..489362060
--- /dev/null
+++ b/pr-preview/pr-83/concepts/backends/mouse-capture.html
@@ -0,0 +1,222 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Backends
+Ratatui interfaces with the terminal emulator through a backend. These libraries enable Ratatui via
+the Terminal type to draw styled text to the screen, manipulate the cursor, and interrogate
+properties of the terminal such as the console or window size. You application will generally also
+use the backend directly to capture keyboard, mouse and window events, and enable raw mode and the
+alternate screen.
Ratatui supports the following backends:
+-
+
- Crossterm via
CrosstermBackendand thecrossterm(enabled by default).
+ - Termion via
TermionBackendand thetermionfeature.
+ - Termwiz via
TermwizBackendand thetermionfeature.
+ - A
TestBackendwhich can be useful to unit test your application’s UI
+
For information on how to choose a backend see: Comparison
+Each backend supports Raw Mode (which changes how the terminal handles input and +output processing), an Alternate Screen which allows it to render to a +separate buffer than your shell commands use, and Mouse Capture, which allows +your application to capture mouse events.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/concepts/backends/raw-mode.html b/pr-preview/pr-83/concepts/backends/raw-mode.html
new file mode 100644
index 000000000..fc59af993
--- /dev/null
+++ b/pr-preview/pr-83/concepts/backends/raw-mode.html
@@ -0,0 +1,230 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Mouse Capture
+Mouse capture is a mode where the terminal captures mouse events such as clicks, scrolls, and +movement, and sends them to the application as special sequences or events. This enables the +application to handle and respond to mouse actions, providing a more interactive and graphical user +experience within the terminal. It’s particularly useful for applications like terminal-based games, +text editors, or other programs that require more direct interaction from the user.
+Each backend handles mouse capture differently, with variations in the types of events that can be +captured and how they are represented. As such, the behavior may vary depending on the backend being +used, and developers should consult the specific backend’s documentation to understand how it +implements mouse capture.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/concepts/event_handling.html b/pr-preview/pr-83/concepts/event_handling.html
new file mode 100644
index 000000000..5bb69c910
--- /dev/null
+++ b/pr-preview/pr-83/concepts/event_handling.html
@@ -0,0 +1,242 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Raw Mode
+Raw mode is a mode where the terminal does not perform any processing or handling of the input and
+output. This means that features such as echoing input characters, line buffering, and special
+character processing (e.g., CTRL-C or SIGINT) are disabled. This is useful for applications that
+want to have complete control over the terminal input and output, processing each keystroke
+themselves.
For example, in raw mode, the terminal will not perform line buffering on the input, so the +application will receive each key press as it is typed, instead of waiting for the user to press +enter. This makes it suitable for real-time applications like text editors, terminal-based games, +and more.
+Each backend handles raw mode differently, so the behavior may vary depending on the backend being +used. Be sure to consult the backend’s specific documentation for exact details on how it implements +raw mode.
+ + +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/concepts/index.html b/pr-preview/pr-83/concepts/index.html
new file mode 100644
index 000000000..27561baee
--- /dev/null
+++ b/pr-preview/pr-83/concepts/index.html
@@ -0,0 +1,220 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Event Handling
+There are many ways to handle events with the ratatui library. Mostly becuase ratatui does not
+directly expose any event catching; the programmer will depend on the chosen backend’s library.
However, there are a few ways to think about event handling that may help you. While this is not an +exhaustive list, it covers a few of the more common implementations. But remember, the correct way, +is the one that works for you and your current application.
+Centralized event handling
+This is the simplest way to handle events because it handles all of the events as they appear. It is
+often simply a match on the results of event::read()? (in crossterm) on the different supported
+keys. Pros: This has the advantage of requiring no message passing, and allows the programmer to
+edit all of the possible keyboard events in one place.
Cons: However, this particular way of handling events simply does not scale well. Because all +events are handled in one place, you will be unable to split different groups of keybinds out into +separate locations.
+Centralized catching, message passing
+This way of handling events involves polling for events in one place, and then sending +messages/calling sub functions with the event that was caught. Pros: This has a similar appeal to +the first method in its simplicity. With this paradigm, you can easily split extensive pattern +matching into sub functions that can go in separate files. This way is also the idea often used in +basic multi-threaded applications because message channels are used to pass multi-threaded safe +messages.
+Cons: This method requires a main loop to be running to consistently poll for events in a +centralized place.
+Distributed event loops/segmented applications
+In this style, control of the Terminal and the main loop to a sub-module. In this case, the entire
+rendering and event handling responsibilities can be safely passed to the sub-module. In theory, an
+application built like this doesn’t need a centralized event listener. Pros: There is no centralized
+event loop that you need to update whenever a new sub-module is created.
Cons: However, if several sub-modules in your application have similar event handling loops, this +way could lead to a lot of duplicated code.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/concepts/rendering.html b/pr-preview/pr-83/concepts/rendering.html
new file mode 100644
index 000000000..fb3eb3c58
--- /dev/null
+++ b/pr-preview/pr-83/concepts/rendering.html
@@ -0,0 +1,288 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Concepts
+In this section, we will cover various concepts associated with terminal user interfaces, such as:
+-
+
- Application patterns +
- Event handling +
- Storing state +
- Rendering +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/contributors.html b/pr-preview/pr-83/contributors.html
new file mode 100644
index 000000000..d2f94dd79
--- /dev/null
+++ b/pr-preview/pr-83/contributors.html
@@ -0,0 +1,210 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Rendering
+The world of UI development consists mainly of two dominant paradigms: retained mode and immediate
+mode. Most traditional GUI libraries operate under the retained mode paradigm. However, ratatui
+employs the immediate mode rendering approach. for TUI development.
This makes ratatui is different from GUI frameworks you might use, because it only updates when
+you tell it to.
What is Immediate Mode Rendering?
+Immediate mode rendering is a UI paradigm where the UI is recreated every frame. Instead of creating +a fixed set of UI widgets and updating their state, you “draw” your UI from scratch in every frame +based on the current application state.
+In a nutshell:
+-
+
- Retained Mode: You set up your UI once, create widgets, and later modify their properties or +handle their events. +
- Immediate Mode: You redraw your UI every frame based on your application state. There’s no +permanent widget object in memory. +
In ratatui, every frame draws the UI anew.
loop {
+ terminal.draw(|f| {
+ if state.condition {
+ f.render_widget(SomeWidget::new(), layout);
+ } else {
+ f.render_widget(AnotherWidget::new(), layout);
+ }
+ })?;
+}This article and the accompanying YouTube video is worth your +time if you are new to the immediate mode rendering paradigm.
+ +This 4 minute talk about IMGUI is also tangentially relevant.
Advantages of Immediate Mode Rendering
+-
+
- Simplicity: Without a persistent widget state, your UI logic becomes a direct reflection of +your application state. You don’t have to sync them or worry about past widget states. +
- Flexibility: You can change your UI layout or logic any time, as nothing is set in stone. Want +to hide a widget conditionally? Just don’t draw it based on some condition. +
Disadvantages of Immediate Mode Rendering
+-
+
- Render loop management: In Immediate mode rendering, the onus of rendering lies solely on the
+programmer. Every visual update necessitates a call to
Backend.draw(). Hence, if the rendering +thread is inadvertently blocked, the UI will not update until the thread resumes.
+
+
+
+
+
+The ratatui library in particular only handles how widget would be rendered to a “Backend”, e.g.
+crossterm. The Backend in question would use an external crate e.g. crossterm for actually
+drawing to the terminal.
-
+
-
+
Event loop orchestration: Along with managing “the render loop”, developers are also +responsible for handling “the event loop”. This involves deciding on a third-party library for the +job.
+crosstermis a popular crate to handle key inputs and you’ll find plenty of examples in the +repository and online for how to use it.crosstermalso supports aasyncevent stream, if you +are interested in usingtokio.
+ -
+
Architecture design considerations: With
+ratatui, out of the box, there’s little to no help +in organizing large applications. Ultimately, the decision on structure and discipline rests with +the developer to be principled.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/css/chrome.css b/pr-preview/pr-83/css/chrome.css
new file mode 100644
index 000000000..29992f7b6
--- /dev/null
+++ b/pr-preview/pr-83/css/chrome.css
@@ -0,0 +1,545 @@
+/* CSS for UI elements (a.k.a. chrome) */
+
+@import 'variables.css';
+
+html {
+ scrollbar-color: var(--scrollbar) var(--bg);
+}
+#searchresults a,
+.content a:link,
+a:visited,
+a > .hljs {
+ color: var(--links);
+}
+
+/*
+ body-container is necessary because mobile browsers don't seem to like
+ overflow-x on the body tag when there is a tag.
+*/
+#body-container {
+ /*
+ This is used when the sidebar pushes the body content off the side of
+ the screen on small screens. Without it, dragging on mobile Safari
+ will want to reposition the viewport in a weird way.
+ */
+ overflow-x: clip;
+}
+
+/* Menu Bar */
+
+#menu-bar,
+#menu-bar-hover-placeholder {
+ z-index: 101;
+ margin: auto calc(0px - var(--page-padding));
+}
+#menu-bar {
+ position: relative;
+ display: flex;
+ flex-wrap: wrap;
+ background-color: var(--bg);
+ border-bottom-color: var(--bg);
+ border-bottom-width: 1px;
+ border-bottom-style: solid;
+}
+#menu-bar.sticky,
+.js #menu-bar-hover-placeholder:hover + #menu-bar,
+.js #menu-bar:hover,
+.js.sidebar-visible #menu-bar {
+ position: -webkit-sticky;
+ position: sticky;
+ top: 0 !important;
+}
+#menu-bar-hover-placeholder {
+ position: sticky;
+ position: -webkit-sticky;
+ top: 0;
+ height: var(--menu-bar-height);
+}
+#menu-bar.bordered {
+ border-bottom-color: var(--table-border-color);
+}
+#menu-bar i, #menu-bar .icon-button {
+ position: relative;
+ padding: 0 8px;
+ z-index: 10;
+ line-height: var(--menu-bar-height);
+ cursor: pointer;
+ transition: color 0.5s;
+}
+@media only screen and (max-width: 420px) {
+ #menu-bar i, #menu-bar .icon-button {
+ padding: 0 5px;
+ }
+}
+
+.icon-button {
+ border: none;
+ background: none;
+ padding: 0;
+ color: inherit;
+}
+.icon-button i {
+ margin: 0;
+}
+
+.right-buttons {
+ margin: 0 15px;
+}
+.right-buttons a {
+ text-decoration: none;
+}
+
+.left-buttons {
+ display: flex;
+ margin: 0 5px;
+}
+.no-js .left-buttons {
+ display: none;
+}
+
+.menu-title {
+ display: inline-block;
+ font-weight: 200;
+ font-size: 2.4rem;
+ line-height: var(--menu-bar-height);
+ text-align: center;
+ margin: 0;
+ flex: 1;
+ white-space: nowrap;
+ overflow: hidden;
+ text-overflow: ellipsis;
+}
+.js .menu-title {
+ cursor: pointer;
+}
+
+.menu-bar,
+.menu-bar:visited,
+.nav-chapters,
+.nav-chapters:visited,
+.mobile-nav-chapters,
+.mobile-nav-chapters:visited,
+.menu-bar .icon-button,
+.menu-bar a i {
+ color: var(--icons);
+}
+
+.menu-bar i:hover,
+.menu-bar .icon-button:hover,
+.nav-chapters:hover,
+.mobile-nav-chapters i:hover {
+ color: var(--icons-hover);
+}
+
+/* Nav Icons */
+
+.nav-chapters {
+ font-size: 2.5em;
+ text-align: center;
+ text-decoration: none;
+
+ position: fixed;
+ top: 0;
+ bottom: 0;
+ margin: 0;
+ max-width: 150px;
+ min-width: 90px;
+
+ display: flex;
+ justify-content: center;
+ align-content: center;
+ flex-direction: column;
+
+ transition: color 0.5s, background-color 0.5s;
+}
+
+.nav-chapters:hover {
+ text-decoration: none;
+ background-color: var(--theme-hover);
+ transition: background-color 0.15s, color 0.15s;
+}
+
+.nav-wrapper {
+ margin-top: 50px;
+ display: none;
+}
+
+.mobile-nav-chapters {
+ font-size: 2.5em;
+ text-align: center;
+ text-decoration: none;
+ width: 90px;
+ border-radius: 5px;
+ background-color: var(--sidebar-bg);
+}
+
+.previous {
+ float: left;
+}
+
+.next {
+ float: right;
+ right: var(--page-padding);
+}
+
+@media only screen and (max-width: 1080px) {
+ .nav-wide-wrapper { display: none; }
+ .nav-wrapper { display: block; }
+}
+
+@media only screen and (max-width: 1380px) {
+ .sidebar-visible .nav-wide-wrapper { display: none; }
+ .sidebar-visible .nav-wrapper { display: block; }
+}
+
+/* Inline code */
+
+:not(pre) > .hljs {
+ display: inline;
+ padding: 0.1em 0.3em;
+ border-radius: 3px;
+}
+
+:not(pre):not(a) > .hljs {
+ color: var(--inline-code-color);
+ overflow-x: initial;
+}
+
+a:hover > .hljs {
+ text-decoration: underline;
+}
+
+pre {
+ position: relative;
+}
+pre > .buttons {
+ position: absolute;
+ z-index: 100;
+ right: 0px;
+ top: 2px;
+ margin: 0px;
+ padding: 2px 0px;
+
+ color: var(--sidebar-fg);
+ cursor: pointer;
+ visibility: hidden;
+ opacity: 0;
+ transition: visibility 0.1s linear, opacity 0.1s linear;
+}
+pre:hover > .buttons {
+ visibility: visible;
+ opacity: 1
+}
+pre > .buttons :hover {
+ color: var(--sidebar-active);
+ border-color: var(--icons-hover);
+ background-color: var(--theme-hover);
+}
+pre > .buttons i {
+ margin-left: 8px;
+}
+pre > .buttons button {
+ cursor: inherit;
+ margin: 0px 5px;
+ padding: 3px 5px;
+ font-size: 14px;
+
+ border-style: solid;
+ border-width: 1px;
+ border-radius: 4px;
+ border-color: var(--icons);
+ background-color: var(--theme-popup-bg);
+ transition: 100ms;
+ transition-property: color,border-color,background-color;
+ color: var(--icons);
+}
+@media (pointer: coarse) {
+ pre > .buttons button {
+ /* On mobile, make it easier to tap buttons. */
+ padding: 0.3rem 1rem;
+ }
+}
+pre > code {
+ padding: 1rem;
+}
+
+/* FIXME: ACE editors overlap their buttons because ACE does absolute
+ positioning within the code block which breaks padding. The only solution I
+ can think of is to move the padding to the outer pre tag (or insert a div
+ wrapper), but that would require fixing a whole bunch of CSS rules.
+*/
+.hljs.ace_editor {
+ padding: 0rem 0rem;
+}
+
+pre > .result {
+ margin-top: 10px;
+}
+
+/* Search */
+
+#searchresults a {
+ text-decoration: none;
+}
+
+mark {
+ border-radius: 2px;
+ padding: 0 3px 1px 3px;
+ margin: 0 -3px -1px -3px;
+ background-color: var(--search-mark-bg);
+ transition: background-color 300ms linear;
+ cursor: pointer;
+}
+
+mark.fade-out {
+ background-color: rgba(0,0,0,0) !important;
+ cursor: auto;
+}
+
+.searchbar-outer {
+ margin-left: auto;
+ margin-right: auto;
+ max-width: var(--content-max-width);
+}
+
+#searchbar {
+ width: 100%;
+ margin: 5px auto 0px auto;
+ padding: 10px 16px;
+ transition: box-shadow 300ms ease-in-out;
+ border: 1px solid var(--searchbar-border-color);
+ border-radius: 3px;
+ background-color: var(--searchbar-bg);
+ color: var(--searchbar-fg);
+}
+#searchbar:focus,
+#searchbar.active {
+ box-shadow: 0 0 3px var(--searchbar-shadow-color);
+}
+
+.searchresults-header {
+ font-weight: bold;
+ font-size: 1em;
+ padding: 18px 0 0 5px;
+ color: var(--searchresults-header-fg);
+}
+
+.searchresults-outer {
+ margin-left: auto;
+ margin-right: auto;
+ max-width: var(--content-max-width);
+ border-bottom: 1px dashed var(--searchresults-border-color);
+}
+
+ul#searchresults {
+ list-style: none;
+ padding-left: 20px;
+}
+ul#searchresults li {
+ margin: 10px 0px;
+ padding: 2px;
+ border-radius: 2px;
+}
+ul#searchresults li.focus {
+ background-color: var(--searchresults-li-bg);
+}
+ul#searchresults span.teaser {
+ display: block;
+ clear: both;
+ margin: 5px 0 0 20px;
+ font-size: 0.8em;
+}
+ul#searchresults span.teaser em {
+ font-weight: bold;
+ font-style: normal;
+}
+
+/* Sidebar */
+
+.sidebar {
+ position: fixed;
+ left: 0;
+ top: 0;
+ bottom: 0;
+ width: var(--sidebar-width);
+ font-size: 0.875em;
+ box-sizing: border-box;
+ -webkit-overflow-scrolling: touch;
+ overscroll-behavior-y: contain;
+ background-color: var(--sidebar-bg);
+ color: var(--sidebar-fg);
+}
+.sidebar-resizing {
+ -moz-user-select: none;
+ -webkit-user-select: none;
+ -ms-user-select: none;
+ user-select: none;
+}
+.js:not(.sidebar-resizing) .sidebar {
+ transition: transform 0.3s; /* Animation: slide away */
+}
+.sidebar code {
+ line-height: 2em;
+}
+.sidebar .sidebar-scrollbox {
+ overflow-y: auto;
+ position: absolute;
+ top: 0;
+ bottom: 0;
+ left: 0;
+ right: 0;
+ padding: 10px 10px;
+}
+.sidebar .sidebar-resize-handle {
+ position: absolute;
+ cursor: col-resize;
+ width: 0;
+ right: 0;
+ top: 0;
+ bottom: 0;
+}
+.js .sidebar .sidebar-resize-handle {
+ cursor: col-resize;
+ width: 5px;
+}
+.sidebar-hidden .sidebar {
+ transform: translateX(calc(0px - var(--sidebar-width)));
+}
+.sidebar::-webkit-scrollbar {
+ background: var(--sidebar-bg);
+}
+.sidebar::-webkit-scrollbar-thumb {
+ background: var(--scrollbar);
+}
+
+.sidebar-visible .page-wrapper {
+ transform: translateX(var(--sidebar-width));
+}
+@media only screen and (min-width: 620px) {
+ .sidebar-visible .page-wrapper {
+ transform: none;
+ margin-left: var(--sidebar-width);
+ }
+}
+
+.chapter {
+ list-style: none outside none;
+ padding-left: 0;
+ line-height: 2.2em;
+}
+
+.chapter ol {
+ width: 100%;
+}
+
+.chapter li {
+ display: flex;
+ color: var(--sidebar-non-existant);
+}
+.chapter li a {
+ display: block;
+ padding: 0;
+ text-decoration: none;
+ color: var(--sidebar-fg);
+}
+
+.chapter li a:hover {
+ color: var(--sidebar-active);
+}
+
+.chapter li a.active {
+ color: var(--sidebar-active);
+}
+
+.chapter li > a.toggle {
+ cursor: pointer;
+ display: block;
+ margin-left: auto;
+ padding: 0 10px;
+ user-select: none;
+ opacity: 0.68;
+}
+
+.chapter li > a.toggle div {
+ transition: transform 0.5s;
+}
+
+/* collapse the section */
+.chapter li:not(.expanded) + li > ol {
+ display: none;
+}
+
+.chapter li.chapter-item {
+ line-height: 1.5em;
+ margin-top: 0.6em;
+}
+
+.chapter li.expanded > a.toggle div {
+ transform: rotate(90deg);
+}
+
+.spacer {
+ width: 100%;
+ height: 3px;
+ margin: 5px 0px;
+}
+.chapter .spacer {
+ background-color: var(--sidebar-spacer);
+}
+
+@media (-moz-touch-enabled: 1), (pointer: coarse) {
+ .chapter li a { padding: 5px 0; }
+ .spacer { margin: 10px 0; }
+}
+
+.section {
+ list-style: none outside none;
+ padding-left: 20px;
+ line-height: 1.9em;
+}
+
+/* Theme Menu Popup */
+
+.theme-popup {
+ position: absolute;
+ left: 10px;
+ top: var(--menu-bar-height);
+ z-index: 1000;
+ border-radius: 4px;
+ font-size: 0.7em;
+ color: var(--fg);
+ background: var(--theme-popup-bg);
+ border: 1px solid var(--theme-popup-border);
+ margin: 0;
+ padding: 0;
+ list-style: none;
+ display: none;
+ /* Don't let the children's background extend past the rounded corners. */
+ overflow: hidden;
+}
+.theme-popup .default {
+ color: var(--icons);
+}
+.theme-popup .theme {
+ width: 100%;
+ border: 0;
+ margin: 0;
+ padding: 2px 20px;
+ line-height: 25px;
+ white-space: nowrap;
+ text-align: left;
+ cursor: pointer;
+ color: inherit;
+ background: inherit;
+ font-size: inherit;
+}
+.theme-popup .theme:hover {
+ background-color: var(--theme-hover);
+}
+
+.theme-selected::before {
+ display: inline-block;
+ content: "✓";
+ margin-left: -14px;
+ width: 14px;
+}
diff --git a/pr-preview/pr-83/css/general.css b/pr-preview/pr-83/css/general.css
new file mode 100644
index 000000000..344b53eb7
--- /dev/null
+++ b/pr-preview/pr-83/css/general.css
@@ -0,0 +1,203 @@
+/* Base styles and content styles */
+
+@import 'variables.css';
+
+:root {
+ /* Browser default font-size is 16px, this way 1 rem = 10px */
+ font-size: 62.5%;
+}
+
+html {
+ font-family: "Open Sans", sans-serif;
+ color: var(--fg);
+ background-color: var(--bg);
+ text-size-adjust: none;
+ -webkit-text-size-adjust: none;
+}
+
+body {
+ margin: 0;
+ font-size: 1.6rem;
+ overflow-x: hidden;
+}
+
+code {
+ font-family: var(--mono-font) !important;
+ font-size: var(--code-font-size);
+}
+
+/* make long words/inline code not x overflow */
+main {
+ overflow-wrap: break-word;
+}
+
+/* make wide tables scroll if they overflow */
+.table-wrapper {
+ overflow-x: auto;
+}
+
+/* Don't change font size in headers. */
+h1 code, h2 code, h3 code, h4 code, h5 code, h6 code {
+ font-size: unset;
+}
+
+.left { float: left; }
+.right { float: right; }
+.boring { opacity: 0.6; }
+.hide-boring .boring { display: none; }
+.hidden { display: none !important; }
+
+h2, h3 { margin-top: 2.5em; }
+h4, h5 { margin-top: 2em; }
+
+.header + .header h3,
+.header + .header h4,
+.header + .header h5 {
+ margin-top: 1em;
+}
+
+h1:target::before,
+h2:target::before,
+h3:target::before,
+h4:target::before,
+h5:target::before,
+h6:target::before {
+ display: inline-block;
+ content: "»";
+ margin-left: -30px;
+ width: 30px;
+}
+
+/* This is broken on Safari as of version 14, but is fixed
+ in Safari Technology Preview 117 which I think will be Safari 14.2.
+ https://bugs.webkit.org/show_bug.cgi?id=218076
+*/
+:target {
+ scroll-margin-top: calc(var(--menu-bar-height) + 0.5em);
+}
+
+.page {
+ outline: 0;
+ padding: 0 var(--page-padding);
+ margin-top: calc(0px - var(--menu-bar-height)); /* Compensate for the #menu-bar-hover-placeholder */
+}
+.page-wrapper {
+ box-sizing: border-box;
+}
+.js:not(.sidebar-resizing) .page-wrapper {
+ transition: margin-left 0.3s ease, transform 0.3s ease; /* Animation: slide away */
+}
+
+.content {
+ overflow-y: auto;
+ padding: 0 5px 50px 5px;
+}
+.content main {
+ margin-left: auto;
+ margin-right: auto;
+ max-width: var(--content-max-width);
+}
+.content p { line-height: 1.45em; }
+.content ol { line-height: 1.45em; }
+.content ul { line-height: 1.45em; }
+.content a { text-decoration: none; }
+.content a:hover { text-decoration: underline; }
+.content img, .content video { max-width: 100%; }
+.content .header:link,
+.content .header:visited {
+ color: var(--fg);
+}
+.content .header:link,
+.content .header:visited:hover {
+ text-decoration: none;
+}
+
+table {
+ margin: 0 auto;
+ border-collapse: collapse;
+}
+table td {
+ padding: 3px 20px;
+ border: 1px var(--table-border-color) solid;
+}
+table thead {
+ background: var(--table-header-bg);
+}
+table thead td {
+ font-weight: 700;
+ border: none;
+}
+table thead th {
+ padding: 3px 20px;
+}
+table thead tr {
+ border: 1px var(--table-header-bg) solid;
+}
+/* Alternate background colors for rows */
+table tbody tr:nth-child(2n) {
+ background: var(--table-alternate-bg);
+}
+
+
+blockquote {
+ margin: 20px 0;
+ padding: 0 20px;
+ color: var(--fg);
+ background-color: var(--quote-bg);
+ border-top: .1em solid var(--quote-border);
+ border-bottom: .1em solid var(--quote-border);
+}
+
+kbd {
+ background-color: var(--table-border-color);
+ border-radius: 4px;
+ border: solid 1px var(--theme-popup-border);
+ box-shadow: inset 0 -1px 0 var(--theme-hover);
+ display: inline-block;
+ font-size: var(--code-font-size);
+ font-family: var(--mono-font);
+ line-height: 10px;
+ padding: 4px 5px;
+ vertical-align: middle;
+}
+
+:not(.footnote-definition) + .footnote-definition,
+.footnote-definition + :not(.footnote-definition) {
+ margin-top: 2em;
+}
+.footnote-definition {
+ font-size: 0.9em;
+ margin: 0.5em 0;
+}
+.footnote-definition p {
+ display: inline;
+}
+
+.tooltiptext {
+ position: absolute;
+ visibility: hidden;
+ color: #fff;
+ background-color: #333;
+ transform: translateX(-50%); /* Center by moving tooltip 50% of its width left */
+ left: -8px; /* Half of the width of the icon */
+ top: -35px;
+ font-size: 0.8em;
+ text-align: center;
+ border-radius: 6px;
+ padding: 5px 8px;
+ margin: 5px;
+ z-index: 1000;
+}
+.tooltipped .tooltiptext {
+ visibility: visible;
+}
+
+.chapter li.part-title {
+ color: var(--sidebar-fg);
+ margin: 5px 0px;
+ font-weight: bold;
+}
+
+.result-no-output {
+ font-style: italic;
+}
diff --git a/pr-preview/pr-83/css/print.css b/pr-preview/pr-83/css/print.css
new file mode 100644
index 000000000..5e690f755
--- /dev/null
+++ b/pr-preview/pr-83/css/print.css
@@ -0,0 +1,54 @@
+
+#sidebar,
+#menu-bar,
+.nav-chapters,
+.mobile-nav-chapters {
+ display: none;
+}
+
+#page-wrapper.page-wrapper {
+ transform: none;
+ margin-left: 0px;
+ overflow-y: initial;
+}
+
+#content {
+ max-width: none;
+ margin: 0;
+ padding: 0;
+}
+
+.page {
+ overflow-y: initial;
+}
+
+code {
+ background-color: #666666;
+ border-radius: 5px;
+
+ /* Force background to be printed in Chrome */
+ -webkit-print-color-adjust: exact;
+}
+
+pre > .buttons {
+ z-index: 2;
+}
+
+a, a:visited, a:active, a:hover {
+ color: #4183c4;
+ text-decoration: none;
+}
+
+h1, h2, h3, h4, h5, h6 {
+ page-break-inside: avoid;
+ page-break-after: avoid;
+}
+
+pre, code {
+ page-break-inside: avoid;
+ white-space: pre-wrap;
+}
+
+.fa {
+ display: none !important;
+}
diff --git a/pr-preview/pr-83/css/variables.css b/pr-preview/pr-83/css/variables.css
new file mode 100644
index 000000000..21bf8e55e
--- /dev/null
+++ b/pr-preview/pr-83/css/variables.css
@@ -0,0 +1,255 @@
+
+/* Globals */
+
+:root {
+ --sidebar-width: 300px;
+ --page-padding: 15px;
+ --content-max-width: 750px;
+ --menu-bar-height: 50px;
+ --mono-font: "Source Code Pro", Consolas, "Ubuntu Mono", Menlo, "DejaVu Sans Mono", monospace, monospace;
+ --code-font-size: 0.875em /* please adjust the ace font size accordingly in editor.js */
+}
+
+/* Themes */
+
+.ayu {
+ --bg: hsl(210, 25%, 8%);
+ --fg: #c5c5c5;
+
+ --sidebar-bg: #14191f;
+ --sidebar-fg: #c8c9db;
+ --sidebar-non-existant: #5c6773;
+ --sidebar-active: #ffb454;
+ --sidebar-spacer: #2d334f;
+
+ --scrollbar: var(--sidebar-fg);
+
+ --icons: #737480;
+ --icons-hover: #b7b9cc;
+
+ --links: #0096cf;
+
+ --inline-code-color: #ffb454;
+
+ --theme-popup-bg: #14191f;
+ --theme-popup-border: #5c6773;
+ --theme-hover: #191f26;
+
+ --quote-bg: hsl(226, 15%, 17%);
+ --quote-border: hsl(226, 15%, 22%);
+
+ --table-border-color: hsl(210, 25%, 13%);
+ --table-header-bg: hsl(210, 25%, 28%);
+ --table-alternate-bg: hsl(210, 25%, 11%);
+
+ --searchbar-border-color: #848484;
+ --searchbar-bg: #424242;
+ --searchbar-fg: #fff;
+ --searchbar-shadow-color: #d4c89f;
+ --searchresults-header-fg: #666;
+ --searchresults-border-color: #888;
+ --searchresults-li-bg: #252932;
+ --search-mark-bg: #e3b171;
+}
+
+.coal {
+ --bg: hsl(200, 7%, 8%);
+ --fg: #98a3ad;
+
+ --sidebar-bg: #292c2f;
+ --sidebar-fg: #a1adb8;
+ --sidebar-non-existant: #505254;
+ --sidebar-active: #3473ad;
+ --sidebar-spacer: #393939;
+
+ --scrollbar: var(--sidebar-fg);
+
+ --icons: #43484d;
+ --icons-hover: #b3c0cc;
+
+ --links: #2b79a2;
+
+ --inline-code-color: #c5c8c6;
+
+ --theme-popup-bg: #141617;
+ --theme-popup-border: #43484d;
+ --theme-hover: #1f2124;
+
+ --quote-bg: hsl(234, 21%, 18%);
+ --quote-border: hsl(234, 21%, 23%);
+
+ --table-border-color: hsl(200, 7%, 13%);
+ --table-header-bg: hsl(200, 7%, 28%);
+ --table-alternate-bg: hsl(200, 7%, 11%);
+
+ --searchbar-border-color: #aaa;
+ --searchbar-bg: #b7b7b7;
+ --searchbar-fg: #000;
+ --searchbar-shadow-color: #aaa;
+ --searchresults-header-fg: #666;
+ --searchresults-border-color: #98a3ad;
+ --searchresults-li-bg: #2b2b2f;
+ --search-mark-bg: #355c7d;
+}
+
+.light {
+ --bg: hsl(0, 0%, 100%);
+ --fg: hsl(0, 0%, 0%);
+
+ --sidebar-bg: #fafafa;
+ --sidebar-fg: hsl(0, 0%, 0%);
+ --sidebar-non-existant: #aaaaaa;
+ --sidebar-active: #1f1fff;
+ --sidebar-spacer: #f4f4f4;
+
+ --scrollbar: #8F8F8F;
+
+ --icons: #747474;
+ --icons-hover: #000000;
+
+ --links: #20609f;
+
+ --inline-code-color: #301900;
+
+ --theme-popup-bg: #fafafa;
+ --theme-popup-border: #cccccc;
+ --theme-hover: #e6e6e6;
+
+ --quote-bg: hsl(197, 37%, 96%);
+ --quote-border: hsl(197, 37%, 91%);
+
+ --table-border-color: hsl(0, 0%, 95%);
+ --table-header-bg: hsl(0, 0%, 80%);
+ --table-alternate-bg: hsl(0, 0%, 97%);
+
+ --searchbar-border-color: #aaa;
+ --searchbar-bg: #fafafa;
+ --searchbar-fg: #000;
+ --searchbar-shadow-color: #aaa;
+ --searchresults-header-fg: #666;
+ --searchresults-border-color: #888;
+ --searchresults-li-bg: #e4f2fe;
+ --search-mark-bg: #a2cff5;
+}
+
+.navy {
+ --bg: hsl(226, 23%, 11%);
+ --fg: #bcbdd0;
+
+ --sidebar-bg: #282d3f;
+ --sidebar-fg: #c8c9db;
+ --sidebar-non-existant: #505274;
+ --sidebar-active: #2b79a2;
+ --sidebar-spacer: #2d334f;
+
+ --scrollbar: var(--sidebar-fg);
+
+ --icons: #737480;
+ --icons-hover: #b7b9cc;
+
+ --links: #2b79a2;
+
+ --inline-code-color: #c5c8c6;
+
+ --theme-popup-bg: #161923;
+ --theme-popup-border: #737480;
+ --theme-hover: #282e40;
+
+ --quote-bg: hsl(226, 15%, 17%);
+ --quote-border: hsl(226, 15%, 22%);
+
+ --table-border-color: hsl(226, 23%, 16%);
+ --table-header-bg: hsl(226, 23%, 31%);
+ --table-alternate-bg: hsl(226, 23%, 14%);
+
+ --searchbar-border-color: #aaa;
+ --searchbar-bg: #aeaec6;
+ --searchbar-fg: #000;
+ --searchbar-shadow-color: #aaa;
+ --searchresults-header-fg: #5f5f71;
+ --searchresults-border-color: #5c5c68;
+ --searchresults-li-bg: #242430;
+ --search-mark-bg: #a2cff5;
+}
+
+.rust {
+ --bg: hsl(60, 9%, 87%);
+ --fg: #262625;
+
+ --sidebar-bg: #3b2e2a;
+ --sidebar-fg: #c8c9db;
+ --sidebar-non-existant: #505254;
+ --sidebar-active: #e69f67;
+ --sidebar-spacer: #45373a;
+
+ --scrollbar: var(--sidebar-fg);
+
+ --icons: #737480;
+ --icons-hover: #262625;
+
+ --links: #2b79a2;
+
+ --inline-code-color: #6e6b5e;
+
+ --theme-popup-bg: #e1e1db;
+ --theme-popup-border: #b38f6b;
+ --theme-hover: #99908a;
+
+ --quote-bg: hsl(60, 5%, 75%);
+ --quote-border: hsl(60, 5%, 70%);
+
+ --table-border-color: hsl(60, 9%, 82%);
+ --table-header-bg: #b3a497;
+ --table-alternate-bg: hsl(60, 9%, 84%);
+
+ --searchbar-border-color: #aaa;
+ --searchbar-bg: #fafafa;
+ --searchbar-fg: #000;
+ --searchbar-shadow-color: #aaa;
+ --searchresults-header-fg: #666;
+ --searchresults-border-color: #888;
+ --searchresults-li-bg: #dec2a2;
+ --search-mark-bg: #e69f67;
+}
+
+@media (prefers-color-scheme: dark) {
+ .light.no-js {
+ --bg: hsl(200, 7%, 8%);
+ --fg: #98a3ad;
+
+ --sidebar-bg: #292c2f;
+ --sidebar-fg: #a1adb8;
+ --sidebar-non-existant: #505254;
+ --sidebar-active: #3473ad;
+ --sidebar-spacer: #393939;
+
+ --scrollbar: var(--sidebar-fg);
+
+ --icons: #43484d;
+ --icons-hover: #b3c0cc;
+
+ --links: #2b79a2;
+
+ --inline-code-color: #c5c8c6;
+
+ --theme-popup-bg: #141617;
+ --theme-popup-border: #43484d;
+ --theme-hover: #1f2124;
+
+ --quote-bg: hsl(234, 21%, 18%);
+ --quote-border: hsl(234, 21%, 23%);
+
+ --table-border-color: hsl(200, 7%, 13%);
+ --table-header-bg: hsl(200, 7%, 28%);
+ --table-alternate-bg: hsl(200, 7%, 11%);
+
+ --searchbar-border-color: #aaa;
+ --searchbar-bg: #b7b7b7;
+ --searchbar-fg: #000;
+ --searchbar-shadow-color: #aaa;
+ --searchresults-header-fg: #666;
+ --searchresults-border-color: #98a3ad;
+ --searchresults-li-bg: #2b2b2f;
+ --search-mark-bg: #355c7d;
+ }
+}
diff --git a/pr-preview/pr-83/developer-guide/book.html b/pr-preview/pr-83/developer-guide/book.html
new file mode 100644
index 000000000..2b38c3621
--- /dev/null
+++ b/pr-preview/pr-83/developer-guide/book.html
@@ -0,0 +1,371 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Contributors
+See the contributors graph on GitHub +for more up to date information.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/developer-guide/ratatui.html b/pr-preview/pr-83/developer-guide/ratatui.html
new file mode 100644
index 000000000..1e9a05865
--- /dev/null
+++ b/pr-preview/pr-83/developer-guide/ratatui.html
@@ -0,0 +1,291 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Ratatui Book
+The ratatui-book is written in
+mdbook.
The book is built as HTML pages as part of a +GitHub Action +and is available to view at https://ratatui-org.github.io/ratatui-book/.
+Feel free to make contributions if you’d like to improve the documentation.
+If you want to set up your local environment, you can run the following:
+cargo install mdbook --version 0.4.30
+cargo install mdbook-admonish --version 1.9.0
+cargo install mdbook-svgbob2 --version 0.3.0
+cargo install mdbook-linkcheck --version 0.7.7
+cargo install mdbook-mermaid --version 0.12.6
+cargo install mdbook-emojicodes --version 0.2.2
+These plugins allow additional features.
+mdbook-admonish
+The following raw markdown:
+```admonish note
+This is a note
+```
+
+```admonish tip
+This is a tip
+```
+
+```admonish warning
+This is a warning
+```
+
+```admonish info
+This is a info
+```
+will render as the following:
+ + + + +mdbook-mermaid
+The following raw markdown:
+```mermaid
+graph TD;
+ A-->B;
+ A-->C;
+ B-->D;
+ C-->D;
+```
+will render as the following:
+graph TD; + A-->B; + A-->C; + B-->D; + C-->D; ++
mdbook-svgbob2
+The following raw markdown:
+```svgbob
+ .---.
+ /-o-/--
+ .-/ / /->
+ ( * \/
+ '-. \
+ \ /
+ '
+```
+will render as the following:
+ +mdbook-emojicodes
+The following raw markdown:
+I love cats 🐱 and dogs 🐶, I have two, one's gray, like a raccoon 🦝, and the other
+one is black, like the night 🌃.
+will render as the following:
+I love cats 🐱 and dogs 🐶, I have two, one’s gray, like a raccoon 🦝, and the other +one is black, like the night 🌃.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/elasticlunr.min.js b/pr-preview/pr-83/elasticlunr.min.js
new file mode 100644
index 000000000..94b20dd2e
--- /dev/null
+++ b/pr-preview/pr-83/elasticlunr.min.js
@@ -0,0 +1,10 @@
+/**
+ * elasticlunr - http://weixsong.github.io
+ * Lightweight full-text search engine in Javascript for browser search and offline search. - 0.9.5
+ *
+ * Copyright (C) 2017 Oliver Nightingale
+ * Copyright (C) 2017 Wei Song
+ * MIT Licensed
+ * @license
+ */
+!function(){function e(e){if(null===e||"object"!=typeof e)return e;var t=e.constructor();for(var n in e)e.hasOwnProperty(n)&&(t[n]=e[n]);return t}var t=function(e){var n=new t.Index;return n.pipeline.add(t.trimmer,t.stopWordFilter,t.stemmer),e&&e.call(n,n),n};t.version="0.9.5",lunr=t,t.utils={},t.utils.warn=function(e){return function(t){e.console&&console.warn&&console.warn(t)}}(this),t.utils.toString=function(e){return void 0===e||null===e?"":e.toString()},t.EventEmitter=function(){this.events={}},t.EventEmitter.prototype.addListener=function(){var e=Array.prototype.slice.call(arguments),t=e.pop(),n=e;if("function"!=typeof t)throw new TypeError("last argument must be a function");n.forEach(function(e){this.hasHandler(e)||(this.events[e]=[]),this.events[e].push(t)},this)},t.EventEmitter.prototype.removeListener=function(e,t){if(this.hasHandler(e)){var n=this.events[e].indexOf(t);-1!==n&&(this.events[e].splice(n,1),0==this.events[e].length&&delete this.events[e])}},t.EventEmitter.prototype.emit=function(e){if(this.hasHandler(e)){var t=Array.prototype.slice.call(arguments,1);this.events[e].forEach(function(e){e.apply(void 0,t)},this)}},t.EventEmitter.prototype.hasHandler=function(e){return e in this.events},t.tokenizer=function(e){if(!arguments.length||null===e||void 0===e)return[];if(Array.isArray(e)){var n=e.filter(function(e){return null===e||void 0===e?!1:!0});n=n.map(function(e){return t.utils.toString(e).toLowerCase()});var i=[];return n.forEach(function(e){var n=e.split(t.tokenizer.seperator);i=i.concat(n)},this),i}return e.toString().trim().toLowerCase().split(t.tokenizer.seperator)},t.tokenizer.defaultSeperator=/[\s\-]+/,t.tokenizer.seperator=t.tokenizer.defaultSeperator,t.tokenizer.setSeperator=function(e){null!==e&&void 0!==e&&"object"==typeof e&&(t.tokenizer.seperator=e)},t.tokenizer.resetSeperator=function(){t.tokenizer.seperator=t.tokenizer.defaultSeperator},t.tokenizer.getSeperator=function(){return t.tokenizer.seperator},t.Pipeline=function(){this._queue=[]},t.Pipeline.registeredFunctions={},t.Pipeline.registerFunction=function(e,n){n in t.Pipeline.registeredFunctions&&t.utils.warn("Overwriting existing registered function: "+n),e.label=n,t.Pipeline.registeredFunctions[n]=e},t.Pipeline.getRegisteredFunction=function(e){return e in t.Pipeline.registeredFunctions!=!0?null:t.Pipeline.registeredFunctions[e]},t.Pipeline.warnIfFunctionNotRegistered=function(e){var n=e.label&&e.label in this.registeredFunctions;n||t.utils.warn("Function is not registered with pipeline. This may cause problems when serialising the index.\n",e)},t.Pipeline.load=function(e){var n=new t.Pipeline;return e.forEach(function(e){var i=t.Pipeline.getRegisteredFunction(e);if(!i)throw new Error("Cannot load un-registered function: "+e);n.add(i)}),n},t.Pipeline.prototype.add=function(){var e=Array.prototype.slice.call(arguments);e.forEach(function(e){t.Pipeline.warnIfFunctionNotRegistered(e),this._queue.push(e)},this)},t.Pipeline.prototype.after=function(e,n){t.Pipeline.warnIfFunctionNotRegistered(n);var i=this._queue.indexOf(e);if(-1===i)throw new Error("Cannot find existingFn");this._queue.splice(i+1,0,n)},t.Pipeline.prototype.before=function(e,n){t.Pipeline.warnIfFunctionNotRegistered(n);var i=this._queue.indexOf(e);if(-1===i)throw new Error("Cannot find existingFn");this._queue.splice(i,0,n)},t.Pipeline.prototype.remove=function(e){var t=this._queue.indexOf(e);-1!==t&&this._queue.splice(t,1)},t.Pipeline.prototype.run=function(e){for(var t=[],n=e.length,i=this._queue.length,o=0;n>o;o++){for(var r=e[o],s=0;i>s&&(r=this._queue[s](r,o,e),void 0!==r&&null!==r);s++);void 0!==r&&null!==r&&t.push(r)}return t},t.Pipeline.prototype.reset=function(){this._queue=[]},t.Pipeline.prototype.get=function(){return this._queue},t.Pipeline.prototype.toJSON=function(){return this._queue.map(function(e){return t.Pipeline.warnIfFunctionNotRegistered(e),e.label})},t.Index=function(){this._fields=[],this._ref="id",this.pipeline=new t.Pipeline,this.documentStore=new t.DocumentStore,this.index={},this.eventEmitter=new t.EventEmitter,this._idfCache={},this.on("add","remove","update",function(){this._idfCache={}}.bind(this))},t.Index.prototype.on=function(){var e=Array.prototype.slice.call(arguments);return this.eventEmitter.addListener.apply(this.eventEmitter,e)},t.Index.prototype.off=function(e,t){return this.eventEmitter.removeListener(e,t)},t.Index.load=function(e){e.version!==t.version&&t.utils.warn("version mismatch: current "+t.version+" importing "+e.version);var n=new this;n._fields=e.fields,n._ref=e.ref,n.documentStore=t.DocumentStore.load(e.documentStore),n.pipeline=t.Pipeline.load(e.pipeline),n.index={};for(var i in e.index)n.index[i]=t.InvertedIndex.load(e.index[i]);return n},t.Index.prototype.addField=function(e){return this._fields.push(e),this.index[e]=new t.InvertedIndex,this},t.Index.prototype.setRef=function(e){return this._ref=e,this},t.Index.prototype.saveDocument=function(e){return this.documentStore=new t.DocumentStore(e),this},t.Index.prototype.addDoc=function(e,n){if(e){var n=void 0===n?!0:n,i=e[this._ref];this.documentStore.addDoc(i,e),this._fields.forEach(function(n){var o=this.pipeline.run(t.tokenizer(e[n]));this.documentStore.addFieldLength(i,n,o.length);var r={};o.forEach(function(e){e in r?r[e]+=1:r[e]=1},this);for(var s in r){var u=r[s];u=Math.sqrt(u),this.index[n].addToken(s,{ref:i,tf:u})}},this),n&&this.eventEmitter.emit("add",e,this)}},t.Index.prototype.removeDocByRef=function(e){if(e&&this.documentStore.isDocStored()!==!1&&this.documentStore.hasDoc(e)){var t=this.documentStore.getDoc(e);this.removeDoc(t,!1)}},t.Index.prototype.removeDoc=function(e,n){if(e){var n=void 0===n?!0:n,i=e[this._ref];this.documentStore.hasDoc(i)&&(this.documentStore.removeDoc(i),this._fields.forEach(function(n){var o=this.pipeline.run(t.tokenizer(e[n]));o.forEach(function(e){this.index[n].removeToken(e,i)},this)},this),n&&this.eventEmitter.emit("remove",e,this))}},t.Index.prototype.updateDoc=function(e,t){var t=void 0===t?!0:t;this.removeDocByRef(e[this._ref],!1),this.addDoc(e,!1),t&&this.eventEmitter.emit("update",e,this)},t.Index.prototype.idf=function(e,t){var n="@"+t+"/"+e;if(Object.prototype.hasOwnProperty.call(this._idfCache,n))return this._idfCache[n];var i=this.index[t].getDocFreq(e),o=1+Math.log(this.documentStore.length/(i+1));return this._idfCache[n]=o,o},t.Index.prototype.getFields=function(){return this._fields.slice()},t.Index.prototype.search=function(e,n){if(!e)return[];e="string"==typeof e?{any:e}:JSON.parse(JSON.stringify(e));var i=null;null!=n&&(i=JSON.stringify(n));for(var o=new t.Configuration(i,this.getFields()).get(),r={},s=Object.keys(e),u=0;u
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Search
+
+
+
+
+ Ratatui
+Check out the CONTRIBUTING GUIDE +for more information.
+Keep PRs small, intentional and focused
+Try to do one pull request per change. The time taken to review a PR grows exponential with the size +of the change. Small focused PRs will generally be much more faster to review. PRs that include both +refactoring (or reformatting) with actual changes are more difficult to review as every line of the +change becomes a place where a bug may have been introduced. Consider splitting refactoring / +reformatting changes into a separate PR from those that make a behavioral change, as the tests help +guarantee that the behavior is unchanged.
+Search tui-rs for similar work
+The original fork of Ratatui, tui-rs, has a large amount of
+history of the project. Please search, read, link, and summarize any relevant
+issues,
+discussions and
+pull requests.
Use conventional commits
+We use conventional commits and check for them as +a lint build step. To help adhere to the format, we recommend to install +Commitizen. By using this tool you automatically +follow the configuration defined in .cz.toml. Your commit messages should have enough +information to help someone reading the CHANGELOG understand what is new just from +the title. The summary helps expand on that to provide information that helps provide more context, +describes the nature of the problem that the commit is solving and any unintuitive effects of the +change. It’s rare that code changes can easily communicate intent, so make sure this is clearly +documented.
+Clean up your commits
+The final version of your PR that will be committed to the repository should be rebased and tested +against main. Every commit will end up as a line in the changelog, so please squash commits that are +only formatting or incremental fixes to things brought up as part of the PR review. Aim for a single +commit (unless there is a strong reason to stack the commits). See +Git Best Practices - On Sausage Making +for more on this.
+Run CI tests before pushing a PR
+We’re using cargo-husky to automatically run git hooks,
+which will run cargo make ci before each push. To initialize the hook run cargo test. If
+cargo-make is not installed, it will provide instructions to install it for you. This will ensure
+that your code is formatted, compiles and passes all tests before you push. If you need to skip this
+check, you can use git push --no-verify.
Sign your commits
+We use commit signature verification, which will block commits from being merged via the UI unless +they are signed. To set up your machine to sign commits, see +managing commit signature verification +in GitHub docs.
+Setup
+Clone the repo and build it using cargo-make
+Ratatui is an ordinary Rust project where common tasks are managed with
+cargo-make. It wraps common cargo commands with sane
+defaults depending on your platform of choice. Building the project should be as easy as running
+cargo make build.
git clone https://github.com/ratatui-org/ratatui.git
+cd ratatui
+cargo make build
+Tests
+The test coverage of the crate is reasonably good,
+but this can always be improved. Focus on keeping the tests simple and obvious and write unit tests
+for all new or modified code. Beside the usual doc and unit tests, one of the most valuable test you
+can write for Ratatui is a test against the TestBackend. It allows you to assert the content of
+the output buffer that would have been flushed to the terminal after a given draw call. See
+widgets_block_renders in tests/widgets_block.rs for an example.
When writing tests, generally prefer to write unit tests and doc tests directly in the code file
+being tested rather than integration tests in the tests/ folder.
If an area that you’re making a change in is not tested, write tests to characterize the existing
+behavior before changing it. This helps ensure that we don’t introduce bugs to existing software
+using Ratatui (and helps make it easy to migrate apps still using tui-rs).
For coverage, we have two bacon jobs (one for all tests, and one for
+unit tests, keyboard shortcuts v and u respectively) that run
+cargo-llvm-cov to report the coverage. Several plugins
+exist to show coverage directly in your editor. E.g.:
-
+
- https://marketplace.visualstudio.com/items?itemName=ryanluker.vscode-coverage-gutters +
- https://github.com/alepez/vim-llvmcov +
Use of unsafe for optimization purposes
+We don’t currently use any unsafe code in Ratatui, and would like to keep it that way. However there +may be specific cases that this becomes necessary in order to avoid slowness. Please see +this discussion for more about the +decision.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/faq/index.html b/pr-preview/pr-83/faq/index.html
new file mode 100644
index 000000000..12567d1ec
--- /dev/null
+++ b/pr-preview/pr-83/faq/index.html
@@ -0,0 +1,219 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Why am I getting duplicate key events on Windows?
+A lot of examples out there in the wild might use the following code for sending key presses:
+ CrosstermEvent::Key(e) => tx.send(Event::Key(e)),However, on Windows, when using Crossterm, this will send the same Event::Key(e) twice; one for
+when you press the key, i.e. KeyEventKind::Press and one for when you release the key, i.e.
+KeyEventKind::Release. On MacOS and Linux only KeyEventKind::Press kinds of key event is
+generated.
To make the code work as expected across all platforms, you can do this instead:
+ CrosstermEvent::Key(key) => {
+ if key.kind == KeyEventKind::Press {
+ event_tx.send(Event::Key(key)).unwrap();
+ }
+ },
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/faq/ratatui-vs-tui-realm.html b/pr-preview/pr-83/faq/ratatui-vs-tui-realm.html
new file mode 100644
index 000000000..7167a91b0
--- /dev/null
+++ b/pr-preview/pr-83/faq/ratatui-vs-tui-realm.html
@@ -0,0 +1,250 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ FAQ
+ + +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/faq/tokio-async.html b/pr-preview/pr-83/faq/tokio-async.html
new file mode 100644
index 000000000..35bc40dd6
--- /dev/null
+++ b/pr-preview/pr-83/faq/tokio-async.html
@@ -0,0 +1,462 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ratatui vs tui-realm
+Fundamentally, the difference is that ratatui is a library but
+tui-realm is a framework.
The terms library and framework are often used interchangeably in software development, but they +serve different purposes and have distinct characteristics.
+Library
+-
+
- Usage: A library is a collection of functions and procedures that a programmer can call in +their application. The library provides specific functionality, but it’s the developer’s +responsibility to explicitly call and use it. +
- Control Flow: In the case of a library, the control flow remains with the developer’s +application. The developer chooses when and where to use the library. +
- Passivity: Libraries are passive in nature. They wait for the application’s code to invoke +their methods. +
- Example: Imagine you’re building a house. A library would be like a toolbox with tools +(functions) that you can use at will. You decide when and where to use each tool. +
Framework
+-
+
- Usage: A framework is a pre-built structure or scaffold that developers build their +application within. It provides a foundation, enforcing a particular way of creating an +application. +
- Control Flow: With a framework, the control flow is inverted. The framework decides the flow +of control by providing places for the developer to plug in their own logic (often referred to as +“Inversion of Control” or IoC). +
- Activeness: Frameworks are active and have a predefined flow of their own. The developer fills +in specific pieces of the framework with their own code. +
- Example: Using the house-building analogy, a framework would be like a prefabricated house +where the main structure is already built. You’re tasked with filling in the interiors and decor, +but you have to follow the design and architecture already provided by the prefabricated design. +
While ratatui provides tools (widgets) for building terminal UIs, it doesn’t dictate or enforce a
+specific way to structure your application. You need to decide how to best use the library in your
+particular context, giving you more flexibility.
In contrast, tui-realm might provide more guidelines and enforcements about how your application
+should be structured or how data flows through it. And, for the price of that freedom, you get more
+features out of the box with tui-realm and potentially lesser code in your application to do the
+same thing that you would with ratatui.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/faq/tui-rs-history.html b/pr-preview/pr-83/faq/tui-rs-history.html
new file mode 100644
index 000000000..de2c60221
--- /dev/null
+++ b/pr-preview/pr-83/faq/tui-rs-history.html
@@ -0,0 +1,232 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ When should I use
+
+
+
+
+ When should I use tokio and async/await?
+ratatui isn’t a native async library. So is it beneficial to use tokio or async/await?
And as a user, there really is only one point of interface with the ratatui library and that’s the
+terminal.draw(|f| ui(f)) functionality, because the rendering of widgets happens in ui(f).
+Everything else in your code is your own to do as you wish.
Should terminal.draw(|f| ui(f)) be async? Possibly. Rendering to the terminal buffer is
+relatively fast, especially using the double buffer technique that only renders diffs that ratatui
+uses.
Can we make it async ourselves? Yes, we can. Check out
+https://github.com/ratatui-org/ratatui-async-template for an example.
The only other part related to ratatui that is beneficial to being async is reading the key
+event inputs from stdin, and that can be made async with crossterm’s event-stream.
So the real question is what other parts of your app require async or benefit from being async?
+If the answer is not much, maybe it is simpler to not use async and avoiding tokio.
Another way to think about it is, do you think your app would work better with 1 thread like this?
+ +Or would it work with 3 threads / tokio tasks like this:
The former can be done without any async code and the latter is the approach showcased in
+ratatui-async-template with tokio.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/favicon.png b/pr-preview/pr-83/favicon.png
new file mode 100644
index 000000000..a5b1aa16c
Binary files /dev/null and b/pr-preview/pr-83/favicon.png differ
diff --git a/pr-preview/pr-83/favicon.svg b/pr-preview/pr-83/favicon.svg
new file mode 100644
index 000000000..90e0ea58b
--- /dev/null
+++ b/pr-preview/pr-83/favicon.svg
@@ -0,0 +1,22 @@
+
+
diff --git a/pr-preview/pr-83/fonts/OPEN-SANS-LICENSE.txt b/pr-preview/pr-83/fonts/OPEN-SANS-LICENSE.txt
new file mode 100644
index 000000000..d64569567
--- /dev/null
+++ b/pr-preview/pr-83/fonts/OPEN-SANS-LICENSE.txt
@@ -0,0 +1,202 @@
+
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
+
+ APPENDIX: How to apply the Apache License to your work.
+
+ To apply the Apache License to your work, attach the following
+ boilerplate notice, with the fields enclosed by brackets "[]"
+ replaced with your own identifying information. (Don't include
+ the brackets!) The text should be enclosed in the appropriate
+ comment syntax for the file format. We also recommend that a
+ file or class name and description of purpose be included on the
+ same "printed page" as the copyright notice for easier
+ identification within third-party archives.
+
+ Copyright [yyyy] [name of copyright owner]
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
diff --git a/pr-preview/pr-83/fonts/SOURCE-CODE-PRO-LICENSE.txt b/pr-preview/pr-83/fonts/SOURCE-CODE-PRO-LICENSE.txt
new file mode 100644
index 000000000..366206f54
--- /dev/null
+++ b/pr-preview/pr-83/fonts/SOURCE-CODE-PRO-LICENSE.txt
@@ -0,0 +1,93 @@
+Copyright 2010, 2012 Adobe Systems Incorporated (http://www.adobe.com/), with Reserved Font Name 'Source'. All Rights Reserved. Source is a trademark of Adobe Systems Incorporated in the United States and/or other countries.
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.
diff --git a/pr-preview/pr-83/fonts/fonts.css b/pr-preview/pr-83/fonts/fonts.css
new file mode 100644
index 000000000..858efa598
--- /dev/null
+++ b/pr-preview/pr-83/fonts/fonts.css
@@ -0,0 +1,100 @@
+/* Open Sans is licensed under the Apache License, Version 2.0. See http://www.apache.org/licenses/LICENSE-2.0 */
+/* Source Code Pro is under the Open Font License. See https://scripts.sil.org/cms/scripts/page.php?site_id=nrsi&id=OFL */
+
+/* open-sans-300 - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
+@font-face {
+ font-family: 'Open Sans';
+ font-style: normal;
+ font-weight: 300;
+ src: local('Open Sans Light'), local('OpenSans-Light'),
+ url('open-sans-v17-all-charsets-300.woff2') format('woff2');
+}
+
+/* open-sans-300italic - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
+@font-face {
+ font-family: 'Open Sans';
+ font-style: italic;
+ font-weight: 300;
+ src: local('Open Sans Light Italic'), local('OpenSans-LightItalic'),
+ url('open-sans-v17-all-charsets-300italic.woff2') format('woff2');
+}
+
+/* open-sans-regular - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
+@font-face {
+ font-family: 'Open Sans';
+ font-style: normal;
+ font-weight: 400;
+ src: local('Open Sans Regular'), local('OpenSans-Regular'),
+ url('open-sans-v17-all-charsets-regular.woff2') format('woff2');
+}
+
+/* open-sans-italic - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
+@font-face {
+ font-family: 'Open Sans';
+ font-style: italic;
+ font-weight: 400;
+ src: local('Open Sans Italic'), local('OpenSans-Italic'),
+ url('open-sans-v17-all-charsets-italic.woff2') format('woff2');
+}
+
+/* open-sans-600 - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
+@font-face {
+ font-family: 'Open Sans';
+ font-style: normal;
+ font-weight: 600;
+ src: local('Open Sans SemiBold'), local('OpenSans-SemiBold'),
+ url('open-sans-v17-all-charsets-600.woff2') format('woff2');
+}
+
+/* open-sans-600italic - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
+@font-face {
+ font-family: 'Open Sans';
+ font-style: italic;
+ font-weight: 600;
+ src: local('Open Sans SemiBold Italic'), local('OpenSans-SemiBoldItalic'),
+ url('open-sans-v17-all-charsets-600italic.woff2') format('woff2');
+}
+
+/* open-sans-700 - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
+@font-face {
+ font-family: 'Open Sans';
+ font-style: normal;
+ font-weight: 700;
+ src: local('Open Sans Bold'), local('OpenSans-Bold'),
+ url('open-sans-v17-all-charsets-700.woff2') format('woff2');
+}
+
+/* open-sans-700italic - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
+@font-face {
+ font-family: 'Open Sans';
+ font-style: italic;
+ font-weight: 700;
+ src: local('Open Sans Bold Italic'), local('OpenSans-BoldItalic'),
+ url('open-sans-v17-all-charsets-700italic.woff2') format('woff2');
+}
+
+/* open-sans-800 - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
+@font-face {
+ font-family: 'Open Sans';
+ font-style: normal;
+ font-weight: 800;
+ src: local('Open Sans ExtraBold'), local('OpenSans-ExtraBold'),
+ url('open-sans-v17-all-charsets-800.woff2') format('woff2');
+}
+
+/* open-sans-800italic - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
+@font-face {
+ font-family: 'Open Sans';
+ font-style: italic;
+ font-weight: 800;
+ src: local('Open Sans ExtraBold Italic'), local('OpenSans-ExtraBoldItalic'),
+ url('open-sans-v17-all-charsets-800italic.woff2') format('woff2');
+}
+
+/* source-code-pro-500 - latin_vietnamese_latin-ext_greek_cyrillic-ext_cyrillic */
+@font-face {
+ font-family: 'Source Code Pro';
+ font-style: normal;
+ font-weight: 500;
+ src: url('source-code-pro-v11-all-charsets-500.woff2') format('woff2');
+}
diff --git a/pr-preview/pr-83/fonts/open-sans-v17-all-charsets-300.woff2 b/pr-preview/pr-83/fonts/open-sans-v17-all-charsets-300.woff2
new file mode 100644
index 000000000..9f51be370
Binary files /dev/null and b/pr-preview/pr-83/fonts/open-sans-v17-all-charsets-300.woff2 differ
diff --git a/pr-preview/pr-83/fonts/open-sans-v17-all-charsets-300italic.woff2 b/pr-preview/pr-83/fonts/open-sans-v17-all-charsets-300italic.woff2
new file mode 100644
index 000000000..2f5454484
Binary files /dev/null and b/pr-preview/pr-83/fonts/open-sans-v17-all-charsets-300italic.woff2 differ
diff --git a/pr-preview/pr-83/fonts/open-sans-v17-all-charsets-600.woff2 b/pr-preview/pr-83/fonts/open-sans-v17-all-charsets-600.woff2
new file mode 100644
index 000000000..f503d558d
Binary files /dev/null and b/pr-preview/pr-83/fonts/open-sans-v17-all-charsets-600.woff2 differ
diff --git a/pr-preview/pr-83/fonts/open-sans-v17-all-charsets-600italic.woff2 b/pr-preview/pr-83/fonts/open-sans-v17-all-charsets-600italic.woff2
new file mode 100644
index 000000000..c99aabe80
Binary files /dev/null and b/pr-preview/pr-83/fonts/open-sans-v17-all-charsets-600italic.woff2 differ
diff --git a/pr-preview/pr-83/fonts/open-sans-v17-all-charsets-700.woff2 b/pr-preview/pr-83/fonts/open-sans-v17-all-charsets-700.woff2
new file mode 100644
index 000000000..421a1ab25
Binary files /dev/null and b/pr-preview/pr-83/fonts/open-sans-v17-all-charsets-700.woff2 differ
diff --git a/pr-preview/pr-83/fonts/open-sans-v17-all-charsets-700italic.woff2 b/pr-preview/pr-83/fonts/open-sans-v17-all-charsets-700italic.woff2
new file mode 100644
index 000000000..12ce3d20d
Binary files /dev/null and b/pr-preview/pr-83/fonts/open-sans-v17-all-charsets-700italic.woff2 differ
diff --git a/pr-preview/pr-83/fonts/open-sans-v17-all-charsets-800.woff2 b/pr-preview/pr-83/fonts/open-sans-v17-all-charsets-800.woff2
new file mode 100644
index 000000000..c94a223b0
Binary files /dev/null and b/pr-preview/pr-83/fonts/open-sans-v17-all-charsets-800.woff2 differ
diff --git a/pr-preview/pr-83/fonts/open-sans-v17-all-charsets-800italic.woff2 b/pr-preview/pr-83/fonts/open-sans-v17-all-charsets-800italic.woff2
new file mode 100644
index 000000000..eed7d3c63
Binary files /dev/null and b/pr-preview/pr-83/fonts/open-sans-v17-all-charsets-800italic.woff2 differ
diff --git a/pr-preview/pr-83/fonts/open-sans-v17-all-charsets-italic.woff2 b/pr-preview/pr-83/fonts/open-sans-v17-all-charsets-italic.woff2
new file mode 100644
index 000000000..398b68a08
Binary files /dev/null and b/pr-preview/pr-83/fonts/open-sans-v17-all-charsets-italic.woff2 differ
diff --git a/pr-preview/pr-83/fonts/open-sans-v17-all-charsets-regular.woff2 b/pr-preview/pr-83/fonts/open-sans-v17-all-charsets-regular.woff2
new file mode 100644
index 000000000..8383e94c6
Binary files /dev/null and b/pr-preview/pr-83/fonts/open-sans-v17-all-charsets-regular.woff2 differ
diff --git a/pr-preview/pr-83/fonts/source-code-pro-v11-all-charsets-500.woff2 b/pr-preview/pr-83/fonts/source-code-pro-v11-all-charsets-500.woff2
new file mode 100644
index 000000000..722245682
Binary files /dev/null and b/pr-preview/pr-83/fonts/source-code-pro-v11-all-charsets-500.woff2 differ
diff --git a/pr-preview/pr-83/highlight.css b/pr-preview/pr-83/highlight.css
new file mode 100644
index 000000000..ba57b82b2
--- /dev/null
+++ b/pr-preview/pr-83/highlight.css
@@ -0,0 +1,82 @@
+/*
+ * An increased contrast highlighting scheme loosely based on the
+ * "Base16 Atelier Dune Light" theme by Bram de Haan
+ * (http://atelierbram.github.io/syntax-highlighting/atelier-schemes/dune)
+ * Original Base16 color scheme by Chris Kempson
+ * (https://github.com/chriskempson/base16)
+ */
+
+/* Comment */
+.hljs-comment,
+.hljs-quote {
+ color: #575757;
+}
+
+/* Red */
+.hljs-variable,
+.hljs-template-variable,
+.hljs-attribute,
+.hljs-tag,
+.hljs-name,
+.hljs-regexp,
+.hljs-link,
+.hljs-name,
+.hljs-selector-id,
+.hljs-selector-class {
+ color: #d70025;
+}
+
+/* Orange */
+.hljs-number,
+.hljs-meta,
+.hljs-built_in,
+.hljs-builtin-name,
+.hljs-literal,
+.hljs-type,
+.hljs-params {
+ color: #b21e00;
+}
+
+/* Green */
+.hljs-string,
+.hljs-symbol,
+.hljs-bullet {
+ color: #008200;
+}
+
+/* Blue */
+.hljs-title,
+.hljs-section {
+ color: #0030f2;
+}
+
+/* Purple */
+.hljs-keyword,
+.hljs-selector-tag {
+ color: #9d00ec;
+}
+
+.hljs {
+ display: block;
+ overflow-x: auto;
+ background: #f6f7f6;
+ color: #000;
+}
+
+.hljs-emphasis {
+ font-style: italic;
+}
+
+.hljs-strong {
+ font-weight: bold;
+}
+
+.hljs-addition {
+ color: #22863a;
+ background-color: #f0fff4;
+}
+
+.hljs-deletion {
+ color: #b31d28;
+ background-color: #ffeef0;
+}
diff --git a/pr-preview/pr-83/highlight.js b/pr-preview/pr-83/highlight.js
new file mode 100644
index 000000000..180385b70
--- /dev/null
+++ b/pr-preview/pr-83/highlight.js
@@ -0,0 +1,6 @@
+/*
+ Highlight.js 10.1.1 (93fd0d73)
+ License: BSD-3-Clause
+ Copyright (c) 2006-2020, Ivan Sagalaev
+*/
+var hljs=function(){"use strict";function e(n){Object.freeze(n);var t="function"==typeof n;return Object.getOwnPropertyNames(n).forEach((function(r){!Object.hasOwnProperty.call(n,r)||null===n[r]||"object"!=typeof n[r]&&"function"!=typeof n[r]||t&&("caller"===r||"callee"===r||"arguments"===r)||Object.isFrozen(n[r])||e(n[r])})),n}class n{constructor(e){void 0===e.data&&(e.data={}),this.data=e.data}ignoreMatch(){this.ignore=!0}}function t(e){return e.replace(/&/g,"&").replace(//g,">").replace(/"/g,""").replace(/'/g,"'")}function r(e,...n){var t={};for(const n in e)t[n]=e[n];return n.forEach((function(e){for(const n in e)t[n]=e[n]})),t}function a(e){return e.nodeName.toLowerCase()}var i=Object.freeze({__proto__:null,escapeHTML:t,inherit:r,nodeStream:function(e){var n=[];return function e(t,r){for(var i=t.firstChild;i;i=i.nextSibling)3===i.nodeType?r+=i.nodeValue.length:1===i.nodeType&&(n.push({event:"start",offset:r,node:i}),r=e(i,r),a(i).match(/br|hr|img|input/)||n.push({event:"stop",offset:r,node:i}));return r}(e,0),n},mergeStreams:function(e,n,r){var i=0,s="",o=[];function l(){return e.length&&n.length?e[0].offset!==n[0].offset?e[0].offset
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ tui.rs history
+This project was forked from tui-rs in February 2023, with
+the blessing of the original author, Florian Dehau
+(@fdehau).
The original repository contains all the issues, PRs and discussion that were raised originally, and +it is useful to refer to when contributing code, documentation, or issues with Ratatui.
+We imported all the PRs from the original repository and implemented many of the smaller ones and +made notes on the leftovers. These are marked as draft PRs and labelled as +imported from tui. +We have documented the current state of those PRs, and anyone is welcome to pick them up and +continue the work on them.
+We have not imported all issues opened on the previous repository. For that reason, anyone wanting +to work on or discuss an issue will have to follow the following workflow:
+-
+
- Recreate the issue +
- Start by referencing the original issue:
+
Referencing issue #[<issue number>](<original issue link>)
+ - Then, paste the original issues opening text +
You can then resume the conversation by replying to the new issue you have created.
+ +":e:f.tabReplace?e.replace(/\t/g,f.tabReplace):e):e}function E(e){let n=null;const t=function(e){var n=e.className+" ";n+=e.parentNode?e.parentNode.className:"";const t=f.languageDetectRe.exec(n);if(t){var r=T(t[1]);return r||(console.warn(g.replace("{}",t[1])),console.warn("Falling back to no-highlight mode for this block.",e)),r?t[1]:"no-highlight"}return n.split(/\s+/).find(e=>p(e)||T(e))}(e);if(p(t))return;S("before:highlightBlock",{block:e,language:t}),f.useBR?(n=document.createElement("div")).innerHTML=e.innerHTML.replace(/\n/g,"").replace(/
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/highlights/v0.22.html b/pr-preview/pr-83/highlights/v0.22.html
new file mode 100644
index 000000000..772a43a0f
--- /dev/null
+++ b/pr-preview/pr-83/highlights/v0.22.html
@@ -0,0 +1,397 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ New backend:
+
+
+
+
+
+
+
+
+
+Color: support conversion from
+
+
+
+
+
+Migration from
+
+
+
+
+
+ v0.21
+New backend: termwiz
+ratatui supports a new backend called termwiz which is a “Terminal Wizardry” crate that powers
+wezterm.
To use it, enable the termwiz feature in Cargo.toml:
[dependencies.ratatui]
+version = "0.21.0"
+features = ["termwiz"]
+default-features = false
+Then you can utilize TermwizBackend object for creating a terminal. Here is a simple program that
+shows a text on the screen for 5 seconds using ratatui + termwiz:
use ratatui::{backend::TermwizBackend, widgets::Paragraph, Terminal};
+use std::{
+ error::Error,
+ thread,
+ time::{Duration, Instant},
+};
+
+fn main() -> Result<(), Box<dyn Error>> {
+ let backend = TermwizBackend::new()?;
+ let mut terminal = Terminal::new(backend)?;
+ terminal.hide_cursor()?;
+
+ let now = Instant::now();
+ while now.elapsed() < Duration::from_secs(5) {
+ terminal.draw(|f| f.render_widget(Paragraph::new("termwiz example"), f.size()))?;
+ thread::sleep(Duration::from_millis(250));
+ }
+
+ terminal.show_cursor()?;
+ terminal.flush()?;
+ Ok(())
+}
++
New widget: Calendar
+A calendar widget has been added which was originally a part of the +extra-widgets repository.
+Since this new widget depends on time crate, we gated it behind widget-calendar feature to avoid
+an extra dependency:
[dependencies.ratatui]
+version = "0.21.0"
+features = ["widget-calendar"]
+Here is the example usage:
+Monthly::new(
+ time::Date::from_calendar_date(2023, time::Month::January, 1).unwrap(),
+ CalendarEventStore::default(),
+)
+.show_weekdays_header(Style::default())
+.show_month_header(Style::default())
+.show_surrounding(Style::default()),
+Results in:
+ January 2023
+ Su Mo Tu We Th Fr Sa
+ 1 2 3 4 5 6 7
+ 8 9 10 11 12 13 14
+ 15 16 17 18 19 20 21
+ 22 23 24 25 26 27 28
+ 29 30 31 1 2 3 4
++
New widget: Circle
+Circle widget has been added with the use-case of showing an accuracy radius on the world map.
Here is an example of how to use it with Canvas:
Canvas::default()
+ .paint(|ctx| {
+ ctx.draw(&Circle {
+ x: 5.0,
+ y: 2.0,
+ radius: 5.0,
+ color: Color::Reset,
+ });
+ })
+ .marker(Marker::Braille)
+ .x_bounds([-10.0, 10.0])
+ .y_bounds([-10.0, 10.0]),
+Results in:
+ ⡠⠤⢤⡀
+⢸⡁ ⡧
+ ⠑⠒⠚⠁
++
Inline Viewport
+This was a highly requested feature and the original implementation was done by +@fdehau himself. Folks at Atuin completed the +implementation and we are happy to finally have this incorporated in the new release!
+An inline viewport refers to a rectangular section of the terminal window that is set aside for +displaying content.
+In the repository, there is an example that simulates downloading multiple files in parallel: +https://github.com/ratatui-org/ratatui/blob/main/examples/inline.rs
++
Block: title on bottom
+++Before you could only put the title on the top row of a Block. Now you can put it on the bottom +row! Revolutionary.
+
For example, place the title on the bottom and center:
+Paragraph::new("ratatui")
+ .alignment(Alignment::Center)
+ .block(
+ Block::default()
+ .title(Span::styled("Title", Style::default()))
+ .title_on_bottom()
+ .title_alignment(Alignment::Center)
+ .borders(Borders::ALL),
+ )
+Results in:
+┌─────────────────────┐
+│ ratatui │
+│ │
+└────────Title────────┘
++
Block: support adding padding
+If we want to render a widget inside a Block with a certain distance from its borders, we need to
+create another Layout element based on the outer Block, add a margin and render the Widget
+into it. Adding a padding property on the block element skips the creation of this second Layout.
This property works especially when rendering texts, as we can just create a block with padding and +use it as the text wrapper:
+let block = Block::default()
+ .borders(Borders::ALL)
+ .padding(Padding::new(1, 1, 2, 2));
+let paragraph = Paragraph::new("example paragraph").block(block);
+f.render_widget(paragraph, area);
+Rendering another widget should be easy too, using the .inner method:
let block = Block::default().borders(Borders::ALL).padding(Padding {
+ left: todo!(),
+ right: todo!(),
+ top: todo!(),
+ bottom: todo!(),
+});
+let inner_block = Block::default().borders(Borders::ALL);
+let inner_area = block.inner(area);
+
+f.render_widget(block, area);
+f.render_widget(inner_block, inner_area);
+f.render_widget(paragraph, area);
++
Text: display secure data
+A new type called Masked is added for text-related types for masking data with a mask character.
+The example usage is as follows:
Line::from(vec![
+ Span::raw("Masked text: "),
+ Span::styled(
+ Masked::new("password", '*'),
+ Style::default().fg(Color::Red),
+ ),
+])
+Results in:
+Masked text: ********
++
border! macro
+A border! macro has been added that takes TOP, BOTTOM, LEFT, RIGHT, and ALL and returns
+a Borders object.
An empty border!() call returns NONE.
For example:
+border!(ALL)
+border!(LEFT, RIGHT)
+border!()
+This is gated behind a macros feature flag to ensure short build times. To enable it, update
+Cargo.toml as follows:
[dependencies.ratatui]
+version = "0.21.0"
+features = ["macros"]
+Going forward, we will most likely put the new macros behind macros feature as well.
+
Color: support conversion from String
+Have you ever needed this conversion?
+"black" => Color::Black,
+"red" => Color::Red,
+"green" => Color::Green,
+// etc.
+Don’t worry, we got you covered:
+Color::from_str("lightblue") // Color::LightBlue
+Color::from_str("10") // Color::Indexed(10)
+Color::from_str("#FF0000") // Color::Rgb(255, 0, 0)
++
Spans -> Line
+Line is a significantly better name over Spans as the plural causes confusion and the type
+really is a representation of a line of text made up of spans.
So, Spans is renamed as Line and a deprecation notice has been added.
See +https://github.com/ratatui-org/ratatui/pull/178 +for more discussion.
++
Other features
+-
+
Listnow has alen()method for returning the number of items
+Sparklinenow has adirection()method for specifying the render direction (left to right / +right to left)
+TableandListstates now haveoffset()andoffset_mut()methods
+- Expose the test buffer (
TestBackend) withDisplayimplementation
+
+
New apps
+Here is the list of applications that has been added:
+-
+
- oxycards: quiz card application built within the +terminal. +
- twitch-tui: twitch chat in the terminal. +
- tenere: TUI interface for LLMs. +
Also, we moved APPS.md file to the
+Wiki so check it out for more
+applications built with ratatui!
+
Migration from tui-rs
+We put together a migration guide at the Wiki: +Migrating from TUI
+Also, the minimum supported Rust version is 1.65.0
+
Contributing
+Any contribution is highly appreciated! There are +contribution guidelines for +getting started.
+Feel free to submit issues and throw in +ideas!
+If you are having a problem with ratatui or want to contribute to the project or just want to
+chit-chat, feel free to join our Discord server!
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/highlights/v0.23.html b/pr-preview/pr-83/highlights/v0.23.html
new file mode 100644
index 000000000..6edece07e
--- /dev/null
+++ b/pr-preview/pr-83/highlights/v0.23.html
@@ -0,0 +1,387 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ v0.22
+
+
+
+
+
+reposted from https://blog.orhun.dev/ratatui-0-22-0/
+Prelude
+We now have a prelude module! This allows users of the library to easily use ratatui without a
+huge amount of imports.
use ratatui::prelude::*;
+Aside from the main types that are used in the library, this prelude also re-exports several
+modules to make it easy to qualify types that would otherwise collide. For example:
use ratatui::{prelude::*, widgets::*};
+
+#[derive(Debug, Default, PartialEq, Eq)]
+struct Line;
+
+assert_eq!(Line::default(), Line);
+assert_eq!(text::Line::default(), ratatui::text::Line::from(vec![]));
++
New widget: Scrollbar
+A scrollbar widget has been added which can be used with any Rect. It can also be customized with
+different styles and symbols.
Here are the components of a Scrollbar:
<--▮------->
+^ ^ ^ ^
+│ │ │ └ end
+│ │ └──── track
+│ └──────── thumb
+└─────────── begin
+To use it, render it as a stateful widget along with ScrollbarState:
frame.render_stateful_widget(
+ Scrollbar::default()
+ .orientation(ScrollbarOrientation::VerticalRight)
+ .begin_symbol(Some("↑"))
+ .end_symbol(Some("↓")),
+ rect,
+ &mut scrollbar_state,
+);
+Will result in:
+┌scrollbar──────────────────↑
+│This is a longer line ║
+│Veeeeeeeeeeeeeeeery looo█
+│This is a line ║
+└───────────────────────────↓
++
Block: support multiple titles
+Block widget now supports having more than one title via Title widget.
Each title will be rendered with a single space separating titles that are in the same position or +alignment. When both centered and non-centered titles are rendered, the centered space is calculated +based on the full width of the block, rather than the leftover width.
+You can provide various types as the title, including strings, string slices, borrowed strings
+(Cow<str>), spans, or vectors of spans (Vec<Span>).
It can be used as follows:
+Block::default()
+ .borders(Borders::ALL)
+ .title("Title") // By default in the top right corner
+ .title(Title::from("Left").alignment(Alignment::Left))
+ .title(Title::from("Center").alignment(Alignment::Center))
+ .title(Title::from("Bottom").position(Position::Bottom))
+ .title(
+ Title::from("Bottom center")
+ .alignment(Alignment::Center)
+ .position(Position::Bottom),
+ );
+Results in:
+┌Title─Left──Center─────────────┐
+│ │
+│ │
+│ │
+└Bottom───Bottom center─────────┘
++
Barchart: support groups
+Barchart has been improved to support adding multiple bars from different data sets. This can be
+done by using the newly added Bar and BarGroup objects.
See the barchart example +for more information and implementation details.
++
Stylization shorthands
+It is possible to use style shorthands for str, Span, and Paragraph.
A crazy example would be:
+"hello"
+ .on_black()
+ .black()
+ .bold()
+ .underline()
+ .dimmed()
+ .slow_blink()
+ .crossed_out()
+ .reversed()
+This especially helps with concise styling:
+assert_eq!(
+ "hello".red().on_blue().bold(),
+ Span::styled("hello", Style::default().fg(Color::Red).bg(Color::Blue).add_modifier(Modifier::BOLD))
+)
++
Stylize everything
+All widgets can be styled now (i.e. set_style)
Styled trait is implemented for all the remaining widgets, including:
-
+
Barchart
+Chart(includingAxisandDataset)
+GaugeandLineGauge
+ListandListItem
+Sparkline
+Table,Row, andCell
+Tabs
+Style
+
+
Constant styles
+Styles can be constructed in a const context as follows:
const DEFAULT_MODIFIER: Modifier = Modifier::BOLD.union(Modifier::ITALIC);
+const EMPTY: Modifier = Modifier::empty();
+
+const DEFAULT_STYLE: Style = Style::with(DEFAULT_MODIFIER, EMPTY)
+ .fg(Color::Red)
+ .bg(Color::Black);
++
More colors formats
+It is now possible to parse hyphenated color names like light-red via Color::from_str.
Additionally, all colors from the +ANSI color table are supported (though some +names are not exactly the same).
+-
+
grayis sometimes calledwhite- this is not supported as we usewhitefor bright white
+grayis sometimes calledsilver- this is supported
+darkgrayis sometimes calledlight blackorbright black(both are supported)
+whiteis sometimes calledlight whiteorbright white(both are supported)
+- we support
brightandlightprefixes for all colors
+ - we support
"-","_", and" "as separators for all colors
+ - we support both
grayandgreyspellings
+
For example:
+use ratatui::style::Color;
+use std::str::FromStr;
+
+assert_eq!(Color::from_str("red"), Ok(Color::Red));
+assert_eq!("red".parse(), Ok(Color::Red));
+assert_eq!("lightred".parse(), Ok(Color::LightRed));
+assert_eq!("light red".parse(), Ok(Color::LightRed));
+assert_eq!("light-red".parse(), Ok(Color::LightRed));
+assert_eq!("light_red".parse(), Ok(Color::LightRed));
+assert_eq!("lightRed".parse(), Ok(Color::LightRed));
+assert_eq!("bright red".parse(), Ok(Color::LightRed));
+assert_eq!("bright-red".parse(), Ok(Color::LightRed));
+assert_eq!("silver".parse(), Ok(Color::Gray));
+assert_eq!("dark-grey".parse(), Ok(Color::DarkGray));
+assert_eq!("dark gray".parse(), Ok(Color::DarkGray));
+assert_eq!("light-black".parse(), Ok(Color::DarkGray));
+assert_eq!("white".parse(), Ok(Color::White));
+assert_eq!("bright white".parse(), Ok(Color::White));
++
Integrations
+Following tools are now integrated into the repository:
+-
+
cargo-husky: git pre-push hooks
+bacon: background code checks / coverage
+commitizen: conventional commits
+cargo-deny: linting dependencies
+typos: spell checker
+
+
Other
+-
+
- Benchmarks added for the
Paragraphwidget
+ - Added underline colors support for
crosstermbackend
+ - Mark some of the low-level functions of
Block,LayoutandRectasconst
+ - The project license has been updated to acknowledge
ratatuidevelopers
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/how-to/develop-apps/abstract-terminal-and-event-handler.html b/pr-preview/pr-83/how-to/develop-apps/abstract-terminal-and-event-handler.html
new file mode 100644
index 000000000..e945bd52f
--- /dev/null
+++ b/pr-preview/pr-83/how-to/develop-apps/abstract-terminal-and-event-handler.html
@@ -0,0 +1,458 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ v0.23.0
+
+
+
+
+
+reposted from https://blog.orhun.dev/ratatui-0-23-0/
+Coolify everything 😎
+We already had a cool name and a logo, and now we have a cool description as well:
+- ratatui: A Rust library to build rich terminal user interfaces or dashboards.
++ ratatui: A Rust library that's all about cooking up terminal user interfaces.
+We also renamed our organization from tui-rs-revival to ratatui-org:
Barchart: horizontal bars
+You can now render the bars horizontally for the Barchart widget. This is especially useful in
+some cases to make more efficient use of the available space.
Simply use the Direction attribute for rendering horizontal bars:
let mut barchart = BarChart::default()
+ .block(Block::default().title("Data1").borders(Borders::ALL))
+ .bar_width(1)
+ .group_gap(1)
+ .bar_gap(0)
+ .direction(Direction::Horizontal);
+Here is an example of what you can do with the Barchart widget (see the bottom right for
+horizontal bars):
+
Voluntary skipping capability for Sixel
+++Sixel is a bitmap graphics format supported by terminals. +“Sixel mode” is entered by sending the sequence
+ESC+Pq. The “String Terminator” sequenceESC+\+exits the mode.
Cell widget now has a set_skip method that allows the cell to be skipped when copying (diffing)
+the buffer to the screen. This is helpful when it is necessary to prevent the buffer from
+overwriting a cell that is covered by an image from some terminal graphics protocol such as Sixel,
+iTerm, Kitty, etc.
See the pull request for more information: +https://github.com/ratatui-org/ratatui/pull/215
+In this context, there is also an experimental image rendering crate: +ratatu-image
+
+
Table/List: Highlight spacing
+We added a new property called HighlightSpacing to the Table and List widgets and it can be
+optionally set via calling highlight_spacing function.
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. The idea is that we want this behaviour to be +configurable with this newly added option.
+let list = List::new(items)
+ .highlight_symbol(">>")
+ .highlight_spacing(HighlightSpacing::Always);
+Right now, there are 3 variants:
+-
+
Always: Always add spacing for the selection symbol column.
+WhenSelected: Only add spacing for the selection symbol column if a row is selected.
+Never: Never add spacing to the selection symbol column, regardless of whether something is +selected or not.
+
+
Table: support line alignment
+let table = Table::new(vec![
+ Row::new(vec![Line::from("Left").alignment(Alignment::Left)]),
+ Row::new(vec![Line::from("Center").alignment(Alignment::Center)]),
+ Row::new(vec![Line::from("Right").alignment(Alignment::Right)]),
+ ])
+ .widths(&[Constraint::Percentage(100)]);
+Now results in:
+Left
+ Center
+ Right
++
Scrollbar: optional track symbol
+The track symbol in the Scrollbar is now optional, simplifying composition with other widgets. It
+also makes it easier to use the Scrollbar in tandem with a block with special block characters.
One breaking change is that track_symbol needs to be set in the following way now:
-let scrollbar = Scrollbar::default().track_symbol("-");
++let scrollbar = Scrollbar::default().track_symbol(Some("-"));
+It also makes it possible to render a custom track that is composed out of multiple differing track +symbols.
++
symbols::scrollbar module
+The symbols and sets are moved from widgets::scrollbar to symbols::scrollbar. This makes it
+consistent with the other symbol sets. We also made the scrollbar module private.
Since this is a breaking change, you need to update your code to add an import for
+ratatui::symbols::scrollbar::* (or the specific symbols you need).
+
Alpha releases
+The alpha releases (i.e. pre-releases) are created *every Saturday* and they are automated with
+the help of
+this GitHub Actions workflow.
+This is especially useful if you want to test ratatui or use unstable/experimental features before
+we hit a stable release.
The versioning scheme is v<version>-alpha.<num>, for example:
+v0.22.1-alpha.2
Additionally, see the following issue for possible contributions in the context of alpha releases +and documentation: +https://github.com/ratatui-org/ratatui/issues/412
++
Example GIFs
+We added GIFs for each example in the examples/ directory and added a README.md for preview.
+This should make it easier to see what each example does without having to run it.
See: +https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
+One thing to note here is that we used vhs for generating +GIFs from a set of instructions. For example:
+# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
+# To run this script, install vhs and run `vhs ./examples/demo.tape`
+Output "target/demo.gif"
+Set Theme "OceanicMaterial"
+Set Width 1200
+Set Height 1200
+Set PlaybackSpeed 0.5
+Hide
+Type "cargo run --example demo"
+Enter
+Sleep 2s
+Show
+Sleep 1s
+Down@1s 12
+Right
+Sleep 4s
+Right
+Sleep 4s
+Results in:
+We also host these GIFs at https://vhs.charm.sh but there is an issue about +moving everything to GitHub. If you are interested in contributing regarding this, see +https://github.com/ratatui-org/ratatui/issues/401
++
Common traits
+With the help of strum crate, we added Display and FromStr
+implementation to enum types.
Also, we implemented common traits such as Debug, Default, Clone, Copy, Eq, PartialEq,
+Ord, PartialOrd, Hash to the structs/enums where possible.
+
Test coverage 🧪
+ratatui now has 90% test coverage!
Shoutout to everyone who added tests/benchmarks for various widgets made this possible.
++
No unsafe ⚠️
+We now forbid unsafe code in ratatui.
+Also, see this discussion we had in the
+past about using unsafe code for optimization purposes.
+
The book 📕
+We are working on a book for more in-depth ratatui documentation and usage examples, you can read
+it from here:
+https://ratatui-org.github.io/ratatui-book/
Repository: +https://github.com/ratatui-org/ratatui-book
++
Other
+-
+
- Expand serde attributes for
TestBufferfor de/serializing the whole test buffer.
+ - Add weak constraints to make
Rects closer to each other in size.
+ - Simplify
Layout::splitfunction.
+ - Various bug fixes and improvements in Barchart, Block, Layout and other widgets. +
- Add documentation to various widgets and improve existing documentation. +
- Add examples for colors and modifiers. +
- We created a Matrix bridge at #ratatui:matrix.org. +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/how-to/develop-apps/better-panic-hooks.html b/pr-preview/pr-83/how-to/develop-apps/better-panic-hooks.html
new file mode 100644
index 000000000..e78f40dab
--- /dev/null
+++ b/pr-preview/pr-83/how-to/develop-apps/better-panic-hooks.html
@@ -0,0 +1,493 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Single
+
+
+
+
+ Single Tui struct with Terminal and EventHandler
+
+
+
+
+
+This is just one way to setup your application, there are many others. See +Application Patterns for more.
+If you want a tui.rs with Terminal with Deref and DerefMut, and an EventHandler, you can
+use the following code.
Add the following dependencies:
+cargo add ratatui crossterm tokio tokio_util futures # required
+cargo add color_eyre serde serde_derive # optional
+Then you’ll be able write code like this:
+impl App {
+ async fn run(&mut self) -> Result<()> {
+ let mut tui = tui::Tui::new()?;
+ tui.tick_rate(4.0); // 4 ticks per second
+ tui.frame_rate(30.0); // 30 frames per second
+ tui.enter()?; // Starts event handler
+ loop {
+ tui.draw(|f| { // Deref allows calling `tui.draw`
+ self.ui(f);
+ })?;
+
+ if let Some(evt) = tui.next().await { // `tui.next().await` returns next event
+ let mut maybe_action = self.handle_event(evt);
+ while let Some(action) = maybe_action {
+ maybe_action = self.update(action);
+ }
+ };
+
+ if self.should_quit {
+ break;
+ }
+ }
+ tui.exit()?; // Stops event handler
+ Ok(())
+ }
+}You’ll need to copy the code to a ./src/tui.rs:
use std::{
+ ops::{Deref, DerefMut},
+ time::Duration,
+};
+
+use color_eyre::eyre::Result;
+use crossterm::{
+ cursor,
+ event::{Event as CrosstermEvent, KeyEvent, KeyEventKind, MouseEvent},
+ terminal::{EnterAlternateScreen, LeaveAlternateScreen},
+};
+use futures::{FutureExt, StreamExt};
+use ratatui::backend::CrosstermBackend as Backend;
+use serde_derive::{Deserialize, Serialize};
+use tokio::{
+ sync::mpsc::{self, UnboundedReceiver, UnboundedSender},
+ task::JoinHandle,
+};
+use tokio_util::sync::CancellationToken;
+
+pub type Frame<'a> = ratatui::Frame<'a, Backend<std::io::Stderr>>;
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub enum Event {
+ Init,
+ Quit,
+ Error,
+ Closed,
+ Tick,
+ Render,
+ FocusGained,
+ FocusLost,
+ Paste(String),
+ Key(KeyEvent),
+ Mouse(MouseEvent),
+ Resize(u16, u16),
+}
+
+pub struct Tui {
+ pub terminal: ratatui::Terminal<Backend<std::io::Stderr>>,
+ pub task: JoinHandle<()>,
+ pub cancellation_token: CancellationToken,
+ pub event_rx: UnboundedReceiver<Event>,
+ pub event_tx: UnboundedSender<Event>,
+ pub frame_rate: f64,
+ pub tick_rate: f64,
+}
+
+impl Tui {
+ pub fn new() -> Result<Self> {
+ let tick_rate = 4.0; // 4 ticks per second
+ let frame_rate = 30.0; // 30 frames per seconds
+ let terminal = ratatui::Terminal::new(Backend::new(std::io::stderr()))?;
+ let (event_tx, event_rx) = mpsc::unbounded_channel();
+ let cancellation_token = CancellationToken::new();
+ let task = tokio::spawn(async {});
+ Ok(Self { terminal, task, cancellation_token, event_rx, event_tx, frame_rate, tick_rate })
+ }
+
+ pub fn tick_rate(&mut self, tick_rate: f64) {
+ self.tick_rate = tick_rate;
+ }
+
+ pub fn frame_rate(&mut self, frame_rate: f64) {
+ self.frame_rate = frame_rate;
+ }
+
+ pub fn start(&mut self) {
+ let tick_delay = std::time::Duration::from_secs_f64(1.0 / self.tick_rate);
+ let render_delay = std::time::Duration::from_secs_f64(1.0 / self.frame_rate);
+ self.cancel();
+ self.cancellation_token = CancellationToken::new();
+ let _cancellation_token = self.cancellation_token.clone();
+ let _event_tx = self.event_tx.clone();
+ self.task = tokio::spawn(async move {
+ let mut reader = crossterm::event::EventStream::new();
+ let mut tick_interval = tokio::time::interval(tick_delay);
+ let mut render_interval = tokio::time::interval(render_delay);
+ _event_tx.send(Event::Init).unwrap();
+ loop {
+ let tick_delay = tick_interval.tick();
+ let render_delay = render_interval.tick();
+ let crossterm_event = reader.next().fuse();
+ tokio::select! {
+ _ = _cancellation_token.cancelled() => {
+ break;
+ }
+ maybe_event = crossterm_event => {
+ match maybe_event {
+ Some(Ok(evt)) => {
+ match evt {
+ CrosstermEvent::Key(key) => {
+ if key.kind == KeyEventKind::Press {
+ _event_tx.send(Event::Key(key)).unwrap();
+ }
+ },
+ CrosstermEvent::Mouse(mouse) => {
+ _event_tx.send(Event::Mouse(mouse)).unwrap();
+ },
+ CrosstermEvent::Resize(x, y) => {
+ _event_tx.send(Event::Resize(x, y)).unwrap();
+ },
+ CrosstermEvent::FocusLost => {
+ _event_tx.send(Event::FocusLost).unwrap();
+ },
+ CrosstermEvent::FocusGained => {
+ _event_tx.send(Event::FocusGained).unwrap();
+ },
+ CrosstermEvent::Paste(s) => {
+ _event_tx.send(Event::Paste(s)).unwrap();
+ },
+ }
+ }
+ Some(Err(_)) => {
+ _event_tx.send(Event::Error).unwrap();
+ }
+ None => {},
+ }
+ },
+ _ = tick_delay => {
+ _event_tx.send(Event::Tick).unwrap();
+ },
+ _ = render_delay => {
+ _event_tx.send(Event::Render).unwrap();
+ },
+ }
+ }
+ });
+ }
+
+ pub fn stop(&self) -> Result<()> {
+ self.cancel();
+ let mut counter = 0;
+ while !self.task.is_finished() {
+ std::thread::sleep(Duration::from_millis(1));
+ counter += 1;
+ if counter > 50 {
+ self.task.abort();
+ }
+ if counter > 100 {
+ log::error!("Failed to abort task for unknown reason");
+ return Err(color_eyre::eyre::eyre!("Unable to abort task"));
+ }
+ }
+ Ok(())
+ }
+
+ pub fn enter(&mut self) -> Result<()> {
+ crossterm::terminal::enable_raw_mode()?;
+ crossterm::execute!(std::io::stderr(), EnterAlternateScreen, cursor::Hide)?;
+ self.start();
+ Ok(())
+ }
+
+ pub fn exit(&self) -> Result<()> {
+ self.stop()?;
+ crossterm::execute!(std::io::stderr(), LeaveAlternateScreen, cursor::Show)?;
+ crossterm::terminal::disable_raw_mode()?;
+ Ok(())
+ }
+
+ pub fn cancel(&self) {
+ self.cancellation_token.cancel();
+ }
+
+ pub fn suspend(&self) -> Result<()> {
+ self.exit()?;
+ #[cfg(not(windows))]
+ signal_hook::low_level::raise(signal_hook::consts::signal::SIGTSTP)?;
+ Ok(())
+ }
+
+ pub fn resume(&mut self) -> Result<()> {
+ self.enter()?;
+ Ok(())
+ }
+
+ pub async fn next(&mut self) -> Option<Event> {
+ self.event_rx.recv().await
+ }
+}
+
+impl Deref for Tui {
+ type Target = ratatui::Terminal<Backend<std::io::Stderr>>;
+
+ fn deref(&self) -> &Self::Target {
+ &self.terminal
+ }
+}
+
+impl DerefMut for Tui {
+ fn deref_mut(&mut self) -> &mut Self::Target {
+ &mut self.terminal
+ }
+}
+
+impl Drop for Tui {
+ fn drop(&mut self) {
+ self.exit().unwrap();
+ }
+}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/how-to/develop-apps/cli-arguments.html b/pr-preview/pr-83/how-to/develop-apps/cli-arguments.html
new file mode 100644
index 000000000..cebce9afb
--- /dev/null
+++ b/pr-preview/pr-83/how-to/develop-apps/cli-arguments.html
@@ -0,0 +1,316 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Better Panic Hooks using
+
+
+
+
+
+ Better Panic Hooks using better-panic, color-eyre and human-panic
+Your application may panic for a number of reasons (e.g. when you call .unwrap() on a None). And
+when this happens, you want to be a good citizen and:
-
+
- provide a useful stacktrace so that they can report errors back to you. +
- not leave the users terminal state in a botched condition, resetting it back to the way it was. +
better-panic
+better-panic gives you pretty backtraces for panics.
cargo add better-panic
+Here’s an example of initialize_panic_handler() using better-panic to provide a prettier
+backtrace by default.
use better_panic::Settings;
+
+pub fn initialize_panic_handler() {
+ std::panic::set_hook(Box::new(|panic_info| {
+ crossterm::execute!(std::io::stderr(), crossterm::terminal::LeaveAlternateScreen).unwrap();
+ crossterm::terminal::disable_raw_mode().unwrap();
+ Settings::auto().most_recent_first(false).lineno_suffix(true).create_panic_handler()(panic_info);
+ }));
+}I personally like to reuse the Tui struct in the panic
+handler. That way, if I ever decide to move from crossterm to termion in the future, there’s one
+less place in the project that I have to worry about refactoring.
Here’s an example of initialize_panic_handler() using
+better_panic and
+libc to provide a prettier backtrace by default.
use better_panic::Settings;
+
+pub fn initialize_panic_handler() {
+ std::panic::set_hook(Box::new(|panic_info| {
+ match crate::tui::Tui::new() {
+ Ok(t) => {
+ if let Err(r) = t.exit() {
+ error!("Unable to exit Terminal: {r:?}");
+ }
+ },
+ Err(r) => error!("Unable to exit Terminal: {r:?}"),
+ }
+ better_panic::Settings::auto()
+ .most_recent_first(false)
+ .lineno_suffix(true)
+ .verbosity(better_panic::Verbosity::Full)
+ .create_panic_handler()(panic_info);
+ std::process::exit(libc::EXIT_FAILURE);
+ }));
+}Now, let’s say I added a panic! to
+an application as an example:
diff --git a/src/components/app.rs b/src/components/app.rs
+index 289e40b..de48392 100644
+--- a/src/components/app.rs
++++ b/src/components/app.rs
+@@ -77,6 +77,7 @@ impl App {
+ }
+
+ pub fn increment(&mut self, i: usize) {
++ panic!("At the disco");
+ self.counter = self.counter.saturating_add(i);
+ }
+This is what a prettier stacktrace would look like with better-panic:
Backtrace (most recent call last):
+ File "/Users/kd/gitrepos/ratatui-async-template/src/main.rs:46", in ratatui_async_template::main
+ Ok(())
+ File "/Users/kd/.cargo/registry/src/index.crates.io-6f17d22bba15001f/tokio-1.28.2/src/runtime/runtime.rs:304", in tokio::runtime::runtime::Runtime::block_on
+ Scheduler::MultiThread(exec) => exec.block_on(&self.handle.inner, future),
+ File "/Users/kd/.cargo/registry/src/index.crates.io-6f17d22bba15001f/tokio-1.28.2/src/runtime/scheduler/multi_thread/mod.rs:66", in tokio::runtime::scheduler::multi_thread::MultiThread::block_on
+ enter
+ File "/Users/kd/.cargo/registry/src/index.crates.io-6f17d22bba15001f/tokio-1.28.2/src/runtime/context.rs:315", in tokio::runtime::context::BlockingRegionGuard::block_on
+ park.block_on(f)
+ File "/Users/kd/.cargo/registry/src/index.crates.io-6f17d22bba15001f/tokio-1.28.2/src/runtime/park.rs:283", in tokio::runtime::park::CachedParkThread::block_on
+ if let Ready(v) = crate::runtime::coop::budget(|| f.as_mut().poll(&mut cx)) {
+ File "/Users/kd/.cargo/registry/src/index.crates.io-6f17d22bba15001f/tokio-1.28.2/src/runtime/coop.rs:73", in tokio::runtime::coop::budget
+ with_budget(Budget::initial(), f)
+ File "/Users/kd/.cargo/registry/src/index.crates.io-6f17d22bba15001f/tokio-1.28.2/src/runtime/coop.rs:107", in tokio::runtime::coop::with_budget
+ f()
+ File "/Users/kd/.cargo/registry/src/index.crates.io-6f17d22bba15001f/tokio-1.28.2/src/runtime/park.rs:283", in tokio::runtime::park::CachedParkThread::block_on::{{closure}}
+ if let Ready(v) = crate::runtime::coop::budget(|| f.as_mut().poll(&mut cx)) {
+ File "/Users/kd/gitrepos/ratatui-async-template/src/main.rs:44", in ratatui_async_template::main::{{closure}}
+ runner.run().await?;
+ File "/Users/kd/gitrepos/ratatui-async-template/src/runner.rs:80", in ratatui_async_template:🏃:Runner::run::{{closure}}
+ if let Some(action) = component.update(action.clone())? {
+ File "/Users/kd/gitrepos/ratatui-async-template/src/components/app.rs:132", in <ratatui_async_template::components::app::App as ratatui_async_template::components::Component>::update
+ Action::Increment(i) => self.increment(i),
+ File "/Users/kd/gitrepos/ratatui-async-template/src/components/app.rs:80", in ratatui_async_template::components::app::App::increment
+ panic!("At the disco");
+
+The application panicked (crashed).
+ At the disco
+in src/components/app.rs:80
+thread: main
+With .most_recent_first(false) the last line of the stacktrace is typically where the error has
+occurred. This makes it fast and easy to find the error without having to scroll up the terminal
+history, and iterate on your application rapidly during development.
This kind of detailed stacktrace is only available in debug builds. For release builds, you may get +inlined or truncated stacktraces.
+For example, here’s what I get when I compile with all optimizations on:
+Backtrace (most recent call last):
+ File "<unknown>:0", in __mh_execute_header
+ File "<unknown>:0", in __mh_execute_header
+ File "<unknown>:0", in __mh_execute_header
+ File "<unknown>:0", in __mh_execute_header
+ File "<unknown>:0", in __mh_execute_header
+ File "<unknown>:0", in __mh_execute_header
+ File "<unknown>:0", in __mh_execute_header
+ File "<unknown>:0", in __mh_execute_header
+ File "<unknown>:0", in __mh_execute_header
+ File "<unknown>:0", in __mh_execute_header
+ File "<unknown>:0", in __mh_execute_header
+ File "<unknown>:0", in __mh_execute_header
+ File "<unknown>:0", in __mh_execute_header
+
+The application panicked (crashed).
+ At the disco
+in src/components/app.rs:80
+thread: main
+This is not particularly useful to show to the average user. We’ll discuss better solutions for what +to show the users of your application in the following subsections.
+color-eyre panic hook
+Another way to manage printing of stack-traces is by using
+color-eyre:
cargo add color-eyre
+color-eyre has a panic hook that is better suited for users in my opinion.
+
+
+
+
+You will also want to add a repository key to your Cargo.toml file:
repository = "https://github.com/ratatui-org/ratatui-async-template" # used by env!("CARGO_PKG_REPOSITORY")
+When a panic! occurs, after the application cleanly restores the terminal, we can print out a nice
+error message created by color-eyre like so:
The application panicked (crashed).
+Message: At the disco
+Location: src/components/app.rs:80
+
+This is a bug. Consider reporting it at https://github.com/ratatui-org/ratatui-async-template
+
+Backtrace omitted. Run with RUST_BACKTRACE=1 environment variable to display it.
+Run with RUST_BACKTRACE=full to include source snippets.
+This is short and clear, providing a link to the user to report the bug.
+Users can also opt to give you a more detailed stacktrace if they can reproduce the error (with a
+debug build and with export RUST_BACKTRACE=1):
The application panicked (crashed).
+Message: At the disco
+Location: src/components/app.rs:80
+
+This is a bug. Consider reporting it at https://github.com/ratatui-org/ratatui-async-template
+
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ BACKTRACE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ ⋮ 13 frames hidden ⋮
+ 14: ratatui_async_template::components::app::App::increment::h4e8b6e0d83d3d575
+ at /Users/kd/gitrepos/ratatui-async-template/src/components/app.rs:80
+ 15: <ratatui_async_template::components::app::App as ratatui_async_template::components::Component>::update::hc78145b4a91e06b6
+ at /Users/kd/gitrepos/ratatui-async-template/src/components/app.rs:132
+ 16: ratatui_async_template:🏃:Runner::run::{{closure}}::h802b0d3c3413762b
+ at /Users/kd/gitrepos/ratatui-async-template/src/runner.rs:80
+ 17: ratatui_async_template::main::{{closure}}::hd78d335f19634c3f
+ at /Users/kd/gitrepos/ratatui-async-template/src/main.rs:44
+ 18: tokio::runtime::park::CachedParkThread::block_on::{{closure}}::hd7949515524de9f8
+ at /Users/kd/.cargo/registry/src/index.crates.io-6f17d22bba15001f/tokio-1.28.2/src/runtime/park.rs:283
+ 19: tokio::runtime::coop::with_budget::h39648e20808374d3
+ at /Users/kd/.cargo/registry/src/index.crates.io-6f17d22bba15001f/tokio-1.28.2/src/runtime/coop.rs:107
+ 20: tokio::runtime::coop::budget::h653c1593abdd982d
+ at /Users/kd/.cargo/registry/src/index.crates.io-6f17d22bba15001f/tokio-1.28.2/src/runtime/coop.rs:73
+ 21: tokio::runtime::park::CachedParkThread::block_on::hb0a0dd4a7c3cf33b
+ at /Users/kd/.cargo/registry/src/index.crates.io-6f17d22bba15001f/tokio-1.28.2/src/runtime/park.rs:283
+ 22: tokio::runtime::context::BlockingRegionGuard::block_on::h4d02ab23bd93d0fd
+ at /Users/kd/.cargo/registry/src/index.crates.io-6f17d22bba15001f/tokio-1.28.2/src/runtime/context.rs:315
+ 23: tokio::runtime::scheduler::multi_thread::MultiThread::block_on::h8aaba9030519c80d
+ at /Users/kd/.cargo/registry/src/index.crates.io-6f17d22bba15001f/tokio-1.28.2/src/runtime/scheduler/multi_thread/mod.rs:66
+ 24: tokio::runtime::runtime::Runtime::block_on::h73a6fbfba201fac9
+ at /Users/kd/.cargo/registry/src/index.crates.io-6f17d22bba15001f/tokio-1.28.2/src/runtime/runtime.rs:304
+ 25: ratatui_async_template::main::h6da543b193746523
+ at /Users/kd/gitrepos/ratatui-async-template/src/main.rs:46
+ 26: core::ops::function::FnOnce::call_once::h6cac3edc975fcef2
+ at /rustc/eb26296b556cef10fb713a38f3d16b9886080f26/library/core/src/ops/function.rs:250
+ ⋮ 13 frames hidden ⋮
+human-panic
+To use human-panic, you’ll have to install it as a +dependency:
+cargo add human-panic
+Personally, I think human-panic provides the most user friendly panic handling functionality out
+of the box when users experience an unexpected panic:
Well, this is embarrassing.
+
+ratatui-async-template had a problem and crashed. To help us diagnose the problem you can send us a crash report.
+
+We have generated a report file at "/var/folders/l4/bnjjc6p15zd3jnty8c_qkrtr0000gn/T/report-ce1e29cb-c17c-4684-b9d4-92d9678242b7.toml". Submit an issue or email with the subject of "ratatui-async-template Crash Report" and include the report as an attachment.
+
+- Authors: Dheepak Krishnamurthy
+
+We take privacy seriously, and do not perform any automated error collection. In order to improve the software, we rely on people to submit reports.
+
+Thank you kindly!
+It generates a report where information relevant to the crash is logged. Here’s the content of the
+temporary report file that human-panic creates (with optimizations turned on):
name = "ratatui-async-template"
+operating_system = "Mac OS 13.5.2 [64-bit]"
+crate_version = "0.1.0"
+explanation = """
+Panic occurred in file 'src/components/app.rs' at line 80
+"""
+cause = "At the disco"
+method = "Panic"
+backtrace = """
+
+ 0: 0x10448f5f8 - __mh_execute_header
+ 1: 0x1044a43c8 - __mh_execute_header
+ 2: 0x1044a01ac - __mh_execute_header
+ 3: 0x10446f8c0 - __mh_execute_header
+ 4: 0x1044ac850 - __mh_execute_header"""
+In debug mode, the stacktrace is as descriptive as earlier.
+Configuration
+You can mix and match these different panic handlers, using better-panic for debug builds and
+color-eyre and human-panic for release builds. The code below also prints the color-eyre
+stacktrace to log::error! for good measure (after striping ansi escape sequences).
cargo add color-eyre human-panic libc better-panic strip-ansi-escapes
+Here’s code you can copy paste into your project (if you use the
+Tui struct to handle terminal exits):
pub fn initialize_panic_handler() -> Result<()> {
+ let (panic_hook, eyre_hook) = color_eyre::config::HookBuilder::default()
+ .panic_section(format!("This is a bug. Consider reporting it at {}", env!("CARGO_PKG_REPOSITORY")))
+ .display_location_section(true)
+ .display_env_section(true)
+ .into_hooks();
+ eyre_hook.install()?;
+ std::panic::set_hook(Box::new(move |panic_info| {
+ if let Ok(t) = crate::tui::Tui::new() {
+ if let Err(r) = t.exit() {
+ error!("Unable to exit Terminal: {:?}", r);
+ }
+ }
+
+ let msg = format!("{}", panic_hook.panic_report(panic_info));
+ #[cfg(not(debug_assertions))]
+ {
+ eprintln!("{}", msg); // prints color-eyre stack trace to stderr
+ use human_panic::{handle_dump, print_msg, Metadata};
+ let meta = Metadata {
+ version: env!("CARGO_PKG_VERSION").into(),
+ name: env!("CARGO_PKG_NAME").into(),
+ authors: env!("CARGO_PKG_AUTHORS").replace(':', ", ").into(),
+ homepage: env!("CARGO_PKG_HOMEPAGE").into(),
+ };
+
+ let file_path = handle_dump(&meta, panic_info);
+ // prints human-panic message
+ print_msg(file_path, &meta).expect("human-panic: printing error message to console failed");
+ }
+ log::error!("Error: {}", strip_ansi_escapes::strip_str(msg));
+
+ #[cfg(debug_assertions)]
+ {
+ // Better Panic stacktrace that is only enabled when debugging.
+ better_panic::Settings::auto()
+ .most_recent_first(false)
+ .lineno_suffix(true)
+ .verbosity(better_panic::Verbosity::Full)
+ .create_panic_handler()(panic_info);
+ }
+
+ std::process::exit(libc::EXIT_FAILURE);
+ }));
+ Ok(())
+}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/how-to/develop-apps/config-directories.html b/pr-preview/pr-83/how-to/develop-apps/config-directories.html
new file mode 100644
index 000000000..f6e223487
--- /dev/null
+++ b/pr-preview/pr-83/how-to/develop-apps/config-directories.html
@@ -0,0 +1,278 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Handle CLI arguments
+Command Line Interface (CLI) tools often require input parameters to dictate their behavior.
+clap (Command Line Argument Parser) is a feature-rich Rust
+library that facilitates the parsing of these arguments in an intuitive manner.
Defining Command Line Arguments
+In this snippet, we utilize the clap library to define an Args struct, which will be used to
+capture and structure the arguments passed to the application:
use clap::Parser;
+
+#[derive(Parser, Debug)]
+#[command(version = version(), about = "ratatui template with crossterm and tokio")]
+struct Args {
+ /// App tick rate
+ #[arg(short, long, default_value_t = 1000)]
+ app_tick_rate: u64,
+}Here, the Args struct defines one command-line arguments:
+-
+
app_tick_rate: Dictates the application’s tick rate.
+
This is supplied with default values, ensuring that even if the user doesn’t provide this argument, +the application can still proceed with its defaults.
+Displaying Version Information
+One common convention in CLIs is the ability to display version information. Here, the version +information is presented as a combination of various parameters, including the Git commit hash.
+The version() function, as seen in the snippet, fetches this information:
pub fn version() -> String {
+ let author = clap::crate_authors!();
+
+ let commit_hash = env!("RATATUI_TEMPLATE_GIT_INFO");
+
+ // let current_exe_path = PathBuf::from(clap::crate_name!()).display().to_string();
+ let config_dir_path = get_config_dir().unwrap().display().to_string();
+ let data_dir_path = get_data_dir().unwrap().display().to_string();
+
+ format!(
+ "\
+{commit_hash}
+
+Authors: {author}
+
+Config directory: {config_dir_path}
+Data directory: {data_dir_path}"
+ )
+}This function uses the get_data_dir() and get_config_dir() from
+the section on XDG directories.
This function also makes use of an environment variable RATATUI_TEMPLATE_GIT_INFO to derive the
+Git commit hash. The variable can be populated during the build process by build.rs:
println!("cargo:rustc-env=RATATUI_TEMPLATE_GIT_INFO={}", git_describe);By invoking the CLI tool with the --version flag, users will be presented with the version
+details, including the authors, commit hash, and the paths to the configuration and data
+directories.
The version() function’s output is just an example. You can easily adjust its content by amending
+the string template code above.
Here’s the full build.rs for your reference:
fn main() {
+ let git_output = std::process::Command::new("git").args(["rev-parse", "--git-dir"]).output().ok();
+ let git_dir = git_output.as_ref().and_then(|output| {
+ std::str::from_utf8(&output.stdout).ok().and_then(|s| s.strip_suffix('\n').or_else(|| s.strip_suffix("\r\n")))
+ });
+
+ // Tell cargo to rebuild if the head or any relevant refs change.
+ if let Some(git_dir) = git_dir {
+ let git_path = std::path::Path::new(git_dir);
+ let refs_path = git_path.join("refs");
+ if git_path.join("HEAD").exists() {
+ println!("cargo:rerun-if-changed={}/HEAD", git_dir);
+ }
+ if git_path.join("packed-refs").exists() {
+ println!("cargo:rerun-if-changed={}/packed-refs", git_dir);
+ }
+ if refs_path.join("heads").exists() {
+ println!("cargo:rerun-if-changed={}/refs/heads", git_dir);
+ }
+ if refs_path.join("tags").exists() {
+ println!("cargo:rerun-if-changed={}/refs/tags", git_dir);
+ }
+ }
+
+ let git_output =
+ std::process::Command::new("git").args(["describe", "--always", "--tags", "--long", "--dirty"]).output().ok();
+ let git_info = git_output.as_ref().and_then(|output| std::str::from_utf8(&output.stdout).ok().map(str::trim));
+ let cargo_pkg_version = env!("CARGO_PKG_VERSION");
+
+ // Default git_describe to cargo_pkg_version
+ let mut git_describe = String::from(cargo_pkg_version);
+
+ if let Some(git_info) = git_info {
+ // If the `git_info` contains `CARGO_PKG_VERSION`, we simply use `git_info` as it is.
+ // Otherwise, prepend `CARGO_PKG_VERSION` to `git_info`.
+ if git_info.contains(cargo_pkg_version) {
+ // Remove the 'g' before the commit sha
+ let git_info = &git_info.replace('g', "");
+ git_describe = git_info.to_string();
+ } else {
+ git_describe = format!("v{}-{}", cargo_pkg_version, git_info);
+ }
+ }
+
+ println!("cargo:rustc-env=RATATUI_TEMPLATE_GIT_INFO={}", git_describe);
+}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/how-to/develop-apps/index.html b/pr-preview/pr-83/how-to/develop-apps/index.html
new file mode 100644
index 000000000..07ca01705
--- /dev/null
+++ b/pr-preview/pr-83/how-to/develop-apps/index.html
@@ -0,0 +1,222 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Using
+
+
+
+
+ Handle XDG Directories
+Handling files and directories correctly in a command-line or TUI application ensures that the +application fits seamlessly into a user’s workflow and adheres to established conventions. One of +the key conventions on Linux-based systems is the XDG Base Directory Specification.
+Why the XDG Base Directory Specification?
+The XDG Base Directory Specification is a set of standards that define where user files should +reside, ensuring a cleaner home directory and a more organized storage convention. By adhering to +this standard, your application will store files in the expected directories, making it more +predictable and user-friendly.
+Using directories-rs for Path Resolution
+The directories-rs library offers a Rust-friendly interface to locate common directories (like
+config and data directories) based on established conventions, including the XDG Base Directory
+Specification.
-
+
-
+
Add
+directories-rsto yourCargo.toml
+cargo add directories +
+ -
+
Use the
+ProjectDirsstruct to retrieve paths based on your project’s domain and project name +and create helper functions for getting thedata_dirandconfig_dir.
+ -
+
Allow users to specify custom locations using environment variables. This flexibility can be +crucial for users with unique directory structures or for testing.
+
+ -
+
A good practice is to notify the user about the location of the configuration and data +directories. An example from the template is to print out these locations when the user invokes +the
+--versioncommand-line argument. See the section on +Command line argument parsing
+
Here’s an example get_data_dir() and get_config_dir() functions for your reference:
use std::path::PathBuf;
+
+use anyhow::{anyhow, Context, Result};
+use directories::ProjectDirs;
+
+pub fn get_data_dir() -> Result<PathBuf> {
+ let directory = if let Ok(s) = std::env::var("RATATUI_TEMPLATE_DATA") {
+ PathBuf::from(s)
+ } else if let Some(proj_dirs) = ProjectDirs::from("com", "kdheepak", "ratatui-template") {
+ proj_dirs.data_local_dir().to_path_buf()
+ } else {
+ return Err(anyhow!("Unable to find data directory for ratatui-template"));
+ };
+ Ok(directory)
+}
+
+pub fn get_config_dir() -> Result<PathBuf> {
+ let directory = if let Ok(s) = std::env::var("RATATUI_TEMPLATE_CONFIG") {
+ PathBuf::from(s)
+ } else if let Some(proj_dirs) = ProjectDirs::from("com", "kdheepak", "ratatui-template") {
+ proj_dirs.config_local_dir().to_path_buf()
+ } else {
+ return Err(anyhow!("Unable to find config directory for ratatui-template"));
+ };
+ Ok(directory)
+}You will want to replace kdheepak with your user name or company name (or any unique name for that
+matter); and ratatui-app with the name of your CLI.
I own https://kdheepak.com so I tend to use com.kdheepak.ratatui-app for my project directories.
+That way it is unlikely that any other program will mess with the configuration files for the app I
+plan on distributing.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/how-to/develop-apps/migrate-from-tui-rs.html b/pr-preview/pr-83/how-to/develop-apps/migrate-from-tui-rs.html
new file mode 100644
index 000000000..190e94ad9
--- /dev/null
+++ b/pr-preview/pr-83/how-to/develop-apps/migrate-from-tui-rs.html
@@ -0,0 +1,244 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Develop Applications
+This section covers topics on how to develop applications:
+ + +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/how-to/develop-apps/setup-panic-hooks.html b/pr-preview/pr-83/how-to/develop-apps/setup-panic-hooks.html
new file mode 100644
index 000000000..24240429a
--- /dev/null
+++ b/pr-preview/pr-83/how-to/develop-apps/setup-panic-hooks.html
@@ -0,0 +1,272 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Migrate from tui-rs
+Ratatui is a fork of +tui-rs, created to continue maintenance of the project.
+Several options are available to migrate apps and libs:
+-
+
- Use
ratatuias a drop in replacement aliased as tui
+ - Replace
ratatuifully
+ - Support both
tuiandratatui(useful for libraries)
+
Drop in replacement
+The simplest approach to migrating to ratatui is to use it as drop in replacement for tui and
+updating the terminal libraries used (crossterm / termion). E.g.:
tui = { package = "ratatui", version = "0.21.0", features = ["crossterm"] }
+crossterm = { version = "0.26.1" }
+Or:
+tui = { package = "ratatui", version = "0.21.0", default-features = false, features = ["termion"] }
+termion = { version = "2.0" }
+Fully replace Tui with Ratatui
+Most new code would instead use the following. To take this approach to migration requires find and
+replace tui::->ratatui:: on the entire codebase.
ratatui = { version = "0.21.0" }
+crossterm = { version = "0.26.1" }
+Support both tui and ratatui
+For more complex scenarios where a library (or in some cases an app) needs to support both ratatui +and maintain existing support for tui, it may be feasible to use feature flags to select which +library to use. See tui-logger for an example of this +approach.
+Backwards compatibility and breaking changes
+ + +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/how-to/develop-apps/tracing.html b/pr-preview/pr-83/how-to/develop-apps/tracing.html
new file mode 100644
index 000000000..ecce32176
--- /dev/null
+++ b/pr-preview/pr-83/how-to/develop-apps/tracing.html
@@ -0,0 +1,315 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Setup Panic Hooks
+When building TUIs with ratatui, it’s vital to ensure that if your application encounters a panic,
+it gracefully returns to the original terminal state. This prevents the terminal from getting stuck
+in a modified state, which can be quite disruptive for users.
Here’s an example initialize_panic_handler that works with crossterm and with the Rust standard
+library functionality and no external dependencies.
pub fn initialize_panic_handler() {
+ let original_hook = std::panic::take_hook();
+ std::panic::set_hook(Box::new(move |panic_info| {
+ crossterm::execute!(std::io::stderr(), crossterm::terminal::LeaveAlternateScreen).unwrap();
+ crossterm::terminal::disable_raw_mode().unwrap();
+ original_hook(panic_info);
+ }));
+}With this function, all your need to do is call initialize_panic_handler() in main() before
+running any terminal initialization code:
fn main() -> Result<()> {
+ initialize_panic_handler();
+
+ // Startup
+ crossterm::terminal::enable_raw_mode()?;
+ crossterm::execute!(std::io::stderr(), crossterm::terminal::EnterAlternateScreen)?;
+
+ let mut terminal = Terminal::new(CrosstermBackend::new(std::io::stderr()))?;
+
+ // ...
+
+ // Shutdown
+ crossterm::execute!(std::io::stderr(), crossterm::terminal::LeaveAlternateScreen)?;
+ crossterm::terminal::disable_raw_mode()?;
+ Ok(())
+}We used crossterm for panic handling. If you are using termion you can do something like the
+following:
use std::panic;
+use std::error::Error;
+
+pub fn initialize_panic_handler() {
+ let panic_hook = panic::take_hook();
+ panic::set_hook(Box::new(move |panic| {
+ let panic_cleanup = || -> Result<(), Box<dyn Error>> {
+ let mut output = io::stderr();
+ write!(
+ output,
+ "{}{}{}",
+ termion::clear::All,
+ termion::screen::ToMainScreen,
+ termion::cursor::Show
+ )?;
+ output.into_raw_mode()?.suspend_raw_mode()?;
+ io::stderr().flush()?;
+ Ok(())
+ };
+ panic_cleanup().expect("failed to clean up for panic");
+ panic_hook(panic);
+ }));
+}As a general rule, you want to take the original panic hook and execute it after cleaning up the +terminal. In the next sections we will discuss some third party packages that can help give better +stacktraces.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/how-to/index.html b/pr-preview/pr-83/how-to/index.html
new file mode 100644
index 000000000..c27518307
--- /dev/null
+++ b/pr-preview/pr-83/how-to/index.html
@@ -0,0 +1,223 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Setup Logging with tracing
+You’ll need to install tracing and a few related dependencies:
cargo add tracing-error tracing
+cargo add tracing-subscriber --features env-filter
+cargo add directories lazy_static color-eyre # (optional)
+You can paste the following in any module in your project.
+use std::path::PathBuf;
+
+use color_eyre::eyre::{Context, Result};
+use directories::ProjectDirs;
+use lazy_static::lazy_static;
+use tracing::error;
+use tracing_error::ErrorLayer;
+use tracing_subscriber::{self, layer::SubscriberExt, util::SubscriberInitExt, Layer};
+
+lazy_static! {
+ pub static ref PROJECT_NAME: String = env!("CARGO_CRATE_NAME").to_uppercase().to_string();
+ pub static ref DATA_FOLDER: Option<PathBuf> =
+ std::env::var(format!("{}_DATA", PROJECT_NAME.clone())).ok().map(PathBuf::from);
+ pub static ref LOG_ENV: String = format!("{}_LOGLEVEL", PROJECT_NAME.clone());
+ pub static ref LOG_FILE: String = format!("{}.log", env!("CARGO_PKG_NAME"));
+}
+
+fn project_directory() -> Option<ProjectDirs> {
+ ProjectDirs::from("com", "kdheepak", env!("CARGO_PKG_NAME"))
+}
+
+pub fn get_data_dir() -> PathBuf {
+ let directory = if let Some(s) = DATA_FOLDER.clone() {
+ s
+ } else if let Some(proj_dirs) = project_directory() {
+ proj_dirs.data_local_dir().to_path_buf()
+ } else {
+ PathBuf::from(".").join(".data")
+ };
+ directory
+}
+
+pub fn initialize_logging() -> Result<()> {
+ let directory = get_data_dir();
+ std::fs::create_dir_all(directory.clone())?;
+ let log_path = directory.join(LOG_FILE.clone());
+ let log_file = std::fs::File::create(log_path)?;
+ std::env::set_var(
+ "RUST_LOG",
+ std::env::var("RUST_LOG")
+ .or_else(|_| std::env::var(LOG_ENV.clone()))
+ .unwrap_or_else(|_| format!("{}=info", env!("CARGO_CRATE_NAME"))),
+ );
+ let file_subscriber = tracing_subscriber::fmt::layer()
+ .with_file(true)
+ .with_line_number(true)
+ .with_writer(log_file)
+ .with_target(false)
+ .with_ansi(false)
+ .with_filter(tracing_subscriber::filter::EnvFilter::from_default_env());
+ tracing_subscriber::registry().with(file_subscriber).with(ErrorLayer::default()).init();
+ Ok(())
+}
+
+/// Similar to the `std::dbg!` macro, but generates `tracing` events rather
+/// than printing to stdout.
+///
+/// By default, the verbosity level for the generated events is `DEBUG`, but
+/// this can be customized.
+#[macro_export]
+macro_rules! trace_dbg {
+ (target: $target:expr, level: $level:expr, $ex:expr) => {{
+ match $ex {
+ value => {
+ tracing::event!(target: $target, $level, ?value, stringify!($ex));
+ value
+ }
+ }
+ }};
+ (level: $level:expr, $ex:expr) => {
+ trace_dbg!(target: module_path!(), level: $level, $ex)
+ };
+ (target: $target:expr, $ex:expr) => {
+ trace_dbg!(target: $target, level: tracing::Level::DEBUG, $ex)
+ };
+ ($ex:expr) => {
+ trace_dbg!(level: tracing::Level::DEBUG, $ex)
+ };
+}
+Call initialize_logging()? in your main() function.
The log level is decided by the ${YOUR_CRATE_NAME}_LOGLEVEL environment variable (default =
+log::LevelFilter::Info).
Additionally, the location of the log files would be decided by your environment variables. See +the section on XDG directories for more information.
+
+
+
+
+
+Check out tui-logger for setting up a
+tui logger widget with tracing.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/how-to/layout/center-a-rect.html b/pr-preview/pr-83/how-to/layout/center-a-rect.html
new file mode 100644
index 000000000..5e13ab353
--- /dev/null
+++ b/pr-preview/pr-83/how-to/layout/center-a-rect.html
@@ -0,0 +1,244 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ How To
+-
+
- Layout UIs: Articles regarding how to layout your application’s User Interface +including widgets and nesting blocks +
- Render Text: Articles related to actually rendering test and widgets to the screen +including how to style and write to the buffer. +
- Use Widgets: Articles related to using individual widgets suchs as the paragraph, +block, and creating your own custom widget. +
- Develop Applications: Articles related to developing applications. E.g. how to +handle CLI arguments, tracing, configuration, panics, etc. +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/how-to/layout/index.html b/pr-preview/pr-83/how-to/layout/index.html
new file mode 100644
index 000000000..9a425e699
--- /dev/null
+++ b/pr-preview/pr-83/how-to/layout/index.html
@@ -0,0 +1,334 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Center a
+
+
+
+
+ Center a Rect
+You can use a Vertical layout followed by a Horizontal layout to get a centered Rect.
/// # Usage
+///
+/// ```rust
+/// let rect = centered_rect(f.size(), 50, 50);
+/// ```
+fn centered_rect(r: Rect, percent_x: u16, percent_y: u16) -> Rect {
+ let popup_layout = Layout::default()
+ .direction(Direction::Vertical)
+ .constraints(
+ [
+ Constraint::Percentage((100 - percent_y) / 2),
+ Constraint::Percentage(percent_y),
+ Constraint::Percentage((100 - percent_y) / 2),
+ ]
+ .as_ref(),
+ )
+ .split(r);
+
+ Layout::default()
+ .direction(Direction::Horizontal)
+ .constraints(
+ [
+ Constraint::Percentage((100 - percent_x) / 2),
+ Constraint::Percentage(percent_x),
+ Constraint::Percentage((100 - percent_x) / 2),
+ ]
+ .as_ref(),
+ )
+ .split(popup_layout[1])[1]
+}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/how-to/render/display-text.html b/pr-preview/pr-83/how-to/render/display-text.html
new file mode 100644
index 000000000..b547b6dc6
--- /dev/null
+++ b/pr-preview/pr-83/how-to/render/display-text.html
@@ -0,0 +1,328 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Layout Constraints Basics
+Here’s the “hello world” example again:
+pub fn render(app: &mut App, f: &mut Frame) {
+ f.render_widget(
+ Paragraph::new("Hello World!")
+ .block(Block::default().borders(Borders::ALL).border_type(BorderType::Rounded)),
+ f.size()
+ )
+}Here’s what the docs say for f.size():
ratatui::terminal::Frame
+
+pub fn size(&self) -> Rect
+────────────────────────────────────────────────────
+Frame size, guaranteed not to change when rendering.
+f.size() returns a Rect struct. A Rect has the following struct definition:
#[derive(Debug, Clone, Copy, Hash, PartialEq, Eq, Default)]
+pub struct Rect {
+ pub x: u16,
+ pub y: u16,
+ pub width: u16,
+ pub height: u16,
+}That is to say, they have a x and y positional coordinates and width and height dimensional
+values.
The coordinate system in ratatui (and in terminals in general) starts at the top left of the
+terminal or container widget. This point represents (0,0).
Here’s the “hello world” example from above rendered:
+╭───────────────────────────────────╮
+│Hello World! │
+│ │
+│ │
+╰───────────────────────────────────╯
+What if hypothetically we wanted to render this instead:
+╭────────────────╮╭─────────────────╮
+│Hello World! ││Hello World! │
+│ ││ │
+│ ││ │
+╰────────────────╯╰─────────────────╯
+We could integer divide the width by 2, account of the borders calculate the x position for
+the second paragraph but that is cumbersome and error prone.
Now, that’s where layouts come in.
+let rects = Layout::default()
+ .direction(Direction::Horizontal)
+ .constraints(
+ [
+ Constraint::Percentage(50),
+ Constraint::Percentage(50),
+ ]
+ .as_ref(),
+ )
+ .split(f.size());Here we created a layout and added two “constraints”. The constraints determine the size of the
+resulting Rects. Calling split on a Layout splits the layout based on the constraints.
That is, rects behaves as a Vec<Rect>, whose length always matches the number of constraints.
So for the example above, we might want to do something like this:
+pub fn render(app: &mut App, f: &mut Frame) {
+ let chunks = Layout::default()
+ .direction(Direction::Horizontal)
+ .constraints(
+ [
+ Constraint::Percentage(50),
+ Constraint::Percentage(50),
+ ]
+ .as_ref(),
+ )
+ .split(f.size());
+ f.render_widget(
+ Paragraph::new("Hello World!")
+ .block(Block::default().borders(Borders::ALL).border_type(BorderType::Rounded)),
+ chunks[0]
+ )
+ f.render_widget(
+ Paragraph::new("Hello World!")
+ .block(Block::default().borders(Borders::ALL).border_type(BorderType::Rounded)),
+ chunks[1]
+ )
+}Notice that we used the first chunk for the first Paragraph and the second chunk for the
+second Paragraph.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/how-to/render/index.html b/pr-preview/pr-83/how-to/render/index.html
new file mode 100644
index 000000000..776146e73
--- /dev/null
+++ b/pr-preview/pr-83/how-to/render/index.html
@@ -0,0 +1,217 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Displaying Text
+This page covers how text displaying works. It will cover Span, Line, and Text, and how these
+can be created, styled, displayed, altered, and such.
Span
+A Span is a styled segment of text. You can think of it as a substring with its own unique style.
+It is the most basic unit of displaying text in ratatui.
The examples below assume the following imports:
+use ratatui::{prelude::*, widgets::*};
+pub type Frame<'a> = ratatui::Frame<'a, CrosstermBackend<std::io::Stderr>>;A Span consists of “content” and a “style” for the content. And a Span can be created in a few
+different ways.
-
+
-
+
using
+Span::raw:
+fn ui(_app: &App, f: &mut Frame<'_>) { + let span = Span::raw("This is text that is not styled"); + // -- snip --- +}
+ -
+
using
+Span::styled:
+fn ui(_app: &App, f: &mut Frame<'_>) { + let span = Span::styled("This is text that will be yellow", Style::default().fg(Color::Yellow)); + // -- snip --- +}
+ -
+
using the
+Stylizetrait:
+fn ui(_app: &App, f: &mut Frame<'_>) { + let span = "This is text that will be yellow".yellow(); + // -- snip --- +}
+
A Span is the basic building block for any styled text, and can be used anywhere text is
+displayed.
Line
+The next building block that we are going to talk about is a Line. A Line represents a cluster
+of graphemes, where each unit in the cluster can have its own style. You can think of an instance of
+the Line struct as essentially a collection of Span objects, i.e. Vec<Span>.
Since each Line struct consists of multiple Span objects, this allows for varied styling in a
+row of words, phrases or sentences.
fn ui(_: &App, f: &mut Frame<'_>) {
+ let line = Line::from(vec![
+ "hello".red(),
+ " ".into(),
+ "world".red().bold()
+ ]);
+ // -- snip ---
+}A Line can be constructed directly from content, where the content is Into<Cow<'a, &str>>.
fn ui(_: &App, f: &mut Frame<'_>) {
+ let line = Line::from("hello world");
+ // -- snip ---
+}You can even style a full line directly:
+fn ui(_: &App, f: &mut Frame<'_>) {
+ let line = Line::styled("hello world", Style::default().fg(Color::Yellow));
+ // -- snip ---
+}And you can use the Stylize trait on the line directly by using into():
fn ui(_: &App, f: &mut Frame<'_>) {
+ let line: Line = "hello world".yellow().into();
+ // -- snip ---
+}Text
+Text is the final building block of outputting text. A Text object represents a collection of
+Lines.
Most widgets accept content that can be converted to Text.
fn ui(_: &App, f: &mut Frame<'_>) {
+ let span1 = "hello".red();
+ let span2 = "world".red().bold();
+ let line = Line::from(vec![span1, " ".into(), span2]);
+ let text = Text::from(line);
+ f.render_widget(Paragraph::new(text).block(Block::default().borders(Borders::ALL)), f.size());
+}Here’s an HTML representation of what you’d get in the terminal:
+
+ hello
+ world
+
+Often code like the one above can be simplified:
+fn ui(_: &App, f: &mut Frame<'_>) {
+ let line: Line = vec![
+ "hello".red(),
+ " ".into(),
+ "world".red().bold()
+ ].into();
+ f.render_widget(Paragraph::new(line).block(Block::default().borders(Borders::ALL)), f.size());
+}This is because in this case, Rust is able to infer the types and convert them into appropriately.
+Text instances can be created using the raw or styled constructors too.
Something that you might find yourself doing pretty often for a Paragraph is wanting to have
+multiple lines styled differently. This is one way you might go about that:
fn ui(_: &App, f: &mut Frame<'_>) {
+ let text = vec![
+ "hello world 1".into(),
+ "hello world 2".blue().into(),
+ Line::from(vec!["hello".green(), " ".into(), "world".green().bold(), "3".into()]),
+ ]
+ .into();
+ f.render_widget(Paragraph::new(text).block(Block::default().borders(Borders::ALL)), f.size());
+}
+
++ hello world 1 +
++ hello world 2 +
++ hello + world 3 +
+We will talk more about styling in the next section.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/how-to/render/style-text.html b/pr-preview/pr-83/how-to/render/style-text.html
new file mode 100644
index 000000000..ca8332a7f
--- /dev/null
+++ b/pr-preview/pr-83/how-to/render/style-text.html
@@ -0,0 +1,311 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Render Text
+ + +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/how-to/widgets/block.html b/pr-preview/pr-83/how-to/widgets/block.html
new file mode 100644
index 000000000..dad55add8
--- /dev/null
+++ b/pr-preview/pr-83/how-to/widgets/block.html
@@ -0,0 +1,214 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Styling-Text
+Styling enhances user experience by adding colors, emphasis, and other visual aids. In ratatui,
+the primary tool for this is the ratatui::style::Style struct.
ratatui::style::Style provides a set of methods to apply styling attributes to your text. These
+styles can then be applied to various text structures like Text, Span, and Line (as well as
+other non text structures).
Common styling attributes include:
+-
+
- Foreground and Background Colors (
fgandbg)
+ - Modifiers (like
bold,italic, andunderline)
+
-
+
-
+
Basic Color Styling
+Setting the foreground (text color) and background:
+
+let styled_text = Span::styled( + "Hello, Ratatui!", + Style::default().fg(Color::Red).bg(Color::Yellow) +);
+ -
+
Using
+ModifiersMaking text bold or italic:
+
+let bold_text = Span::styled( + "This is bold", + Style::default().modifier(Modifier::BOLD) +); + +let italic_text = Span::styled( + "This is italic", + Style::default().modifier(Modifier::ITALIC) +);You can also combine multiple modifiers:
+
+let bold_italic_text = Span::styled( + "This is bold and italic", + Style::default().modifier(Modifier::BOLD | Modifier::ITALIC) +);
+ -
+
Styling within a Line
+You can mix and match different styled spans within a single line:
+
+let mixed_line = Line::from(vec![ + Span::styled("This is mixed", Style::default().fg(Color::Green)), + Span::styled("styling", Style::default().fg(Color::Red).add_modifier(Modifier::BOLD)), + Span::from("!"), +]);
+
This is what it would look like if you rendered a Paragraph with different styles for each line:
fn ui(_: &App, f: &mut Frame<'_>) {
+ let styled_text = Span::styled("Hello, Ratatui!", Style::default().fg(Color::Red).bg(Color::Yellow));
+ let bold_text = Span::styled("This is bold", Style::default().add_modifier(Modifier::BOLD));
+ let italic_text = Span::styled("This is italic", Style::default().add_modifier(Modifier::ITALIC));
+ let bold_italic_text =
+ Span::styled("This is bold and italic", Style::default().add_modifier(Modifier::BOLD | Modifier::ITALIC));
+ let mixed_line = vec![
+ Span::styled("This is mixed", Style::default().fg(Color::Green)),
+ Span::styled("styling", Style::default().fg(Color::Red).add_modifier(Modifier::BOLD)),
+ Span::from("!"),
+ ];
+ let text: Vec<Line<'_>> =
+ vec![styled_text.into(), bold_text.into(), italic_text.into(), bold_italic_text.into(), mixed_line.into()];
+ f.render_widget(Paragraph::new(text).block(Block::default().borders(Borders::ALL)), f.size());
+}Here’s the HTML representation of the above styling:
+
+
+Hello, Ratatui!
+This is bold
+This is italic
+This is bold and italic
++ This is mixed + styling + ! +
+
+
+
+
+
+You can also create instances of Color from a string:
use std::str::FromStr;
+
+let color: Color = Color::from_str("blue").unwrap();
+assert_eq!(color, Color::Blue);
+
+let color: Color = Color::from_str("#FF0000").unwrap();
+assert_eq!(color, Color::Rgb(255, 0, 0));
+
+let color: Color = Color::from_str("10").unwrap();
+assert_eq!(color, Color::Indexed(10));You can read more about the
+Color enum and
+Modifier in the reference
+documentation online.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/how-to/widgets/index.html b/pr-preview/pr-83/how-to/widgets/index.html
new file mode 100644
index 000000000..53300c166
--- /dev/null
+++ b/pr-preview/pr-83/how-to/widgets/index.html
@@ -0,0 +1,217 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Block
+(Stub) This How-To covers the ratatui::widgets::block::Block.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/how-to/widgets/paragraph.html b/pr-preview/pr-83/how-to/widgets/paragraph.html
new file mode 100644
index 000000000..641861d37
--- /dev/null
+++ b/pr-preview/pr-83/how-to/widgets/paragraph.html
@@ -0,0 +1,214 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Use Widgets
+ + +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/index.html b/pr-preview/pr-83/index.html
new file mode 100644
index 000000000..45a013cd6
--- /dev/null
+++ b/pr-preview/pr-83/index.html
@@ -0,0 +1,254 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Paragraph
+(Stub) This page covers ratatui::widgets::Paragraph.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/installation.html b/pr-preview/pr-83/installation.html
new file mode 100644
index 000000000..02be61af0
--- /dev/null
+++ b/pr-preview/pr-83/installation.html
@@ -0,0 +1,261 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Introduction
+
What is ratatui?
+ratatui is a Rust crate that provides widgets allowing you to
+imperatively declare what the view of your application should be, and then draws those widgets
+efficiently to the terminal.
ratatui is based on the principle of immediate rendering. This means that at each new frame all
+widgets that are supposed to be part of the UI are re-built.
The ratatui crate is a library and not a framework.
It is important because ratatui:
-
+
- does not handle keyboard input events +
- does not modify the state of your application +
- does not dicate how you want to structure your application +
ratatui can be highly flexible and customizable. And while this can be empowering, it also puts
+the onus on developers using ratatui to understand how to best architect their applications, to
+tailor the experience for users as they see fit.
Who is ratatui for?
+ratatui is designed for developers and enthusiasts who:
-
+
- appreciate the retro aesthetic of the terminal, +
- want a lightweight alternative to graphical user interfaces (GUIs), +
- need applications that are to be deployed in constrained environments, like on servers with +limited resources, and +
- prefer to have full control over input and events, allowing for a more customized and tailored +user experience. +
Who is this book for?
+In this book, we will cover beginner guides to advanced patterns for developing terminal user +interfaces.
+Those new to the world of TUIs will find this book a comprehensive guide, introducing the
+foundational concepts and walking through common patterns of using ratatui. Additionally,
+developers who have worked with TUIs will understand the nuances and benefits of using ratatui.
We hope that this book can be a journey into creating beautiful and functional terminal-based +applications.
+
+
+
+
+
+
+We want to hear your feedback and suggestions.
+Feel free to give some suggestions on improving the book or documentation via
+GitHub Discussions or chat with us on
+#doc-discussion on Discord.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/integrations/index.html b/pr-preview/pr-83/integrations/index.html
new file mode 100644
index 000000000..6ba80982a
--- /dev/null
+++ b/pr-preview/pr-83/integrations/index.html
@@ -0,0 +1,245 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Installation
+ratatui is a standard rust crate and can be installed into your app using the following command:
cargo add ratatui crossterm
+or by adding the following to your Cargo.toml file:
[dependencies]
+crossterm = "0.27.0"
+ratatui = "0.23.0"
+
+
+
+
+
+Additionally, you can use the all-widgets feature, which enables additional widgets:
cargo add ratatui --features all-widgets
+cargo add crossterm
+or by adding the following to your Cargo.toml file:
[dependencies]
+crossterm = "0.27.0"
+ratatui = { version = "0.23.0", features = ["all-widgets"]}
+You can learn more about available widgets from the +docs.rs page on widgets.
+By default, ratatui enables the crossterm, but it’s possible to alternatively use termion, or
+termwiz instead by enabling the appropriate feature and disabling the default features. See
+Backend for more information.
For Termion:
+cargo add ratatui --no-default-features --features termion
+cargo add termion
+or in your Cargo.toml:
[dependencies]
+ratatui = { version = "0.23", default-features = false, features = ["termion"] }
+termion = "2.0.1"
+For Termwiz:
+cargo add ratatui --no-default-features --features termwiz
+cargo add termwiz
+or in your Cargo.toml:
[dependencies]
+ratatui = { version = "0.23", default-features = false, features = ["termion"] }
+termwiz = "0.20.0"
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/mark.min.js b/pr-preview/pr-83/mark.min.js
new file mode 100644
index 000000000..163623188
--- /dev/null
+++ b/pr-preview/pr-83/mark.min.js
@@ -0,0 +1,7 @@
+/*!***************************************************
+* mark.js v8.11.1
+* https://markjs.io/
+* Copyright (c) 2014–2018, Julian Kühnel
+* Released under the MIT license https://git.io/vwTVl
+*****************************************************/
+!function(e,t){"object"==typeof exports&&"undefined"!=typeof module?module.exports=t():"function"==typeof define&&define.amd?define(t):e.Mark=t()}(this,function(){"use strict";var e="function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?function(e){return typeof e}:function(e){return e&&"function"==typeof Symbol&&e.constructor===Symbol&&e!==Symbol.prototype?"symbol":typeof e},t=function(e,t){if(!(e instanceof t))throw new TypeError("Cannot call a class as a function")},n=function(){function e(e,t){for(var n=0;n
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Integrations
+-
+
- ansi-to-tui — Convert ansi colored text to
+
ratatui::text::Text
+ - color-to-tui — Parse hex colors to
+
ratatui::style::Color
+ - rust-tui-template — A template for +bootstrapping a Rust TUI application with Tui-rs & crossterm +
- simple-tui-rs — A simple example tui-rs app +
- tui-builder — Batteries-included MVC framework for +Tui-rs + Crossterm apps +
- tui-clap — Use clap-rs together with Tui-rs +
- tui-log — Example of how to use logging with Tui-rs +
- tui-logger — Logger and Widget for Tui-rs +
- tui-realm — Tui-rs framework to build stateful applications +with a React/Elm inspired approach +
- tui-realm-treeview — Treeview component for +Tui-realm +
- tui-rs-tree-widgets: Widget for tree data +structures. +
- tui-windows — Tui-rs abstraction to handle multiple +windows and their rendering +
- tui-textarea: Simple yet powerful multi-line text editor +widget supporting several key shortcuts, undo/redo, text search, etc. +
- tui-input: TUI input library supporting multiple +backends and tui-rs. +
- tui-term: A pseudoterminal widget library that enables the +rendering of terminal applications as ratatui widgets. +
- tui-big-text: A Rust crate that renders large pixel text +as a ratatui widget using the glyphs from the font8x8 crate. +
- crokey: Crokey helps incorporate configurable keybindings in +crossterm based terminal applications by providing functions to handle key combinations. +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/references/features.html b/pr-preview/pr-83/references/features.html
new file mode 100644
index 000000000..c4f3f8286
--- /dev/null
+++ b/pr-preview/pr-83/references/features.html
@@ -0,0 +1,242 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Install
+Install
+
+
+Breaking up
+
+
+
+
+
+
+
+
+
+Center a
+
+
+
+Using
+Single
+Better Panic Hooks using
+
+When should I use
+
+Using The Elm Architecture (TEA) with
+Applying The Elm Architecture to
+Why
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+New backend:
+
+
+
+
+
+
+
+
+
+Color: support conversion from
+
+
+
+
+
+Migration from
+
+Search
+
+
+
+
+
+
+
+
+ Introduction
+
What is ratatui?
+ratatui is a Rust crate that provides widgets allowing you to
+imperatively declare what the view of your application should be, and then draws those widgets
+efficiently to the terminal.
ratatui is based on the principle of immediate rendering. This means that at each new frame all
+widgets that are supposed to be part of the UI are re-built.
The ratatui crate is a library and not a framework.
It is important because ratatui:
-
+
- does not handle keyboard input events +
- does not modify the state of your application +
- does not dicate how you want to structure your application +
ratatui can be highly flexible and customizable. And while this can be empowering, it also puts
+the onus on developers using ratatui to understand how to best architect their applications, to
+tailor the experience for users as they see fit.
Who is ratatui for?
+ratatui is designed for developers and enthusiasts who:
-
+
- appreciate the retro aesthetic of the terminal, +
- want a lightweight alternative to graphical user interfaces (GUIs), +
- need applications that are to be deployed in constrained environments, like on servers with +limited resources, and +
- prefer to have full control over input and events, allowing for a more customized and tailored +user experience. +
Who is this book for?
+In this book, we will cover beginner guides to advanced patterns for developing terminal user +interfaces.
+Those new to the world of TUIs will find this book a comprehensive guide, introducing the
+foundational concepts and walking through common patterns of using ratatui. Additionally,
+developers who have worked with TUIs will understand the nuances and benefits of using ratatui.
We hope that this book can be a journey into creating beautiful and functional terminal-based +applications.
+
+
+
+
+
+We want to hear your feedback and suggestions.
+Feel free to give some suggestions on improving the book or documentation via
+GitHub Discussions or chat with us on
+#doc-discussion on Discord.
Installation
+ratatui is a standard rust crate and can be installed into your app using the following command:
cargo add ratatui crossterm
+or by adding the following to your Cargo.toml file:
[dependencies]
+crossterm = "0.27.0"
+ratatui = "0.23.0"
+
+
+
+
+
+Additionally, you can use the all-widgets feature, which enables additional widgets:
cargo add ratatui --features all-widgets
+cargo add crossterm
+or by adding the following to your Cargo.toml file:
[dependencies]
+crossterm = "0.27.0"
+ratatui = { version = "0.23.0", features = ["all-widgets"]}
+You can learn more about available widgets from the +docs.rs page on widgets.
+By default, ratatui enables the crossterm, but it’s possible to alternatively use termion, or
+termwiz instead by enabling the appropriate feature and disabling the default features. See
+Backend for more information.
For Termion:
+cargo add ratatui --no-default-features --features termion
+cargo add termion
+or in your Cargo.toml:
[dependencies]
+ratatui = { version = "0.23", default-features = false, features = ["termion"] }
+termion = "2.0.1"
+For Termwiz:
+cargo add ratatui --no-default-features --features termwiz
+cargo add termwiz
+or in your Cargo.toml:
[dependencies]
+ratatui = { version = "0.23", default-features = false, features = ["termion"] }
+termwiz = "0.20.0"
+Tutorial
+-
+
- Hello World: This tutorial takes you through the basics of creating a simple +Ratatui application that displays “Hello World”. +
- Counter App: This tutorial will set up the basics of a
ratatuiproject by +building a app that displays a counter.
+ - JSON Editor: This tutorial will guide you through setting up a Rust project and
+organizing its structure for a
ratatui-based application to edit json key value pairs. JSON +Editor TUI will provide an interface for users to input key-value pairs, which are then converted +into correct JSON format and printed to stdout.
+ - Async Counter App: This tutorial, expands on the Counter app to build a an +async TUI using tokio. +
- Stopwatch App: This tutorial will build a working stopwatch application that +uses an external big-text widget library, runs asynchronously using tokio. +
Hello World
+Getting started with ratatui is straightforward — Add it to the project, and you are ready to
+start creating beautiful TUIs.
In this section, we will build a “hello world” TUI application.
+Install rust
+The first step is to install rust.
Check
+Installation section of the official Rust Book
+for more information. Most people tend to use rustup to manage their installation.
+
+
+
+
+rustup installs The Rust Programming Language from the official release channels,
+enabling you to easily switch between stable, beta, and nightly compilers and keep them updated.
rustup will set you up with the latest stable version of rust as well as cargo. cargo is
+Rust’s package manager, and it is what we will use to create a new project and add ratatui as a
+dependency.
Create a “hello world” project
+To start with a new project, you can run the following:
+cargo new hello-world-tui
+cd hello-world-tui
+This creates a new folder called hello-world-tui and changes the directory to that folder.
cargo new will instantiate a “binary” project by default.
$ tree .
+.
+├── Cargo.toml
+└── src
+ └── main.rs
+You can compile and execute a “binary” project by running cargo run:
$ cargo run
+ Compiling hello-world-tui v0.1.0 (/Users/USER/gitrepos/hello-world-tui)
+ Finished dev [unoptimized + debuginfo] target(s) in 0.00s
+ Running `target/debug/hello-world-tui`
+Hello, world!
+
+
+
+
+
+By default cargo run compiles your program with no optimizations and with debug information.
+If you want to run it in with more optimizations, you can run cargo run --release.
cargo run --release
+ Compiling hello-world-tui v0.1.0 (/Users/USER/gitrepos/hello-world-tui)
+ Finished release [optimized] target(s) in 0.08s
+ Running `target/release/hello-world-tui`
+Hello, world!
+For more information, check out the cargo section in the official rust
+book.
Install ratatui
+Installing ratatui is as easy as running the following:
cargo add ratatui crossterm
+
+
+
+
+
+ratatui has to be combined with a terminal backend.
+You can learn more about the different terminal backends in the how to choose a
+backend section. For the examples in this book, we are going to
+use crossterm.
Running the above command in your console will add the latest version of ratatui and crossterm
+to your project.
+
+
+
+
+If you are interested in adding a specific version, you can run the following:
+cargo add ratatui --version 0.19.0
+src/main.rs
+Open src/main.rs in your favorite editor, and copy paste the following code to it:
use ratatui::{
+ prelude::{CrosstermBackend, Terminal},
+ widgets::Paragraph,
+};
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+ crossterm::terminal::enable_raw_mode()?;
+ crossterm::execute!(std::io::stderr(), crossterm::terminal::EnterAlternateScreen)?;
+
+ let mut terminal = Terminal::new(CrosstermBackend::new(std::io::stderr()))?;
+
+ loop {
+ terminal.draw(|f| {
+ f.render_widget(Paragraph::new("Hello World! (press 'q' to quit)"), f.size());
+ })?;
+
+ if crossterm::event::poll(std::time::Duration::from_millis(250))? {
+ if let crossterm::event::Event::Key(key) = crossterm::event::read()? {
+ if key.code == crossterm::event::KeyCode::Char('q') {
+ break;
+ }
+ }
+ }
+ }
+
+ crossterm::execute!(std::io::stderr(), crossterm::terminal::LeaveAlternateScreen)?;
+ crossterm::terminal::disable_raw_mode()?;
+
+ Ok(())
+}Make sure you save and exit the file! Now we are ready to run the TUI.
+Running the TUI
+We can run our program with:
+cargo run
+You should see a TUI app with Hello World! (press 'q' to quit) show up in your terminal as a TUI
+app.
You can press q to exit and go back to your terminal as it was before.
Congratulations! 🎉
+You have written a “hello world” terminal user interface with ratatui. We will learn more about
+how ratatui works in the next sections.
Counter App
+In the previous section, we built a “hello world” TUI. In this tutorial, we’ll develop a simple +counter application.
+For the app, we’ll need a Paragraph to display the counter. We’ll also want to increment or
+decrement the counter when a key is pressed. Let’s increment and decrement the counter with j and
+k.
Initialization
+Go ahead and set up a new rust project with
+cargo init ratatui-counter-app
+cd ratatui-counter-app
+We are only going to use 3 dependencies in this tutorial:
+cargo add ratatui crossterm anyhow
+
+
+
+
+
+We opt to use the anyhow crate for easier error handling; it is not necessary to build apps with ratatui.
Filestructure
+We are going to start off like in the previous “hello world” tutorial with one file like so:
+tree .
+├── Cargo.toml
+├── LICENSE
+└── src
+ └── main.rs
+but this time for the counter example, we will expand it out to multiple files like so:
+tree .
+├── Cargo.toml
+├── LICENSE
+└── src
+ ├── app.rs
+ ├── event.rs
+ ├── lib.rs
+ ├── main.rs
+ ├── tui.rs
+ ├── ui.rs
+ └── update.rs
+Single Function
+In this section, we’ll walk through building a simple counter application, allowing users to +increase or decrease a displayed number using keyboard input.
+Here’s a first pass at a counter application in Rust using ratatui where all the code is in one
+main function:
use ratatui::{
+ prelude::{CrosstermBackend, Terminal},
+ widgets::Paragraph,
+};
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+ // startup: Enable raw mode for the terminal, giving us fine control over user input
+ crossterm::terminal::enable_raw_mode()?;
+ crossterm::execute!(std::io::stderr(), crossterm::terminal::EnterAlternateScreen)?;
+
+ // Initialize the terminal backend using crossterm
+ let mut terminal = Terminal::new(CrosstermBackend::new(std::io::stderr()))?;
+
+ // Define our counter variable
+ // This is the state of our application
+ let mut counter = 0;
+
+ // Main application loop
+ loop {
+ // Render the UI
+ terminal.draw(|f| {
+ f.render_widget(Paragraph::new(format!("Counter: {counter}")), f.size());
+ })?;
+
+ // Check for user input every 250 milliseconds
+ if crossterm::event::poll(std::time::Duration::from_millis(250))? {
+ // If a key event occurs, handle it
+ if let crossterm::event::Event::Key(key) = crossterm::event::read()? {
+ match key.code {
+ crossterm::event::KeyCode::Char('j') => counter += 1,
+ crossterm::event::KeyCode::Char('k') => counter -= 1,
+ crossterm::event::KeyCode::Char('q') => break,
+ _ => (),
+ }
+ }
+ }
+ }
+
+ // shutdown down: reset terminal back to original state
+ crossterm::execute!(std::io::stderr(), crossterm::terminal::LeaveAlternateScreen)?;
+ crossterm::terminal::disable_raw_mode()?;
+
+ Ok(())
+}In the code above, it is useful to think about various parts of the code as separate pieces of the +puzzle. This is useful to help refactor and reorganize your code for larger applications.
+Imports
+We start by importing necessary components from the ratatui library, which provides a number of
+different widgets and utilities.
use ratatui::{
+ prelude::{CrosstermBackend, Terminal},
+ widgets::Paragraph,
+};Start up
+Using crossterm, we can set the terminal to raw mode and enter an alternate screen.
crossterm::terminal::enable_raw_mode()?;
+crossterm::execute!(std::io::stderr(), crossterm::terminal::EnterAlternateScreen)?;Initialize
+Again using crossterm, we can create an instance of terminal backend
let mut terminal = Terminal::new(CrosstermBackend::new(std::io::stderr()))?;Shut Down
+Terminal disables raw mode and exits the alternate screen for a clean exit, ensuring the terminal +returns to its original state
+crossterm::execute!(std::io::stderr(), crossterm::terminal::LeaveAlternateScreen)?;
+crossterm::terminal::disable_raw_mode()?;App state
+Our application has just one variable that tracks the “state”, i.e. the counter value.
+let mut counter = 0;Run loop
+Our application runs in a continuous loop, constantly checking for user input and updating the +state, which in turn updates the display on the next loop.
+ // Main application loop
+ loop {
+ // draw UI based on state
+ // ...
+ // Update state based on user input
+ // ...
+ // Break from loop based on user input and/or state
+ }Every TUI with ratatui is bound to have (at least) one main application run loop like this.
UI
+The UI part of our code takes the state of the application, i.e. the value of counter and uses it
+to render a widget, i.e. a Paragraph widget.
terminal.draw(|f| {
+ f.render_widget(Paragraph::new(format!("Counter: {counter}")), f.size());
+ })?;User Input
+Every 250 milliseconds, the application checks if the user has pressed a key:
+-
+
jincreases the counter
+kdecreases the counter
+qexits the application
+
if crossterm::event::poll(std::time::Duration::from_millis(250))? {
+ // If a key event occurs, handle it
+ if let crossterm::event::Event::Key(key) = crossterm::event::read()? {
+ match key.code {
+ crossterm::event::KeyCode::Char('j') => counter += 1,
+ crossterm::event::KeyCode::Char('k') => counter -= 1,
+ crossterm::event::KeyCode::Char('q') => break,
+ _ => (),
+ }
+ }
+ }Conclusion
+By understanding the structure and components used in this simple counter application, you are set
+up to explore crafting more intricate terminal-based interfaces using ratatui.
In the next section, we will explore a refactor of the above code to separate the various parts into +individual functions.
+Multiple Functions
+In this section, we will walk through the process of refactoring the application to set ourselves up
+better for bigger projects. Not all of these changes are ratatui specific, and are generally good
+coding practices to follow.
We are still going to keep everything in one file for this section, but we are going to split the +previous functionality into separate functions.
+Organizing imports
+The first thing you might consider doing is reorganizing imports with qualified names.
+use crossterm::{
+ event::{self, Event::Key, KeyCode::Char},
+ execute,
+ terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+};
+use ratatui::{
+ prelude::{CrosstermBackend, Terminal},
+ widgets::Paragraph,
+};Typedefs and Type Aliases
+By defining custom types and aliases, we can simplify our code and make it more expressive.
+type Err = Box<dyn std::error::Error>;
+type Result<T> = std::result::Result<T, Err>;
+pub type Frame<'a> = ratatui::Frame<'a, CrosstermBackend<std::io::Stderr>>;
+
+
+
+
+If you use the popular anyhow
+then instead of these two lines:
type Err = Box<dyn std::error::Error>;
+type Result<T> = std::result::Result<T, Err>;you can simply import Result from anyhow:
use anyhow::Result;You will need to run cargo add anyhow for this to work.
Frame is a shorthand type to represent the frame we draw to when we render our application.
App struct
+By defining an App struct, we can encapsulate our application state and make it more structured.
struct App {
+ counter: i64,
+ should_quit: bool,
+}-
+
counterholds the current value of our counter.
+should_quitis a flag that indicates whether the application should exit its main loop.
+
Breaking up main()
+We can extract significant parts of the main() function into separate smaller functions, e.g.
+startup(), shutdown(), ui(), update(), run().
startup() is responsible for initializing the terminal.
fn startup() -> Result<()> {
+ enable_raw_mode()?;
+ execute!(std::io::stderr(), EnterAlternateScreen)?;
+ Ok(())
+}shutdown() cleans up the terminal.
fn shutdown() -> Result<()> {
+ execute!(std::io::stderr(), LeaveAlternateScreen)?;
+ disable_raw_mode()?;
+ Ok(())
+}ui() handles rendering of our application state.
fn ui(app: &App, f: &mut Frame<'_>) {
+ f.render_widget(Paragraph::new(format!("Counter: {}", app.counter)), f.size());
+}update() processes user input and updates our application state.
fn update(app: &mut App) -> Result<()> {
+ if event::poll(std::time::Duration::from_millis(250))? {
+ if let Key(key) = event::read()? {
+ match key.code {
+ Char('j') => app.counter += 1,
+ Char('k') => app.counter -= 1,
+ Char('q') => app.should_quit = true,
+ _ => (),
+ }
+ }
+ }
+ Ok(())
+}
+
+
+
+
+You’ll notice that in the update() function we make use of pattern matching for handling user
+input. This is a powerful feature in rust; and enhances readability and provides a clear pattern for
+how each input is processed.
You can learn more about pattern matching in the official rust +book.
+run() contains our main application loop.
fn run() -> Result<()> {
+ // ratatui terminal
+ let mut t = Terminal::new(CrosstermBackend::new(std::io::stderr()))?;
+
+ // application state
+ let mut app = App { counter: 0, should_quit: false };
+
+ loop {
+ // application render
+ t.draw(|f| {
+ ui(&app, f);
+ })?;
+
+ // application update
+ update(&mut app)?;
+
+ // application exit
+ if app.should_quit {
+ break;
+ }
+ }
+
+ Ok(())
+}Each function now has a specific task, making our main application logic more organized and easier +to follow.
+fn main() -> Result<()> {
+ startup()?;
+ let status = run();
+ shutdown()?;
+ status?;
+ Ok(())
+}
+
+
+
+
+You may be wondering if we could have written the main function like so:
fn main() -> Result<()> {
+ startup()?;
+ run()?;
+ shutdown()?;
+ Ok(())
+}This works fine during the happy path of a program.
+However, if your run() function returns an error, the program will not call shutdown().
+And this can leave your terminal in a messed up
+state for your users.
Instead, we should ensure that shutdown() is always called before the program exits.
fn main() -> Result<()> {
+ startup()?;
+ let result = run();
+ shutdown()?;
+ result?;
+ Ok(())
+}Here, we can get the result of run(), and call shutdown() first and then unwrap() on the result.
+This will be a much better experience for users.
We will discuss in future sections how to handle the situation when your code unexpectedly panics.
+Conclusion
+By making our code more organized, modular, and readable, we not only make it easier for others to +understand and work with but also set the stage for future enhancements and extensions.
+Here’s the full code for reference:
+use anyhow::Result;
+use crossterm::{
+ event::{self, Event::Key, KeyCode::Char},
+ execute,
+ terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+};
+use ratatui::{
+ prelude::{CrosstermBackend, Terminal},
+ widgets::Paragraph,
+};
+
+pub type Frame<'a> = ratatui::Frame<'a, CrosstermBackend<std::io::Stderr>>;
+
+fn startup() -> Result<()> {
+ enable_raw_mode()?;
+ execute!(std::io::stderr(), EnterAlternateScreen)?;
+ Ok(())
+}
+
+fn shutdown() -> Result<()> {
+ execute!(std::io::stderr(), LeaveAlternateScreen)?;
+ disable_raw_mode()?;
+ Ok(())
+}
+
+// App state
+struct App {
+ counter: i64,
+ should_quit: bool,
+}
+
+// App ui render function
+fn ui(app: &App, f: &mut Frame<'_>) {
+ f.render_widget(Paragraph::new(format!("Counter: {}", app.counter)), f.size());
+}
+
+// App update function
+fn update(app: &mut App) -> Result<()> {
+ if event::poll(std::time::Duration::from_millis(250))? {
+ if let Key(key) = event::read()? {
+ match key.code {
+ Char('j') => app.counter += 1,
+ Char('k') => app.counter -= 1,
+ Char('q') => app.should_quit = true,
+ _ => (),
+ }
+ }
+ }
+ Ok(())
+}
+
+fn run() -> Result<()> {
+ // ratatui terminal
+ let mut t = Terminal::new(CrosstermBackend::new(std::io::stderr()))?;
+
+ // application state
+ let mut app = App { counter: 0, should_quit: false };
+
+ loop {
+ // application update
+ update(&mut app)?;
+
+ // application render
+ t.draw(|f| {
+ ui(&app, f);
+ })?;
+
+ // application exit
+ if app.should_quit {
+ break;
+ }
+ }
+
+ Ok(())
+}
+
+fn main() -> Result<()> {
+ // setup terminal
+ startup()?;
+
+ let result = run();
+
+ // teardown terminal before unwrapping Result of app run
+ shutdown()?;
+
+ result?;
+
+ Ok(())
+}Here’s a flow chart representation of the various steps in the program:
+graph TD + MainRun[Main: Run]; + CheckEvent[Main: Poll KeyPress]; + UpdateApp[Main: Update App]; + ShouldQuit[Main: Check should_quit?]; + BreakLoop[Main: Break Loop]; + MainStart[Main: Start]; + MainEnd[Main: End]; + MainStart --> MainRun; + MainRun --> CheckEvent; + CheckEvent -->|No KeyPress| Draw; + CheckEvent --> |KeyPress Received| UpdateApp; + Draw --> ShouldQuit; + UpdateApp --> Draw; + ShouldQuit -->|Yes| BreakLoop; + BreakLoop --> MainEnd; + ShouldQuit -->|No| CheckEvent; ++
+
+
+
+
+What do you think happens if you modify the example above to change the polling to 0 milliseconds?
What would happen if you change the example to poll every 10 seconds?
+Experiment with different “tick rates” and see how that affects the user experience. +Monitor your CPU usage when you do this experiment. +What happens to your CPU usage as you change the poll frequency?
+Multiple Files
+At the moment, we have everything in just one file. However, this can be impractical if we want to +expand our app further.
+Let’s start by creating a number of different files to represent the various concepts we covered in +the previous section:
+$ tree .
+├── Cargo.toml
+├── LICENSE
+└── src
+ ├── app.rs
+ ├── event.rs
+ ├── main.rs
+ ├── tui.rs
+ ├── ui.rs
+ └── update.rs
+Let’s go ahead and declare these files as modules in src/main.rs
/// Application.
+pub mod app;
+
+/// Terminal events handler.
+pub mod event;
+
+/// Widget renderer.
+pub mod ui;
+
+/// Terminal user interface.
+pub mod tui;
+
+/// Application updater.
+pub mod update;We are going to use anyhow in this section of the tutorial.
cargo add anyhow
+
+
+
+
+
+Instead of anyhow you can also use eyre or color-eyre.
- use anyhow::Result;
++ use color_eyre::eyre::Result;
+You’ll need to add color-eyre and remove anyhow:
cargo remove anyhow
+cargo add color-eyre
+If you are using color_eyre, you’ll also want to add color_eyre::install()? to the beginning of
+your main() function:
use color_eyre::eyre::Result;
+
+fn main() -> Result<()> {
+ color_eyre::install()?;
+ // ...
+ Ok(())
+}color_eyre is an error report handler for colorful, consistent, and well formatted error
+reports for all kinds of errors.
+Check out the section for
+setting up panic hooks with color-eyre.
Now we are ready to start refactoring our app.
+app.rs
+Let’s start with the same struct as we had before:
/// Application.
+#[derive(Debug, Default)]
+pub struct App {
+ /// should the application exit?
+ pub should_quit: bool,
+ /// counter
+ pub counter: u8,
+}We can add additional methods to this Application struct:
impl App {
+ /// Constructs a new instance of [`App`].
+ pub fn new() -> Self {
+ Self::default()
+ }
+
+ /// Handles the tick event of the terminal.
+ pub fn tick(&self) {}
+
+ /// Set running to false to quit the application.
+ pub fn quit(&mut self) {
+ self.should_quit = true;
+ }
+
+ pub fn increment_counter(&mut self) {
+ if let Some(res) = self.counter.checked_add(1) {
+ self.counter = res;
+ }
+ }
+
+ pub fn decrement_counter(&mut self) {
+ if let Some(res) = self.counter.checked_sub(1) {
+ self.counter = res;
+ }
+ }
+}We use the principle of encapsulation to expose an interface to modify the state. In this particular +instance, it may seem like overkill but it is good practice nonetheless.
+The practical advantage of this is that it makes the state changes easy to test.
+mod tests {
+ use super::*;
+ #[test]
+ fn test_app_increment_counter() {
+ let mut app = App::default();
+ app.increment_counter();
+ assert_eq!(app.counter, 1);
+ }
+
+ #[test]
+ fn test_app_decrement_counter() {
+ let mut app = App::default();
+ app.decrement_counter();
+ assert_eq!(app.counter, 0);
+ }
+}
+
+
+
+
+You can test a single function by writing out fully qualified module path +to the test function, like so:
+cargo test -- app::tests::test_app_increment_counter --nocapture
+Or even test all functions that start with test_app_ by doing this:
cargo test -- app::tests::test_app_ --nocapture
+The --nocapture flag prints stdout stderr to the console, which can help debugging tests.
ui.rs
+Previously we were rendering a Paragraph with no styling.
Let’s make some improvements:
+-
+
- Add a
Blockwith a rounded border and the title"Counter App".
+ - Make everything in the Paragraph have a foreground color of
Color::Yellow
+
This is what our code will now look like:
+use ratatui::{
+ layout::Alignment,
+ style::{Color, Style},
+ widgets::{Block, BorderType, Borders, Paragraph},
+};
+
+use crate::{app::App, tui::Frame};
+
+pub fn render(app: &mut App, f: &mut Frame) {
+ f.render_widget(
+ Paragraph::new(format!(
+ "
+ Press `Esc`, `Ctrl-C` or `q` to stop running.\n\
+ Press `j` and `k` to increment and decrement the counter respectively.\n\
+ Counter: {}
+ ",
+ app.counter
+ ))
+ .block(
+ Block::default()
+ .title("Counter App")
+ .title_alignment(Alignment::Center)
+ .borders(Borders::ALL)
+ .border_type(BorderType::Rounded),
+ )
+ .style(Style::default().fg(Color::Yellow))
+ .alignment(Alignment::Center),
+ f.size(),
+ )
+}Keep in mind it won’t render until we have written the code for tui::Frame
When rendered, this is what the UI will look like:
+
event.rs
+We are going to introduce a new concept right now. The concept of an EventHandler.
Previously, we were polling for key inputs every 250 ms using crossterm as part of the main loop.
+Instead, now we are going to start a thread in the background that does the same thing.
First, let’s create an Event enum to handle the different kinds of events that can occur:
use crossterm::event::{self, KeyEvent, MouseEvent};
+
+
+/// Terminal events.
+#[derive(Clone, Copy, Debug)]
+pub enum Event {
+ /// Terminal tick.
+ Tick,
+ /// Key press.
+ Key(KeyEvent),
+ /// Mouse click/scroll.
+ Mouse(MouseEvent),
+ /// Terminal resize.
+ Resize(u16, u16),
+}Next, let’s create an EventHandler struct:
use std::{sync::mpsc, thread};
+
+/// Terminal event handler.
+#[derive(Debug)]
+pub struct EventHandler {
+ /// Event sender channel.
+ sender: mpsc::Sender<Event>,
+ /// Event receiver channel.
+ receiver: mpsc::Receiver<Event>,
+ /// Event handler thread.
+ handler: thread::JoinHandle<()>,
+}We are using std::sync::mpsc which is a “Multiple
+Producer Single Consumer” channel.
+
+
+
+
+A channel is a thread-safe communication mechanism that allows data to be transmitted between +threads. Essentially, it’s a conduit where one or more threads (the producers) can send data, and +another thread (the consumer) can receive this data.
+In Rust, channels are particularly useful for sending data between threads without the need for
+locks or other synchronization mechanisms. The “Multiple Producer, Single Consumer” aspect of
+std::sync::mpsc means that while multiple threads can send data into the channel, only a single
+thread can retrieve and process this data, ensuring a clear and orderly flow of information.
+
+
+
+
+In the code in this section, we only need a “Single Producer, Single Consumer” but we are going to
+use mpsc to set us up for the future.
Finally, here’s the code that starts a thread that polls for events from crossterm and maps it to
+our Event enum.
use std::{
+ sync::mpsc,
+ thread,
+ time::{Duration, Instant},
+};
+
+use anyhow::Result;
+use crossterm::event::{self, Event as CrosstermEvent, KeyEvent, MouseEvent};
+
+// --snip--
+
+impl EventHandler {
+ /// Constructs a new instance of [`EventHandler`].
+ pub fn new(tick_rate: u64) -> Self {
+ let tick_rate = Duration::from_millis(tick_rate);
+ let (sender, receiver) = mpsc::channel();
+ let handler = {
+ let sender = sender.clone();
+ thread::spawn(move || {
+ let mut last_tick = Instant::now();
+ loop {
+ let timeout = tick_rate.checked_sub(last_tick.elapsed()).unwrap_or(tick_rate);
+
+ if event::poll(timeout).expect("no events available") {
+ match event::read().expect("unable to read event") {
+ CrosstermEvent::Key(e) => sender.send(Event::Key(e)),
+ CrosstermEvent::Mouse(e) => sender.send(Event::Mouse(e)),
+ CrosstermEvent::Resize(w, h) => sender.send(Event::Resize(w, h)),
+ _ => unimplemented!(),
+ }
+ .expect("failed to send terminal event")
+ }
+
+ if last_tick.elapsed() >= tick_rate {
+ sender.send(Event::Tick).expect("failed to send tick event");
+ last_tick = Instant::now();
+ }
+ }
+ })
+ };
+ Self { sender, receiver, handler }
+ }
+
+ /// Receive the next event from the handler thread.
+ ///
+ /// This function will always block the current thread if
+ /// there is no data available and it's possible for more data to be sent.
+ pub fn next(&self) -> Result<Event> {
+ Ok(self.receiver.recv()?)
+ }
+}At the beginning of our EventHandler new method, we create a channel using mpsc::channel().
let (sender, receiver) = mpsc::channel();This gives us a sender and receiver pair. The sender can be used to send events, while the
+receiver can be used to receive them.
A new thread is spawned to handle events. This thread runs in the background and is responsible for +polling and sending events to our main application through the channel.
+Within our background thread, we continuously poll for events with event::poll(timeout). If an
+event is available, it’s read and sent through the sender channel. The types of events we handle
+include keypresses, mouse movements, screen resizing, and regular time ticks.
if event::poll(timeout)? {
+ match event::read()? {
+ CrosstermEvent::Key(e) => sender.send(Event::Key(e))?,
+ CrosstermEvent::Mouse(e) => sender.send(Event::Mouse(e))?,
+ CrosstermEvent::Resize(w, h) => sender.send(Event::Resize(w, h))?,
+ _ => unimplemented!(),
+ }
+}We expose the receiver channel as part of a next() method.
pub fn next(&self) -> Result<Event> {
+ Ok(self.receiver.recv()?)
+ }Calling event_handler.next() method will call receiver.recv() which will cause the thread to
+block until the receiver gets a new event.
Finally, we update the last_tick value based on the time elapsed since the previous Tick. We
+also send a Event::Tick on the channel during this.
if last_tick.elapsed() >= tick_rate {
+ sender.send(Event::Tick).expect("failed to send tick event");
+ last_tick = Instant::now();
+}In summary, our EventHandler abstracts away the complexity of event polling and handling into a
+dedicated background thread.
Here’s the full code for your reference:
+use std::{
+ sync::mpsc,
+ thread,
+ time::{Duration, Instant},
+};
+
+use anyhow::Result;
+use crossterm::event::{self, Event as CrosstermEvent, KeyEvent, MouseEvent};
+
+
+/// Terminal events.
+#[derive(Clone, Copy, Debug)]
+pub enum Event {
+ /// Terminal tick.
+ Tick,
+ /// Key press.
+ Key(KeyEvent),
+ /// Mouse click/scroll.
+ Mouse(MouseEvent),
+ /// Terminal resize.
+ Resize(u16, u16),
+}
+
+/// Terminal event handler.
+#[derive(Debug)]
+pub struct EventHandler {
+ /// Event sender channel.
+ sender: mpsc::Sender<Event>,
+ /// Event receiver channel.
+ receiver: mpsc::Receiver<Event>,
+ /// Event handler thread.
+ handler: thread::JoinHandle<()>,
+}
+
+impl EventHandler {
+ /// Constructs a new instance of [`EventHandler`].
+ pub fn new(tick_rate: u64) -> Self {
+ let tick_rate = Duration::from_millis(tick_rate);
+ let (sender, receiver) = mpsc::channel();
+ let handler = {
+ let sender = sender.clone();
+ thread::spawn(move || {
+ let mut last_tick = Instant::now();
+ loop {
+ let timeout = tick_rate.checked_sub(last_tick.elapsed()).unwrap_or(tick_rate);
+
+ if event::poll(timeout).expect("no events available") {
+ match event::read().expect("unable to read event") {
+ CrosstermEvent::Key(e) => sender.send(Event::Key(e)),
+ CrosstermEvent::Mouse(e) => sender.send(Event::Mouse(e)),
+ CrosstermEvent::Resize(w, h) => sender.send(Event::Resize(w, h)),
+ _ => unimplemented!(),
+ }
+ .expect("failed to send terminal event")
+ }
+
+ if last_tick.elapsed() >= tick_rate {
+ sender.send(Event::Tick).expect("failed to send tick event");
+ last_tick = Instant::now();
+ }
+ }
+ })
+ };
+ Self { sender, receiver, handler }
+ }
+
+ /// Receive the next event from the handler thread.
+ ///
+ /// This function will always block the current thread if
+ /// there is no data available and it's possible for more data to be sent.
+ pub fn next(&self) -> Result<Event> {
+ Ok(self.receiver.recv()?)
+ }
+}tui.rs
+Next, we can further abstract the terminal functionality from earlier into a Tui struct.
It provides a concise and efficient way to manage the terminal, handle events, and render content. +Let’s dive into its composition and functionality.
+This introductory section includes the same imports and type definitions as before. We add an
+additional type alias for CrosstermTerminal.
use std::{io, panic};
+
+use anyhow::Result;
+use crossterm::{
+ event::{DisableMouseCapture, EnableMouseCapture},
+ terminal::{self, EnterAlternateScreen, LeaveAlternateScreen},
+};
+
+pub type Frame<'a> = ratatui::Frame<'a, ratatui::backend::CrosstermBackend<std::io::Stderr>>;
+pub type CrosstermTerminal = ratatui::Terminal<ratatui::backend::CrosstermBackend<std::io::Stderr>>;
+
+use crate::{app::App, event::EventHandler, ui};The Tui struct can be defined with two primary fields:
-
+
terminal: This provides a direct interface to the terminal, allowing operations like drawing, +clearing the screen, and more.
+events: An event handler that we defined in the previous section, which would help in managing +terminal events like keystrokes, mouse movements, and other input events.
+
/// Representation of a terminal user interface.
+///
+/// It is responsible for setting up the terminal,
+/// initializing the interface and handling the draw events.
+pub struct Tui {
+ /// Interface to the Terminal.
+ terminal: CrosstermTerminal,
+ /// Terminal event handler.
+ pub events: EventHandler,
+}With this Tui struct, we can add helper methods to handle modifying the terminal state. For
+example, here’s the init method:
impl Tui {
+ /// Constructs a new instance of [`Tui`].
+ pub fn new(terminal: CrosstermTerminal, events: EventHandler) -> Self {
+ Self { terminal, events }
+ }
+
+ /// Initializes the terminal interface.
+ ///
+ /// It enables the raw mode and sets terminal properties.
+ pub fn init(&mut self) -> Result<()> {
+ terminal::enable_raw_mode()?;
+ crossterm::execute!(io::stderr(), EnterAlternateScreen, EnableMouseCapture)?;
+
+ // Define a custom panic hook to reset the terminal properties.
+ // This way, you won't have your terminal messed up if an unexpected error happens.
+ let panic_hook = panic::take_hook();
+ panic::set_hook(Box::new(move |panic| {
+ Self::reset().expect("failed to reset the terminal");
+ panic_hook(panic);
+ }));
+
+ self.terminal.hide_cursor()?;
+ self.terminal.clear()?;
+ Ok(())
+ }
+
+}This is essentially the same as the startup function from before. One important thing to note that
+this function can be used to set a panic hook that calls the reset() method.
impl tui {
+ // --snip--
+
+ /// Resets the terminal interface.
+ ///
+ /// This function is also used for the panic hook to revert
+ /// the terminal properties if unexpected errors occur.
+ fn reset() -> Result<()> {
+ terminal::disable_raw_mode()?;
+ crossterm::execute!(io::stderr(), LeaveAlternateScreen, DisableMouseCapture)?;
+ Ok(())
+ }
+
+ /// Exits the terminal interface.
+ ///
+ /// It disables the raw mode and reverts back the terminal properties.
+ pub fn exit(&mut self) -> Result<()> {
+ Self::reset()?;
+ self.terminal.show_cursor()?;
+ Ok(())
+ }
+
+ // --snip--
+}With this panic hook, in the event of an unexpected error or panic, the terminal properties will be +reset, ensuring that the terminal doesn’t remain in a disrupted state.
+Finally, we can set up the draw method:
+impl tui {
+ // --snip--
+
+ /// [`Draw`] the terminal interface by [`rendering`] the widgets.
+ ///
+ /// [`Draw`]: tui::Terminal::draw
+ /// [`rendering`]: crate::ui:render
+ pub fn draw(&mut self, app: &mut App) -> Result<()> {
+ self.terminal.draw(|frame| ui::render(app, frame))?;
+ Ok(())
+ }
+
+}This draw method leverages the ui::render function from earlier in this section to transform the
+state of our application into widgets that are then displayed on the terminal.
Here’s the full tui.rs file for your reference:
+use std::{io, panic};
+
+use anyhow::Result;
+use crossterm::{
+ event::{DisableMouseCapture, EnableMouseCapture},
+ terminal::{self, EnterAlternateScreen, LeaveAlternateScreen},
+};
+
+pub type Frame<'a> = ratatui::Frame<'a, ratatui::backend::CrosstermBackend<std::io::Stderr>>;
+pub type CrosstermTerminal = ratatui::Terminal<ratatui::backend::CrosstermBackend<std::io::Stderr>>;
+
+use crate::{app::App, event::EventHandler, ui};
+
+/// Representation of a terminal user interface.
+///
+/// It is responsible for setting up the terminal,
+/// initializing the interface and handling the draw events.
+pub struct Tui {
+ /// Interface to the Terminal.
+ terminal: CrosstermTerminal,
+ /// Terminal event handler.
+ pub events: EventHandler,
+}
+
+impl Tui {
+ /// Constructs a new instance of [`Tui`].
+ pub fn new(terminal: CrosstermTerminal, events: EventHandler) -> Self {
+ Self { terminal, events }
+ }
+
+ /// Initializes the terminal interface.
+ ///
+ /// It enables the raw mode and sets terminal properties.
+ pub fn init(&mut self) -> Result<()> {
+ terminal::enable_raw_mode()?;
+ crossterm::execute!(io::stderr(), EnterAlternateScreen, EnableMouseCapture)?;
+
+ // Define a custom panic hook to reset the terminal properties.
+ // This way, you won't have your terminal messed up if an unexpected error happens.
+ let panic_hook = panic::take_hook();
+ panic::set_hook(Box::new(move |panic| {
+ Self::reset().expect("failed to reset the terminal");
+ panic_hook(panic);
+ }));
+
+ self.terminal.hide_cursor()?;
+ self.terminal.clear()?;
+ Ok(())
+ }
+
+
+ /// [`Draw`] the terminal interface by [`rendering`] the widgets.
+ ///
+ /// [`Draw`]: tui::Terminal::draw
+ /// [`rendering`]: crate::ui:render
+ pub fn draw(&mut self, app: &mut App) -> Result<()> {
+ self.terminal.draw(|frame| ui::render(app, frame))?;
+ Ok(())
+ }
+
+
+ /// Resets the terminal interface.
+ ///
+ /// This function is also used for the panic hook to revert
+ /// the terminal properties if unexpected errors occur.
+ fn reset() -> Result<()> {
+ terminal::disable_raw_mode()?;
+ crossterm::execute!(io::stderr(), LeaveAlternateScreen, DisableMouseCapture)?;
+ Ok(())
+ }
+
+ /// Exits the terminal interface.
+ ///
+ /// It disables the raw mode and reverts back the terminal properties.
+ pub fn exit(&mut self) -> Result<()> {
+ Self::reset()?;
+ self.terminal.show_cursor()?;
+ Ok(())
+ }
+}
+update.rs
+Finally we have the update.rs file. Here, the update() function takes in two arguments:
-
+
key_event: This is an event provided by thecrosstermcrate, representing a key press from the +user.
+app: A mutable reference to our application’s state, represented by theAppstruct.
+
use crossterm::event::{KeyCode, KeyEvent, KeyModifiers};
+
+use crate::app::App;
+
+pub fn update(app: &mut App, key_event: KeyEvent) {
+ match key_event.code {
+ KeyCode::Esc | KeyCode::Char('q') => app.quit(),
+ KeyCode::Char('c') | KeyCode::Char('C') => {
+ if key_event.modifiers == KeyModifiers::CONTROL {
+ app.quit()
+ }
+ },
+ KeyCode::Right | KeyCode::Char('j') => app.increment_counter(),
+ KeyCode::Left | KeyCode::Char('k') => app.decrement_counter(),
+ _ => {},
+ };
+}
+
+
+
+
+As an exercise, can you refactor this app to use “The Elm Architecture” principles?
+Check out the concepts page on The Elm Architecture for reference.
+main.rs
+Putting it all together, we have the main.rs function:
/// Application.
+pub mod app;
+
+/// Terminal events handler.
+pub mod event;
+
+/// Widget renderer.
+pub mod ui;
+
+/// Terminal user interface.
+pub mod tui;
+
+/// Application updater.
+pub mod update;
+
+use anyhow::Result;
+use app::App;
+use event::{Event, EventHandler};
+use ratatui::{backend::CrosstermBackend, Terminal};
+use tui::Tui;
+use update::update;
+
+fn main() -> Result<()> {
+ // Create an application.
+ let mut app = App::new();
+
+ // Initialize the terminal user interface.
+ let backend = CrosstermBackend::new(std::io::stderr());
+ let terminal = Terminal::new(backend)?;
+ let events = EventHandler::new(250);
+ let mut tui = Tui::new(terminal, events);
+ tui.init()?;
+
+ // Start the main loop.
+ while !app.should_quit {
+ // Render the user interface.
+ tui.draw(&mut app)?;
+ // Handle events.
+ match tui.events.next()? {
+ Event::Tick => {},
+ Event::Key(key_event) => update(&mut app, key_event),
+ Event::Mouse(_) => {},
+ Event::Resize(_, _) => {},
+ };
+ }
+
+ // Exit the user interface.
+ tui.exit()?;
+ Ok(())
+}Because we call tui.events.next() in a loop, it blocks until there’s an event generated. If
+there’s a key press, the state updates and the UI is refreshed. If there’s no key press, a Tick
+event is generated every 250 milliseconds, which causes the UI to be refreshed.
This is what it looks like in practice to:
+-
+
- Run the TUI +
- Wait 2.5 seconds +
- Press
j5 times
+ - Wait 2.5 seconds +
- Press
k5 times
+ - Wait 2.5 seconds +
- Press
q
+
+
+
+
+
+Check out the concepts pages, e.g. The Elm Architecture for more information on how to structure your applications.
+JSON Editor
+Now that we have covered some of the basics of a “hello world” and “counter” app, we are ready to +build and manage something more involved.
+In this tutorial, we will be creating an application that gives the user a simple interface to enter
+key-value pairs, which will be converted and printed to stdout in json. The purpose of this
+application will be to give the user an interface to create correct json, instead of having to worry
+about commas and brackets themselves.
Initialization
+Go ahead and set up a new rust project with
+cargo init ratatui-json-editor
+and put the following in the Cargo.toml:
[dependencies]
+crossterm = "0.26.1"
+ratatui = "0.22.0"
+serde = { version = "1.0.181", features = ["derive"] }
+serde_json = "1.0.104"
+or the latest version of these libraries.
+Filestructure
+Now create two files inside of src/ so it looks like this:
src
+├── main.rs
+├── ui.rs
+└── app.rs
+This follows a common approach to small applications in ratatui, where we have a state file, a UI
+file, and the main file to tie it all together.
App.rs
+As we saw in the previous section, a common model for smaller ratatui applications is to have one
+application state struct called App or some variant of that name. We will be using this paradigm
+in this application as well.
This struct will contain all of our “persistent” data and will be passed to any function that needs +to know the current state of the application.
+ +Application modes
+It is useful to think about the several “modes” that your application can be in. Thinking in “modes” +will make it easier to segregate everything from what window is getting drawn, to what keybinds to +listen for.
+We will be using the application’s state to track two things:
+-
+
- what screen the user is seeing, +
- which box should be highlighted, the “key” or “value” (this only applies when the user is editing +a key-value pair). +
Current Screen Enum
+In this tutorial application, we will have three “screens”:
+-
+
Main: the main summary screen showing all past key-value pairs entered
+Editing: the screen shown when the user wishes to create a new key-value pair
+Exiting: displays a prompt asking if the user wants to output the key-value pairs they have +entered.
+
We represent these possible modes with a simple enum:
+pub enum CurrentScreen {
+ Main,
+ Editing,
+ Exiting,
+}Currently Editing Enum
+As you may already know, ratatui does not automatically redraw the screen1. ratatui also
+does not remember anything about what it drew last frame.
This means that the programmer is responsible for handling all state and updating widgets to reflect
+changes. In this case, we will allow the user to input two strings in the Editing mode - a key and
+a value. The programmer is responsible for knowing which the user is trying to edit.
For this purpose, we will create another enum for our application state called CurrentlyEditing to
+keep track of which field the user is currently entering:
pub enum CurrentlyEditing {
+ Key,
+ Value,
+}The full application state
+Now that we have enums to help us track where the user is, we will create the struct that actually +stores this data which can be passed around where it is needed.
+pub struct App {
+ pub key_input: String, // the currently being edited json key.
+ pub value_input: String, // the currently being edited json value.
+ pub pairs: HashMap<String, String>, // The representation of our key and value pairs with serde Serialize support
+ pub current_screen: CurrentScreen, // the current screen the user is looking at, and will later determine what is rendered.
+ pub currently_editing: Option<CurrentlyEditing>, // the optional state containing which of the key or value pair the user is editing. It is an option, because when the user is not directly editing a key-value pair, this will be set to `None`.
+}Helper functions
+While we could simply keep our application state as simply a holder of values, we can also create a +few helper functions which will make our life easier elsewhere. Of course, these functions should +only affect the application state itself, and nothing outside of it.
+new()
+We will be adding this function simply to make creating the state easier. While this could be +avoided by specifying it all in the instantiation of the variable, doing it here allows for easy to +change universal defaults for the state.
+impl App {
+ pub fn new() -> App {
+ App {
+ key_input: String::new(),
+ value_input: String::new(),
+ pairs: HashMap::new(),
+ current_screen: CurrentScreen::Main,
+ currently_editing: None,
+ }
+ }
+ ...save_key_value()
+This function will be called when the user saves a key-value pair in the editor. It adds the two
+stored variables to the key-value pairs HashMap, and resets the status of all of the editing
+variables.
...
+ pub fn save_key_value(&mut self) {
+ self.pairs
+ .insert(self.key_input.clone(), self.value_input.clone());
+
+ self.key_input = String::new();
+ self.value_input = String::new();
+ self.currently_editing = None;
+ }
+ ...toggle_editing()
+Sometimes it is easier to put simple logic into a convenience function so we don’t have to worry
+about it in the main code block. toggle_editing is one of those cases. All we are doing, is
+checking if something is currently being edited, and if it is, swapping between editing the Key and
+Value fields.
...
+ pub fn toggle_editing(&mut self) {
+ if let Some(edit_mode) = &self.currently_editing {
+ match edit_mode {
+ CurrentlyEditing::Key => self.currently_editing = Some(CurrentlyEditing::Value),
+ CurrentlyEditing::Value => self.currently_editing = Some(CurrentlyEditing::Key),
+ };
+ } else {
+ self.currently_editing = Some(CurrentlyEditing::Key);
+ }
+ }
+ ...print_json()
+Finally, is another convenience function to print out the serialized json from all of our key-value +pairs.
+ ...
+ pub fn print_json(&self) -> Result<()> {
+ let output = serde_json::to_string(&self.pairs)?;
+ println!("{}", output);
+ Ok(())
+ }
+ ...1
+
+In ratatui, every frame draws the UI anew. See the Rendering section for more information.
+Main.rs
+The main file in many ratatui applications is simply a place to store the startup loop, and
+occasionally event handling. (See more ways to handle events in
+Event Handling))
In this application, we will be using our main function to run the startup steps, and start the
+main loop. We will also put our main loop logic and event handling in this file.
Main
+In our main function, we will set up the terminal, create an application state and run our +application, and finally reset the terminal to the state we found it in.
+Application pre-run steps
+Because a ratatui application takes the whole screen, and captures all of the keyboard input, we
+need some boilerplate at the beginning of our main function.
use crossterm::event::EnableMouseCapture;
+use crossterm::execute;
+use crossterm::terminal::{enable_raw_mode, EnterAlternateScreen};
+use std::io;fn main() -> Result<(), Box<dyn Error>> {
+ // setup terminal
+ enable_raw_mode()?;
+ let mut stderr = io::stderr(); // This is a special case. Normally using stdout is fine
+ execute!(stderr, EnterAlternateScreen, EnableMouseCapture)?;
+ ...You might notice that we are using stderr for our output. This is because we want to allow the
+user to pipe their completed json to other programs like ratatui-tutorial > output.json. To do
+this, we are utilizing the fact that stderr is piped differently than stdout, and rendering out
+project in stderr, and printout our completed json in stdout.
For more information, please read the +crossterm documentation
+State creation, and loop starting
+Now that we have prepared the terminal for our application to run, it is time to actually run it.
+First, we need to create an instance of our ApplicationState or app, to hold all of the
+program’s state, and then we will call our function which handles the event and draw loop.
...
+ let backend = CrosstermBackend::new(stderr);
+ let mut terminal = Terminal::new(backend)?;
+
+ // create app and run it
+ let mut app = App::new();
+ let res = run_app(&mut terminal, &mut app);
+
+ ...Application post-run steps
+Since our ratatui application has changed the state of the user’s terminal with our
+pre-run boilerplate, we need to undo what have did, and put the
+terminal back to the way we found it.
Most of these functions will simply be the inverse of what we have done above.
+use crossterm::event::DisableMouseCapture;
+use crossterm::terminal::{disable_raw_mode, LeaveAlternateScreen}; ...
+ // restore terminal
+ disable_raw_mode()?;
+ execute!(
+ terminal.backend_mut(),
+ LeaveAlternateScreen,
+ DisableMouseCapture
+ )?;
+ terminal.show_cursor()?;
+ ...When an application exits without running this closing boilerplate, the terminal will act very +strange, and the user will usually have to end the terminal session and start a new one. Thus it is +important that we handle our error in such a way that we can call this last piece.
+ ...
+ if let Ok(do_print) = res {
+ if do_print {
+ app.print_json()?;
+ }
+ } else if let Err(err) = res {
+ println!("{err:?}");
+ }
+
+ Ok(())
+}The if statement at the end of boilerplate checks if the run_app function errored. If run_app
+returned an Ok state. If it returned an Ok state, we need to check if we should print the json.
If we don’t call our print function before we call execute!(LeaveAlternateScreen), our prints will
+be rendered on an old screen and lost when we leave the alternate screen. (For more information on
+how this works, read the
+Crossterm documentation)
So, altogether, our finished function should looks like this:
+fn main() -> Result<(), Box<dyn Error>> {
+ // setup terminal
+ enable_raw_mode()?;
+ let mut stderr = io::stderr(); // This is a special case. Normally using stdout is fine
+ execute!(stderr, EnterAlternateScreen, EnableMouseCapture)?;
+ let backend = CrosstermBackend::new(stderr);
+ let mut terminal = Terminal::new(backend)?;
+
+ // create app and run it
+ let mut app = App::new();
+ let res = run_app(&mut terminal, &mut app);
+
+
+ // restore terminal
+ disable_raw_mode()?;
+ execute!(
+ terminal.backend_mut(),
+ LeaveAlternateScreen,
+ DisableMouseCapture
+ )?;
+ terminal.show_cursor()?;
+
+ if let Ok(do_print) = res {
+ if do_print {
+ app.print_json()?;
+ }
+ } else if let Err(err) = res {
+ println!("{err:?}");
+ }
+
+ Ok(())
+}run_app
+In this function, we will start to do the actual logic.
+Method signature
+Let’s start with the method signature:
+fn run_app<B: Backend>(terminal: &mut Terminal<B>, app: &mut App) -> io::Result<bool> {
+...You’ll notice that we make this function generic across the ratatui::backend::Backend. In previous
+sections we hardcoded the CrosstermBackend. This trait approach allows us to make our code
+backend agnostic.
This method accepts an object of type Terminal which implements the ratatui::backend::Backend
+trait. This trait includes the three (four counting the TestBackend) officially supported backends
+included in ratatui. It allows for 3rd party backends to be implemented.
run_app also requires a mutable borrow to an application state object, as defined in this project.
Finally, the run_app returns an io::Result<bool> that indicates if there was an io error with
+the Err state, and an Ok(true) or Ok(false) that indicates if the program should print out the
+finished json.
UI Loop
+Because ratatui requires us to implement our own event/ui loop, we will simply use the following
+code to update our main loop.
...
+ loop {
+ terminal.draw(|f| ui(f, app))?;
+ ...Let’s unpack that draw call really quick.
-
+
terminalis theTerminal<Backend>that we take as an argument,
+drawis theratatuicommand to draw aFrameto the terminal1.
+|f| ui(f, &app)tellsdrawthat we want to takef: <Frame>and pass it to our functionui, +anduiwill draw to thatFrame.
+
1
+
+Technically this is the command to the Terminal<Backend>, but that only matters on the TestBackend.
Notice that we also pass an immutable borrow of our application state to the ui function. This will
+be important later.
Event handling
+Now that we have started our app , and have set up the UI rendering, we will implement the event +handling.
+Polling
+Because we are using crossterm, we can simply poll for keyboard events with
if let Event::Key(key) = event::read()? {
+ dbg!(key.code)
+}and then match the results.
+Alternatively, we can set up a thread to run in the background to poll and send Events (as we did
+in the “counter” tutorial). Let’s keep things simple here for the sake of illustration.
Note that the process for polling events will vary on the backend you are utilizing, and you will +need to refer to the documentation of that backend for more information.
+Main Screen
+We will start with the keybinds and event handling for the CurrentScreen::Main.
...
+ if let Event::Key(key) = event::read()? {
+ match app.current_screen {
+ CurrentScreen::Main => match key.code {
+ KeyCode::Char('e') => {
+ app.current_screen = CurrentScreen::Editing;
+ app.currently_editing = Some(CurrentlyEditing::Key);
+ }
+ KeyCode::Char('q') => {
+ app.current_screen = CurrentScreen::Exiting;
+ }
+ _ => {}
+ },
+ ...After matching to the Main enum variant, we match the event. When the user is in the main screen,
+there are only two keybinds, and the rest are ignored.
In this case, KeyCode::Char('e') changes the current screen to CurrentScreen::Editing and sets
+the CurrentlyEditing to a Some and notes that the user should be editing the Key value field,
+as opposed to the Value field.
KeyCode::Char('q') is straightforward, as it simply switches the application to the Exiting
+screen, and allows the ui and future event handling runs to do the rest.
Exiting
+The next handler we will prepare, will handle events while the application is on the
+CurrentScreen::Exiting. The job of this screen is to ask if the user wants to exit without
+outputting the json. It is simply a y/n question, so that is all we listen for. We also add an
+alternate exit key with q. If the user chooses to output the json, we return an Ok(true) that
+indicates that our main function should call app.print_json() to perform the serialization and
+printing for us after resetting the terminal to normal
...
+ CurrentScreen::Exiting => match key.code {
+ KeyCode::Char('y') => {
+ return Ok(true);
+ }
+ KeyCode::Char('n') | KeyCode::Char('q') => {
+ return Ok(false);
+ }
+ _ => {}
+ },
+ ...Editing
+Our final handler will be a bit more involved, as we will be changing the state of internal +variables.
+We would like the Enter key to serve two purposes. When the user is editing the Key, we want the
+enter key to switch the focus to editing the Value. However, if the Value is what is being
+currently edited, Enter will save the key-value pair, and return to the Main screen.
...
+ CurrentScreen::Editing if key.kind == KeyEventKind::Press => {
+ match key.code {
+ KeyCode::Enter => {
+ if let Some(editing) = &app.currently_editing {
+ match editing {
+ CurrentlyEditing::Key => {
+ app.currently_editing = Some(CurrentlyEditing::Value);
+ }
+ CurrentlyEditing::Value => {
+ app.save_key_value();
+ app.current_screen = CurrentScreen::Main;
+ }
+ }
+ }
+ }
+ ...When Backspace is pressed, we need to first determine if the user is editing a Key or a Value,
+then pop() the endings of those strings accordingly.
...
+ KeyCode::Backspace => {
+ if let Some(editing) = &app.currently_editing {
+ match editing {
+ CurrentlyEditing::Key => {
+ app.key_input.pop();
+ }
+ CurrentlyEditing::Value => {
+ app.value_input.pop();
+ }
+ }
+ }
+ }
+ ...When Escape is pressed, we want to quit editing.
...
+ KeyCode::Esc => {
+ app.current_screen = CurrentScreen::Main;
+ app.currently_editing = None;
+ }
+ ...When Tab is pressed, we want the currently editing selection to switch.
...
+ KeyCode::Tab => {
+ app.toggle_editing();
+ }
+ ...And finally, if the user types a valid character, we want to capture that, and add it to the string +that is the final key or value.
+ ...
+ KeyCode::Char(value) => {
+ if let Some(editing) = &app.currently_editing {
+ match editing {
+ CurrentlyEditing::Key => {
+ app.key_input.push(value);
+ }
+ CurrentlyEditing::Value => {
+ app.value_input.push(value);
+ }
+ }
+ }
+ }
+ ...Altogether, the event loop should look like this:
+ ...
+ if let Event::Key(key) = event::read()? {
+ match app.current_screen {
+ CurrentScreen::Main => match key.code {
+ KeyCode::Char('e') => {
+ app.current_screen = CurrentScreen::Editing;
+ app.currently_editing = Some(CurrentlyEditing::Key);
+ }
+ KeyCode::Char('q') => {
+ app.current_screen = CurrentScreen::Exiting;
+ }
+ _ => {}
+ },
+ CurrentScreen::Exiting => match key.code {
+ KeyCode::Char('y') => {
+ return Ok(true);
+ }
+ KeyCode::Char('n') | KeyCode::Char('q') => {
+ return Ok(false);
+ }
+ _ => {}
+ },
+ CurrentScreen::Editing if key.kind == KeyEventKind::Press => {
+ match key.code {
+ KeyCode::Enter => {
+ if let Some(editing) = &app.currently_editing {
+ match editing {
+ CurrentlyEditing::Key => {
+ app.currently_editing = Some(CurrentlyEditing::Value);
+ }
+ CurrentlyEditing::Value => {
+ app.save_key_value();
+ app.current_screen = CurrentScreen::Main;
+ }
+ }
+ }
+ }
+ KeyCode::Backspace => {
+ if let Some(editing) = &app.currently_editing {
+ match editing {
+ CurrentlyEditing::Key => {
+ app.key_input.pop();
+ }
+ CurrentlyEditing::Value => {
+ app.value_input.pop();
+ }
+ }
+ }
+ }
+ KeyCode::Esc => {
+ app.current_screen = CurrentScreen::Main;
+ app.currently_editing = None;
+ }
+ KeyCode::Tab => {
+ app.toggle_editing();
+ }
+ KeyCode::Char(value) => {
+ if let Some(editing) = &app.currently_editing {
+ match editing {
+ CurrentlyEditing::Key => {
+ app.key_input.push(value);
+ }
+ CurrentlyEditing::Value => {
+ app.value_input.push(value);
+ }
+ }
+ }
+ }
+ _ => {}
+ }
+ }
+ _ => {}
+ }
+ }
+ ...UI.rs
+Finally we come to the last piece of the puzzle, and also the hardest part when you are just
+starting out creating ratatui TUIs — the UI. We created a very simple UI with just one widget in
+the previous tutorial, but here we’ll explore some more sophisticated layouts.
+
+
+
+
+If you have created a UI before, you should know that the UI code can take up much more space than
+you think it should, and this is not exception. We will only briefly cover all the functionality
+available in ratatui and how the core of ratatui design works.
There will be links to more resources where they are covered in depth in the following sections.
+Layout basics
+Our first step is to grasp how we render widgets onto the terminal.
+In essence: Widgets are constructed and then drawn onto the screen using a Frame, which is placed
+within a specified Rect.
Now, envision a scenario where we wish to divide our renderable Rect area into three distinct
+areas. For this, we can use the Layout functionality in ratatui.
let chunks = Layout::default()
+ .direction(Direction::Vertical)
+ .constraints(
+ [
+ Constraint::Length(3),
+ Constraint::Min(1),
+ Constraint::Length(3),
+ ]
+ .as_ref(),
+ )
+ .split(f.size());This can be likened to partitioning a large rectangle into smaller sections.
+
+
+
+
+
+For a comprehensive understanding of layout and constraints, refer to +Layout Constraints Basics +and Layout Constraints Intermediate sections.
+In the example above, you can read the instructions aloud like this:
+-
+
- Take the area
f.size()(which is a rectangle), and cut it into three vertical pieces (making +horizontal cuts).
+ - The first section will be 3 lines tall +
- The second section should never be smaller than one line tall, but can expand if needed. +
- The final section should also be 3 lines tall +
For those visual learners, I have the following graphic:
+ +Now that we have that out of the way, let us create the TUI for our application.
+The function signature
+Our ui function needs two things to successfully create our UI elements. The Frame which contains
+the size of the terminal at render time (this is important, because it allows us to take resizeable
+terminals into account), and the application state.
pub fn ui<B: Backend>(f: &mut Frame<B>, app: &App) {Before we proceed, let’s implement a centered_rect helper function. This code is adapted from the
+popup example found in the
+official repo.
/// helper function to create a centered rect using up certain percentage of the available rect `r`
+fn centered_rect(percent_x: u16, percent_y: u16, r: Rect) -> Rect {
+ // Cut the given rectangle into three vertical pieces
+ let popup_layout = Layout::default()
+ .direction(Direction::Vertical)
+ .constraints(
+ [
+ Constraint::Percentage((100 - percent_y) / 2),
+ Constraint::Percentage(percent_y),
+ Constraint::Percentage((100 - percent_y) / 2),
+ ]
+ .as_ref(),
+ )
+ .split(r);
+
+ // Then cut the middle vertical piece into three width-wise pieces
+ Layout::default()
+ .direction(Direction::Horizontal)
+ .constraints(
+ [
+ Constraint::Percentage((100 - percent_x) / 2),
+ Constraint::Percentage(percent_x),
+ Constraint::Percentage((100 - percent_x) / 2),
+ ]
+ .as_ref(),
+ )
+ .split(popup_layout[1])[1] // Return the middle chunk
+}This will be useful for the later subsections.
+The Main screen
+Because we want the Main screen to be rendered behind the editing popup, we will draw it first,
+and then have additional logic about our popups
Our layout
+Now that we have our Frame, we can actually begin drawing widgets onto it. We will begin by
+creating out layout.
let chunks = Layout::default()
+ .direction(Direction::Vertical)
+ .constraints(
+ [
+ Constraint::Length(3),
+ Constraint::Min(1),
+ Constraint::Length(3),
+ ]
+ .as_ref(),
+ )
+ .split(f.size());The variable chunks now contains a length 3 array of Rect objects that contain the top left
+corner of their space, and their size. We will use these later, after we prepare our widgets.
The title
+The title is an important piece for any application. It helps the user understand what they can do
+and where they are. To create our title, we are going to use a Paragraph widget (which is used to
+display only text), and we are going to tell that Paragraph we want a border all around it by
+giving it a Block with borders enabled. (See How-To: Block and
+How-To: Paragraph for more information about Block and
+Paragraph).
let title_block = Block::default()
+ .borders(Borders::ALL)
+ .style(Style::default());
+
+ let title = Paragraph::new(Text::styled(
+ "Create New Json",
+ Style::default().fg(Color::Green),
+ ))
+ .block(title_block);
+
+ f.render_widget(title, chunks[0]);In this code, the first thing we do, is create a Block with all borders enabled, and the default
+style. Next, we created a paragraph widget with the text “Create New Json” styled green. (See
+How-To: Paragraphs for more information about creating
+paragraphs and How-To: Styling-Text for styling text) Finally,
+we call render_widget on our Frame, and give it the widget we want to render it, and the Rect
+representing where it needs to go and what size it should be. (this is the way all widgets are
+drawn)
The list of existing pairs
+We would also like the user to be able to see any key-value pairs that they have already entered.
+For this, we will be using another widget, the List. The list is what it sounds like - it creates
+a new line of text for each ListItem, and it supports passing in a state so you can implement
+selecting items on the list with little extra work. We will not be implementing selection, as we
+simply want the user to be able to see what they have already entered.
let mut list_items = Vec::<ListItem>::new();
+
+ for key in app.pairs.keys() {
+ list_items.push(ListItem::new(Line::from(Span::styled(
+ format!("{: <25} : {}", key, app.pairs.get(key).unwrap()),
+ Style::default().fg(Color::Yellow),
+ ))));
+ }
+
+ let list = List::new(list_items);
+
+ f.render_widget(list, chunks[1]);For more information on Line, Span, and Style see +How-To: Displaying Text
+In this piece of the function, we create a vector of ListItems, and populate it with styled and
+formatted key-value pairs. Finally, we create the List widget, and render it.
The bottom navigational bar
+It can help new users of your application, to see hints about what keys they can press. For this, we
+are going to implement two bars, and another layout. These two bars will contain information on 1)
+The current screen (Main, Editing, and Exiting), and 2) what keybinds are available.
Here, we will create a Vec of Span which will be converted later into a single line by the
+Paragraph. (A Span is different from a Line, because a Span indicates a section of Text
+with a style applied, and doesn’t end with a newline)
let current_navigation_text = vec![
+ // The first half of the text
+ match app.current_screen {
+ CurrentScreen::Main => Span::styled("Normal Mode", Style::default().fg(Color::Green)),
+ CurrentScreen::Editing => {
+ Span::styled("Editing Mode", Style::default().fg(Color::Yellow))
+ }
+ CurrentScreen::Exiting => Span::styled("Exiting", Style::default().fg(Color::LightRed)),
+ }
+ .to_owned(),
+ // A white divider bar to separate the two sections
+ Span::styled(" | ", Style::default().fg(Color::White)),
+ // The final section of the text, with hints on what the user is editing
+ {
+ if let Some(editing) = &app.currently_editing {
+ match editing {
+ CurrentlyEditing::Key => {
+ Span::styled("Editing Json Key", Style::default().fg(Color::Green))
+ }
+ CurrentlyEditing::Value => {
+ Span::styled("Editing Json Value", Style::default().fg(Color::LightGreen))
+ }
+ }
+ } else {
+ Span::styled("Not Editing Anything", Style::default().fg(Color::DarkGray))
+ }
+ },
+ ];
+
+ let mode_footer = Paragraph::new(Line::from(current_navigation_text))
+ .block(Block::default().borders(Borders::ALL));Next, we are also going to make a hint in the navigation bar with available keys. This one does not +have several sections of text with different styles, and is thus less code.
+ let current_keys_hint = {
+ match app.current_screen {
+ CurrentScreen::Main => Span::styled(
+ "(q) to quit / (e) to make new pair",
+ Style::default().fg(Color::Red),
+ ),
+ CurrentScreen::Editing => Span::styled(
+ "(ESC) to cancel/(Tab) to switch boxes/enter to complete",
+ Style::default().fg(Color::Red),
+ ),
+ CurrentScreen::Exiting => Span::styled(
+ "(q) to quit / (e) to make new pair",
+ Style::default().fg(Color::Red),
+ ),
+ }
+ };
+
+ let key_notes_footer =
+ Paragraph::new(Line::from(current_keys_hint)).block(Block::default().borders(Borders::ALL));Finally, we are going to create our first nested layout. Because the Layout.split function
+requires a Rect, and not a Frame, we can pass one of our chunks from the previous layout as the
+space for the new layout. If you remember the bottom most section from the above graphic:
We will create a new layout in this space by passing it (chunks[2]) as the parameter for split.
let footer_chunks = Layout::default()
+ .direction(Direction::Horizontal)
+ .constraints([Constraint::Percentage(50), Constraint::Percentage(50)].as_ref())
+ .split(chunks[2]);This code is the visual equivalent of this:
+ +And now we can render our footer paragraphs in the appropriate spaces.
+ f.render_widget(mode_footer, footer_chunks[0]);
+ f.render_widget(key_notes_footer, footer_chunks[1]);The Editing Popup
+Now that the Main screen is rendered, we now need to check if the Editing popup needs to be
+rendered. Since the ratatui renderer simply writes over the cells within a Rect on a
+render_widget, we simply need to give render_widget an area on top of our Main screen to
+create the appearance of a popup.
Popup area and title
+The first thing we will do, is draw the Block that will contain the popup. We will give this
+Block a title to display as well to explain to the user what it is. (We will cover centered_rect
+below)
if let Some(editing) = &app.currently_editing {
+ let popup_block = Block::default()
+ .title("Enter a new key-value pair")
+ .borders(Borders::NONE)
+ .style(Style::default().bg(Color::DarkGray));
+
+ let area = centered_rect(60, 25, f.size());
+ f.render_widget(popup_block, area);Popup contents
+Now that we have where our popup is going to go, we can create the layout for the popup, and create +and draw the widgets inside of it.
+First, we will create split the Rect given to us by centered_rect, and create a layout from it.
+Note the use of margin(1), which gives a 1 space margin around any layout block, meaning our new
+blocks and widgets don’t overwrite anything from the first popup block.
let popup_chunks = Layout::default()
+ .direction(Direction::Horizontal)
+ .margin(1)
+ .constraints([Constraint::Percentage(50), Constraint::Percentage(50)])
+ .split(area);Now that we have the layout for where we want to display the keys and values, we will actually +create the blocks and paragraphs to show what the user has already entered.
+ let mut key_block = Block::default().title("Key").borders(Borders::ALL);
+ let mut value_block = Block::default().title("Value").borders(Borders::ALL);
+
+ let active_style = Style::default().bg(Color::LightYellow).fg(Color::Black);
+
+ match editing {
+ CurrentlyEditing::Key => key_block = key_block.style(active_style),
+ CurrentlyEditing::Value => value_block = value_block.style(active_style),
+ };
+
+ let key_text = Paragraph::new(app.key_input.clone()).block(key_block);
+ f.render_widget(key_text, popup_chunks[0]);
+
+ let value_text = Paragraph::new(app.value_input.clone()).block(value_block);
+ f.render_widget(value_text, popup_chunks[1]);Note that we are declaring the blocks as variables, and then adding extra styling to the block the
+user is currently editing. Then we create the Paragraph widgets, and assign the blocks with those
+variables. Also note how we used the popup_chunks layout instead of the popup_block layout to
+render these widgets into.
The Exit Popup
+We have a way for the user to view their already entered key-value pairs, and we have a way for the +user to enter new ones. The last screen we need to create, is the exit/confirmation screen.
+In this screen, we are asking the user if they want to output the key-value pairs they have entered
+in the stdout pipe, or close without outputting anything.
if let CurrentScreen::Exiting = app.current_screen {
+ f.render_widget(Clear, f.size()); //this clears the entire screen and anything already drawn
+ let popup_block = Block::default()
+ .title("Y/N")
+ .borders(Borders::NONE)
+ .style(Style::default().bg(Color::DarkGray));
+
+ let exit_text = Text::styled(
+ "Would you like to output the buffer as json? (y/n)",
+ Style::default().fg(Color::Red),
+ );
+ // the `trim: false` will stop the text from being cut off when over the edge of the block
+ let exit_paragraph = Paragraph::new(exit_text)
+ .block(popup_block)
+ .wrap(Wrap { trim: false });
+
+ let area = centered_rect(60, 25, f.size());
+ f.render_widget(exit_paragraph, area);
+ }The only thing in this part that we haven’t done before, is use the Clear widget. This is a
+special widget that does what the name suggests - it clears everything in the space it is rendered.
+In this case, it clears all of the menu that was prerendered behind it.
Closing Thoughts
+This tutorial should get you started with a basic understanding of the flow of a ratatui program.
+However, this is only one way to create a ratatui application. Because ratatui is relatively
+low level compared to other UI frameworks, almost any application model can be implemented. You can
+explore more of these in Concepts: Application Patterns and
+get some inspiration for what model will work best for your application.
Finished Files
+Here you can find the finished project used for the tutorial. You can test this application by +yourself, but running
+cargo run > test.json
+and double checking the output.
+Main.rs
+use std::{error::Error, io};
+
+use crossterm::{
+ event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode, KeyEventKind},
+ execute,
+ terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+};
+use ratatui::{
+ backend::{Backend, CrosstermBackend},
+ Terminal,
+};
+
+mod app;
+mod ui;
+use crate::{
+ app::{App, CurrentScreen, CurrentlyEditing},
+ ui::ui,
+};
+
+fn main() -> Result<(), Box<dyn Error>> {
+ // setup terminal
+ enable_raw_mode()?;
+ let mut stderr = io::stderr(); // This is a special case. Normally using stdout is fine
+ execute!(stderr, EnterAlternateScreen, EnableMouseCapture)?;
+ let backend = CrosstermBackend::new(stderr);
+ let mut terminal = Terminal::new(backend)?;
+
+ // create app and run it
+ let mut app = App::new();
+ let res = run_app(&mut terminal, &mut app);
+
+
+ // restore terminal
+ disable_raw_mode()?;
+ execute!(
+ terminal.backend_mut(),
+ LeaveAlternateScreen,
+ DisableMouseCapture
+ )?;
+ terminal.show_cursor()?;
+
+ if let Ok(do_print) = res {
+ if do_print {
+ app.print_json()?;
+ }
+ } else if let Err(err) = res {
+ println!("{err:?}");
+ }
+
+ Ok(())
+}
+
+fn run_app<B: Backend>(terminal: &mut Terminal<B>, app: &mut App) -> io::Result<bool> {
+ loop {
+ terminal.draw(|f| ui(f, app))?;
+
+ if let Event::Key(key) = event::read()? {
+ match app.current_screen {
+ CurrentScreen::Main => match key.code {
+ KeyCode::Char('e') => {
+ app.current_screen = CurrentScreen::Editing;
+ app.currently_editing = Some(CurrentlyEditing::Key);
+ }
+ KeyCode::Char('q') => {
+ app.current_screen = CurrentScreen::Exiting;
+ }
+ _ => {}
+ },
+ CurrentScreen::Exiting => match key.code {
+ KeyCode::Char('y') => {
+ return Ok(true);
+ }
+ KeyCode::Char('n') | KeyCode::Char('q') => {
+ return Ok(false);
+ }
+ _ => {}
+ },
+ CurrentScreen::Editing if key.kind == KeyEventKind::Press => {
+ match key.code {
+ KeyCode::Enter => {
+ if let Some(editing) = &app.currently_editing {
+ match editing {
+ CurrentlyEditing::Key => {
+ app.currently_editing = Some(CurrentlyEditing::Value);
+ }
+ CurrentlyEditing::Value => {
+ app.save_key_value();
+ app.current_screen = CurrentScreen::Main;
+ }
+ }
+ }
+ }
+ KeyCode::Backspace => {
+ if let Some(editing) = &app.currently_editing {
+ match editing {
+ CurrentlyEditing::Key => {
+ app.key_input.pop();
+ }
+ CurrentlyEditing::Value => {
+ app.value_input.pop();
+ }
+ }
+ }
+ }
+ KeyCode::Esc => {
+ app.current_screen = CurrentScreen::Main;
+ app.currently_editing = None;
+ }
+ KeyCode::Tab => {
+ app.toggle_editing();
+ }
+ KeyCode::Char(value) => {
+ if let Some(editing) = &app.currently_editing {
+ match editing {
+ CurrentlyEditing::Key => {
+ app.key_input.push(value);
+ }
+ CurrentlyEditing::Value => {
+ app.value_input.push(value);
+ }
+ }
+ }
+ }
+ _ => {}
+ }
+ }
+ _ => {}
+ }
+ }
+ }
+}
+App.rs
+use serde_json::Result;
+
+pub enum CurrentScreen {
+ Main,
+ Editing,
+ Exiting,
+}
+
+pub enum CurrentlyEditing {
+ Key,
+ Value,
+}
+
+pub struct App {
+ pub key_input: String, // the currently being edited json key.
+ pub value_input: String, // the currently being edited json value.
+ pub pairs: HashMap<String, String>, // The representation of our key and value pairs with serde Serialize support
+ pub current_screen: CurrentScreen, // the current screen the user is looking at, and will later determine what is rendered.
+ pub currently_editing: Option<CurrentlyEditing>, // the optional state containing which of the key or value pair the user is editing. It is an option, because when the user is not directly editing a key-value pair, this will be set to `None`.
+}
+
+impl App {
+ pub fn new() -> App {
+ App {
+ key_input: String::new(),
+ value_input: String::new(),
+ pairs: HashMap::new(),
+ current_screen: CurrentScreen::Main,
+ currently_editing: None,
+ }
+ }
+
+ pub fn save_key_value(&mut self) {
+ self.pairs
+ .insert(self.key_input.clone(), self.value_input.clone());
+
+ self.key_input = String::new();
+ self.value_input = String::new();
+ self.currently_editing = None;
+ }
+
+ pub fn toggle_editing(&mut self) {
+ if let Some(edit_mode) = &self.currently_editing {
+ match edit_mode {
+ CurrentlyEditing::Key => self.currently_editing = Some(CurrentlyEditing::Value),
+ CurrentlyEditing::Value => self.currently_editing = Some(CurrentlyEditing::Key),
+ };
+ } else {
+ self.currently_editing = Some(CurrentlyEditing::Key);
+ }
+ }
+
+ pub fn print_json(&self) -> Result<()> {
+ let output = serde_json::to_string(&self.pairs)?;
+ println!("{}", output);
+ Ok(())
+ }
+}UI.rs
+use ratatui::{
+ backend::Backend,
+ layout::{Constraint, Direction, Layout, Rect},
+ style::{Color, Style},
+ text::{Line, Span, Text},
+ widgets::{Block, Borders, Clear, List, ListItem, Paragraph, Wrap},
+ Frame,
+};
+
+use crate::app::{App, CurrentScreen, CurrentlyEditing};
+
+pub fn ui<B: Backend>(f: &mut Frame<B>, app: &App) {
+ // Create the layout sections.
+ let chunks = Layout::default()
+ .direction(Direction::Vertical)
+ .constraints(
+ [
+ Constraint::Length(3),
+ Constraint::Min(1),
+ Constraint::Length(3),
+ ]
+ .as_ref(),
+ )
+ .split(f.size());
+
+ let title_block = Block::default()
+ .borders(Borders::ALL)
+ .style(Style::default());
+
+ let title = Paragraph::new(Text::styled(
+ "Create New Json",
+ Style::default().fg(Color::Green),
+ ))
+ .block(title_block);
+
+ f.render_widget(title, chunks[0]);
+ let mut list_items = Vec::<ListItem>::new();
+
+ for key in app.pairs.keys() {
+ list_items.push(ListItem::new(Line::from(Span::styled(
+ format!("{: <25} : {}", key, app.pairs.get(key).unwrap()),
+ Style::default().fg(Color::Yellow),
+ ))));
+ }
+
+ let list = List::new(list_items);
+
+ f.render_widget(list, chunks[1]);
+ let current_navigation_text = vec![
+ // The first half of the text
+ match app.current_screen {
+ CurrentScreen::Main => Span::styled("Normal Mode", Style::default().fg(Color::Green)),
+ CurrentScreen::Editing => {
+ Span::styled("Editing Mode", Style::default().fg(Color::Yellow))
+ }
+ CurrentScreen::Exiting => Span::styled("Exiting", Style::default().fg(Color::LightRed)),
+ }
+ .to_owned(),
+ // A white divider bar to separate the two sections
+ Span::styled(" | ", Style::default().fg(Color::White)),
+ // The final section of the text, with hints on what the user is editing
+ {
+ if let Some(editing) = &app.currently_editing {
+ match editing {
+ CurrentlyEditing::Key => {
+ Span::styled("Editing Json Key", Style::default().fg(Color::Green))
+ }
+ CurrentlyEditing::Value => {
+ Span::styled("Editing Json Value", Style::default().fg(Color::LightGreen))
+ }
+ }
+ } else {
+ Span::styled("Not Editing Anything", Style::default().fg(Color::DarkGray))
+ }
+ },
+ ];
+
+ let mode_footer = Paragraph::new(Line::from(current_navigation_text))
+ .block(Block::default().borders(Borders::ALL));
+
+ let current_keys_hint = {
+ match app.current_screen {
+ CurrentScreen::Main => Span::styled(
+ "(q) to quit / (e) to make new pair",
+ Style::default().fg(Color::Red),
+ ),
+ CurrentScreen::Editing => Span::styled(
+ "(ESC) to cancel/(Tab) to switch boxes/enter to complete",
+ Style::default().fg(Color::Red),
+ ),
+ CurrentScreen::Exiting => Span::styled(
+ "(q) to quit / (e) to make new pair",
+ Style::default().fg(Color::Red),
+ ),
+ }
+ };
+
+ let key_notes_footer =
+ Paragraph::new(Line::from(current_keys_hint)).block(Block::default().borders(Borders::ALL));
+
+ let footer_chunks = Layout::default()
+ .direction(Direction::Horizontal)
+ .constraints([Constraint::Percentage(50), Constraint::Percentage(50)].as_ref())
+ .split(chunks[2]);
+
+ f.render_widget(mode_footer, footer_chunks[0]);
+ f.render_widget(key_notes_footer, footer_chunks[1]);
+
+ if let Some(editing) = &app.currently_editing {
+ let popup_block = Block::default()
+ .title("Enter a new key-value pair")
+ .borders(Borders::NONE)
+ .style(Style::default().bg(Color::DarkGray));
+
+ let area = centered_rect(60, 25, f.size());
+ f.render_widget(popup_block, area);
+
+ let popup_chunks = Layout::default()
+ .direction(Direction::Horizontal)
+ .margin(1)
+ .constraints([Constraint::Percentage(50), Constraint::Percentage(50)])
+ .split(area);
+
+ let mut key_block = Block::default().title("Key").borders(Borders::ALL);
+ let mut value_block = Block::default().title("Value").borders(Borders::ALL);
+
+ let active_style = Style::default().bg(Color::LightYellow).fg(Color::Black);
+
+ match editing {
+ CurrentlyEditing::Key => key_block = key_block.style(active_style),
+ CurrentlyEditing::Value => value_block = value_block.style(active_style),
+ };
+
+ let key_text = Paragraph::new(app.key_input.clone()).block(key_block);
+ f.render_widget(key_text, popup_chunks[0]);
+
+ let value_text = Paragraph::new(app.value_input.clone()).block(value_block);
+ f.render_widget(value_text, popup_chunks[1]);
+ }
+
+ if let CurrentScreen::Exiting = app.current_screen {
+ f.render_widget(Clear, f.size()); //this clears the entire screen and anything already drawn
+ let popup_block = Block::default()
+ .title("Y/N")
+ .borders(Borders::NONE)
+ .style(Style::default().bg(Color::DarkGray));
+
+ let exit_text = Text::styled(
+ "Would you like to output the buffer as json? (y/n)",
+ Style::default().fg(Color::Red),
+ );
+ // the `trim: false` will stop the text from being cut off when over the edge of the block
+ let exit_paragraph = Paragraph::new(exit_text)
+ .block(popup_block)
+ .wrap(Wrap { trim: false });
+
+ let area = centered_rect(60, 25, f.size());
+ f.render_widget(exit_paragraph, area);
+ }
+}
+
+/// helper function to create a centered rect using up certain percentage of the available rect `r`
+fn centered_rect(percent_x: u16, percent_y: u16, r: Rect) -> Rect {
+ // Cut the given rectangle into three vertical pieces
+ let popup_layout = Layout::default()
+ .direction(Direction::Vertical)
+ .constraints(
+ [
+ Constraint::Percentage((100 - percent_y) / 2),
+ Constraint::Percentage(percent_y),
+ Constraint::Percentage((100 - percent_y) / 2),
+ ]
+ .as_ref(),
+ )
+ .split(r);
+
+ // Then cut the middle vertical piece into three width-wise pieces
+ Layout::default()
+ .direction(Direction::Horizontal)
+ .constraints(
+ [
+ Constraint::Percentage((100 - percent_x) / 2),
+ Constraint::Percentage(percent_x),
+ Constraint::Percentage((100 - percent_x) / 2),
+ ]
+ .as_ref(),
+ )
+ .split(popup_layout[1])[1] // Return the middle chunk
+}
+Counter App
+In the previous counter app, we had a purely sequential blocking application. There are times when +you may be interested in running IO operations or compute asynchronously.
+For this tutorial, we will build a single file version of an async TUI using +tokio.
+Installation
+Here’s an example of the Cargo.toml file required for this tutorial:
[package]
+name = "ratatui-counter-async-app"
+version = "0.1.0"
+edition = "2021"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+anyhow = "1.0.75"
+crossterm = { version = "0.27.0", features = ["event-stream"] }
+ratatui = "0.23.0"
+tokio = { version = "1.32.0", features = ["full"] }
+Counter App with Actions
+Let’s take the single file multiple function example from the counter app from earlier.
+This was what the flow chart looked like.
+graph TD + MainRun[Main: Run]; + CheckEvent[Main: Poll KeyPress]; + UpdateApp[Main: Update App]; + ShouldQuit[Main: Check should_quit?]; + BreakLoop[Main: Break Loop]; + MainStart[Main: Start]; + MainEnd[Main: End]; + MainStart --> MainRun; + MainRun --> CheckEvent; + CheckEvent -->|No KeyPress| Draw; + CheckEvent --> |KeyPress Received| UpdateApp; + Draw --> ShouldQuit; + UpdateApp --> Draw; + ShouldQuit -->|Yes| BreakLoop; + BreakLoop --> MainEnd; + ShouldQuit -->|No| CheckEvent; ++
Now that we know what enums are, we are going to extend the counter application to include
+“Action“s. One of the first steps to building a async applications is to use the Command,
+Action, or Message pattern.
+
+
+
+
+The Command pattern is the concept of “reified method calls”.
+You can learn a lot more about this pattern from the excellent http://gameprogrammingpatterns.com.
You can learn more about this concept in +The Elm Architecture section of the +documentation.
+The key idea is that we have an Action enum that tracks all the actions that can be carried out by
+the App.
use anyhow::Result;
+use crossterm::{
+ event::{self, Event::Key, KeyCode::Char},
+ execute,
+ terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+};
+use ratatui::{
+ prelude::{CrosstermBackend, Terminal},
+ widgets::Paragraph,
+};
+
+pub type Frame<'a> = ratatui::Frame<'a, CrosstermBackend<std::io::Stderr>>;
+
+fn startup() -> Result<()> {
+ enable_raw_mode()?;
+ execute!(std::io::stderr(), EnterAlternateScreen)?;
+ Ok(())
+}
+
+fn shutdown() -> Result<()> {
+ execute!(std::io::stderr(), LeaveAlternateScreen)?;
+ disable_raw_mode()?;
+ Ok(())
+}
+
+// App state
+struct App {
+ counter: i64,
+ should_quit: bool,
+}
+
+// App actions
+pub enum Action {
+ Tick,
+ Increment,
+ Decrement,
+ Quit,
+ None,
+}
+
+// App ui render function
+fn ui(f: &mut Frame<'_>, app: &App) {
+ f.render_widget(Paragraph::new(format!("Counter: {}", app.counter)), f.size());
+}
+
+fn get_action(_app: &App) -> Action {
+ let tick_rate = std::time::Duration::from_millis(250);
+ if event::poll(tick_rate).unwrap() {
+ if let Key(key) = event::read().unwrap() {
+ match key.code {
+ Char('j') => Action::Increment,
+ Char('k') => Action::Decrement,
+ Char('q') => Action::Quit,
+ _ => Action::None,
+ }
+ } else {
+ Action::None
+ }
+ } else {
+ Action::None
+ }
+}
+
+fn update(app: &mut App, action: Action) {
+ match action {
+ Action::Quit => app.should_quit = true,
+ Action::Increment => app.counter += 1,
+ Action::Decrement => app.counter -= 1,
+ Action::Tick => {},
+ _ => {},
+ };
+}
+
+fn run() -> Result<()> {
+ // ratatui terminal
+ let mut t = Terminal::new(CrosstermBackend::new(std::io::stderr()))?;
+
+ // application state
+ let mut app = App { counter: 0, should_quit: false };
+
+ loop {
+ let action = get_action(&mut app);
+
+ // application update
+ update(&mut app, action);
+
+ // application render
+ t.draw(|f| {
+ ui(f, &app);
+ })?;
+
+ // application exit
+ if app.should_quit {
+ break;
+ }
+ }
+
+ Ok(())
+}
+
+fn main() -> Result<()> {
+ // setup terminal
+ startup()?;
+
+ let result = run();
+
+ // teardown terminal before unwrapping Result of app run
+ shutdown()?;
+
+ result?;
+
+ Ok(())
+}graph TD + MainRun[Main: Run]; + CheckEvent[Main: Poll KeyPress]; + UpdateApp[Main: Update App with Action]; + KeyPressToAction[Main: Convert KeyPress to Action]; + ShouldQuit[Main: Check should_quit?]; + BreakLoop[Main: Break Loop]; + MainStart[Main: Start]; + MainEnd[Main: End]; + MainStart --> MainRun; + MainRun --> CheckEvent; + CheckEvent -->|No KeyPress| Draw; + CheckEvent --> |KeyPress Received| KeyPressToAction; + KeyPressToAction --> |Action| UpdateApp; + UpdateApp --> Draw; + Draw --> ShouldQuit; + ShouldQuit -->|Yes| BreakLoop; + BreakLoop --> MainEnd; + ShouldQuit -->|No| CheckEvent; ++
This may seem like a lot more boilerplate to achieve the same thing. However, Action enums have a
+few advantages.
Firstly, they can be mapped from keypresses programmatically. For example, you can define a
+configuration file that reads which keys are mapped to which Action like so:
[keymap]
+"q" = "Quit"
+"j" = "Increment"
+"k" = "Decrement"
+Then you can add a new key configuration like so:
+struct App {
+ counter: i64,
+ should_quit: bool,
+ // new field
+ keyconfig: HashMap<KeyCode, Action>
+}If you populate keyconfig with the contents of a user provided toml file, then you can figure
+out which action to take by updating the get_action() function:
fn get_action(app: &App) -> Action {
+ let tick_rate = std::time::Duration::from_millis(250);
+ if event::poll(tick_rate).unwrap() {
+ if let Key(key) = event::read().unwrap() {
+ app.keyconfig.get(key.code).unwrap_or(Action::None)
+ } else {
+ Action::None
+ }
+ } else {
+ Action::None
+ }
+}The other advantage of using an Action enum is that you can tell your application what it should
+do next by sending a message over a channel. We will discuss this approach in the next section.
Sync Increment & Decrement
+In order to set up an async application, it is important to make the generation of Actions
+“asynchronous”.
We can do this by spawning a tokio task like so:
+fn start_event_handler(app: &App, tx: mpsc::UnboundedSender<Action>) -> tokio::task::JoinHandle<()> {
+ let tick_rate = std::time::Duration::from_millis(250);
+ tokio::spawn(async move {
+ loop {
+ let action = if crossterm::event::poll(tick_rate).unwrap() {
+ if let crossterm::event::Event::Key(key) = crossterm::event::read().unwrap() {
+ match key.code {
+ crossterm::event::KeyCode::Char('j') => Action::Increment,
+ crossterm::event::KeyCode::Char('k') => Action::Decrement,
+ crossterm::event::KeyCode::Char('q') => Action::Quit,
+ _ => Action::None,
+ }
+ } else {
+ Action::None
+ }
+ } else {
+ Action::None
+ };
+ if let Err(_) = tx.send(action) {
+ break;
+ }
+ }
+ })
+}Here’s the architecture of the application when using a separate tokio task to manage the
+generation of Action events.
graph TD + MainRun[Main: Run]; + CheckAction[Main: Check action_rx]; + UpdateTicker[Main: Update Ticker]; + UpdateApp[Main: Update App with Action]; + ShouldQuit[Main: Check should_quit?]; + BreakLoop[Main: Break Loop]; + MainStart[Main: Start]; + MainEnd[Main: End]; + MainStart --> MainRun; + MainRun --> CheckAction; + CheckAction -->|No Action| UpdateTicker; + UpdateTicker --> ShouldQuit; + CheckAction -->|Action Received| UpdateApp; + UpdateApp --> ShouldQuit; + ShouldQuit -->|Yes| BreakLoop; + BreakLoop --> MainEnd; + ShouldQuit -->|No| CheckAction; + EventStart[Event: start_event_handler]; + PollEvent[Event: Poll]; + ProcessKeyPress[Event: Process Key Press]; + SendAction[Event: Send Action]; + ContinueLoop[Event: Continue Loop]; + EventStart --> PollEvent; + PollEvent -->|Event Detected| ProcessKeyPress; + ProcessKeyPress --> SendAction; + SendAction --> ContinueLoop; + ContinueLoop --> PollEvent; + PollEvent -->|No Event| ContinueLoop; + SendAction -.-> CheckAction; ++
Here’s the full code for your reference:
+use std::time::Duration;
+
+use anyhow::Result;
+use ratatui::{prelude::*, widgets::*};
+use tokio::sync::mpsc;
+
+pub fn initialize_panic_handler() {
+ let original_hook = std::panic::take_hook();
+ std::panic::set_hook(Box::new(move |panic_info| {
+ shutdown().unwrap();
+ original_hook(panic_info);
+ }));
+}
+
+pub type Frame<'a> = ratatui::Frame<'a, CrosstermBackend<std::io::Stderr>>;
+
+fn startup() -> Result<()> {
+ crossterm::terminal::enable_raw_mode()?;
+ crossterm::execute!(std::io::stderr(), crossterm::terminal::EnterAlternateScreen)?;
+ Ok(())
+}
+
+fn shutdown() -> Result<()> {
+ crossterm::execute!(std::io::stderr(), crossterm::terminal::LeaveAlternateScreen)?;
+ crossterm::terminal::disable_raw_mode()?;
+ Ok(())
+}
+
+struct App {
+ action_tx: mpsc::UnboundedSender<Action>,
+ counter: i64,
+ should_quit: bool,
+ ticker: i64,
+}
+
+fn ui(f: &mut Frame<'_>, app: &mut App) {
+ let area = f.size();
+ f.render_widget(
+ Paragraph::new(format!(
+ "Press j or k to increment or decrement.\n\nCounter: {}\n\nTicker: {}",
+ app.counter, app.ticker
+ ))
+ .block(
+ Block::default()
+ .title("ratatui async counter app")
+ .title_alignment(Alignment::Center)
+ .borders(Borders::ALL)
+ .border_type(BorderType::Rounded),
+ )
+ .style(Style::default().fg(Color::Cyan))
+ .alignment(Alignment::Center),
+ area,
+ );
+}
+
+#[derive(PartialEq)]
+enum Action {
+ Increment,
+ Decrement,
+ Quit,
+ None,
+}
+
+fn update(app: &mut App, msg: Action) -> Action {
+ match msg {
+ Action::Increment => {
+ app.counter += 1;
+ },
+ Action::Decrement => {
+ app.counter -= 1;
+ },
+ Action::Quit => app.should_quit = true, // You can handle cleanup and exit here
+ _ => {},
+ };
+ Action::None
+}
+
+fn start_event_handler(app: &App, tx: mpsc::UnboundedSender<Action>) -> tokio::task::JoinHandle<()> {
+ let tick_rate = std::time::Duration::from_millis(250);
+ tokio::spawn(async move {
+ loop {
+ let action = if crossterm::event::poll(tick_rate).unwrap() {
+ if let crossterm::event::Event::Key(key) = crossterm::event::read().unwrap() {
+ match key.code {
+ crossterm::event::KeyCode::Char('j') => Action::Increment,
+ crossterm::event::KeyCode::Char('k') => Action::Decrement,
+ crossterm::event::KeyCode::Char('q') => Action::Quit,
+ _ => Action::None,
+ }
+ } else {
+ Action::None
+ }
+ } else {
+ Action::None
+ };
+ if let Err(_) = tx.send(action) {
+ break;
+ }
+ }
+ })
+}
+
+async fn run() -> Result<()> {
+ let mut t = Terminal::new(CrosstermBackend::new(std::io::stderr()))?;
+
+ let (action_tx, mut action_rx) = mpsc::unbounded_channel();
+
+ let mut app = App { counter: 0, should_quit: false, action_tx, ticker: 0 };
+
+ let task = start_event_handler(&app, app.action_tx.clone());
+
+ loop {
+ t.draw(|f| {
+ ui(f, &mut app);
+ })?;
+
+ if let Some(action) = action_rx.recv().await {
+ update(&mut app, action);
+ }
+
+ if app.should_quit {
+ break;
+ }
+ app.ticker += 1;
+ }
+
+ task.abort();
+
+ Ok(())
+}
+
+#[tokio::main]
+async fn main() -> Result<()> {
+ initialize_panic_handler();
+ startup()?;
+ run().await?;
+ shutdown()?;
+ Ok(())
+}Async Increment & Decrement
+Finally we can schedule increments and decrements using tokio::spawn.
Here’s the code for your reference:
+use std::time::Duration;
+
+use anyhow::Result;
+use ratatui::{prelude::*, widgets::*};
+use tokio::sync::mpsc;
+
+pub fn initialize_panic_handler() {
+ let original_hook = std::panic::take_hook();
+ std::panic::set_hook(Box::new(move |panic_info| {
+ shutdown().unwrap();
+ original_hook(panic_info);
+ }));
+}
+
+pub type Frame<'a> = ratatui::Frame<'a, CrosstermBackend<std::io::Stderr>>;
+
+fn startup() -> Result<()> {
+ crossterm::terminal::enable_raw_mode()?;
+ crossterm::execute!(std::io::stderr(), crossterm::terminal::EnterAlternateScreen)?;
+ Ok(())
+}
+
+fn shutdown() -> Result<()> {
+ crossterm::execute!(std::io::stderr(), crossterm::terminal::LeaveAlternateScreen)?;
+ crossterm::terminal::disable_raw_mode()?;
+ Ok(())
+}
+
+struct App {
+ action_tx: mpsc::UnboundedSender<Action>,
+ counter: i64,
+ should_quit: bool,
+ ticker: i64,
+}
+
+fn ui(f: &mut Frame<'_>, app: &mut App) {
+ let area = f.size();
+ f.render_widget(
+ Paragraph::new(format!(
+ "Press j or k to increment or decrement.\n\nCounter: {}\n\nTicker: {}",
+ app.counter, app.ticker
+ ))
+ .block(
+ Block::default()
+ .title("ratatui async counter app")
+ .title_alignment(Alignment::Center)
+ .borders(Borders::ALL)
+ .border_type(BorderType::Rounded),
+ )
+ .style(Style::default().fg(Color::Cyan))
+ .alignment(Alignment::Center),
+ area,
+ );
+}
+
+#[derive(PartialEq)]
+enum Action {
+ ScheduleIncrement,
+ ScheduleDecrement,
+ Increment,
+ Decrement,
+ Quit,
+ None,
+}
+
+fn update(app: &mut App, msg: Action) -> Action {
+ match msg {
+ Action::Increment => {
+ app.counter += 1;
+ },
+ Action::Decrement => {
+ app.counter -= 1;
+ },
+ Action::ScheduleIncrement => {
+ let tx = app.action_tx.clone();
+ tokio::spawn(async move {
+ tokio::time::sleep(Duration::from_secs(5)).await;
+ tx.send(Action::Increment).unwrap();
+ });
+ },
+ Action::ScheduleDecrement => {
+ let tx = app.action_tx.clone();
+ tokio::spawn(async move {
+ tokio::time::sleep(Duration::from_secs(5)).await;
+ tx.send(Action::Decrement).unwrap();
+ });
+ },
+ Action::Quit => app.should_quit = true, // You can handle cleanup and exit here
+ _ => {},
+ };
+ Action::None
+}
+
+fn handle_event(app: &App, tx: mpsc::UnboundedSender<Action>) -> tokio::task::JoinHandle<()> {
+ let tick_rate = std::time::Duration::from_millis(250);
+ tokio::spawn(async move {
+ loop {
+ let action = if crossterm::event::poll(tick_rate).unwrap() {
+ if let crossterm::event::Event::Key(key) = crossterm::event::read().unwrap() {
+ match key.code {
+ crossterm::event::KeyCode::Char('j') => Action::ScheduleIncrement,
+ crossterm::event::KeyCode::Char('k') => Action::ScheduleDecrement,
+ crossterm::event::KeyCode::Char('q') => Action::Quit,
+ _ => Action::None,
+ }
+ } else {
+ Action::None
+ }
+ } else {
+ Action::None
+ };
+ if let Err(_) = tx.send(action) {
+ break;
+ }
+ }
+ })
+}
+
+async fn run() -> Result<()> {
+ let mut t = Terminal::new(CrosstermBackend::new(std::io::stderr()))?;
+
+ let (action_tx, mut action_rx) = mpsc::unbounded_channel();
+
+ let mut app = App { counter: 0, should_quit: false, action_tx, ticker: 0 };
+
+ let task = handle_event(&app, app.action_tx.clone());
+
+ loop {
+ t.draw(|f| {
+ ui(f, &mut app);
+ })?;
+
+ if let Some(action) = action_rx.recv().await {
+ update(&mut app, action);
+ }
+
+ if app.should_quit {
+ break;
+ }
+ app.ticker += 1;
+ }
+
+ task.abort();
+
+ Ok(())
+}
+
+#[tokio::main]
+async fn main() -> Result<()> {
+ initialize_panic_handler();
+ startup()?;
+ run().await?;
+ shutdown()?;
+ Ok(())
+}
+Async Event Stream
+In it’s simplest form, most applications will have a main loop like this:
fn main() -> Result<()> {
+ let mut app = App::new();
+
+ let mut t = Tui::new()?;
+
+ t.enter()?; // raw mode enabled
+
+ loop {
+
+ // get key event and update state
+ // ... Special handling to read key or mouse events required here
+
+ t.terminal.draw(|f| { // <- `terminal.draw` is the only ratatui function here
+ ui(app, f) // render state to terminal
+ })?;
+
+ }
+
+ t.exit()?; // raw mode disabled
+
+ Ok(())
+}
+
+
+
+
+The terminal.draw(|f| { ui(app, f); }) call is the only line in the code above that
+uses ratatui functionality. You can learn more about
+draw from the official documentation.
+Essentially, terminal.draw() takes a callback that takes a
+Frame and
+expects the callback to render widgets to that frame, which is then drawn to the terminal
+using a double buffer technique.
While we are in the “raw mode”, i.e. after we call t.enter(), any key presses in that terminal
+window are sent to stdin. We have to read these key presses from stdin if we want to act on
+them.
There’s a number of different ways to do that. crossterm has a event module that implements
+features to read these key presses for us.
Let’s assume we were building a simple “counter” application, that incremented a counter when we
+pressed j and decremented a counter when we pressed k.
fn main() -> Result {
+ let mut app = App::new();
+
+ let mut t = Tui::new()?;
+
+ t.enter()?;
+
+ loop {
+ if crossterm::event::poll(Duration::from_millis(250))? {
+ if let Event::Key(key) = crossterm::event::read()? {
+ match key.code {
+ KeyCode::Char('j') => app.increment(),
+ KeyCode::Char('k') => app.decrement(),
+ KeyCode::Char('q') => break,
+ _ => (),
+ }
+ }
+ };
+
+ t.terminal.draw(|f| {
+ ui(app, f)
+ })?;
+ }
+
+ t.exit()?;
+
+ Ok(())
+}This works perfectly fine, and a lot of small to medium size programs can get away with doing just +that.
+However, this approach conflates the key input handling with app state updates, and does so in the +“draw” loop. The practical issue with this approach is we block the draw loop for 250 ms waiting for +a key press. This can have odd side effects, for example pressing an holding a key will result in +faster draws to the terminal.
+In terms of architecture, the code could get complicated to reason about. For example, we may even
+want key presses to mean different things depending on the state of the app (when you are focused
+on an input field, you may want to enter the letter "j" into the text input field, but when
+focused on a list of items, you may want to scroll down the list.)
We have to do a few different things set ourselves up, so let’s take things one step at a time.
+First, instead of polling, we are going to introduce channels to get the key presses asynchronously
+and send them over a channel. We will then receive on the channel in the main loop.
There are two ways to do this. We can either use OS threads or “green” threads, i.e. tasks, i.e.
+rust’s async-await features + a future executor.
Here’s example code of reading key presses asynchronously using std::thread and tokio::task.
std::thread
+enum Event {
+ Key(crossterm::event::KeyEvent)
+}
+
+struct EventHandler {
+ rx: std::sync::mpsc::Receiver<Event>,
+}
+
+impl EventHandler {
+ fn new() -> Self {
+ let tick_rate = std::time::Duration::from_millis(250);
+ let (tx, rx) = std::sync::mpsc::channel();
+ std::thread::spawn(move || {
+ loop {
+ if crossterm::event::poll(tick_rate)? {
+ match crossterm::event::read()? {
+ CrosstermEvent::Key(e) => tx.send(Event::Key(e)),
+ _ => unimplemented!(),
+ }?
+ }
+ }
+ })
+
+ EventHandler { rx }
+ }
+
+ fn next(&self) -> Result<Event> {
+ Ok(self.rx.recv()?)
+ }
+}tokio::task
+enum Event {
+ Key(crossterm::event::KeyEvent)
+}
+
+struct EventHandler {
+ rx: tokio::sync::mpsc::UnboundedReceiver<Event>,
+}
+
+impl EventHandler {
+ fn new() -> Self {
+ let tick_rate = std::time::Duration::from_millis(250);
+ let (tx, mut rx) = tokio::sync::mpsc::unbounded_channel();
+ tokio::spawn(async move {
+ loop {
+ if crossterm::event::poll(tick_rate)? {
+ match crossterm::event::read()? {
+ CrosstermEvent::Key(e) => tx.send(Event::Key(e)),
+ _ => unimplemented!(),
+ }?
+ }
+ }
+ })
+
+ EventHandler { rx }
+ }
+
+ async fn next(&self) -> Result<Event> {
+ Ok(self.rx.recv().await.ok()?)
+ }
+}diff
+ enum Event {
+ Key(crossterm::event::KeyEvent)
+ }
+
+ struct EventHandler {
+- rx: std::sync::mpsc::Receiver<Event>,
++ rx: tokio::sync::mpsc::UnboundedReceiver<Event>,
+ }
+
+ impl EventHandler {
+ fn new() -> Self {
+ let tick_rate = std::time::Duration::from_millis(250);
+- let (tx, rx) = std::sync::mpsc::channel();
++ let (tx, mut rx) = tokio::sync::mpsc::unbounded_channel();
+- std::thread::spawn(move || {
++ tokio::spawn(async move {
+ loop {
+ if crossterm::event::poll(tick_rate)? {
+ match crossterm::event::read()? {
+ CrosstermEvent::Key(e) => tx.send(Event::Key(e)),
+ _ => unimplemented!(),
+ }?
+ }
+ }
+ })
+
+ EventHandler { rx }
+ }
+
+- fn next(&self) -> Result<Event> {
++ async fn next(&self) -> Result<Event> {
+- Ok(self.rx.recv()?)
++ Ok(self.rx.recv().await.ok()?)
+ }
+ }
+
+
+
+
+
+A lot of examples out there in the wild might use the following code for sending key presses:
+ CrosstermEvent::Key(e) => tx.send(Event::Key(e)),However, on Windows, when using Crossterm, this will send the same Event::Key(e) twice; one for when you press the key, i.e. KeyEventKind::Press and one for when you release the key, i.e. KeyEventKind::Release.
+On MacOS and Linux only KeyEventKind::Press kinds of key event is generated.
To make the code work as expected across all platforms, you can do this instead:
+ CrosstermEvent::Key(key) => {
+ if key.kind == KeyEventKind::Press {
+ event_tx.send(Event::Key(key)).unwrap();
+ }
+ },Tokio is an asynchronous runtime for the Rust programming language. It is one of the more popular
+runtimes for asynchronous programming in rust. You can learn more about here
+https://tokio.rs/tokio/tutorial. For the rest of the tutorial here, we are going to assume we want
+to use tokio. I highly recommend you read the official tokio documentation.
If we use tokio, receiving a event requires .await. So our main loop now looks like this:
#[tokio::main]
+async fn main() -> {
+ let mut app = App::new();
+
+ let events = EventHandler::new();
+
+ let mut t = Tui::new()?;
+
+ t.enter()?;
+
+ loop {
+ if let Event::Key(key) = events.next().await? {
+ match key.code {
+ KeyCode::Char('j') => app.increment(),
+ KeyCode::Char('k') => app.decrement(),
+ KeyCode::Char('q') => break,
+ _ => (),
+ }
+ }
+
+ t.terminal.draw(|f| {
+ ui(app, f)
+ })?;
+ }
+
+ t.exit()?;
+
+ Ok(())
+}CancellationToken
+We want to use a CancellationToken to stop the tokio task on request.
tokio’s select! macro allows us to wait on multiple
+async computations and returns when a single computation completes.
Here’s what the completed EventHandler code now looks like:
use anyhow::Result;
+use crossterm::{
+ cursor,
+ event::{Event as CrosstermEvent, KeyEvent, KeyEventKind, MouseEvent},
+};
+use futures::{FutureExt, StreamExt};
+use tokio::{
+ sync::{mpsc, oneshot},
+ task::JoinHandle,
+};
+
+#[derive(Clone, Copy, Debug)]
+pub enum Event {
+ Error,
+ AppTick,
+ Key(KeyEvent),
+}
+
+#[derive(Debug)]
+pub struct EventHandler {
+ _tx: mpsc::UnboundedSender<Event>,
+ rx: mpsc::UnboundedReceiver<Event>,
+ task: Option<JoinHandle<()>>,
+ stop_cancellation_token: CancellationToken,
+}
+
+impl EventHandler {
+ pub fn new(tick_rate: u64) -> Self {
+ let tick_rate = std::time::Duration::from_millis(tick_rate);
+
+ let (tx, rx) = mpsc::unbounded_channel();
+ let _tx = tx.clone();
+
+ let stop_cancellation_token = CancellationToken::new();
+ let _stop_cancellation_token = stop_cancellation_token.clone();
+
+ let task = tokio::spawn(async move {
+ let mut reader = crossterm::event::EventStream::new();
+ let mut interval = tokio::time::interval(tick_rate);
+ loop {
+ let delay = interval.tick();
+ let crossterm_event = reader.next().fuse();
+ tokio::select! {
+ _ = _stop_cancellation_token.cancelled() => {
+ break;
+ }
+ maybe_event = crossterm_event => {
+ match maybe_event {
+ Some(Ok(evt)) => {
+ match evt {
+ CrosstermEvent::Key(key) => {
+ if key.kind == KeyEventKind::Press {
+ tx.send(Event::Key(key)).unwrap();
+ }
+ },
+ _ => {},
+ }
+ }
+ Some(Err(_)) => {
+ tx.send(Event::Error).unwrap();
+ }
+ None => {},
+ }
+ },
+ _ = delay => {
+ tx.send(Event::AppTick).unwrap();
+ },
+ }
+ }
+ });
+
+ Self { _tx, rx, task: Some(task), stop_cancellation_token }
+ }
+
+ pub async fn next(&mut self) -> Option<Event> {
+ self.rx.recv().await
+ }
+
+ pub async fn stop(&mut self) -> Result<()> {
+ self.stop_cancellation_token.cancel();
+ if let Some(handle) = self.task.take() {
+ handle.await.unwrap();
+ }
+ Ok(())
+ }
+}
+
+
+
+
+Using crossterm::event::EventStream::new() requires the event-stream feature to be enabled.
crossterm = { version = "0.27.0", features = ["event-stream"] }
+With this EventHandler implemented, we can use tokio to create a separate “task” that handles
+any key asynchronously in our main loop.
Full Async
+One way to achieve full async behavior is to wrap the App struct in a Arc<Mutex<App>>.
The main run loop might look something like this:
pub async fn run() -> Result<()> {
+ let (action_tx, mut action_rx) = mpsc::unbounded_channel();
+
+ let mut app = Arc::new(Mutex::new(App::new(action_tx.clone())));
+
+ let mut tui = TerminalHandler::new(app.clone());
+
+ loop {
+ if let Some(action) = action_rx.recv().await {
+ match action {
+ Action::RenderTick => tui.render()?,
+ Action::Quit => app.lock().await.quit(),
+ action => {
+ if let Some(_action) = app.lock().await.update(action) {
+ action_tx.send(_action)?
+ };
+ },
+ }
+ }
+ app.lock().await.should_quit {
+ tui.stop()?;
+ break;
+ }
+ }
+ Ok(())
+ }And you might have a tui.rs file that looks like this:
pub struct TerminalHandler {
+ pub task: JoinHandle<()>,
+ tx: mpsc::UnboundedSender<Message>,
+}
+
+impl TerminalHandler {
+ pub fn new(app: Arc<Mutex<App>>) -> Self {
+ let (tx, mut rx) = mpsc::unbounded_channel::<Message>();
+
+ let task = tokio::spawn(async move {
+ let mut t = Tui::new().context(anyhow!("Unable to create terminal")).unwrap();
+ t.enter().unwrap();
+ loop {
+ match rx.recv().await {
+ Some(Message::Stop) => {
+ t.exit().unwrap_or_default();
+ break;
+ },
+ Some(Message::Suspend) => {
+ t.suspend().unwrap_or_default();
+ break;
+ },
+ Some(Message::Render) => {
+ let mut _app = app.lock().await;
+ t.draw(|f| {
+ _app.render(f, f.size());
+ })
+ .unwrap();
+ },
+ None => {},
+ }
+ }
+ });
+ Self { task, tx }
+ }
+
+ pub fn suspend(&self) -> Result<()> {
+ self.tx.send(Message::Suspend)?;
+ Ok(())
+ }
+
+ pub fn stop(&self) -> Result<()> {
+ self.tx.send(Message::Stop)?;
+ Ok(())
+ }
+
+ pub fn render(&self) -> Result<()> {
+ self.tx.send(Message::Render)?;
+ Ok(())
+ }
+}In this particular code above, since we take the lock to render, the app handle event or update
+methods will not be called while rendering is occurring.
In order for this approach to be useful, you’ll have to break your state down into different +structs. In cases where you do this, and have different parts of your app state being updated and +rendered, this approach may be viable. This is usually overkill and almost never required.
+Stopwatch App
+Here’s the dependencies:
+[package]
+name = "ratatui-stopwatch-app"
+version = "0.1.0"
+edition = "2021"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+color-eyre = "0.6.2"
+crossterm = { version = "0.27.0", features = ["event-stream"] }
+directories = "5.0.1"
+futures = "0.3.28"
+human-panic = "1.2.0"
+itertools = "0.11.0"
+lazy_static = "1.4.0"
+libc = "0.2.147"
+log = "0.4.20"
+ratatui = "0.23.0"
+strip-ansi-escapes = "0.2.0"
+strum = "0.25.0"
+tokio = { version = "1.32.0", features = ["full"] }
+tokio-util = "0.7.8"
+tracing = "0.1.37"
+tracing-error = "0.2.0"
+tracing-subscriber = { version = "0.3.17", features = ["env-filter"] }
+tui-big-text = "0.1.4"
+Here’s a gif of what it will look like if you run this:
+
Here’s the full application:
+use std::time::{Duration, Instant};
+
+use color_eyre::eyre::{eyre, Result};
+use futures::{FutureExt, StreamExt};
+use itertools::Itertools;
+use lazy_static::lazy_static;
+use ratatui::{backend::CrosstermBackend as Backend, prelude::*, widgets::*};
+use strum::EnumIs;
+use tracing_subscriber::{prelude::__tracing_subscriber_SubscriberExt, util::SubscriberInitExt, Layer};
+use tui_big_text::BigText;
+
+pub type Frame<'a> = ratatui::Frame<'a, Backend<std::io::Stderr>>;
+
+lazy_static! {
+ pub static ref PROJECT_NAME: String = env!("CARGO_PKG_NAME").to_uppercase().to_string();
+ pub static ref DATA_FOLDER: Option<std::path::PathBuf> =
+ std::env::var(format!("{}_DATA", PROJECT_NAME.clone())).ok().map(std::path::PathBuf::from);
+ pub static ref LOG_FILE: String = format!("{}.log", PROJECT_NAME.to_lowercase());
+}
+
+fn project_directory() -> Option<directories::ProjectDirs> {
+ directories::ProjectDirs::from("com", "kdheepak", PROJECT_NAME.clone().to_lowercase().as_str())
+}
+
+pub fn get_data_dir() -> std::path::PathBuf {
+ let directory = if let Some(s) = DATA_FOLDER.clone() {
+ s
+ } else if let Some(proj_dirs) = project_directory() {
+ proj_dirs.data_local_dir().to_path_buf()
+ } else {
+ std::path::PathBuf::from(".").join(".data")
+ };
+ directory
+}
+
+pub fn initialize_logging() -> Result<()> {
+ let directory = get_data_dir();
+ std::fs::create_dir_all(directory.clone())?;
+ let log_path = directory.join(LOG_FILE.clone());
+ let log_file = std::fs::File::create(log_path)?;
+ let file_subscriber = tracing_subscriber::fmt::layer()
+ .with_file(true)
+ .with_line_number(true)
+ .with_writer(log_file)
+ .with_target(false)
+ .with_ansi(false)
+ .with_filter(tracing_subscriber::filter::EnvFilter::from_default_env());
+
+ tracing_subscriber::registry().with(file_subscriber).with(tracing_error::ErrorLayer::default()).init();
+
+ Ok(())
+}
+
+pub fn initialize_panic_handler() -> Result<()> {
+ let (panic_hook, eyre_hook) = color_eyre::config::HookBuilder::default().into_hooks();
+ eyre_hook.install()?;
+ std::panic::set_hook(Box::new(move |panic_info| {
+ if let Ok(t) = Tui::new() {
+ if let Err(r) = t.exit() {
+ log::error!("Unable to exit Terminal: {:?}", r);
+ }
+ }
+ let msg = format!("{}", panic_hook.panic_report(panic_info));
+ log::error!("{}", strip_ansi_escapes::strip_str(&msg));
+ use human_panic::{handle_dump, print_msg, Metadata};
+ let meta = Metadata {
+ version: env!("CARGO_PKG_VERSION").into(),
+ name: env!("CARGO_PKG_NAME").into(),
+ authors: env!("CARGO_PKG_AUTHORS").replace(':', ", ").into(),
+ homepage: env!("CARGO_PKG_HOMEPAGE").into(),
+ };
+ let file_path = handle_dump(&meta, panic_info);
+ print_msg(file_path, &meta).expect("human-panic: printing error message to console failed");
+ eprintln!("{}", msg);
+ std::process::exit(libc::EXIT_FAILURE);
+ }));
+ Ok(())
+}
+
+#[tokio::main]
+async fn main() -> Result<()> {
+ initialize_panic_handler()?;
+ let mut app = StopwatchApp::default();
+ app.run().await
+}
+
+#[derive(Clone, Debug)]
+pub enum Event {
+ Quit,
+ Error,
+ Tick,
+ Key(crossterm::event::KeyEvent),
+}
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, EnumIs)]
+enum AppState {
+ #[default]
+ Stopped,
+ Running,
+ Quitting,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum Message {
+ StartOrSplit,
+ Stop,
+ Tick,
+ Quit,
+}
+
+#[derive(Debug, Clone, PartialEq)]
+struct StopwatchApp {
+ state: AppState,
+ splits: Vec<Instant>,
+ start_time: Instant,
+ frames: u32,
+ fps: f64,
+}
+
+impl Default for StopwatchApp {
+ fn default() -> Self {
+ Self::new()
+ }
+}
+
+impl StopwatchApp {
+ fn new() -> Self {
+ Self {
+ start_time: Instant::now(),
+ frames: Default::default(),
+ fps: Default::default(),
+ splits: Default::default(),
+ state: Default::default(),
+ }
+ }
+
+ async fn run(&mut self) -> Result<()> {
+ let mut tui = Tui::new()?;
+ tui.enter()?;
+ while !self.state.is_quitting() {
+ tui.draw(|f| self.ui(f).expect("Unexpected error during drawing"))?;
+ let event = tui.next().await.ok_or(eyre!("Unable to get event"))?; // blocks until next event
+ let message = self.handle_event(event)?;
+ self.update(message)?;
+ }
+ tui.exit()?;
+ Ok(())
+ }
+
+ fn handle_event(&self, event: Event) -> Result<Message> {
+ let msg = match event {
+ Event::Key(key) => {
+ match key.code {
+ crossterm::event::KeyCode::Char('q') => Message::Quit,
+ crossterm::event::KeyCode::Char(' ') => Message::StartOrSplit,
+ crossterm::event::KeyCode::Char('s') | crossterm::event::KeyCode::Enter => Message::Stop,
+ _ => Message::Tick,
+ }
+ },
+ _ => Message::Tick,
+ };
+ Ok(msg)
+ }
+
+ fn update(&mut self, message: Message) -> Result<()> {
+ match message {
+ Message::StartOrSplit => self.start_or_split(),
+ Message::Stop => self.stop(),
+ Message::Tick => self.tick(),
+ Message::Quit => self.quit(),
+ }
+ Ok(())
+ }
+
+ fn start_or_split(&mut self) {
+ if self.state.is_stopped() {
+ self.start();
+ } else {
+ self.record_split();
+ }
+ }
+
+ fn stop(&mut self) {
+ self.record_split();
+ self.state = AppState::Stopped;
+ }
+
+ fn tick(&mut self) {
+ self.frames += 1;
+ let now = Instant::now();
+ let elapsed = (now - self.start_time).as_secs_f64();
+ if elapsed >= 1.0 {
+ self.fps = self.frames as f64 / elapsed;
+ self.start_time = now;
+ self.frames = 0;
+ }
+ }
+
+ fn quit(&mut self) {
+ self.state = AppState::Quitting
+ }
+
+ fn start(&mut self) {
+ self.splits.clear();
+ self.state = AppState::Running;
+ self.record_split();
+ }
+
+ fn record_split(&mut self) {
+ if !self.state.is_running() {
+ return;
+ }
+ self.splits.push(Instant::now());
+ }
+
+ fn elapsed(&mut self) -> Duration {
+ if self.state.is_running() {
+ self.splits.first().map_or(Duration::ZERO, Instant::elapsed)
+ } else {
+ // last - first or 0 if there are no splits
+ let now = Instant::now();
+ let first = *self.splits.first().unwrap_or(&now);
+ let last = *self.splits.last().unwrap_or(&now);
+ last - first
+ }
+ }
+
+ fn ui(&mut self, f: &mut Frame) -> Result<()> {
+ let layout = self.layout(f.size());
+ f.render_widget(Paragraph::new("Stopwatch Example"), layout[0]);
+ f.render_widget(self.fps_paragraph(), layout[1]);
+ f.render_widget(self.timer_paragraph(), layout[2]);
+ f.render_widget(Paragraph::new("Splits:"), layout[3]);
+ f.render_widget(self.splits_paragraph(), layout[4]);
+ f.render_widget(self.help_paragraph(), layout[5]);
+ Ok(())
+ }
+
+ fn fps_paragraph(&mut self) -> Paragraph<'_> {
+ let fps = format!("{:.2} fps", self.fps);
+ Paragraph::new(fps).style(Style::new().dim()).alignment(Alignment::Right)
+ }
+
+ fn timer_paragraph(&mut self) -> BigText<'_> {
+ let style = if self.state.is_running() { Style::new().green() } else { Style::new().red() };
+ let elapsed = self.elapsed();
+ let duration = self.format_duration(elapsed);
+ let lines = vec![duration.into()];
+ tui_big_text::BigTextBuilder::default().lines(lines).style(style).build().unwrap()
+ }
+
+ /// Renders the splits as a list of lines.
+ ///
+ /// ```text
+ /// #01 -- 00:00.693 -- 00:00.693
+ /// #02 -- 00:00.719 -- 00:01.413
+ /// ```
+ fn splits_paragraph(&mut self) -> Paragraph<'_> {
+ let start = *self.splits.first().unwrap_or(&Instant::now());
+ let mut splits = self
+ .splits
+ .iter()
+ .copied()
+ .tuple_windows()
+ .enumerate()
+ .map(|(index, (prev, current))| self.format_split(index, start, prev, current))
+ .collect::<Vec<_>>();
+ splits.reverse();
+ Paragraph::new(splits)
+ }
+
+ fn help_paragraph(&mut self) -> Paragraph<'_> {
+ let space_action = if self.state.is_stopped() { "start" } else { "split" };
+ let help_text =
+ Line::from(vec!["space ".into(), space_action.dim(), " enter ".into(), "stop".dim(), " q ".into(), "quit".dim()]);
+ Paragraph::new(help_text).gray()
+ }
+
+ fn layout(&self, area: Rect) -> Vec<Rect> {
+ let layout = Layout::default()
+ .direction(Direction::Vertical)
+ .constraints(vec![
+ Constraint::Length(2), // top bar
+ Constraint::Length(8), // timer
+ Constraint::Length(1), // splits header
+ Constraint::Min(0), // splits
+ Constraint::Length(1), // help
+ ])
+ .split(area);
+ let top_layout = Layout::default()
+ .direction(Direction::Horizontal)
+ .constraints(vec![
+ Constraint::Length(20), // title
+ Constraint::Min(0), // fps counter
+ ])
+ .split(layout[0]);
+
+ // return a new vec with the top_layout rects and then rest of layout
+ top_layout[..].iter().chain(layout[1..].iter()).copied().collect()
+ }
+
+ fn format_split<'a>(&self, index: usize, start: Instant, previous: Instant, current: Instant) -> Line<'a> {
+ let split = self.format_duration(current - previous);
+ let elapsed = self.format_duration(current - start);
+ Line::from(vec![
+ format!("#{:02} -- ", index + 1).into(),
+ Span::styled(split, Style::new().yellow()),
+ " -- ".into(),
+ Span::styled(elapsed, Style::new()),
+ ])
+ }
+
+ fn format_duration(&self, duration: Duration) -> String {
+ format!("{:02}:{:02}.{:03}", duration.as_secs() / 60, duration.as_secs() % 60, duration.subsec_millis())
+ }
+}
+
+struct Tui {
+ pub terminal: Terminal<Backend<std::io::Stderr>>,
+ pub task: tokio::task::JoinHandle<()>,
+ pub cancellation_token: tokio_util::sync::CancellationToken,
+ pub event_rx: tokio::sync::mpsc::UnboundedReceiver<Event>,
+ pub event_tx: tokio::sync::mpsc::UnboundedSender<Event>,
+}
+
+impl Tui {
+ fn new() -> Result<Tui> {
+ let terminal = ratatui::Terminal::new(Backend::new(std::io::stderr()))?;
+ let (event_tx, event_rx) = tokio::sync::mpsc::unbounded_channel();
+ let cancellation_token = tokio_util::sync::CancellationToken::new();
+ let task = tokio::spawn(async {});
+ Ok(Self { terminal, task, cancellation_token, event_rx, event_tx })
+ }
+
+ pub async fn next(&mut self) -> Option<Event> {
+ self.event_rx.recv().await
+ }
+
+ pub fn enter(&mut self) -> Result<()> {
+ crossterm::terminal::enable_raw_mode()?;
+ crossterm::execute!(std::io::stderr(), crossterm::terminal::EnterAlternateScreen, crossterm::cursor::Hide)?;
+ self.start();
+ Ok(())
+ }
+
+ pub fn exit(&self) -> Result<()> {
+ self.stop()?;
+ crossterm::execute!(std::io::stderr(), crossterm::terminal::LeaveAlternateScreen, crossterm::cursor::Show)?;
+ crossterm::terminal::disable_raw_mode()?;
+ Ok(())
+ }
+
+ pub fn cancel(&self) {
+ self.cancellation_token.cancel();
+ }
+
+ pub fn stop(&self) -> Result<()> {
+ self.cancel();
+ let mut counter = 0;
+ while !self.task.is_finished() {
+ std::thread::sleep(Duration::from_millis(250));
+ counter += 1;
+ if counter > 5 {
+ self.task.abort();
+ }
+ if counter > 10 {
+ log::error!("Failed to abort task for unknown reason");
+ return Err(eyre!("Unable to abort task"));
+ }
+ }
+ Ok(())
+ }
+
+ pub fn start(&mut self) {
+ let tick_rate = std::time::Duration::from_millis(60);
+ self.cancel();
+ self.cancellation_token = tokio_util::sync::CancellationToken::new();
+ let _cancellation_token = self.cancellation_token.clone();
+ let _event_tx = self.event_tx.clone();
+ self.task = tokio::spawn(async move {
+ let mut reader = crossterm::event::EventStream::new();
+ let mut interval = tokio::time::interval(tick_rate);
+ loop {
+ let delay = interval.tick();
+ let crossterm_event = reader.next().fuse();
+ tokio::select! {
+ _ = _cancellation_token.cancelled() => {
+ break;
+ }
+ maybe_event = crossterm_event => {
+ match maybe_event {
+ Some(Ok(evt)) => {
+ match evt {
+ crossterm::event::Event::Key(key) => {
+ if key.kind == crossterm::event::KeyEventKind::Press {
+ _event_tx.send(Event::Key(key)).unwrap();
+ }
+ },
+ _ => {}
+ }
+ }
+ Some(Err(_)) => {
+ _event_tx.send(Event::Error).unwrap();
+ }
+ None => {},
+ }
+ },
+ _ = delay => {
+ _event_tx.send(Event::Tick).unwrap();
+ },
+ }
+ }
+ });
+ }
+}
+
+impl std::ops::Deref for Tui {
+ type Target = ratatui::Terminal<Backend<std::io::Stderr>>;
+
+ fn deref(&self) -> &Self::Target {
+ &self.terminal
+ }
+}
+
+impl std::ops::DerefMut for Tui {
+ fn deref_mut(&mut self) -> &mut Self::Target {
+ &mut self.terminal
+ }
+}
+
+impl Drop for Tui {
+ fn drop(&mut self) {
+ self.exit().unwrap();
+ }
+}How To
+-
+
- Layout UIs: Articles regarding how to layout your application’s User Interface +including widgets and nesting blocks +
- Render Text: Articles related to actually rendering test and widgets to the screen +including how to style and write to the buffer. +
- Use Widgets: Articles related to using individual widgets suchs as the paragraph, +block, and creating your own custom widget. +
- Develop Applications: Articles related to developing applications. E.g. how to +handle CLI arguments, tracing, configuration, panics, etc. +
Layout Constraints Basics
+Here’s the “hello world” example again:
+pub fn render(app: &mut App, f: &mut Frame) {
+ f.render_widget(
+ Paragraph::new("Hello World!")
+ .block(Block::default().borders(Borders::ALL).border_type(BorderType::Rounded)),
+ f.size()
+ )
+}Here’s what the docs say for f.size():
ratatui::terminal::Frame
+
+pub fn size(&self) -> Rect
+────────────────────────────────────────────────────
+Frame size, guaranteed not to change when rendering.
+f.size() returns a Rect struct. A Rect has the following struct definition:
#[derive(Debug, Clone, Copy, Hash, PartialEq, Eq, Default)]
+pub struct Rect {
+ pub x: u16,
+ pub y: u16,
+ pub width: u16,
+ pub height: u16,
+}That is to say, they have a x and y positional coordinates and width and height dimensional
+values.
The coordinate system in ratatui (and in terminals in general) starts at the top left of the
+terminal or container widget. This point represents (0,0).
Here’s the “hello world” example from above rendered:
+╭───────────────────────────────────╮
+│Hello World! │
+│ │
+│ │
+╰───────────────────────────────────╯
+What if hypothetically we wanted to render this instead:
+╭────────────────╮╭─────────────────╮
+│Hello World! ││Hello World! │
+│ ││ │
+│ ││ │
+╰────────────────╯╰─────────────────╯
+We could integer divide the width by 2, account of the borders calculate the x position for
+the second paragraph but that is cumbersome and error prone.
Now, that’s where layouts come in.
+let rects = Layout::default()
+ .direction(Direction::Horizontal)
+ .constraints(
+ [
+ Constraint::Percentage(50),
+ Constraint::Percentage(50),
+ ]
+ .as_ref(),
+ )
+ .split(f.size());Here we created a layout and added two “constraints”. The constraints determine the size of the
+resulting Rects. Calling split on a Layout splits the layout based on the constraints.
That is, rects behaves as a Vec<Rect>, whose length always matches the number of constraints.
So for the example above, we might want to do something like this:
+pub fn render(app: &mut App, f: &mut Frame) {
+ let chunks = Layout::default()
+ .direction(Direction::Horizontal)
+ .constraints(
+ [
+ Constraint::Percentage(50),
+ Constraint::Percentage(50),
+ ]
+ .as_ref(),
+ )
+ .split(f.size());
+ f.render_widget(
+ Paragraph::new("Hello World!")
+ .block(Block::default().borders(Borders::ALL).border_type(BorderType::Rounded)),
+ chunks[0]
+ )
+ f.render_widget(
+ Paragraph::new("Hello World!")
+ .block(Block::default().borders(Borders::ALL).border_type(BorderType::Rounded)),
+ chunks[1]
+ )
+}Notice that we used the first chunk for the first Paragraph and the second chunk for the
+second Paragraph.
Center a Rect
+You can use a Vertical layout followed by a Horizontal layout to get a centered Rect.
/// # Usage
+///
+/// ```rust
+/// let rect = centered_rect(f.size(), 50, 50);
+/// ```
+fn centered_rect(r: Rect, percent_x: u16, percent_y: u16) -> Rect {
+ let popup_layout = Layout::default()
+ .direction(Direction::Vertical)
+ .constraints(
+ [
+ Constraint::Percentage((100 - percent_y) / 2),
+ Constraint::Percentage(percent_y),
+ Constraint::Percentage((100 - percent_y) / 2),
+ ]
+ .as_ref(),
+ )
+ .split(r);
+
+ Layout::default()
+ .direction(Direction::Horizontal)
+ .constraints(
+ [
+ Constraint::Percentage((100 - percent_x) / 2),
+ Constraint::Percentage(percent_x),
+ Constraint::Percentage((100 - percent_x) / 2),
+ ]
+ .as_ref(),
+ )
+ .split(popup_layout[1])[1]
+}Render Text
+ +Displaying Text
+This page covers how text displaying works. It will cover Span, Line, and Text, and how these
+can be created, styled, displayed, altered, and such.
Span
+A Span is a styled segment of text. You can think of it as a substring with its own unique style.
+It is the most basic unit of displaying text in ratatui.
The examples below assume the following imports:
+use ratatui::{prelude::*, widgets::*};
+pub type Frame<'a> = ratatui::Frame<'a, CrosstermBackend<std::io::Stderr>>;A Span consists of “content” and a “style” for the content. And a Span can be created in a few
+different ways.
-
+
-
+
using
+Span::raw:
+fn ui(_app: &App, f: &mut Frame<'_>) { + let span = Span::raw("This is text that is not styled"); + // -- snip --- +}
+ -
+
using
+Span::styled:
+fn ui(_app: &App, f: &mut Frame<'_>) { + let span = Span::styled("This is text that will be yellow", Style::default().fg(Color::Yellow)); + // -- snip --- +}
+ -
+
using the
+Stylizetrait:
+fn ui(_app: &App, f: &mut Frame<'_>) { + let span = "This is text that will be yellow".yellow(); + // -- snip --- +}
+
A Span is the basic building block for any styled text, and can be used anywhere text is
+displayed.
Line
+The next building block that we are going to talk about is a Line. A Line represents a cluster
+of graphemes, where each unit in the cluster can have its own style. You can think of an instance of
+the Line struct as essentially a collection of Span objects, i.e. Vec<Span>.
Since each Line struct consists of multiple Span objects, this allows for varied styling in a
+row of words, phrases or sentences.
fn ui(_: &App, f: &mut Frame<'_>) {
+ let line = Line::from(vec![
+ "hello".red(),
+ " ".into(),
+ "world".red().bold()
+ ]);
+ // -- snip ---
+}A Line can be constructed directly from content, where the content is Into<Cow<'a, &str>>.
fn ui(_: &App, f: &mut Frame<'_>) {
+ let line = Line::from("hello world");
+ // -- snip ---
+}You can even style a full line directly:
+fn ui(_: &App, f: &mut Frame<'_>) {
+ let line = Line::styled("hello world", Style::default().fg(Color::Yellow));
+ // -- snip ---
+}And you can use the Stylize trait on the line directly by using into():
fn ui(_: &App, f: &mut Frame<'_>) {
+ let line: Line = "hello world".yellow().into();
+ // -- snip ---
+}Text
+Text is the final building block of outputting text. A Text object represents a collection of
+Lines.
Most widgets accept content that can be converted to Text.
fn ui(_: &App, f: &mut Frame<'_>) {
+ let span1 = "hello".red();
+ let span2 = "world".red().bold();
+ let line = Line::from(vec![span1, " ".into(), span2]);
+ let text = Text::from(line);
+ f.render_widget(Paragraph::new(text).block(Block::default().borders(Borders::ALL)), f.size());
+}Here’s an HTML representation of what you’d get in the terminal:
+
+ hello
+ world
+
+Often code like the one above can be simplified:
+fn ui(_: &App, f: &mut Frame<'_>) {
+ let line: Line = vec![
+ "hello".red(),
+ " ".into(),
+ "world".red().bold()
+ ].into();
+ f.render_widget(Paragraph::new(line).block(Block::default().borders(Borders::ALL)), f.size());
+}This is because in this case, Rust is able to infer the types and convert them into appropriately.
+Text instances can be created using the raw or styled constructors too.
Something that you might find yourself doing pretty often for a Paragraph is wanting to have
+multiple lines styled differently. This is one way you might go about that:
fn ui(_: &App, f: &mut Frame<'_>) {
+ let text = vec![
+ "hello world 1".into(),
+ "hello world 2".blue().into(),
+ Line::from(vec!["hello".green(), " ".into(), "world".green().bold(), "3".into()]),
+ ]
+ .into();
+ f.render_widget(Paragraph::new(text).block(Block::default().borders(Borders::ALL)), f.size());
+}
+
++ hello world 1 +
++ hello world 2 +
++ hello + world 3 +
+We will talk more about styling in the next section.
+Styling-Text
+Styling enhances user experience by adding colors, emphasis, and other visual aids. In ratatui,
+the primary tool for this is the ratatui::style::Style struct.
ratatui::style::Style provides a set of methods to apply styling attributes to your text. These
+styles can then be applied to various text structures like Text, Span, and Line (as well as
+other non text structures).
Common styling attributes include:
+-
+
- Foreground and Background Colors (
fgandbg)
+ - Modifiers (like
bold,italic, andunderline)
+
-
+
-
+
Basic Color Styling
+Setting the foreground (text color) and background:
+
+let styled_text = Span::styled( + "Hello, Ratatui!", + Style::default().fg(Color::Red).bg(Color::Yellow) +);
+ -
+
Using
+ModifiersMaking text bold or italic:
+
+let bold_text = Span::styled( + "This is bold", + Style::default().modifier(Modifier::BOLD) +); + +let italic_text = Span::styled( + "This is italic", + Style::default().modifier(Modifier::ITALIC) +);You can also combine multiple modifiers:
+
+let bold_italic_text = Span::styled( + "This is bold and italic", + Style::default().modifier(Modifier::BOLD | Modifier::ITALIC) +);
+ -
+
Styling within a Line
+You can mix and match different styled spans within a single line:
+
+let mixed_line = Line::from(vec![ + Span::styled("This is mixed", Style::default().fg(Color::Green)), + Span::styled("styling", Style::default().fg(Color::Red).add_modifier(Modifier::BOLD)), + Span::from("!"), +]);
+
This is what it would look like if you rendered a Paragraph with different styles for each line:
fn ui(_: &App, f: &mut Frame<'_>) {
+ let styled_text = Span::styled("Hello, Ratatui!", Style::default().fg(Color::Red).bg(Color::Yellow));
+ let bold_text = Span::styled("This is bold", Style::default().add_modifier(Modifier::BOLD));
+ let italic_text = Span::styled("This is italic", Style::default().add_modifier(Modifier::ITALIC));
+ let bold_italic_text =
+ Span::styled("This is bold and italic", Style::default().add_modifier(Modifier::BOLD | Modifier::ITALIC));
+ let mixed_line = vec![
+ Span::styled("This is mixed", Style::default().fg(Color::Green)),
+ Span::styled("styling", Style::default().fg(Color::Red).add_modifier(Modifier::BOLD)),
+ Span::from("!"),
+ ];
+ let text: Vec<Line<'_>> =
+ vec![styled_text.into(), bold_text.into(), italic_text.into(), bold_italic_text.into(), mixed_line.into()];
+ f.render_widget(Paragraph::new(text).block(Block::default().borders(Borders::ALL)), f.size());
+}Here’s the HTML representation of the above styling:
+
+
+Hello, Ratatui!
+This is bold
+This is italic
+This is bold and italic
++ This is mixed + styling + ! +
+
+
+
+
+
+You can also create instances of Color from a string:
use std::str::FromStr;
+
+let color: Color = Color::from_str("blue").unwrap();
+assert_eq!(color, Color::Blue);
+
+let color: Color = Color::from_str("#FF0000").unwrap();
+assert_eq!(color, Color::Rgb(255, 0, 0));
+
+let color: Color = Color::from_str("10").unwrap();
+assert_eq!(color, Color::Indexed(10));You can read more about the
+Color enum and
+Modifier in the reference
+documentation online.
Use Widgets
+ +Paragraph
+(Stub) This page covers ratatui::widgets::Paragraph.
Block
+(Stub) This How-To covers the ratatui::widgets::block::Block.
Develop Applications
+This section covers topics on how to develop applications:
+-
+
- CLI arguments +
- Configuration Directories +
- Tracing +
- Arrange your App Code +
- Setup Panic Hooks +
- Better Panic Hooks +
Handle CLI arguments
+Command Line Interface (CLI) tools often require input parameters to dictate their behavior.
+clap (Command Line Argument Parser) is a feature-rich Rust
+library that facilitates the parsing of these arguments in an intuitive manner.
Defining Command Line Arguments
+In this snippet, we utilize the clap library to define an Args struct, which will be used to
+capture and structure the arguments passed to the application:
use clap::Parser;
+
+#[derive(Parser, Debug)]
+#[command(version = version(), about = "ratatui template with crossterm and tokio")]
+struct Args {
+ /// App tick rate
+ #[arg(short, long, default_value_t = 1000)]
+ app_tick_rate: u64,
+}Here, the Args struct defines one command-line arguments:
+-
+
app_tick_rate: Dictates the application’s tick rate.
+
This is supplied with default values, ensuring that even if the user doesn’t provide this argument, +the application can still proceed with its defaults.
+Displaying Version Information
+One common convention in CLIs is the ability to display version information. Here, the version +information is presented as a combination of various parameters, including the Git commit hash.
+The version() function, as seen in the snippet, fetches this information:
pub fn version() -> String {
+ let author = clap::crate_authors!();
+
+ let commit_hash = env!("RATATUI_TEMPLATE_GIT_INFO");
+
+ // let current_exe_path = PathBuf::from(clap::crate_name!()).display().to_string();
+ let config_dir_path = get_config_dir().unwrap().display().to_string();
+ let data_dir_path = get_data_dir().unwrap().display().to_string();
+
+ format!(
+ "\
+{commit_hash}
+
+Authors: {author}
+
+Config directory: {config_dir_path}
+Data directory: {data_dir_path}"
+ )
+}This function uses the get_data_dir() and get_config_dir() from
+the section on XDG directories.
This function also makes use of an environment variable RATATUI_TEMPLATE_GIT_INFO to derive the
+Git commit hash. The variable can be populated during the build process by build.rs:
println!("cargo:rustc-env=RATATUI_TEMPLATE_GIT_INFO={}", git_describe);By invoking the CLI tool with the --version flag, users will be presented with the version
+details, including the authors, commit hash, and the paths to the configuration and data
+directories.
The version() function’s output is just an example. You can easily adjust its content by amending
+the string template code above.
Here’s the full build.rs for your reference:
fn main() {
+ let git_output = std::process::Command::new("git").args(["rev-parse", "--git-dir"]).output().ok();
+ let git_dir = git_output.as_ref().and_then(|output| {
+ std::str::from_utf8(&output.stdout).ok().and_then(|s| s.strip_suffix('\n').or_else(|| s.strip_suffix("\r\n")))
+ });
+
+ // Tell cargo to rebuild if the head or any relevant refs change.
+ if let Some(git_dir) = git_dir {
+ let git_path = std::path::Path::new(git_dir);
+ let refs_path = git_path.join("refs");
+ if git_path.join("HEAD").exists() {
+ println!("cargo:rerun-if-changed={}/HEAD", git_dir);
+ }
+ if git_path.join("packed-refs").exists() {
+ println!("cargo:rerun-if-changed={}/packed-refs", git_dir);
+ }
+ if refs_path.join("heads").exists() {
+ println!("cargo:rerun-if-changed={}/refs/heads", git_dir);
+ }
+ if refs_path.join("tags").exists() {
+ println!("cargo:rerun-if-changed={}/refs/tags", git_dir);
+ }
+ }
+
+ let git_output =
+ std::process::Command::new("git").args(["describe", "--always", "--tags", "--long", "--dirty"]).output().ok();
+ let git_info = git_output.as_ref().and_then(|output| std::str::from_utf8(&output.stdout).ok().map(str::trim));
+ let cargo_pkg_version = env!("CARGO_PKG_VERSION");
+
+ // Default git_describe to cargo_pkg_version
+ let mut git_describe = String::from(cargo_pkg_version);
+
+ if let Some(git_info) = git_info {
+ // If the `git_info` contains `CARGO_PKG_VERSION`, we simply use `git_info` as it is.
+ // Otherwise, prepend `CARGO_PKG_VERSION` to `git_info`.
+ if git_info.contains(cargo_pkg_version) {
+ // Remove the 'g' before the commit sha
+ let git_info = &git_info.replace('g', "");
+ git_describe = git_info.to_string();
+ } else {
+ git_describe = format!("v{}-{}", cargo_pkg_version, git_info);
+ }
+ }
+
+ println!("cargo:rustc-env=RATATUI_TEMPLATE_GIT_INFO={}", git_describe);
+}
+Handle XDG Directories
+Handling files and directories correctly in a command-line or TUI application ensures that the +application fits seamlessly into a user’s workflow and adheres to established conventions. One of +the key conventions on Linux-based systems is the XDG Base Directory Specification.
+Why the XDG Base Directory Specification?
+The XDG Base Directory Specification is a set of standards that define where user files should +reside, ensuring a cleaner home directory and a more organized storage convention. By adhering to +this standard, your application will store files in the expected directories, making it more +predictable and user-friendly.
+Using directories-rs for Path Resolution
+The directories-rs library offers a Rust-friendly interface to locate common directories (like
+config and data directories) based on established conventions, including the XDG Base Directory
+Specification.
-
+
-
+
Add
+directories-rsto yourCargo.toml
+cargo add directories +
+ -
+
Use the
+ProjectDirsstruct to retrieve paths based on your project’s domain and project name +and create helper functions for getting thedata_dirandconfig_dir.
+ -
+
Allow users to specify custom locations using environment variables. This flexibility can be +crucial for users with unique directory structures or for testing.
+
+ -
+
A good practice is to notify the user about the location of the configuration and data +directories. An example from the template is to print out these locations when the user invokes +the
+--versioncommand-line argument. See the section on +Command line argument parsing
+
Here’s an example get_data_dir() and get_config_dir() functions for your reference:
use std::path::PathBuf;
+
+use anyhow::{anyhow, Context, Result};
+use directories::ProjectDirs;
+
+pub fn get_data_dir() -> Result<PathBuf> {
+ let directory = if let Ok(s) = std::env::var("RATATUI_TEMPLATE_DATA") {
+ PathBuf::from(s)
+ } else if let Some(proj_dirs) = ProjectDirs::from("com", "kdheepak", "ratatui-template") {
+ proj_dirs.data_local_dir().to_path_buf()
+ } else {
+ return Err(anyhow!("Unable to find data directory for ratatui-template"));
+ };
+ Ok(directory)
+}
+
+pub fn get_config_dir() -> Result<PathBuf> {
+ let directory = if let Ok(s) = std::env::var("RATATUI_TEMPLATE_CONFIG") {
+ PathBuf::from(s)
+ } else if let Some(proj_dirs) = ProjectDirs::from("com", "kdheepak", "ratatui-template") {
+ proj_dirs.config_local_dir().to_path_buf()
+ } else {
+ return Err(anyhow!("Unable to find config directory for ratatui-template"));
+ };
+ Ok(directory)
+}You will want to replace kdheepak with your user name or company name (or any unique name for that
+matter); and ratatui-app with the name of your CLI.
I own https://kdheepak.com so I tend to use com.kdheepak.ratatui-app for my project directories.
+That way it is unlikely that any other program will mess with the configuration files for the app I
+plan on distributing.
Setup Logging with tracing
+You’ll need to install tracing and a few related dependencies:
cargo add tracing-error tracing
+cargo add tracing-subscriber --features env-filter
+cargo add directories lazy_static color-eyre # (optional)
+You can paste the following in any module in your project.
+use std::path::PathBuf;
+
+use color_eyre::eyre::{Context, Result};
+use directories::ProjectDirs;
+use lazy_static::lazy_static;
+use tracing::error;
+use tracing_error::ErrorLayer;
+use tracing_subscriber::{self, layer::SubscriberExt, util::SubscriberInitExt, Layer};
+
+lazy_static! {
+ pub static ref PROJECT_NAME: String = env!("CARGO_CRATE_NAME").to_uppercase().to_string();
+ pub static ref DATA_FOLDER: Option<PathBuf> =
+ std::env::var(format!("{}_DATA", PROJECT_NAME.clone())).ok().map(PathBuf::from);
+ pub static ref LOG_ENV: String = format!("{}_LOGLEVEL", PROJECT_NAME.clone());
+ pub static ref LOG_FILE: String = format!("{}.log", env!("CARGO_PKG_NAME"));
+}
+
+fn project_directory() -> Option<ProjectDirs> {
+ ProjectDirs::from("com", "kdheepak", env!("CARGO_PKG_NAME"))
+}
+
+pub fn get_data_dir() -> PathBuf {
+ let directory = if let Some(s) = DATA_FOLDER.clone() {
+ s
+ } else if let Some(proj_dirs) = project_directory() {
+ proj_dirs.data_local_dir().to_path_buf()
+ } else {
+ PathBuf::from(".").join(".data")
+ };
+ directory
+}
+
+pub fn initialize_logging() -> Result<()> {
+ let directory = get_data_dir();
+ std::fs::create_dir_all(directory.clone())?;
+ let log_path = directory.join(LOG_FILE.clone());
+ let log_file = std::fs::File::create(log_path)?;
+ std::env::set_var(
+ "RUST_LOG",
+ std::env::var("RUST_LOG")
+ .or_else(|_| std::env::var(LOG_ENV.clone()))
+ .unwrap_or_else(|_| format!("{}=info", env!("CARGO_CRATE_NAME"))),
+ );
+ let file_subscriber = tracing_subscriber::fmt::layer()
+ .with_file(true)
+ .with_line_number(true)
+ .with_writer(log_file)
+ .with_target(false)
+ .with_ansi(false)
+ .with_filter(tracing_subscriber::filter::EnvFilter::from_default_env());
+ tracing_subscriber::registry().with(file_subscriber).with(ErrorLayer::default()).init();
+ Ok(())
+}
+
+/// Similar to the `std::dbg!` macro, but generates `tracing` events rather
+/// than printing to stdout.
+///
+/// By default, the verbosity level for the generated events is `DEBUG`, but
+/// this can be customized.
+#[macro_export]
+macro_rules! trace_dbg {
+ (target: $target:expr, level: $level:expr, $ex:expr) => {{
+ match $ex {
+ value => {
+ tracing::event!(target: $target, $level, ?value, stringify!($ex));
+ value
+ }
+ }
+ }};
+ (level: $level:expr, $ex:expr) => {
+ trace_dbg!(target: module_path!(), level: $level, $ex)
+ };
+ (target: $target:expr, $ex:expr) => {
+ trace_dbg!(target: $target, level: tracing::Level::DEBUG, $ex)
+ };
+ ($ex:expr) => {
+ trace_dbg!(level: tracing::Level::DEBUG, $ex)
+ };
+}
+Call initialize_logging()? in your main() function.
The log level is decided by the ${YOUR_CRATE_NAME}_LOGLEVEL environment variable (default =
+log::LevelFilter::Info).
Additionally, the location of the log files would be decided by your environment variables. See +the section on XDG directories for more information.
+
+
+
+
+
+Check out tui-logger for setting up a
+tui logger widget with tracing.
Single Tui struct with Terminal and EventHandler
+
+
+
+
+
+This is just one way to setup your application, there are many others. See +Application Patterns for more.
+If you want a tui.rs with Terminal with Deref and DerefMut, and an EventHandler, you can
+use the following code.
Add the following dependencies:
+cargo add ratatui crossterm tokio tokio_util futures # required
+cargo add color_eyre serde serde_derive # optional
+Then you’ll be able write code like this:
+impl App {
+ async fn run(&mut self) -> Result<()> {
+ let mut tui = tui::Tui::new()?;
+ tui.tick_rate(4.0); // 4 ticks per second
+ tui.frame_rate(30.0); // 30 frames per second
+ tui.enter()?; // Starts event handler
+ loop {
+ tui.draw(|f| { // Deref allows calling `tui.draw`
+ self.ui(f);
+ })?;
+
+ if let Some(evt) = tui.next().await { // `tui.next().await` returns next event
+ let mut maybe_action = self.handle_event(evt);
+ while let Some(action) = maybe_action {
+ maybe_action = self.update(action);
+ }
+ };
+
+ if self.should_quit {
+ break;
+ }
+ }
+ tui.exit()?; // Stops event handler
+ Ok(())
+ }
+}You’ll need to copy the code to a ./src/tui.rs:
use std::{
+ ops::{Deref, DerefMut},
+ time::Duration,
+};
+
+use color_eyre::eyre::Result;
+use crossterm::{
+ cursor,
+ event::{Event as CrosstermEvent, KeyEvent, KeyEventKind, MouseEvent},
+ terminal::{EnterAlternateScreen, LeaveAlternateScreen},
+};
+use futures::{FutureExt, StreamExt};
+use ratatui::backend::CrosstermBackend as Backend;
+use serde_derive::{Deserialize, Serialize};
+use tokio::{
+ sync::mpsc::{self, UnboundedReceiver, UnboundedSender},
+ task::JoinHandle,
+};
+use tokio_util::sync::CancellationToken;
+
+pub type Frame<'a> = ratatui::Frame<'a, Backend<std::io::Stderr>>;
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub enum Event {
+ Init,
+ Quit,
+ Error,
+ Closed,
+ Tick,
+ Render,
+ FocusGained,
+ FocusLost,
+ Paste(String),
+ Key(KeyEvent),
+ Mouse(MouseEvent),
+ Resize(u16, u16),
+}
+
+pub struct Tui {
+ pub terminal: ratatui::Terminal<Backend<std::io::Stderr>>,
+ pub task: JoinHandle<()>,
+ pub cancellation_token: CancellationToken,
+ pub event_rx: UnboundedReceiver<Event>,
+ pub event_tx: UnboundedSender<Event>,
+ pub frame_rate: f64,
+ pub tick_rate: f64,
+}
+
+impl Tui {
+ pub fn new() -> Result<Self> {
+ let tick_rate = 4.0; // 4 ticks per second
+ let frame_rate = 30.0; // 30 frames per seconds
+ let terminal = ratatui::Terminal::new(Backend::new(std::io::stderr()))?;
+ let (event_tx, event_rx) = mpsc::unbounded_channel();
+ let cancellation_token = CancellationToken::new();
+ let task = tokio::spawn(async {});
+ Ok(Self { terminal, task, cancellation_token, event_rx, event_tx, frame_rate, tick_rate })
+ }
+
+ pub fn tick_rate(&mut self, tick_rate: f64) {
+ self.tick_rate = tick_rate;
+ }
+
+ pub fn frame_rate(&mut self, frame_rate: f64) {
+ self.frame_rate = frame_rate;
+ }
+
+ pub fn start(&mut self) {
+ let tick_delay = std::time::Duration::from_secs_f64(1.0 / self.tick_rate);
+ let render_delay = std::time::Duration::from_secs_f64(1.0 / self.frame_rate);
+ self.cancel();
+ self.cancellation_token = CancellationToken::new();
+ let _cancellation_token = self.cancellation_token.clone();
+ let _event_tx = self.event_tx.clone();
+ self.task = tokio::spawn(async move {
+ let mut reader = crossterm::event::EventStream::new();
+ let mut tick_interval = tokio::time::interval(tick_delay);
+ let mut render_interval = tokio::time::interval(render_delay);
+ _event_tx.send(Event::Init).unwrap();
+ loop {
+ let tick_delay = tick_interval.tick();
+ let render_delay = render_interval.tick();
+ let crossterm_event = reader.next().fuse();
+ tokio::select! {
+ _ = _cancellation_token.cancelled() => {
+ break;
+ }
+ maybe_event = crossterm_event => {
+ match maybe_event {
+ Some(Ok(evt)) => {
+ match evt {
+ CrosstermEvent::Key(key) => {
+ if key.kind == KeyEventKind::Press {
+ _event_tx.send(Event::Key(key)).unwrap();
+ }
+ },
+ CrosstermEvent::Mouse(mouse) => {
+ _event_tx.send(Event::Mouse(mouse)).unwrap();
+ },
+ CrosstermEvent::Resize(x, y) => {
+ _event_tx.send(Event::Resize(x, y)).unwrap();
+ },
+ CrosstermEvent::FocusLost => {
+ _event_tx.send(Event::FocusLost).unwrap();
+ },
+ CrosstermEvent::FocusGained => {
+ _event_tx.send(Event::FocusGained).unwrap();
+ },
+ CrosstermEvent::Paste(s) => {
+ _event_tx.send(Event::Paste(s)).unwrap();
+ },
+ }
+ }
+ Some(Err(_)) => {
+ _event_tx.send(Event::Error).unwrap();
+ }
+ None => {},
+ }
+ },
+ _ = tick_delay => {
+ _event_tx.send(Event::Tick).unwrap();
+ },
+ _ = render_delay => {
+ _event_tx.send(Event::Render).unwrap();
+ },
+ }
+ }
+ });
+ }
+
+ pub fn stop(&self) -> Result<()> {
+ self.cancel();
+ let mut counter = 0;
+ while !self.task.is_finished() {
+ std::thread::sleep(Duration::from_millis(1));
+ counter += 1;
+ if counter > 50 {
+ self.task.abort();
+ }
+ if counter > 100 {
+ log::error!("Failed to abort task for unknown reason");
+ return Err(color_eyre::eyre::eyre!("Unable to abort task"));
+ }
+ }
+ Ok(())
+ }
+
+ pub fn enter(&mut self) -> Result<()> {
+ crossterm::terminal::enable_raw_mode()?;
+ crossterm::execute!(std::io::stderr(), EnterAlternateScreen, cursor::Hide)?;
+ self.start();
+ Ok(())
+ }
+
+ pub fn exit(&self) -> Result<()> {
+ self.stop()?;
+ crossterm::execute!(std::io::stderr(), LeaveAlternateScreen, cursor::Show)?;
+ crossterm::terminal::disable_raw_mode()?;
+ Ok(())
+ }
+
+ pub fn cancel(&self) {
+ self.cancellation_token.cancel();
+ }
+
+ pub fn suspend(&self) -> Result<()> {
+ self.exit()?;
+ #[cfg(not(windows))]
+ signal_hook::low_level::raise(signal_hook::consts::signal::SIGTSTP)?;
+ Ok(())
+ }
+
+ pub fn resume(&mut self) -> Result<()> {
+ self.enter()?;
+ Ok(())
+ }
+
+ pub async fn next(&mut self) -> Option<Event> {
+ self.event_rx.recv().await
+ }
+}
+
+impl Deref for Tui {
+ type Target = ratatui::Terminal<Backend<std::io::Stderr>>;
+
+ fn deref(&self) -> &Self::Target {
+ &self.terminal
+ }
+}
+
+impl DerefMut for Tui {
+ fn deref_mut(&mut self) -> &mut Self::Target {
+ &mut self.terminal
+ }
+}
+
+impl Drop for Tui {
+ fn drop(&mut self) {
+ self.exit().unwrap();
+ }
+}Setup Panic Hooks
+When building TUIs with ratatui, it’s vital to ensure that if your application encounters a panic,
+it gracefully returns to the original terminal state. This prevents the terminal from getting stuck
+in a modified state, which can be quite disruptive for users.
Here’s an example initialize_panic_handler that works with crossterm and with the Rust standard
+library functionality and no external dependencies.
pub fn initialize_panic_handler() {
+ let original_hook = std::panic::take_hook();
+ std::panic::set_hook(Box::new(move |panic_info| {
+ crossterm::execute!(std::io::stderr(), crossterm::terminal::LeaveAlternateScreen).unwrap();
+ crossterm::terminal::disable_raw_mode().unwrap();
+ original_hook(panic_info);
+ }));
+}With this function, all your need to do is call initialize_panic_handler() in main() before
+running any terminal initialization code:
fn main() -> Result<()> {
+ initialize_panic_handler();
+
+ // Startup
+ crossterm::terminal::enable_raw_mode()?;
+ crossterm::execute!(std::io::stderr(), crossterm::terminal::EnterAlternateScreen)?;
+
+ let mut terminal = Terminal::new(CrosstermBackend::new(std::io::stderr()))?;
+
+ // ...
+
+ // Shutdown
+ crossterm::execute!(std::io::stderr(), crossterm::terminal::LeaveAlternateScreen)?;
+ crossterm::terminal::disable_raw_mode()?;
+ Ok(())
+}We used crossterm for panic handling. If you are using termion you can do something like the
+following:
use std::panic;
+use std::error::Error;
+
+pub fn initialize_panic_handler() {
+ let panic_hook = panic::take_hook();
+ panic::set_hook(Box::new(move |panic| {
+ let panic_cleanup = || -> Result<(), Box<dyn Error>> {
+ let mut output = io::stderr();
+ write!(
+ output,
+ "{}{}{}",
+ termion::clear::All,
+ termion::screen::ToMainScreen,
+ termion::cursor::Show
+ )?;
+ output.into_raw_mode()?.suspend_raw_mode()?;
+ io::stderr().flush()?;
+ Ok(())
+ };
+ panic_cleanup().expect("failed to clean up for panic");
+ panic_hook(panic);
+ }));
+}As a general rule, you want to take the original panic hook and execute it after cleaning up the +terminal. In the next sections we will discuss some third party packages that can help give better +stacktraces.
+Better Panic Hooks using better-panic, color-eyre and human-panic
+Your application may panic for a number of reasons (e.g. when you call .unwrap() on a None). And
+when this happens, you want to be a good citizen and:
-
+
- provide a useful stacktrace so that they can report errors back to you. +
- not leave the users terminal state in a botched condition, resetting it back to the way it was. +
better-panic
+better-panic gives you pretty backtraces for panics.
cargo add better-panic
+Here’s an example of initialize_panic_handler() using better-panic to provide a prettier
+backtrace by default.
use better_panic::Settings;
+
+pub fn initialize_panic_handler() {
+ std::panic::set_hook(Box::new(|panic_info| {
+ crossterm::execute!(std::io::stderr(), crossterm::terminal::LeaveAlternateScreen).unwrap();
+ crossterm::terminal::disable_raw_mode().unwrap();
+ Settings::auto().most_recent_first(false).lineno_suffix(true).create_panic_handler()(panic_info);
+ }));
+}I personally like to reuse the Tui struct in the panic
+handler. That way, if I ever decide to move from crossterm to termion in the future, there’s one
+less place in the project that I have to worry about refactoring.
Here’s an example of initialize_panic_handler() using
+better_panic and
+libc to provide a prettier backtrace by default.
use better_panic::Settings;
+
+pub fn initialize_panic_handler() {
+ std::panic::set_hook(Box::new(|panic_info| {
+ match crate::tui::Tui::new() {
+ Ok(t) => {
+ if let Err(r) = t.exit() {
+ error!("Unable to exit Terminal: {r:?}");
+ }
+ },
+ Err(r) => error!("Unable to exit Terminal: {r:?}"),
+ }
+ better_panic::Settings::auto()
+ .most_recent_first(false)
+ .lineno_suffix(true)
+ .verbosity(better_panic::Verbosity::Full)
+ .create_panic_handler()(panic_info);
+ std::process::exit(libc::EXIT_FAILURE);
+ }));
+}Now, let’s say I added a panic! to
+an application as an example:
diff --git a/src/components/app.rs b/src/components/app.rs
+index 289e40b..de48392 100644
+--- a/src/components/app.rs
++++ b/src/components/app.rs
+@@ -77,6 +77,7 @@ impl App {
+ }
+
+ pub fn increment(&mut self, i: usize) {
++ panic!("At the disco");
+ self.counter = self.counter.saturating_add(i);
+ }
+This is what a prettier stacktrace would look like with better-panic:
Backtrace (most recent call last):
+ File "/Users/kd/gitrepos/ratatui-async-template/src/main.rs:46", in ratatui_async_template::main
+ Ok(())
+ File "/Users/kd/.cargo/registry/src/index.crates.io-6f17d22bba15001f/tokio-1.28.2/src/runtime/runtime.rs:304", in tokio::runtime::runtime::Runtime::block_on
+ Scheduler::MultiThread(exec) => exec.block_on(&self.handle.inner, future),
+ File "/Users/kd/.cargo/registry/src/index.crates.io-6f17d22bba15001f/tokio-1.28.2/src/runtime/scheduler/multi_thread/mod.rs:66", in tokio::runtime::scheduler::multi_thread::MultiThread::block_on
+ enter
+ File "/Users/kd/.cargo/registry/src/index.crates.io-6f17d22bba15001f/tokio-1.28.2/src/runtime/context.rs:315", in tokio::runtime::context::BlockingRegionGuard::block_on
+ park.block_on(f)
+ File "/Users/kd/.cargo/registry/src/index.crates.io-6f17d22bba15001f/tokio-1.28.2/src/runtime/park.rs:283", in tokio::runtime::park::CachedParkThread::block_on
+ if let Ready(v) = crate::runtime::coop::budget(|| f.as_mut().poll(&mut cx)) {
+ File "/Users/kd/.cargo/registry/src/index.crates.io-6f17d22bba15001f/tokio-1.28.2/src/runtime/coop.rs:73", in tokio::runtime::coop::budget
+ with_budget(Budget::initial(), f)
+ File "/Users/kd/.cargo/registry/src/index.crates.io-6f17d22bba15001f/tokio-1.28.2/src/runtime/coop.rs:107", in tokio::runtime::coop::with_budget
+ f()
+ File "/Users/kd/.cargo/registry/src/index.crates.io-6f17d22bba15001f/tokio-1.28.2/src/runtime/park.rs:283", in tokio::runtime::park::CachedParkThread::block_on::{{closure}}
+ if let Ready(v) = crate::runtime::coop::budget(|| f.as_mut().poll(&mut cx)) {
+ File "/Users/kd/gitrepos/ratatui-async-template/src/main.rs:44", in ratatui_async_template::main::{{closure}}
+ runner.run().await?;
+ File "/Users/kd/gitrepos/ratatui-async-template/src/runner.rs:80", in ratatui_async_template:🏃:Runner::run::{{closure}}
+ if let Some(action) = component.update(action.clone())? {
+ File "/Users/kd/gitrepos/ratatui-async-template/src/components/app.rs:132", in <ratatui_async_template::components::app::App as ratatui_async_template::components::Component>::update
+ Action::Increment(i) => self.increment(i),
+ File "/Users/kd/gitrepos/ratatui-async-template/src/components/app.rs:80", in ratatui_async_template::components::app::App::increment
+ panic!("At the disco");
+
+The application panicked (crashed).
+ At the disco
+in src/components/app.rs:80
+thread: main
+With .most_recent_first(false) the last line of the stacktrace is typically where the error has
+occurred. This makes it fast and easy to find the error without having to scroll up the terminal
+history, and iterate on your application rapidly during development.
This kind of detailed stacktrace is only available in debug builds. For release builds, you may get +inlined or truncated stacktraces.
+For example, here’s what I get when I compile with all optimizations on:
+Backtrace (most recent call last):
+ File "<unknown>:0", in __mh_execute_header
+ File "<unknown>:0", in __mh_execute_header
+ File "<unknown>:0", in __mh_execute_header
+ File "<unknown>:0", in __mh_execute_header
+ File "<unknown>:0", in __mh_execute_header
+ File "<unknown>:0", in __mh_execute_header
+ File "<unknown>:0", in __mh_execute_header
+ File "<unknown>:0", in __mh_execute_header
+ File "<unknown>:0", in __mh_execute_header
+ File "<unknown>:0", in __mh_execute_header
+ File "<unknown>:0", in __mh_execute_header
+ File "<unknown>:0", in __mh_execute_header
+ File "<unknown>:0", in __mh_execute_header
+
+The application panicked (crashed).
+ At the disco
+in src/components/app.rs:80
+thread: main
+This is not particularly useful to show to the average user. We’ll discuss better solutions for what +to show the users of your application in the following subsections.
+color-eyre panic hook
+Another way to manage printing of stack-traces is by using
+color-eyre:
cargo add color-eyre
+color-eyre has a panic hook that is better suited for users in my opinion.
+
+
+
+
+You will also want to add a repository key to your Cargo.toml file:
repository = "https://github.com/ratatui-org/ratatui-async-template" # used by env!("CARGO_PKG_REPOSITORY")
+When a panic! occurs, after the application cleanly restores the terminal, we can print out a nice
+error message created by color-eyre like so:
The application panicked (crashed).
+Message: At the disco
+Location: src/components/app.rs:80
+
+This is a bug. Consider reporting it at https://github.com/ratatui-org/ratatui-async-template
+
+Backtrace omitted. Run with RUST_BACKTRACE=1 environment variable to display it.
+Run with RUST_BACKTRACE=full to include source snippets.
+This is short and clear, providing a link to the user to report the bug.
+Users can also opt to give you a more detailed stacktrace if they can reproduce the error (with a
+debug build and with export RUST_BACKTRACE=1):
The application panicked (crashed).
+Message: At the disco
+Location: src/components/app.rs:80
+
+This is a bug. Consider reporting it at https://github.com/ratatui-org/ratatui-async-template
+
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ BACKTRACE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ ⋮ 13 frames hidden ⋮
+ 14: ratatui_async_template::components::app::App::increment::h4e8b6e0d83d3d575
+ at /Users/kd/gitrepos/ratatui-async-template/src/components/app.rs:80
+ 15: <ratatui_async_template::components::app::App as ratatui_async_template::components::Component>::update::hc78145b4a91e06b6
+ at /Users/kd/gitrepos/ratatui-async-template/src/components/app.rs:132
+ 16: ratatui_async_template:🏃:Runner::run::{{closure}}::h802b0d3c3413762b
+ at /Users/kd/gitrepos/ratatui-async-template/src/runner.rs:80
+ 17: ratatui_async_template::main::{{closure}}::hd78d335f19634c3f
+ at /Users/kd/gitrepos/ratatui-async-template/src/main.rs:44
+ 18: tokio::runtime::park::CachedParkThread::block_on::{{closure}}::hd7949515524de9f8
+ at /Users/kd/.cargo/registry/src/index.crates.io-6f17d22bba15001f/tokio-1.28.2/src/runtime/park.rs:283
+ 19: tokio::runtime::coop::with_budget::h39648e20808374d3
+ at /Users/kd/.cargo/registry/src/index.crates.io-6f17d22bba15001f/tokio-1.28.2/src/runtime/coop.rs:107
+ 20: tokio::runtime::coop::budget::h653c1593abdd982d
+ at /Users/kd/.cargo/registry/src/index.crates.io-6f17d22bba15001f/tokio-1.28.2/src/runtime/coop.rs:73
+ 21: tokio::runtime::park::CachedParkThread::block_on::hb0a0dd4a7c3cf33b
+ at /Users/kd/.cargo/registry/src/index.crates.io-6f17d22bba15001f/tokio-1.28.2/src/runtime/park.rs:283
+ 22: tokio::runtime::context::BlockingRegionGuard::block_on::h4d02ab23bd93d0fd
+ at /Users/kd/.cargo/registry/src/index.crates.io-6f17d22bba15001f/tokio-1.28.2/src/runtime/context.rs:315
+ 23: tokio::runtime::scheduler::multi_thread::MultiThread::block_on::h8aaba9030519c80d
+ at /Users/kd/.cargo/registry/src/index.crates.io-6f17d22bba15001f/tokio-1.28.2/src/runtime/scheduler/multi_thread/mod.rs:66
+ 24: tokio::runtime::runtime::Runtime::block_on::h73a6fbfba201fac9
+ at /Users/kd/.cargo/registry/src/index.crates.io-6f17d22bba15001f/tokio-1.28.2/src/runtime/runtime.rs:304
+ 25: ratatui_async_template::main::h6da543b193746523
+ at /Users/kd/gitrepos/ratatui-async-template/src/main.rs:46
+ 26: core::ops::function::FnOnce::call_once::h6cac3edc975fcef2
+ at /rustc/eb26296b556cef10fb713a38f3d16b9886080f26/library/core/src/ops/function.rs:250
+ ⋮ 13 frames hidden ⋮
+human-panic
+To use human-panic, you’ll have to install it as a +dependency:
+cargo add human-panic
+Personally, I think human-panic provides the most user friendly panic handling functionality out
+of the box when users experience an unexpected panic:
Well, this is embarrassing.
+
+ratatui-async-template had a problem and crashed. To help us diagnose the problem you can send us a crash report.
+
+We have generated a report file at "/var/folders/l4/bnjjc6p15zd3jnty8c_qkrtr0000gn/T/report-ce1e29cb-c17c-4684-b9d4-92d9678242b7.toml". Submit an issue or email with the subject of "ratatui-async-template Crash Report" and include the report as an attachment.
+
+- Authors: Dheepak Krishnamurthy
+
+We take privacy seriously, and do not perform any automated error collection. In order to improve the software, we rely on people to submit reports.
+
+Thank you kindly!
+It generates a report where information relevant to the crash is logged. Here’s the content of the
+temporary report file that human-panic creates (with optimizations turned on):
name = "ratatui-async-template"
+operating_system = "Mac OS 13.5.2 [64-bit]"
+crate_version = "0.1.0"
+explanation = """
+Panic occurred in file 'src/components/app.rs' at line 80
+"""
+cause = "At the disco"
+method = "Panic"
+backtrace = """
+
+ 0: 0x10448f5f8 - __mh_execute_header
+ 1: 0x1044a43c8 - __mh_execute_header
+ 2: 0x1044a01ac - __mh_execute_header
+ 3: 0x10446f8c0 - __mh_execute_header
+ 4: 0x1044ac850 - __mh_execute_header"""
+In debug mode, the stacktrace is as descriptive as earlier.
+Configuration
+You can mix and match these different panic handlers, using better-panic for debug builds and
+color-eyre and human-panic for release builds. The code below also prints the color-eyre
+stacktrace to log::error! for good measure (after striping ansi escape sequences).
cargo add color-eyre human-panic libc better-panic strip-ansi-escapes
+Here’s code you can copy paste into your project (if you use the
+Tui struct to handle terminal exits):
pub fn initialize_panic_handler() -> Result<()> {
+ let (panic_hook, eyre_hook) = color_eyre::config::HookBuilder::default()
+ .panic_section(format!("This is a bug. Consider reporting it at {}", env!("CARGO_PKG_REPOSITORY")))
+ .display_location_section(true)
+ .display_env_section(true)
+ .into_hooks();
+ eyre_hook.install()?;
+ std::panic::set_hook(Box::new(move |panic_info| {
+ if let Ok(t) = crate::tui::Tui::new() {
+ if let Err(r) = t.exit() {
+ error!("Unable to exit Terminal: {:?}", r);
+ }
+ }
+
+ let msg = format!("{}", panic_hook.panic_report(panic_info));
+ #[cfg(not(debug_assertions))]
+ {
+ eprintln!("{}", msg); // prints color-eyre stack trace to stderr
+ use human_panic::{handle_dump, print_msg, Metadata};
+ let meta = Metadata {
+ version: env!("CARGO_PKG_VERSION").into(),
+ name: env!("CARGO_PKG_NAME").into(),
+ authors: env!("CARGO_PKG_AUTHORS").replace(':', ", ").into(),
+ homepage: env!("CARGO_PKG_HOMEPAGE").into(),
+ };
+
+ let file_path = handle_dump(&meta, panic_info);
+ // prints human-panic message
+ print_msg(file_path, &meta).expect("human-panic: printing error message to console failed");
+ }
+ log::error!("Error: {}", strip_ansi_escapes::strip_str(msg));
+
+ #[cfg(debug_assertions)]
+ {
+ // Better Panic stacktrace that is only enabled when debugging.
+ better_panic::Settings::auto()
+ .most_recent_first(false)
+ .lineno_suffix(true)
+ .verbosity(better_panic::Verbosity::Full)
+ .create_panic_handler()(panic_info);
+ }
+
+ std::process::exit(libc::EXIT_FAILURE);
+ }));
+ Ok(())
+}Migrate from tui-rs
+Ratatui is a fork of +tui-rs, created to continue maintenance of the project.
+Several options are available to migrate apps and libs:
+-
+
- Use
ratatuias a drop in replacement aliased as tui
+ - Replace
ratatuifully
+ - Support both
tuiandratatui(useful for libraries)
+
Drop in replacement
+The simplest approach to migrating to ratatui is to use it as drop in replacement for tui and
+updating the terminal libraries used (crossterm / termion). E.g.:
tui = { package = "ratatui", version = "0.21.0", features = ["crossterm"] }
+crossterm = { version = "0.26.1" }
+Or:
+tui = { package = "ratatui", version = "0.21.0", default-features = false, features = ["termion"] }
+termion = { version = "2.0" }
+Fully replace Tui with Ratatui
+Most new code would instead use the following. To take this approach to migration requires find and
+replace tui::->ratatui:: on the entire codebase.
ratatui = { version = "0.21.0" }
+crossterm = { version = "0.26.1" }
+Support both tui and ratatui
+For more complex scenarios where a library (or in some cases an app) needs to support both ratatui +and maintain existing support for tui, it may be feasible to use feature flags to select which +library to use. See tui-logger for an example of this +approach.
+Backwards compatibility and breaking changes
+You can see the list of breaking changes here
+FAQ
+ +Why am I getting duplicate key events on Windows?
+A lot of examples out there in the wild might use the following code for sending key presses:
+ CrosstermEvent::Key(e) => tx.send(Event::Key(e)),However, on Windows, when using Crossterm, this will send the same Event::Key(e) twice; one for
+when you press the key, i.e. KeyEventKind::Press and one for when you release the key, i.e.
+KeyEventKind::Release. On MacOS and Linux only KeyEventKind::Press kinds of key event is
+generated.
To make the code work as expected across all platforms, you can do this instead:
+ CrosstermEvent::Key(key) => {
+ if key.kind == KeyEventKind::Press {
+ event_tx.send(Event::Key(key)).unwrap();
+ }
+ },When should I use tokio and async/await?
+ratatui isn’t a native async library. So is it beneficial to use tokio or async/await?
And as a user, there really is only one point of interface with the ratatui library and that’s the
+terminal.draw(|f| ui(f)) functionality, because the rendering of widgets happens in ui(f).
+Everything else in your code is your own to do as you wish.
Should terminal.draw(|f| ui(f)) be async? Possibly. Rendering to the terminal buffer is
+relatively fast, especially using the double buffer technique that only renders diffs that ratatui
+uses.
Can we make it async ourselves? Yes, we can. Check out
+https://github.com/ratatui-org/ratatui-async-template for an example.
The only other part related to ratatui that is beneficial to being async is reading the key
+event inputs from stdin, and that can be made async with crossterm’s event-stream.
So the real question is what other parts of your app require async or benefit from being async?
+If the answer is not much, maybe it is simpler to not use async and avoiding tokio.
Another way to think about it is, do you think your app would work better with 1 thread like this?
+ +Or would it work with 3 threads / tokio tasks like this:
The former can be done without any async code and the latter is the approach showcased in
+ratatui-async-template with tokio.
tui.rs history
+This project was forked from tui-rs in February 2023, with
+the blessing of the original author, Florian Dehau
+(@fdehau).
The original repository contains all the issues, PRs and discussion that were raised originally, and +it is useful to refer to when contributing code, documentation, or issues with Ratatui.
+We imported all the PRs from the original repository and implemented many of the smaller ones and +made notes on the leftovers. These are marked as draft PRs and labelled as +imported from tui. +We have documented the current state of those PRs, and anyone is welcome to pick them up and +continue the work on them.
+We have not imported all issues opened on the previous repository. For that reason, anyone wanting +to work on or discuss an issue will have to follow the following workflow:
+-
+
- Recreate the issue +
- Start by referencing the original issue:
+
Referencing issue #[<issue number>](<original issue link>)
+ - Then, paste the original issues opening text +
You can then resume the conversation by replying to the new issue you have created.
+ratatui vs tui-realm
+Fundamentally, the difference is that ratatui is a library but
+tui-realm is a framework.
The terms library and framework are often used interchangeably in software development, but they +serve different purposes and have distinct characteristics.
+Library
+-
+
- Usage: A library is a collection of functions and procedures that a programmer can call in +their application. The library provides specific functionality, but it’s the developer’s +responsibility to explicitly call and use it. +
- Control Flow: In the case of a library, the control flow remains with the developer’s +application. The developer chooses when and where to use the library. +
- Passivity: Libraries are passive in nature. They wait for the application’s code to invoke +their methods. +
- Example: Imagine you’re building a house. A library would be like a toolbox with tools +(functions) that you can use at will. You decide when and where to use each tool. +
Framework
+-
+
- Usage: A framework is a pre-built structure or scaffold that developers build their +application within. It provides a foundation, enforcing a particular way of creating an +application. +
- Control Flow: With a framework, the control flow is inverted. The framework decides the flow +of control by providing places for the developer to plug in their own logic (often referred to as +“Inversion of Control” or IoC). +
- Activeness: Frameworks are active and have a predefined flow of their own. The developer fills +in specific pieces of the framework with their own code. +
- Example: Using the house-building analogy, a framework would be like a prefabricated house +where the main structure is already built. You’re tasked with filling in the interiors and decor, +but you have to follow the design and architecture already provided by the prefabricated design. +
While ratatui provides tools (widgets) for building terminal UIs, it doesn’t dictate or enforce a
+specific way to structure your application. You need to decide how to best use the library in your
+particular context, giving you more flexibility.
In contrast, tui-realm might provide more guidelines and enforcements about how your application
+should be structured or how data flows through it. And, for the price of that freedom, you get more
+features out of the box with tui-realm and potentially lesser code in your application to do the
+same thing that you would with ratatui.
Concepts
+In this section, we will cover various concepts associated with terminal user interfaces, such as:
+-
+
- Application patterns +
- Event handling +
- Storing state +
- Rendering +
Backends
+Ratatui interfaces with the terminal emulator through a backend. These libraries enable Ratatui via
+the Terminal type to draw styled text to the screen, manipulate the cursor, and interrogate
+properties of the terminal such as the console or window size. You application will generally also
+use the backend directly to capture keyboard, mouse and window events, and enable raw mode and the
+alternate screen.
Ratatui supports the following backends:
+-
+
- Crossterm via
CrosstermBackendand thecrossterm(enabled by default).
+ - Termion via
TermionBackendand thetermionfeature.
+ - Termwiz via
TermwizBackendand thetermionfeature.
+ - A
TestBackendwhich can be useful to unit test your application’s UI
+
For information on how to choose a backend see: Comparison
+Each backend supports Raw Mode (which changes how the terminal handles input and +output processing), an Alternate Screen which allows it to render to a +separate buffer than your shell commands use, and Mouse Capture, which allows +your application to capture mouse events.
+Comparison of Backends
+
+
+
+
+
+Choose Crossterm for most tasks.
+Ratatui interfaces with the terminal emulator through its “backends”. These are powerful libraries
+that grant ratatui the ability to capture keypresses, maneuver the cursor, style the text with
+colors and other features. As of now, ratatui supports three backends:
Selecting a backend does influence your project’s structure, but the core functionalities remain +consistent across all options. Here’s a flowchart that can help you make your decision.
+graph TD; + Q1[Is the TUI only for Wezterm users?] + Q2[Is Windows compatibility important?] + Q3[Are you familiar with Crossterm?] + Q4[Are you familiar with Termion?] + Crossterm + Termwiz + Termion + + Q1 -->|Yes| Termwiz + Q1 -->|No| Q2 + Q2 -->|Yes| Crossterm + Q2 -->|No| Q3 + Q3 -->|Yes| Crossterm + Q3 -->|No| Q4 + Q4 -->|Yes| Termion + Q4 -->|No| Crossterm ++
Though we try to make sure that all backends are fully-supported, the most commonly-used backend is +Crossterm. If you have no particular reason to use Termion or Termwiz, you will find it easiest to +learn Crossterm simply due to its popularity.
+Raw Mode
+Raw mode is a mode where the terminal does not perform any processing or handling of the input and
+output. This means that features such as echoing input characters, line buffering, and special
+character processing (e.g., CTRL-C or SIGINT) are disabled. This is useful for applications that
+want to have complete control over the terminal input and output, processing each keystroke
+themselves.
For example, in raw mode, the terminal will not perform line buffering on the input, so the +application will receive each key press as it is typed, instead of waiting for the user to press +enter. This makes it suitable for real-time applications like text editors, terminal-based games, +and more.
+Each backend handles raw mode differently, so the behavior may vary depending on the backend being +used. Be sure to consult the backend’s specific documentation for exact details on how it implements +raw mode.
+ +Alternate Screen
+The alternate screen is a separate buffer that some terminals provide, distinct from the main +screen. When activated, the terminal will display the alternate screen, hiding the current content +of the main screen. Applications can write to this screen as if it were the regular terminal +display, but when the application exits, the terminal will switch back to the main screen, and the +contents of the alternate screen will be cleared. This is useful for applications like text editors +or terminal games that want to use the full terminal window without disrupting the command line or +other terminal content.
+This creates a seamless transition between the application and the regular terminal session, as the +content displayed before launching the application will reappear after the application exits.
+Note that not all terminal emulators support the alternate screen, and even those that do may handle +it differently. As a result, the behavior may vary depending on the backend being used. Always +consult the specific backend’s documentation to understand how it implements the alternate screen.
+Mouse Capture
+Mouse capture is a mode where the terminal captures mouse events such as clicks, scrolls, and +movement, and sends them to the application as special sequences or events. This enables the +application to handle and respond to mouse actions, providing a more interactive and graphical user +experience within the terminal. It’s particularly useful for applications like terminal-based games, +text editors, or other programs that require more direct interaction from the user.
+Each backend handles mouse capture differently, with variations in the types of events that can be +captured and how they are represented. As such, the behavior may vary depending on the backend being +used, and developers should consult the specific backend’s documentation to understand how it +implements mouse capture.
+Rendering
+The world of UI development consists mainly of two dominant paradigms: retained mode and immediate
+mode. Most traditional GUI libraries operate under the retained mode paradigm. However, ratatui
+employs the immediate mode rendering approach. for TUI development.
This makes ratatui is different from GUI frameworks you might use, because it only updates when
+you tell it to.
What is Immediate Mode Rendering?
+Immediate mode rendering is a UI paradigm where the UI is recreated every frame. Instead of creating +a fixed set of UI widgets and updating their state, you “draw” your UI from scratch in every frame +based on the current application state.
+In a nutshell:
+-
+
- Retained Mode: You set up your UI once, create widgets, and later modify their properties or +handle their events. +
- Immediate Mode: You redraw your UI every frame based on your application state. There’s no +permanent widget object in memory. +
In ratatui, every frame draws the UI anew.
loop {
+ terminal.draw(|f| {
+ if state.condition {
+ f.render_widget(SomeWidget::new(), layout);
+ } else {
+ f.render_widget(AnotherWidget::new(), layout);
+ }
+ })?;
+}This article and the accompanying YouTube video is worth your +time if you are new to the immediate mode rendering paradigm.
+ +This 4 minute talk about IMGUI is also tangentially relevant.
Advantages of Immediate Mode Rendering
+-
+
- Simplicity: Without a persistent widget state, your UI logic becomes a direct reflection of +your application state. You don’t have to sync them or worry about past widget states. +
- Flexibility: You can change your UI layout or logic any time, as nothing is set in stone. Want +to hide a widget conditionally? Just don’t draw it based on some condition. +
Disadvantages of Immediate Mode Rendering
+-
+
- Render loop management: In Immediate mode rendering, the onus of rendering lies solely on the
+programmer. Every visual update necessitates a call to
Backend.draw(). Hence, if the rendering +thread is inadvertently blocked, the UI will not update until the thread resumes.
+
+
+
+
+
+The ratatui library in particular only handles how widget would be rendered to a “Backend”, e.g.
+crossterm. The Backend in question would use an external crate e.g. crossterm for actually
+drawing to the terminal.
-
+
-
+
Event loop orchestration: Along with managing “the render loop”, developers are also +responsible for handling “the event loop”. This involves deciding on a third-party library for the +job.
+crosstermis a popular crate to handle key inputs and you’ll find plenty of examples in the +repository and online for how to use it.crosstermalso supports aasyncevent stream, if you +are interested in usingtokio.
+ -
+
Architecture design considerations: With
+ratatui, out of the box, there’s little to no help +in organizing large applications. Ultimately, the decision on structure and discipline rests with +the developer to be principled.
+
Event Handling
+There are many ways to handle events with the ratatui library. Mostly becuase ratatui does not
+directly expose any event catching; the programmer will depend on the chosen backend’s library.
However, there are a few ways to think about event handling that may help you. While this is not an +exhaustive list, it covers a few of the more common implementations. But remember, the correct way, +is the one that works for you and your current application.
+Centralized event handling
+This is the simplest way to handle events because it handles all of the events as they appear. It is
+often simply a match on the results of event::read()? (in crossterm) on the different supported
+keys. Pros: This has the advantage of requiring no message passing, and allows the programmer to
+edit all of the possible keyboard events in one place.
Cons: However, this particular way of handling events simply does not scale well. Because all +events are handled in one place, you will be unable to split different groups of keybinds out into +separate locations.
+Centralized catching, message passing
+This way of handling events involves polling for events in one place, and then sending +messages/calling sub functions with the event that was caught. Pros: This has a similar appeal to +the first method in its simplicity. With this paradigm, you can easily split extensive pattern +matching into sub functions that can go in separate files. This way is also the idea often used in +basic multi-threaded applications because message channels are used to pass multi-threaded safe +messages.
+Cons: This method requires a main loop to be running to consistently poll for events in a +centralized place.
+Distributed event loops/segmented applications
+In this style, control of the Terminal and the main loop to a sub-module. In this case, the entire
+rendering and event handling responsibilities can be safely passed to the sub-module. In theory, an
+application built like this doesn’t need a centralized event listener. Pros: There is no centralized
+event loop that you need to update whenever a new sub-module is created.
Cons: However, if several sub-modules in your application have similar event handling loops, this +way could lead to a lot of duplicated code.
+Application Patterns
+This page covers several patterns one can use for their application and acts as a top-level page for +the following articles where these patterns are gone into more in-depth.
+ +Using The Elm Architecture (TEA) with ratatui
+When building terminal user interfaces (TUI) with ratatui, it’s helpful to have a solid structure
+for organizing your application. One proven architecture comes from the Elm language, known simply
+as The Elm Architecture (TEA).
+
+
+
+
+If you are interested in a framework that uses ratatui that is based on The Elm Architecture,
+you should check out https://github.com/veeso/tui-realm/.
+The documentation on this page is for theoretical understanding and pedagogical purposes only.
In this section, we’ll explore how to apply The Elm Architecture principles to ratatui TUI apps.
The Elm Architecture: A Quick Overview
+At its core, TEA is split into three main components:
+-
+
- Model: This is your application’s state. It contains all the data your application works with. +
- Update: When there’s a change (like user input), the update function takes the current model +and the input, and produces a new model. +
- View: This function is responsible for displaying your model to the user. In Elm, it produces +HTML. In our case, it’ll produce terminal UI elements. +
sequenceDiagram +participant User +participant TUI Application + +User->>TUI Application: Input/Event/Message +TUI Application->>TUI Application: Update (based on Model and Message) +TUI Application->>TUI Application: Render View (from Model) +TUI Application-->>User: Display UI ++
Applying The Elm Architecture to ratatui
+Following TEA principles typically involves ensuring that you do the following things:
+-
+
- Define Your Model +
- Handling Updates +
- Rendering the View +
1. Define Your Model
+In ratatui, you’ll typically use a struct to represent your model:
struct Model {
+ //... your application's data goes here
+}For a counter app, our model may look like this:
+struct Model {
+ counter: i32,
+ should_quit: bool,
+}2. Handling Updates
+Updates in TEA are actions triggered by events, such as user inputs. The core idea is to map each of +these actions or events to a message. This can be achieved by creating an enum to keep track of +messages. Based on the received message, the current state of the model is used to determine the +next state.
+Defining a Message enum
enum Message {
+ //... various inputs or actions that your app cares about
+ // e.g., ButtonPressed, TextEntered, etc.
+}For a counter app, our Message enum may look like this:
enum Message {
+ Increment,
+ Decrement,
+ Reset,
+ Quit,
+}update() function
The update function is at the heart of this process. It takes the current model and a message, and +decides how the model should change in response to that message.
+A key feature of TEA is immutability. Hence, the update function should avoid direct mutation of the +model. Instead, it should produce a new instance of the model reflecting the desired changes.
+fn update(model: &Model, msg: Message) -> Model {
+ match msg {
+ // Match each possible message and decide how the model should change
+ // Return a new model reflecting those changes
+ }
+}In TEA, it’s crucial to maintain a clear separation between the data (model) and the logic that +alters it (update). This immutability principle ensures predictability and makes the application +easier to reason about.
+
+
+
+
+
+Hence, while immutability is emphasized in TEA, Rust developers can choose the most +suitable approach based on performance and their application’s needs.
+For example, it would be perfectly valid to do the following:
+fn update(model: &mut Model, msg: Message) {
+ match msg {
+ // Match each possible message and decide how the model should change
+ // Modify existing mode reflecting those changes
+ };
+}In TEA, the update() function can not only modify the model based on the Message, but it can
+also return another Message. This design can be particularly useful if you want to chain messages
+or have an update lead to another update.
For example, this is what the update() function may look like for a counter app:
fn update(model: &mut Model, msg: Message) -> Option<Message> {
+ match msg {
+ Message::Increment => {
+ model.counter += 1;
+ if model.counter > 50 {
+ return Some(Message::Reset);
+ }
+ },
+ Message::Decrement => {
+ model.counter -= 1;
+ if model.counter < -50 {
+ return Some(Message::Reset);
+ }
+ },
+ Message::Reset => {
+ model.counter = 0;
+ },
+ Message::Quit => {
+ model.should_quit = true;
+ },
+ _ => {},
+ }
+ None // Default return value if no specific message is to be returned
+}
+
+
+
+
+Remember that this design choice means that the main loop will need to handle the
+returned message, calling update() again based on that returned message.
Returning a Message from the update() function allows a developer to reason about their code as
+a “Finite State Machine”. Finite State Machines operate on defined states and transitions, where an
+initial state and an event (in our case, a Message) lead to a subsequent state. This cascading
+approach ensures that the system remains in a consistent and predictable state after handling a
+series of interconnected events.
Here’s a state transition diagram of the counter example from above:
+stateDiagram-v2
+ state Model {
+ counter : counter = 0
+ should_quit : should_quit = false
+ }
+
+ Model --> Increment
+ Model --> Decrement
+ Model --> Reset
+ Model --> Quit
+
+ Increment --> Model: counter += 1
+ Increment --> Reset: if > 50
+
+ Decrement --> Model: counter -= 1
+ Decrement --> Reset: if < -50
+
+ Reset --> Model: counter = 0
+
+ Quit --> break: should_quit = true
+
+While TEA doesn’t use the Finite State Machine terminology or strictly enforce that paradigm, +thinking of your application’s state as a state machine can allow developers to break down intricate +state transitions into smaller, more manageable steps. This can make designing the application’s +logic clearer and improve code maintainability.
+3. Rendering the View
+The view function in the Elm Architecture is tasked with taking the current model and producing a +visual representation for the user. In the case of ratatui, it translates the model into terminal UI +elements. It’s essential that the view function remains a pure function: for a given state of the +model, it should always produce the same UI representation.
+fn view(model: &Model) {
+ //... use `ratatui` functions to draw your UI based on the model's state
+}Every time the model is updated, the view function should be capable of reflecting those changes +accurately in the terminal UI.
+In TEA, you are expected to ensure that your view function is side-effect free. The view()
+function shouldn’t modify global state or perform any other actions. Its sole job is to map the
+model to a visual representation.
For a given state of the model, the view function should always produce the same visual output. This +predictability makes your TUI application easier to reason about and debug.
+
+
+
+
+
+With immediate mode rendering you may run into an issue: the view function is only aware of the
+area available to draw in at render time.
This limitation is a recognized constraint of immediate mode GUIs. Overcoming it often involves +trade-offs. One common solution is to store the drawable size and reference it in the subsequent +frame, although this can introduce a frame delay in layout adjustments, leading to potential +flickering during the initial rendering when changes in screen size occur.
+An alternative would be using the Resize event from crossterm and to clear the UI and force
+redraw everything during that event.
In ratatui, there are
+StatefulWidgets which
+require a mutable reference to state during render.
For this reason, you may choose to forego the view immutability principle. For example, if you
+were interested in rendering a List, your view function may look like this:
fn view(model: &mut Model, f: &mut Frame) {
+ let items = app.items.items.iter().map(|element| ListItem::new(element)).collect();
+ f.render_stateful_widget(List::new(items), f.size(), &mut app.items.state);
+}
+
+fn main() {
+ loop {
+ ...
+ terminal
+ .draw(|f| {
+ view(&mut model, f);
+ })?;
+ ...
+ }
+}Another advantage of having access to the Frame in the view() function is that you have access
+to setting the cursor position, which is useful for displaying text fields. For example, if you
+wanted to draw an input field using tui-input, you
+might have a view that looks like this:
fn view(model: &mut Model, f: &mut Frame) {
+ let area = f.size();
+ let input = Paragraph::new(app.input.value());
+ f.render_widget(input, area);
+ if app.mode == Mode::Insert {
+ f.set_cursor(
+ (area.x + 1 + self.input.cursor() as u16).min(area.x + area.width - 2),
+ area.y + 1
+ )
+ }
+}Putting it all together
+When you put it all together, your main application loop might look something like:
+-
+
- Listen for user input. +
- Map input to a
Message
+ - Pass that message to the update function. +
- Draw the UI with the view function. +
This cycle repeats, ensuring your TUI is always up-to-date with user interactions.
+As an illustrative example, here’s the Counter App +refactored using TEA.
+The notable difference from before is that we have an Model struct that captures the app state,
+and a Message enum that captures the various actions your app can take.
// cargo add anyhow ratatui crossterm
+use anyhow::Result;
+use ratatui::{
+ prelude::{CrosstermBackend, Terminal},
+ widgets::Paragraph,
+};
+
+pub type Frame<'a> = ratatui::Frame<'a, ratatui::backend::CrosstermBackend<std::io::Stderr>>;
+
+// MODEL
+struct Model {
+ counter: i32,
+ should_quit: bool,
+}
+
+// MESSAGES
+#[derive(PartialEq)]
+enum Message {
+ Increment,
+ Decrement,
+ Reset,
+ Quit,
+}
+
+// UPDATE
+fn update(model: &mut Model, msg: Message) -> Option<Message> {
+ match msg {
+ Message::Increment => {
+ model.counter += 1;
+ if model.counter > 50 {
+ return Some(Message::Reset);
+ }
+ },
+ Message::Decrement => {
+ model.counter -= 1;
+ if model.counter < -50 {
+ return Some(Message::Reset);
+ }
+ },
+ Message::Reset => model.counter = 0,
+ Message::Quit => model.should_quit = true, // You can handle cleanup and exit here
+ };
+ None
+}
+
+// VIEW
+fn view(model: &mut Model, f: &mut Frame) {
+ f.render_widget(Paragraph::new(format!("Counter: {}", model.counter)), f.size());
+}
+
+// Convert Event to Message
+// We don't need to pass in a `model` to this function in this example
+// but you might need it as your project evolves
+fn handle_event(_: &Model) -> Result<Option<Message>> {
+ let message = if crossterm::event::poll(std::time::Duration::from_millis(250))? {
+ if let crossterm::event::Event::Key(key) = crossterm::event::read()? {
+ match key.code {
+ crossterm::event::KeyCode::Char('j') => Message::Increment,
+ crossterm::event::KeyCode::Char('k') => Message::Decrement,
+ crossterm::event::KeyCode::Char('q') => Message::Quit,
+ _ => return Ok(None),
+ }
+ } else {
+ return Ok(None);
+ }
+ } else {
+ return Ok(None);
+ };
+ Ok(Some(message))
+}
+
+pub fn initialize_panic_handler() {
+ let original_hook = std::panic::take_hook();
+ std::panic::set_hook(Box::new(move |panic_info| {
+ crossterm::execute!(std::io::stderr(), crossterm::terminal::LeaveAlternateScreen).unwrap();
+ crossterm::terminal::disable_raw_mode().unwrap();
+ original_hook(panic_info);
+ }));
+}
+
+fn main() -> Result<()> {
+ initialize_panic_handler();
+
+ // Startup
+ crossterm::terminal::enable_raw_mode()?;
+ crossterm::execute!(std::io::stderr(), crossterm::terminal::EnterAlternateScreen)?;
+
+ let mut terminal = Terminal::new(CrosstermBackend::new(std::io::stderr()))?;
+ let mut model = Model { counter: 0, should_quit: false };
+
+ loop {
+ // Render the current view
+ terminal.draw(|f| {
+ view(&mut model, f);
+ })?;
+
+ // Handle events and map to a Message
+ let mut current_msg = handle_event(&model)?;
+
+ // Process updates as long as they return a non-None message
+ while current_msg != None {
+ current_msg = update(&mut model, current_msg.unwrap());
+ }
+
+ // Exit loop if quit flag is set
+ if model.should_quit {
+ break;
+ }
+ }
+
+ // Shutdown
+ crossterm::execute!(std::io::stderr(), crossterm::terminal::LeaveAlternateScreen)?;
+ crossterm::terminal::disable_raw_mode()?;
+ Ok(())
+}Component Architecture
+If you are interested in a more object oriented approach to organizing TUIs, you can use a
+Component based approach.
A couple of projects in the wild use this approach
+ +We also have a ratatui-async-template that has an example of this Component based approach:
We already covered TEA in the previous section. The Component
+architecture takes a slightly more object oriented trait based approach.
Each component encapsulates its own state, event handlers, and rendering logic.
+-
+
-
+
Component Initialization (
+init) - This is where a component can set up any initial state or +resources it needs. It’s a separate process from handling events or rendering.
+ -
+
Event Handling (
+handle_events,handle_key_events,handle_mouse_events) - Each component has +its own event handlers. This allows for a finer-grained approach to event handling, with each +component only dealing with the events it’s interested in. This contrasts with Elm’s single +update function that handles messages for the entire application.
+ -
+
State Update (
+update) - Components can have their own local state and can update it in response +to actions. This state is private to the component, which differs from Elm’s global model.
+ -
+
Rendering (
+render) - Each component defines its own rendering logic. It knows how to draw +itself, given a rendering context. This is similar to Elm’s view function but on a +component-by-component basis.
+
Here’s an example of the Component trait implementation you might use:
use anyhow::Result;
+use crossterm::event::{KeyEvent, MouseEvent};
+use ratatui::layout::Rect;
+
+use crate::{action::Action, event::Event, terminal::Frame};
+
+pub trait Component {
+ fn init(&mut self) -> Result<()> {
+ Ok(())
+ }
+ fn handle_events(&mut self, event: Option<Event>) -> Action {
+ match event {
+ Some(Event::Quit) => Action::Quit,
+ Some(Event::Tick) => Action::Tick,
+ Some(Event::Key(key_event)) => self.handle_key_events(key_event),
+ Some(Event::Mouse(mouse_event)) => self.handle_mouse_events(mouse_event),
+ Some(Event::Resize(x, y)) => Action::Resize(x, y),
+ Some(_) => Action::Noop,
+ None => Action::Noop,
+ }
+ }
+ fn handle_key_events(&mut self, key: KeyEvent) -> Action {
+ Action::Noop
+ }
+ fn handle_mouse_events(&mut self, mouse: MouseEvent) -> Action {
+ Action::Noop
+ }
+ fn update(&mut self, action: Action) -> Action {
+ Action::Noop
+ }
+ fn render(&mut self, f: &mut Frame<'_>, rect: Rect);
+}One advantage of this approach is that it incentivizes co-locating the handle_events, update and
+render functions on a component level.
Flux Architecture
+Flux is a design pattern
+introduced by Facebook to address the challenges of building large scale web applications. Though
+originally designed with web applications in mind, the Flux architecture can be applied to any
+client-side project, including terminal applications. Here’s real world example of using the Flux
+architecture with ratatui: https://github.com/Yengas/rust-chat-server/tree/main/tui.
Why Flux for ratatui?
+Terminal applications often have to deal with complex user interactions, multiple views, and dynamic
+data sources. Keeping the application predictable and the logic decoupled is crucial. Flux, with
+its unidirectional data flow, allows ratatui developers to have a structured way to handle user
+input, process data, and update the views.
Flux ratatui Overview
+Dispatcher
+The dispatcher remains the central hub that manages all data flow in your application. Every action +in the application, whether it’s a user input or a response from a server, will be channeled through +the dispatcher. This ensures a unified way of handling data, and since the dispatcher has no logic +of its own, it simply ensures that all registered callbacks receive the action data.
+struct Dispatcher {
+ store: Store,
+}
+
+impl Dispatcher {
+ fn dispatch(&mut self, action: Action) {
+ self.store.update(action);
+ }
+}Stores
+Stores in Ratatui hold the application’s state and its logic. They could represent things like:
+-
+
- A list of items in a menu. +
- The content of a text editor or viewer. +
- User configurations or preferences. +
Stores listen for actions dispatched from the Dispatcher. When a relevant action is dispatched, the +store updates its state and notifies any listening components (or views) that a change has occurred.
+struct Store {
+ counter: i32,
+}
+
+impl Store {
+ fn new() -> Self {
+ Self { counter: 0 }
+ }
+
+ fn update(&mut self, action: Action) {
+ match action {
+ Action::Increment => self.counter += 1,
+ Action::Decrement => self.counter -= 1,
+ }
+ }
+
+ fn get_state(&self) -> i32 {
+ self.counter
+ }
+}
+Actions
+Actions represent any change or event in your application. For instance, when a user presses a key, +selects a menu item, or inputs text, an action is created. This action is dispatched and processed +by the relevant stores, leading to potential changes in application state.
+enum Action {
+ Increment,
+ Decrement,
+}Views / Widgets
+ratatui’s widgets display the application’s UI. They don’t hold or manage the application state,
+but they display it. When a user interacts with a widget, it can create an action that gets
+dispatched, which may lead to a change in a store, which in turn may lead to the widget being
+updated.
Integrations
+-
+
- ansi-to-tui — Convert ansi colored text to
+
ratatui::text::Text
+ - color-to-tui — Parse hex colors to
+
ratatui::style::Color
+ - rust-tui-template — A template for +bootstrapping a Rust TUI application with Tui-rs & crossterm +
- simple-tui-rs — A simple example tui-rs app +
- tui-builder — Batteries-included MVC framework for +Tui-rs + Crossterm apps +
- tui-clap — Use clap-rs together with Tui-rs +
- tui-log — Example of how to use logging with Tui-rs +
- tui-logger — Logger and Widget for Tui-rs +
- tui-realm — Tui-rs framework to build stateful applications +with a React/Elm inspired approach +
- tui-realm-treeview — Treeview component for +Tui-realm +
- tui-rs-tree-widgets: Widget for tree data +structures. +
- tui-windows — Tui-rs abstraction to handle multiple +windows and their rendering +
- tui-textarea: Simple yet powerful multi-line text editor +widget supporting several key shortcuts, undo/redo, text search, etc. +
- tui-input: TUI input library supporting multiple +backends and tui-rs. +
- tui-term: A pseudoterminal widget library that enables the +rendering of terminal applications as ratatui widgets. +
- tui-big-text: A Rust crate that renders large pixel text +as a ratatui widget using the glyphs from the font8x8 crate. +
- crokey: Crokey helps incorporate configurable keybindings in +crossterm based terminal applications by providing functions to handle key combinations. +
v0.23.0
+
+
+
+
+
+reposted from https://blog.orhun.dev/ratatui-0-23-0/
+Coolify everything 😎
+We already had a cool name and a logo, and now we have a cool description as well:
+- ratatui: A Rust library to build rich terminal user interfaces or dashboards.
++ ratatui: A Rust library that's all about cooking up terminal user interfaces.
+We also renamed our organization from tui-rs-revival to ratatui-org:
Barchart: horizontal bars
+You can now render the bars horizontally for the Barchart widget. This is especially useful in
+some cases to make more efficient use of the available space.
Simply use the Direction attribute for rendering horizontal bars:
let mut barchart = BarChart::default()
+ .block(Block::default().title("Data1").borders(Borders::ALL))
+ .bar_width(1)
+ .group_gap(1)
+ .bar_gap(0)
+ .direction(Direction::Horizontal);
+Here is an example of what you can do with the Barchart widget (see the bottom right for
+horizontal bars):
+
Voluntary skipping capability for Sixel
+++Sixel is a bitmap graphics format supported by terminals. +“Sixel mode” is entered by sending the sequence
+ESC+Pq. The “String Terminator” sequenceESC+\+exits the mode.
Cell widget now has a set_skip method that allows the cell to be skipped when copying (diffing)
+the buffer to the screen. This is helpful when it is necessary to prevent the buffer from
+overwriting a cell that is covered by an image from some terminal graphics protocol such as Sixel,
+iTerm, Kitty, etc.
See the pull request for more information: +https://github.com/ratatui-org/ratatui/pull/215
+In this context, there is also an experimental image rendering crate: +ratatu-image
+
+
Table/List: Highlight spacing
+We added a new property called HighlightSpacing to the Table and List widgets and it can be
+optionally set via calling highlight_spacing function.
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. The idea is that we want this behaviour to be +configurable with this newly added option.
+let list = List::new(items)
+ .highlight_symbol(">>")
+ .highlight_spacing(HighlightSpacing::Always);
+Right now, there are 3 variants:
+-
+
Always: Always add spacing for the selection symbol column.
+WhenSelected: Only add spacing for the selection symbol column if a row is selected.
+Never: Never add spacing to the selection symbol column, regardless of whether something is +selected or not.
+
+
Table: support line alignment
+let table = Table::new(vec![
+ Row::new(vec![Line::from("Left").alignment(Alignment::Left)]),
+ Row::new(vec![Line::from("Center").alignment(Alignment::Center)]),
+ Row::new(vec![Line::from("Right").alignment(Alignment::Right)]),
+ ])
+ .widths(&[Constraint::Percentage(100)]);
+Now results in:
+Left
+ Center
+ Right
++
Scrollbar: optional track symbol
+The track symbol in the Scrollbar is now optional, simplifying composition with other widgets. It
+also makes it easier to use the Scrollbar in tandem with a block with special block characters.
One breaking change is that track_symbol needs to be set in the following way now:
-let scrollbar = Scrollbar::default().track_symbol("-");
++let scrollbar = Scrollbar::default().track_symbol(Some("-"));
+It also makes it possible to render a custom track that is composed out of multiple differing track +symbols.
++
symbols::scrollbar module
+The symbols and sets are moved from widgets::scrollbar to symbols::scrollbar. This makes it
+consistent with the other symbol sets. We also made the scrollbar module private.
Since this is a breaking change, you need to update your code to add an import for
+ratatui::symbols::scrollbar::* (or the specific symbols you need).
+
Alpha releases
+The alpha releases (i.e. pre-releases) are created *every Saturday* and they are automated with
+the help of
+this GitHub Actions workflow.
+This is especially useful if you want to test ratatui or use unstable/experimental features before
+we hit a stable release.
The versioning scheme is v<version>-alpha.<num>, for example:
+v0.22.1-alpha.2
Additionally, see the following issue for possible contributions in the context of alpha releases +and documentation: +https://github.com/ratatui-org/ratatui/issues/412
++
Example GIFs
+We added GIFs for each example in the examples/ directory and added a README.md for preview.
+This should make it easier to see what each example does without having to run it.
See: +https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
+One thing to note here is that we used vhs for generating +GIFs from a set of instructions. For example:
+# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
+# To run this script, install vhs and run `vhs ./examples/demo.tape`
+Output "target/demo.gif"
+Set Theme "OceanicMaterial"
+Set Width 1200
+Set Height 1200
+Set PlaybackSpeed 0.5
+Hide
+Type "cargo run --example demo"
+Enter
+Sleep 2s
+Show
+Sleep 1s
+Down@1s 12
+Right
+Sleep 4s
+Right
+Sleep 4s
+Results in:
+We also host these GIFs at https://vhs.charm.sh but there is an issue about +moving everything to GitHub. If you are interested in contributing regarding this, see +https://github.com/ratatui-org/ratatui/issues/401
++
Common traits
+With the help of strum crate, we added Display and FromStr
+implementation to enum types.
Also, we implemented common traits such as Debug, Default, Clone, Copy, Eq, PartialEq,
+Ord, PartialOrd, Hash to the structs/enums where possible.
+
Test coverage 🧪
+ratatui now has 90% test coverage!
Shoutout to everyone who added tests/benchmarks for various widgets made this possible.
++
No unsafe ⚠️
+We now forbid unsafe code in ratatui.
+Also, see this discussion we had in the
+past about using unsafe code for optimization purposes.
+
The book 📕
+We are working on a book for more in-depth ratatui documentation and usage examples, you can read
+it from here:
+https://ratatui-org.github.io/ratatui-book/
Repository: +https://github.com/ratatui-org/ratatui-book
++
Other
+-
+
- Expand serde attributes for
TestBufferfor de/serializing the whole test buffer.
+ - Add weak constraints to make
Rects closer to each other in size.
+ - Simplify
Layout::splitfunction.
+ - Various bug fixes and improvements in Barchart, Block, Layout and other widgets. +
- Add documentation to various widgets and improve existing documentation. +
- Add examples for colors and modifiers. +
- We created a Matrix bridge at #ratatui:matrix.org. +
v0.22
+
+
+
+
+
+reposted from https://blog.orhun.dev/ratatui-0-22-0/
+Prelude
+We now have a prelude module! This allows users of the library to easily use ratatui without a
+huge amount of imports.
use ratatui::prelude::*;
+Aside from the main types that are used in the library, this prelude also re-exports several
+modules to make it easy to qualify types that would otherwise collide. For example:
use ratatui::{prelude::*, widgets::*};
+
+#[derive(Debug, Default, PartialEq, Eq)]
+struct Line;
+
+assert_eq!(Line::default(), Line);
+assert_eq!(text::Line::default(), ratatui::text::Line::from(vec![]));
++
New widget: Scrollbar
+A scrollbar widget has been added which can be used with any Rect. It can also be customized with
+different styles and symbols.
Here are the components of a Scrollbar:
<--▮------->
+^ ^ ^ ^
+│ │ │ └ end
+│ │ └──── track
+│ └──────── thumb
+└─────────── begin
+To use it, render it as a stateful widget along with ScrollbarState:
frame.render_stateful_widget(
+ Scrollbar::default()
+ .orientation(ScrollbarOrientation::VerticalRight)
+ .begin_symbol(Some("↑"))
+ .end_symbol(Some("↓")),
+ rect,
+ &mut scrollbar_state,
+);
+Will result in:
+┌scrollbar──────────────────↑
+│This is a longer line ║
+│Veeeeeeeeeeeeeeeery looo█
+│This is a line ║
+└───────────────────────────↓
++
Block: support multiple titles
+Block widget now supports having more than one title via Title widget.
Each title will be rendered with a single space separating titles that are in the same position or +alignment. When both centered and non-centered titles are rendered, the centered space is calculated +based on the full width of the block, rather than the leftover width.
+You can provide various types as the title, including strings, string slices, borrowed strings
+(Cow<str>), spans, or vectors of spans (Vec<Span>).
It can be used as follows:
+Block::default()
+ .borders(Borders::ALL)
+ .title("Title") // By default in the top right corner
+ .title(Title::from("Left").alignment(Alignment::Left))
+ .title(Title::from("Center").alignment(Alignment::Center))
+ .title(Title::from("Bottom").position(Position::Bottom))
+ .title(
+ Title::from("Bottom center")
+ .alignment(Alignment::Center)
+ .position(Position::Bottom),
+ );
+Results in:
+┌Title─Left──Center─────────────┐
+│ │
+│ │
+│ │
+└Bottom───Bottom center─────────┘
++
Barchart: support groups
+Barchart has been improved to support adding multiple bars from different data sets. This can be
+done by using the newly added Bar and BarGroup objects.
See the barchart example +for more information and implementation details.
++
Stylization shorthands
+It is possible to use style shorthands for str, Span, and Paragraph.
A crazy example would be:
+"hello"
+ .on_black()
+ .black()
+ .bold()
+ .underline()
+ .dimmed()
+ .slow_blink()
+ .crossed_out()
+ .reversed()
+This especially helps with concise styling:
+assert_eq!(
+ "hello".red().on_blue().bold(),
+ Span::styled("hello", Style::default().fg(Color::Red).bg(Color::Blue).add_modifier(Modifier::BOLD))
+)
++
Stylize everything
+All widgets can be styled now (i.e. set_style)
Styled trait is implemented for all the remaining widgets, including:
-
+
Barchart
+Chart(includingAxisandDataset)
+GaugeandLineGauge
+ListandListItem
+Sparkline
+Table,Row, andCell
+Tabs
+Style
+
+
Constant styles
+Styles can be constructed in a const context as follows:
const DEFAULT_MODIFIER: Modifier = Modifier::BOLD.union(Modifier::ITALIC);
+const EMPTY: Modifier = Modifier::empty();
+
+const DEFAULT_STYLE: Style = Style::with(DEFAULT_MODIFIER, EMPTY)
+ .fg(Color::Red)
+ .bg(Color::Black);
++
More colors formats
+It is now possible to parse hyphenated color names like light-red via Color::from_str.
Additionally, all colors from the +ANSI color table are supported (though some +names are not exactly the same).
+-
+
grayis sometimes calledwhite- this is not supported as we usewhitefor bright white
+grayis sometimes calledsilver- this is supported
+darkgrayis sometimes calledlight blackorbright black(both are supported)
+whiteis sometimes calledlight whiteorbright white(both are supported)
+- we support
brightandlightprefixes for all colors
+ - we support
"-","_", and" "as separators for all colors
+ - we support both
grayandgreyspellings
+
For example:
+use ratatui::style::Color;
+use std::str::FromStr;
+
+assert_eq!(Color::from_str("red"), Ok(Color::Red));
+assert_eq!("red".parse(), Ok(Color::Red));
+assert_eq!("lightred".parse(), Ok(Color::LightRed));
+assert_eq!("light red".parse(), Ok(Color::LightRed));
+assert_eq!("light-red".parse(), Ok(Color::LightRed));
+assert_eq!("light_red".parse(), Ok(Color::LightRed));
+assert_eq!("lightRed".parse(), Ok(Color::LightRed));
+assert_eq!("bright red".parse(), Ok(Color::LightRed));
+assert_eq!("bright-red".parse(), Ok(Color::LightRed));
+assert_eq!("silver".parse(), Ok(Color::Gray));
+assert_eq!("dark-grey".parse(), Ok(Color::DarkGray));
+assert_eq!("dark gray".parse(), Ok(Color::DarkGray));
+assert_eq!("light-black".parse(), Ok(Color::DarkGray));
+assert_eq!("white".parse(), Ok(Color::White));
+assert_eq!("bright white".parse(), Ok(Color::White));
++
Integrations
+Following tools are now integrated into the repository:
+-
+
cargo-husky: git pre-push hooks
+bacon: background code checks / coverage
+commitizen: conventional commits
+cargo-deny: linting dependencies
+typos: spell checker
+
+
Other
+-
+
- Benchmarks added for the
Paragraphwidget
+ - Added underline colors support for
crosstermbackend
+ - Mark some of the low-level functions of
Block,LayoutandRectasconst
+ - The project license has been updated to acknowledge
ratatuidevelopers
+
v0.21
+New backend: termwiz
+ratatui supports a new backend called termwiz which is a “Terminal Wizardry” crate that powers
+wezterm.
To use it, enable the termwiz feature in Cargo.toml:
[dependencies.ratatui]
+version = "0.21.0"
+features = ["termwiz"]
+default-features = false
+Then you can utilize TermwizBackend object for creating a terminal. Here is a simple program that
+shows a text on the screen for 5 seconds using ratatui + termwiz:
use ratatui::{backend::TermwizBackend, widgets::Paragraph, Terminal};
+use std::{
+ error::Error,
+ thread,
+ time::{Duration, Instant},
+};
+
+fn main() -> Result<(), Box<dyn Error>> {
+ let backend = TermwizBackend::new()?;
+ let mut terminal = Terminal::new(backend)?;
+ terminal.hide_cursor()?;
+
+ let now = Instant::now();
+ while now.elapsed() < Duration::from_secs(5) {
+ terminal.draw(|f| f.render_widget(Paragraph::new("termwiz example"), f.size()))?;
+ thread::sleep(Duration::from_millis(250));
+ }
+
+ terminal.show_cursor()?;
+ terminal.flush()?;
+ Ok(())
+}
++
New widget: Calendar
+A calendar widget has been added which was originally a part of the +extra-widgets repository.
+Since this new widget depends on time crate, we gated it behind widget-calendar feature to avoid
+an extra dependency:
[dependencies.ratatui]
+version = "0.21.0"
+features = ["widget-calendar"]
+Here is the example usage:
+Monthly::new(
+ time::Date::from_calendar_date(2023, time::Month::January, 1).unwrap(),
+ CalendarEventStore::default(),
+)
+.show_weekdays_header(Style::default())
+.show_month_header(Style::default())
+.show_surrounding(Style::default()),
+Results in:
+ January 2023
+ Su Mo Tu We Th Fr Sa
+ 1 2 3 4 5 6 7
+ 8 9 10 11 12 13 14
+ 15 16 17 18 19 20 21
+ 22 23 24 25 26 27 28
+ 29 30 31 1 2 3 4
++
New widget: Circle
+Circle widget has been added with the use-case of showing an accuracy radius on the world map.
Here is an example of how to use it with Canvas:
Canvas::default()
+ .paint(|ctx| {
+ ctx.draw(&Circle {
+ x: 5.0,
+ y: 2.0,
+ radius: 5.0,
+ color: Color::Reset,
+ });
+ })
+ .marker(Marker::Braille)
+ .x_bounds([-10.0, 10.0])
+ .y_bounds([-10.0, 10.0]),
+Results in:
+ ⡠⠤⢤⡀
+⢸⡁ ⡧
+ ⠑⠒⠚⠁
++
Inline Viewport
+This was a highly requested feature and the original implementation was done by +@fdehau himself. Folks at Atuin completed the +implementation and we are happy to finally have this incorporated in the new release!
+An inline viewport refers to a rectangular section of the terminal window that is set aside for +displaying content.
+In the repository, there is an example that simulates downloading multiple files in parallel: +https://github.com/ratatui-org/ratatui/blob/main/examples/inline.rs
++
Block: title on bottom
+++Before you could only put the title on the top row of a Block. Now you can put it on the bottom +row! Revolutionary.
+
For example, place the title on the bottom and center:
+Paragraph::new("ratatui")
+ .alignment(Alignment::Center)
+ .block(
+ Block::default()
+ .title(Span::styled("Title", Style::default()))
+ .title_on_bottom()
+ .title_alignment(Alignment::Center)
+ .borders(Borders::ALL),
+ )
+Results in:
+┌─────────────────────┐
+│ ratatui │
+│ │
+└────────Title────────┘
++
Block: support adding padding
+If we want to render a widget inside a Block with a certain distance from its borders, we need to
+create another Layout element based on the outer Block, add a margin and render the Widget
+into it. Adding a padding property on the block element skips the creation of this second Layout.
This property works especially when rendering texts, as we can just create a block with padding and +use it as the text wrapper:
+let block = Block::default()
+ .borders(Borders::ALL)
+ .padding(Padding::new(1, 1, 2, 2));
+let paragraph = Paragraph::new("example paragraph").block(block);
+f.render_widget(paragraph, area);
+Rendering another widget should be easy too, using the .inner method:
let block = Block::default().borders(Borders::ALL).padding(Padding {
+ left: todo!(),
+ right: todo!(),
+ top: todo!(),
+ bottom: todo!(),
+});
+let inner_block = Block::default().borders(Borders::ALL);
+let inner_area = block.inner(area);
+
+f.render_widget(block, area);
+f.render_widget(inner_block, inner_area);
+f.render_widget(paragraph, area);
++
Text: display secure data
+A new type called Masked is added for text-related types for masking data with a mask character.
+The example usage is as follows:
Line::from(vec![
+ Span::raw("Masked text: "),
+ Span::styled(
+ Masked::new("password", '*'),
+ Style::default().fg(Color::Red),
+ ),
+])
+Results in:
+Masked text: ********
++
border! macro
+A border! macro has been added that takes TOP, BOTTOM, LEFT, RIGHT, and ALL and returns
+a Borders object.
An empty border!() call returns NONE.
For example:
+border!(ALL)
+border!(LEFT, RIGHT)
+border!()
+This is gated behind a macros feature flag to ensure short build times. To enable it, update
+Cargo.toml as follows:
[dependencies.ratatui]
+version = "0.21.0"
+features = ["macros"]
+Going forward, we will most likely put the new macros behind macros feature as well.
+
Color: support conversion from String
+Have you ever needed this conversion?
+"black" => Color::Black,
+"red" => Color::Red,
+"green" => Color::Green,
+// etc.
+Don’t worry, we got you covered:
+Color::from_str("lightblue") // Color::LightBlue
+Color::from_str("10") // Color::Indexed(10)
+Color::from_str("#FF0000") // Color::Rgb(255, 0, 0)
++
Spans -> Line
+Line is a significantly better name over Spans as the plural causes confusion and the type
+really is a representation of a line of text made up of spans.
So, Spans is renamed as Line and a deprecation notice has been added.
See +https://github.com/ratatui-org/ratatui/pull/178 +for more discussion.
++
Other features
+-
+
Listnow has alen()method for returning the number of items
+Sparklinenow has adirection()method for specifying the render direction (left to right / +right to left)
+TableandListstates now haveoffset()andoffset_mut()methods
+- Expose the test buffer (
TestBackend) withDisplayimplementation
+
+
New apps
+Here is the list of applications that has been added:
+-
+
- oxycards: quiz card application built within the +terminal. +
- twitch-tui: twitch chat in the terminal. +
- tenere: TUI interface for LLMs. +
Also, we moved APPS.md file to the
+Wiki so check it out for more
+applications built with ratatui!
+
Migration from tui-rs
+We put together a migration guide at the Wiki: +Migrating from TUI
+Also, the minimum supported Rust version is 1.65.0
+
Contributing
+Any contribution is highly appreciated! There are +contribution guidelines for +getting started.
+Feel free to submit issues and throw in +ideas!
+If you are having a problem with ratatui or want to contribute to the project or just want to
+chit-chat, feel free to join our Discord server!
References
+-
+
- Crate Docs +
- Starter Template +
- Starter Async Tokio Template +
- Third Party Crates +
- Apps using
ratatui
+
Features
+As ratatui grows and evolves, this list may change, so make sure to check the +main repo if you are unsure.
+Backend Selection
+For most cases, the default crossterm backend is the correct choice. See
+Backends for more information. However, this can be changed to termion or termwiz
# Defaults to crossterm
+cargo add ratatui
+
+# For termion, unset the default crossterm feature and select the termion feature
+cargo add ratatui --no-default-features --features=terminon
+cargo add termion
+
+# For termwiz, unset the default crossterm feature and select the termwiz feature
+cargo add ratatui --no-default-features --features=termwiz
+cargo add termwiz
+All-Widgets
+This feature enables some extra widgets that are not in default to save on compile time. As of
+v0.21, the only widget in this feature group is the calendar widget, which can be enabled with the
+widget-calendar feature.
cargo add ratatui --features all-widgets
+Widget-Calendar
+This feature enables the calendar widget, which requires the time crate.
cargo add ratatui --features widget-calendar
+Serde
+cargo add ratatui --features serde
+Ratatui
+Check out the CONTRIBUTING GUIDE +for more information.
+Keep PRs small, intentional and focused
+Try to do one pull request per change. The time taken to review a PR grows exponential with the size +of the change. Small focused PRs will generally be much more faster to review. PRs that include both +refactoring (or reformatting) with actual changes are more difficult to review as every line of the +change becomes a place where a bug may have been introduced. Consider splitting refactoring / +reformatting changes into a separate PR from those that make a behavioral change, as the tests help +guarantee that the behavior is unchanged.
+Search tui-rs for similar work
+The original fork of Ratatui, tui-rs, has a large amount of
+history of the project. Please search, read, link, and summarize any relevant
+issues,
+discussions and
+pull requests.
Use conventional commits
+We use conventional commits and check for them as +a lint build step. To help adhere to the format, we recommend to install +Commitizen. By using this tool you automatically +follow the configuration defined in .cz.toml. Your commit messages should have enough +information to help someone reading the CHANGELOG understand what is new just from +the title. The summary helps expand on that to provide information that helps provide more context, +describes the nature of the problem that the commit is solving and any unintuitive effects of the +change. It’s rare that code changes can easily communicate intent, so make sure this is clearly +documented.
+Clean up your commits
+The final version of your PR that will be committed to the repository should be rebased and tested +against main. Every commit will end up as a line in the changelog, so please squash commits that are +only formatting or incremental fixes to things brought up as part of the PR review. Aim for a single +commit (unless there is a strong reason to stack the commits). See +Git Best Practices - On Sausage Making +for more on this.
+Run CI tests before pushing a PR
+We’re using cargo-husky to automatically run git hooks,
+which will run cargo make ci before each push. To initialize the hook run cargo test. If
+cargo-make is not installed, it will provide instructions to install it for you. This will ensure
+that your code is formatted, compiles and passes all tests before you push. If you need to skip this
+check, you can use git push --no-verify.
Sign your commits
+We use commit signature verification, which will block commits from being merged via the UI unless +they are signed. To set up your machine to sign commits, see +managing commit signature verification +in GitHub docs.
+Setup
+Clone the repo and build it using cargo-make
+Ratatui is an ordinary Rust project where common tasks are managed with
+cargo-make. It wraps common cargo commands with sane
+defaults depending on your platform of choice. Building the project should be as easy as running
+cargo make build.
git clone https://github.com/ratatui-org/ratatui.git
+cd ratatui
+cargo make build
+Tests
+The test coverage of the crate is reasonably good,
+but this can always be improved. Focus on keeping the tests simple and obvious and write unit tests
+for all new or modified code. Beside the usual doc and unit tests, one of the most valuable test you
+can write for Ratatui is a test against the TestBackend. It allows you to assert the content of
+the output buffer that would have been flushed to the terminal after a given draw call. See
+widgets_block_renders in tests/widgets_block.rs for an example.
When writing tests, generally prefer to write unit tests and doc tests directly in the code file
+being tested rather than integration tests in the tests/ folder.
If an area that you’re making a change in is not tested, write tests to characterize the existing
+behavior before changing it. This helps ensure that we don’t introduce bugs to existing software
+using Ratatui (and helps make it easy to migrate apps still using tui-rs).
For coverage, we have two bacon jobs (one for all tests, and one for
+unit tests, keyboard shortcuts v and u respectively) that run
+cargo-llvm-cov to report the coverage. Several plugins
+exist to show coverage directly in your editor. E.g.:
-
+
- https://marketplace.visualstudio.com/items?itemName=ryanluker.vscode-coverage-gutters +
- https://github.com/alepez/vim-llvmcov +
Use of unsafe for optimization purposes
+We don’t currently use any unsafe code in Ratatui, and would like to keep it that way. However there +may be specific cases that this becomes necessary in order to avoid slowness. Please see +this discussion for more about the +decision.
+Ratatui Book
+The ratatui-book is written in
+mdbook.
The book is built as HTML pages as part of a +GitHub Action +and is available to view at https://ratatui-org.github.io/ratatui-book/.
+Feel free to make contributions if you’d like to improve the documentation.
+If you want to set up your local environment, you can run the following:
+cargo install mdbook --version 0.4.30
+cargo install mdbook-admonish --version 1.9.0
+cargo install mdbook-svgbob2 --version 0.3.0
+cargo install mdbook-linkcheck --version 0.7.7
+cargo install mdbook-mermaid --version 0.12.6
+cargo install mdbook-emojicodes --version 0.2.2
+These plugins allow additional features.
+mdbook-admonish
+The following raw markdown:
+```admonish note
+This is a note
+```
+
+```admonish tip
+This is a tip
+```
+
+```admonish warning
+This is a warning
+```
+
+```admonish info
+This is a info
+```
+will render as the following:
+ + + + +mdbook-mermaid
+The following raw markdown:
+```mermaid
+graph TD;
+ A-->B;
+ A-->C;
+ B-->D;
+ C-->D;
+```
+will render as the following:
+graph TD; + A-->B; + A-->C; + B-->D; + C-->D; ++
mdbook-svgbob2
+The following raw markdown:
+```svgbob
+ .---.
+ /-o-/--
+ .-/ / /->
+ ( * \/
+ '-. \
+ \ /
+ '
+```
+will render as the following:
+ +mdbook-emojicodes
+The following raw markdown:
+I love cats 🐱 and dogs 🐶, I have two, one's gray, like a raccoon 🦝, and the other
+one is black, like the night 🌃.
+will render as the following:
+I love cats 🐱 and dogs 🐶, I have two, one’s gray, like a raccoon 🦝, and the other +one is black, like the night 🌃.
+LICENSE
+The MIT License
+Copyright (c) 2023 Ratatui Developers
+Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the “Software”), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE.
+Contributors
+See the contributors graph on GitHub +for more up to date information.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/references/index.html b/pr-preview/pr-83/references/index.html
new file mode 100644
index 000000000..9eb0d98c6
--- /dev/null
+++ b/pr-preview/pr-83/references/index.html
@@ -0,0 +1,220 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Features
+As ratatui grows and evolves, this list may change, so make sure to check the +main repo if you are unsure.
+Backend Selection
+For most cases, the default crossterm backend is the correct choice. See
+Backends for more information. However, this can be changed to termion or termwiz
# Defaults to crossterm
+cargo add ratatui
+
+# For termion, unset the default crossterm feature and select the termion feature
+cargo add ratatui --no-default-features --features=terminon
+cargo add termion
+
+# For termwiz, unset the default crossterm feature and select the termwiz feature
+cargo add ratatui --no-default-features --features=termwiz
+cargo add termwiz
+All-Widgets
+This feature enables some extra widgets that are not in default to save on compile time. As of
+v0.21, the only widget in this feature group is the calendar widget, which can be enabled with the
+widget-calendar feature.
cargo add ratatui --features all-widgets
+Widget-Calendar
+This feature enables the calendar widget, which requires the time crate.
cargo add ratatui --features widget-calendar
+Serde
+cargo add ratatui --features serde
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/pr-preview/pr-83/searcher.js b/pr-preview/pr-83/searcher.js
new file mode 100644
index 000000000..d2b0aeed3
--- /dev/null
+++ b/pr-preview/pr-83/searcher.js
@@ -0,0 +1,483 @@
+"use strict";
+window.search = window.search || {};
+(function search(search) {
+ // Search functionality
+ //
+ // You can use !hasFocus() to prevent keyhandling in your key
+ // event handlers while the user is typing their search.
+
+ if (!Mark || !elasticlunr) {
+ return;
+ }
+
+ //IE 11 Compatibility from https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/startsWith
+ if (!String.prototype.startsWith) {
+ String.prototype.startsWith = function(search, pos) {
+ return this.substr(!pos || pos < 0 ? 0 : +pos, search.length) === search;
+ };
+ }
+
+ var search_wrap = document.getElementById('search-wrapper'),
+ searchbar = document.getElementById('searchbar'),
+ searchbar_outer = document.getElementById('searchbar-outer'),
+ searchresults = document.getElementById('searchresults'),
+ searchresults_outer = document.getElementById('searchresults-outer'),
+ searchresults_header = document.getElementById('searchresults-header'),
+ searchicon = document.getElementById('search-toggle'),
+ content = document.getElementById('content'),
+
+ searchindex = null,
+ doc_urls = [],
+ results_options = {
+ teaser_word_count: 30,
+ limit_results: 30,
+ },
+ search_options = {
+ bool: "AND",
+ expand: true,
+ fields: {
+ title: {boost: 1},
+ body: {boost: 1},
+ breadcrumbs: {boost: 0}
+ }
+ },
+ mark_exclude = [],
+ marker = new Mark(content),
+ current_searchterm = "",
+ URL_SEARCH_PARAM = 'search',
+ URL_MARK_PARAM = 'highlight',
+ teaser_count = 0,
+
+ SEARCH_HOTKEY_KEYCODE = 83,
+ ESCAPE_KEYCODE = 27,
+ DOWN_KEYCODE = 40,
+ UP_KEYCODE = 38,
+ SELECT_KEYCODE = 13;
+
+ function hasFocus() {
+ return searchbar === document.activeElement;
+ }
+
+ function removeChildren(elem) {
+ while (elem.firstChild) {
+ elem.removeChild(elem.firstChild);
+ }
+ }
+
+ // Helper to parse a url into its building blocks.
+ function parseURL(url) {
+ var a = document.createElement('a');
+ a.href = url;
+ return {
+ source: url,
+ protocol: a.protocol.replace(':',''),
+ host: a.hostname,
+ port: a.port,
+ params: (function(){
+ var ret = {};
+ var seg = a.search.replace(/^\?/,'').split('&');
+ var len = seg.length, i = 0, s;
+ for (;i
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+