TermRender

A high-performance, async-ready terminal UI library for Rust, built with flexibility and performance in mind. TermRender provides a modern widget system, efficient rendering, and comprehensive input handling for creating rich terminal applications.

Features

• High Performance: Optimized rendering with dirty-rectangle tracking and efficient escape sequence handling

• Flexible Widget System: Build custom UI components with a trait-based approach

• Comprehensive Input: Full keyboard and mouse support with modifier keys

• Rich Text Support: ANSI colors, 24-bit RGB, and text styling

• Async Ready: Built on Tokio for modern async/await workflows

• Dynamic Layouts: Responsive layouts that adapt to terminal resizing

• Extensible: Easy to create custom widgets and renderers

Quick Start

Add TermRender to your Cargo.toml:

toml
[dependencies]
term_render = "0.1.3"
tokio = { version = "1.47.1", features = ["full"] }

Basic usage example:

use term_render::{self, event_handler::KeyCode};
use term_render::widget_impls::WidgetBuilder;

// this acts as the callback that is called every frame
// this is the entry point and any logic needs to branch out from here
fn app_callback(app: &mut term_render::App<AppData>, data: &mut AppData) -> Result<bool, ()> {
    // place app logic here
    if app.events.read().contains_key_code(KeyCode::Return) {
        return Ok(true);
    }
    if data.time.elapsed().as_secs_f64() > 15.0 {
        return Ok(true);
    }
    
    Ok(false)  // return true to exit the app
}

// defining the application data structure
// this can contain any data you want to use in the app callback
struct AppData {
    pub time: std::time::Instant,
}

#[tokio::main(flavor = "multi_thread", worker_threads = 10)]
async fn main() -> tokio::io::Result<()> {
    // creating an instance of the app
    let mut app = term_render::App::new()?;
    let data = AppData {
        time: std::time::Instant::now(),
    };
    
    // creating a new scene to attach widgets to
    let mut scene = term_render::widget::Scene::new();
    
    // creating a widget using the builder trait.
    let (widget, window) =
        term_render::widget_impls::StaticWidgetBuilder::<AppData>::builder(String::from("name"))
            .with_border(true)
            .with_renderer(Box::new(|_size, _position| {
                Some(vec![])
            }))
            .with_position((10, 10))
            .with_size((50, 10))
            .build(&app.area.read()).unwrap();
    scene.add_widget(widget, window, &mut *app.renderer.write()).unwrap();
    app.scene = Some(scene);
    
    // running the application with the callback, and provided data for state tracking.
    app.run(data, |data, app_instance| {
        app_callback(app_instance, data)
    }).await.unwrap();
    Ok(())
}

Basic Explanation

The basis of a TermRender application is the App struct, which manages the terminal state, event handling, and rendering. You create an instance of App, set up your UI components (widgets), and then call run with a callback function that contains your application logic. The callback function is called every frame, allowing you to update your application state and respond to events. The AppData struct is a user-defined structure that holds any state you want to maintain across frames. In this example, it tracks the elapsed time since the application started. The App instance optionally can have a Scene, which is a container for widgets. You can create widgets using the provided builders or implement your own by adhering to the Widget trait.

When a name/string identifier is requested for a widget, it should be unique to that scene, as the backend renderer references Window's (similar to a Widget, but lower level) not by the widget instance itself, but rather that string

Widget System

TermRender provides a flexible widget system:

Built-in Widgets

• StaticWidget: Basic widget with custom rendering logic

• DynamicWidget: An interactable widget. In the future, more advanced versions will be implemented which will default as buttons or other such higher-level widgets.

• ButtonWidget: A simple button with automatic click handling.

• StaticTextWidget: Displays static text with styling options.

• TypingWidget: A customizable text input field.

• More coming soon!

• Creating Custom Widgets Implement the Widget trait to create custom components:

use term_render::{Widget, SendSync, event_handler::KeyParser};

// Where type C is the user defined app data state
struct MyCustomWidget<C> {
    // Your widget state
}

impl<C> Widget<C> for MyCustomWidget<C> {
    fn get_window_ref(&self) -> String {
        "my_custom_widget".to_string()  // note: each widget instance requires a unique identifyer
    }
    
    fn update_with_events(&mut self, events: &SendSync<KeyParser>) {
        // Handle events
    }
    
    fn update_render(&mut self, window: &mut Window, area: &Rect) {
        // Update rendering
    }
    
    // ... implement other required methods
}

Performance Features

TermRender includes several optimizations:

• Dirty Rectangle Rendering: Only updates changed portions of the screen

• Efficient Event Handling: Minimal overhead input processing

• Smart Caching: Redundant render calls are avoided

• Async Rendering: Non-blocking UI updates

Examples

Check out the examples directory for complete implementations (more coming soon):

• Run basic example cargo run --example basic

Documentation

Full API documentation is available:

https://docs.rs/term_render/latest/term_render/

Contributing

Contributions are welcome! Please feel free to submit pull requests, open issues, or suggest new features.

1. Fork the repository

2. Create your feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

License

This project is licensed under:

MIT license (LICENSE-MIT)

Acknowledgments

• Inspired by Ratatui

• Built with performance and developer experience in mind

• Thanks to all contributors and the Rust community

TermRender - Build beautiful terminal applications with Rust