docs/versioned_docs/version-0.1.0/00-intro/overview.md

OSUI: A Rust Terminal User Interface Library

OSUI (Operating System User Interface) is a powerful and flexible library for building interactive and customizable Terminal User Interfaces (TUIs) in Rust. It provides a declarative component system inspired by modern web frameworks, real-time keyboard input handling, and a virtual screen abstraction to simplify TUI development.

Key Features

• Declarative UI with rsx!: Define your UI structure using an intuitive, JSX-like macro that allows for nesting, component composition, and reactive updates.
• Component-Based Design: Build complex UIs from reusable Elements and extend their functionality with Components, promoting modularity and maintainability.
• Reactive State Management: Integrate dynamic behavior effortlessly with the State system, automatically re-rendering parts of your UI when underlying data changes.
• Flexible Layout System: Control element positioning and sizing with Transform, Position, and Dimension properties, supporting both fixed and content-based layouts.
• Extensible Architecture: Customize or extend OSUI's core behavior by implementing the Extension trait, allowing you to add global event handling, custom rendering logic, and more.
• Virtual Screen Abstraction: OSUI manages the complexities of terminal rendering, providing a consistent API for drawing text, shapes, and applying styles across different terminal environments.
• Real-time Input Handling: Built-in support for capturing and dispatching keyboard events, enabling interactive applications.

Quick Example

The following example demonstrates a minimal OSUI application that displays "Hello, World!" on the terminal.

use osui::prelude::*;

fn main() -> std::io::Result<()> {
    // 1. Create a new Screen instance, which manages the TUI environment.
    let screen = Screen::new();

    // 2. Define your UI using the `rsx!` macro.
    //    Here, a simple string "Hello, World!" becomes a renderable element.
    rsx! {
        "👋 Hello, World!"
    }
    // 3. Draw the constructed UI tree onto the screen.
    .draw(&screen);

    // 4. Run the main rendering loop. This will block until the application is closed.
    screen.run()
}

This simple application initializes the Screen, defines a basic text element using rsx!, draws it, and then enters the main rendering loop.

Philosophy

OSUI aims to provide a high-level, ergonomic API for TUI development, abstracting away the low-level details of terminal interaction. By embracing a component-based and reactive paradigm, it encourages developers to build robust and interactive command-line applications with a familiar development experience, similar to modern graphical UI frameworks.

For more detailed guides and API references, explore the rest of the documentation.