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 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 enter(&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 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 enter(&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(())
  }
}