TerminalInterface

bubbletea_rs::terminal

Trait TerminalInterface 

Source 
pub trait TerminalInterface {

Show 18 methods    // Required methods
    fn new(
        output_writer: Option<Arc<Mutex<dyn AsyncWrite + Send + Unpin>>>,
    ) -> Result<Self, Error>
       where Self: Sized;
    fn enter_raw_mode<'life0, 'async_trait>(
        &'life0 mut self,
    ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn exit_raw_mode<'life0, 'async_trait>(
        &'life0 mut self,
    ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn enter_alt_screen<'life0, 'async_trait>(
        &'life0 mut self,
    ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn exit_alt_screen<'life0, 'async_trait>(
        &'life0 mut self,
    ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn enable_mouse<'life0, 'async_trait>(
        &'life0 mut self,
    ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn enable_mouse_cell_motion<'life0, 'async_trait>(
        &'life0 mut self,
    ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn enable_mouse_all_motion<'life0, 'async_trait>(
        &'life0 mut self,
    ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn disable_mouse<'life0, 'async_trait>(
        &'life0 mut self,
    ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn enable_focus_reporting<'life0, 'async_trait>(
        &'life0 mut self,
    ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn disable_focus_reporting<'life0, 'async_trait>(
        &'life0 mut self,
    ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn enable_bracketed_paste<'life0, 'async_trait>(
        &'life0 mut self,
    ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn disable_bracketed_paste<'life0, 'async_trait>(
        &'life0 mut self,
    ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn show_cursor<'life0, 'async_trait>(
        &'life0 mut self,
    ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn hide_cursor<'life0, 'async_trait>(
        &'life0 mut self,
    ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn clear<'life0, 'async_trait>(
        &'life0 mut self,
    ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn render<'life0, 'life1, 'async_trait>(
        &'life0 mut self,
        content: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn size(&self) -> Result<(u16, u16), Error>;

}
Expand description

A trait for abstracting terminal operations.

This trait provides a unified interface for terminal management across different implementations. It supports both direct terminal access and custom output writers for testing or alternative output destinations.

§Design Philosophy

All methods are designed to be idempotent - calling them multiple times with the same parameters should be safe and efficient. Implementations should track state to avoid unnecessary system calls.

§Example

use bubbletea_rs::terminal::{TerminalInterface, Terminal};
use bubbletea_rs::Error;

let mut terminal = Terminal::new(None)?;
terminal.enter_raw_mode().await?;
terminal.hide_cursor().await?;
terminal.render("Hello, world!").await?;
terminal.show_cursor().await?;
terminal.exit_raw_mode().await?;

Required Methods§

Source

fn new( output_writer: Option<Arc<Mutex<dyn AsyncWrite + Send + Unpin>>>, ) -> Result<Self, Error>
where Self: Sized,

Construct a new terminal implementation.

Accepts an optional asynchronous output writer. When provided, rendering will write to this writer instead of stdout. This is useful for testing or redirecting output to files, network streams, or other destinations.

§Arguments
  • output_writer - Optional custom output destination. If None, uses stdout.
§Returns

A new terminal implementation instance.

§Errors

Returns an error if terminal initialization fails or if the output writer cannot be set up properly.

Source

fn enter_raw_mode<'life0, 'async_trait>( &'life0 mut self, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Enable raw mode (disables canonical input processing).

Raw mode allows the application to receive all key events immediately without line buffering or special character processing. This is essential for interactive TUI applications.

§Effects
  • Disables line buffering (canonical mode)
  • Disables echo of typed characters
  • Enables immediate key event delivery
  • Disables special character processing (Ctrl+C, Ctrl+Z, etc.)
§Errors

Returns an error if the terminal cannot be switched to raw mode.

Source

fn exit_raw_mode<'life0, 'async_trait>( &'life0 mut self, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Disable raw mode and restore canonical input processing.

Restores the terminal to its original state with line buffering, echo, and special character processing enabled.

§Effects
  • Re-enables line buffering (canonical mode)
  • Re-enables echo of typed characters
  • Restores special character processing
§Errors

Returns an error if the terminal cannot be restored to canonical mode.

Source

fn enter_alt_screen<'life0, 'async_trait>( &'life0 mut self, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Enter the alternate screen buffer.

Switches to an alternate screen buffer, preserving the current terminal content. This allows the application to run in a “clean” screen that can be restored when the application exits.

§Effects
  • Saves current screen content
  • Switches to alternate buffer
  • Clears the alternate buffer
§Errors

Returns an error if the terminal doesn’t support alternate screens or if the switch fails.

Source

fn exit_alt_screen<'life0, 'async_trait>( &'life0 mut self, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Leave the alternate screen buffer.

Switches back to the main screen buffer, restoring the original terminal content that was visible before entering alternate screen.

§Effects
  • Restores original screen content
  • Switches back to main buffer
§Errors

Returns an error if the switch back to main screen fails.

Source

fn enable_mouse<'life0, 'async_trait>( &'life0 mut self, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Enable basic mouse capture.

Enables the terminal to capture mouse events including clicks, releases, and basic movement. The application will receive mouse events through the normal input stream.

§Errors

Returns an error if mouse capture cannot be enabled.

Source

fn enable_mouse_cell_motion<'life0, 'async_trait>( &'life0 mut self, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Enable cell-motion mouse reporting.

Enables mouse motion reporting when the mouse moves between different character cells. This provides more detailed movement tracking than basic mouse capture while being less intensive than all-motion reporting.

§Errors

Returns an error if cell-motion mouse reporting cannot be enabled.

Source

fn enable_mouse_all_motion<'life0, 'async_trait>( &'life0 mut self, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Enable high-resolution mouse reporting.

Enables reporting of all mouse movement, including sub-cell movements. This provides the highest fidelity mouse tracking but generates many more events and should be used carefully to avoid overwhelming the application.

§Performance Note

This mode generates significantly more events than other mouse modes. Use only when precise mouse tracking is required.

§Errors

Returns an error if all-motion mouse reporting cannot be enabled.

Source

fn disable_mouse<'life0, 'async_trait>( &'life0 mut self, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Disable all mouse capture modes.

Disables mouse event capture and reporting. After calling this, the terminal will not send mouse events to the application.

§Errors

Returns an error if mouse capture cannot be disabled.

Source

fn enable_focus_reporting<'life0, 'async_trait>( &'life0 mut self, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Enable terminal focus change reporting.

Enables the terminal to report when it gains or loses focus. The application will receive focus/blur events when the terminal window becomes active or inactive.

§Use Cases
  • Pausing animations when the terminal loses focus
  • Changing display intensity or colors
  • Triggering auto-save when focus is lost
§Errors

Returns an error if focus reporting cannot be enabled.

Source

fn disable_focus_reporting<'life0, 'async_trait>( &'life0 mut self, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Disable terminal focus change reporting.

Disables focus change event reporting. The terminal will no longer send focus/blur events to the application.

§Errors

Returns an error if focus reporting cannot be disabled.

Source

fn enable_bracketed_paste<'life0, 'async_trait>( &'life0 mut self, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Enable bracketed paste mode.

Enables bracketed paste mode, which wraps pasted text in special escape sequences. This allows the application to distinguish between text that was typed character-by-character and text that was pasted as a block.

§Benefits
  • Prevents auto-indentation from corrupting pasted code
  • Allows special handling of large text blocks
  • Improves security by identifying untrusted input
§Errors

Returns an error if bracketed paste mode cannot be enabled.

Source

fn disable_bracketed_paste<'life0, 'async_trait>( &'life0 mut self, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Disable bracketed paste mode.

Disables bracketed paste mode, returning to normal paste behavior where pasted text is indistinguishable from typed text.

§Errors

Returns an error if bracketed paste mode cannot be disabled.

Source

fn show_cursor<'life0, 'async_trait>( &'life0 mut self, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Show the cursor if hidden.

Makes the cursor visible if it was previously hidden. This is typically called when exiting the application or when cursor visibility is needed for user input.

§Errors

Returns an error if the cursor visibility cannot be changed.

Source

fn hide_cursor<'life0, 'async_trait>( &'life0 mut self, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Hide the cursor if visible.

Hides the cursor from view. This is commonly done in TUI applications to prevent the cursor from interfering with the visual layout or to create a cleaner appearance.

§Errors

Returns an error if the cursor visibility cannot be changed.

Source

fn clear<'life0, 'async_trait>( &'life0 mut self, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Clear the visible screen contents.

Clears the entire visible screen, typically filling it with the default background color. The cursor position may be reset to the top-left corner.

§Errors

Returns an error if the screen cannot be cleared.

Source

fn render<'life0, 'life1, 'async_trait>( &'life0 mut self, content: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Render the provided content to the terminal.

Displays the given content on the terminal screen. This typically involves clearing the screen and writing the new content from the top-left corner. Newlines in the content will be properly handled for the target terminal.

§Arguments
  • content - The text content to display. May contain ANSI escape sequences for colors and formatting.
§Performance

Implementations should buffer output efficiently to minimize the number of system calls and reduce flicker.

§Errors

Returns an error if the content cannot be written to the terminal or output writer.

Source

fn size(&self) -> Result<(u16, u16), Error>

Get the current terminal size as (columns, rows).

Returns the current dimensions of the terminal in character cells. This information is useful for layout calculations and ensuring content fits within the visible area.

§Returns

A tuple of (width, height) where:

  • width is the number of character columns
  • height is the number of character rows
§Errors

Returns an error if the terminal size cannot be determined.

§Note

Terminal size can change during program execution due to window resizing. Applications should handle size change events appropriately.

Implementors§