Elements API Reference

OSUI provides a set of built-in Element implementations that serve as the fundamental visual components for building your terminal user interfaces. This section details their purpose and configurable properties.

All elements implicitly implement the Element trait and can be used within the rsx! macro.

Basic Elements

String

Represents simple plain text.

impl Element for String

• Properties: None directly. Content is the string itself.
• Usage:

  rsx! {
      "Hello, World!"
  }

(String, u32) (Colored Text)

Represents text with a specific 24-bit RGB foreground color.

impl Element for (String, u32)

• Properties:
  • 0: The String content.
  • 1: The u32 RGB color (e.g., 0xFF0000 for red).
• Usage:

  rsx! {
      ("This text is red.", 0xFF0000)
  }

Container Elements

Container elements manage and render their children. They typically take care of positioning children relative to themselves.

Div

A basic rectangular container element. It positions its children at their specified coordinates relative to the div's top-left corner and expands its own Dimension::Content size to fit them.

pub struct Div {
    // children: Vec<Arc<Widget>>, // Internal
    // size: (u16, u16),           // Internal calculated size
}

• Properties: None specific to Div. Layout and style are controlled by attached Transform and Style components.
• Usage:

  rsx! {
      @Transform::new().padding(1, 1);
      @Style { background: Background::Solid(0x333333) };
      Div {
          "Content inside a div."
          @Transform::new().x(2).y(2);
          Div { "Nested div offset by (2,2)" }
      }
  }

FlexRow

A container element that arranges its children vertically, one after another, like a column. It expands its height to fit children and can apply a uniform gap between them.

pub struct FlexRow {
    pub gap: u16,
    // children: Vec<Arc<Widget>>, // Internal
    // size: (u16, u16),           // Internal calculated size
}

• Properties:
  • gap: u16: The number of empty cells between each child element. Defaults to 0.
• Usage:

  rsx! {
      FlexRow, gap: 1, {
          "First Item"
          ("Second Item (colored)", 0x00FFFF)
          Div { "Third Item (a div)" }
      }
  }
  This will render "First Item", then a 1-cell gap, then "Second Item", then a 1-cell gap, etc., all stacked vertically.

FlexCol

A container element that arranges its children horizontally, one after another, like a row. It expands its width to fit children and can apply a uniform gap between them.

pub struct FlexCol {
    pub gap: u16,
    // children: Vec<Arc<Widget>>, // Internal
    // size: (u16, u16),           // Internal calculated size
}

• Properties:
  • gap: u16: The number of empty cells between each child element. Defaults to 0.
• Usage:

  rsx! {
      FlexCol, gap: 2, {
          "Left Item"
          ("Middle Item (colored)", 0xFFCC00)
          Div { "Right Item (a div)" }
      }
  }
  This will render "Left Item", then a 2-cell gap, then "Middle Item", etc., all laid out horizontally.

Paginator

A container element that displays only one of its children at a time. It provides built-in keyboard navigation to cycle through its children.

pub struct Paginator {
    // children: Vec<Arc<Widget>>, // Internal
    // size: (u16, u16),           // Internal calculated size
    // index: usize,               // Internal current page index
}

• Properties: None specific to Paginator.
• Internal Behavior:
  • Handles crossterm::event::KeyCode::Tab to advance to the next child. If at the last child, it wraps to the first.
  • Handles crossterm::event::KeyCode::BackTab (Shift+Tab) to go to the previous child. If at the first child, it wraps to the last.
• Usage:

  rsx! {
      Paginator {
          Div { "Page 1 Content" }
          FlexCol { "Page 2: Item A", "Item B" }
          "Page 3: Just some text."
      }
  }

Form Elements

Input

An interactive element that allows users to type text. It manages its own internal state, cursor position, and handles basic text editing key presses.

pub struct Input {
    pub state: State<String>, // Reactive state holding the input string
    // cursor: usize,           // Internal cursor position
}

• Properties:
  • state: State<String>: A reactive state variable that holds the current text content of the input field. You can pass your own State<String> to bind to it, or Input::new() creates a default one.
• Internal Behavior:
  • Handles crossterm::event::KeyEvent for:
    • KeyCode::Char: Inserts character at cursor.
    • KeyCode::Backspace: Deletes character before cursor.
    • KeyCode::Delete: Deletes character at cursor.
    • KeyCode::Left, KeyCode::Right: Moves cursor.
• Usage:

  use osui::prelude::*;
  
  let my_input_state = use_state(String::from("Initial Text"));
  
  rsx! {
      @Transform::new().dimensions(30, 1).padding(1, 0);
      @Style { background: Background::Outline(0x888888), foreground: Some(0xFFFFFF) };
      Input, state: my_input_state, { }
  }
  // You can access my_input_state.get_dl() elsewhere to get the current value.
  Note that while the Input element has a state field, it's not declared as a dependency with % in rsx!. This is because Input internally manages its own State<String> and triggers its own re-renders when the text changes. You would use % if another widget needed to react to changes in my_input_state.

Display Elements

Heading

An element that renders text using FIGlet ASCII art fonts.

pub struct Heading {
    pub font: FIGfont, // The FIGlet font to use
    pub smooth: bool,  // Whether to replace '-' with '─' and '|' with '│'
    // children: Vec<Arc<Widget>>, // Internal: stores text children
}

• Properties:
  • font: FIGfont: The FIGlet font instance to use. You typically use FIGfont::standard().unwrap() or load a custom font.
  • smooth: bool: If true, replaces standard ASCII box drawing characters with Unicode smooth box drawing characters for a cleaner look. Defaults to false.
• Usage:

  use figlet_rs::FIGfont; // Import for `FIGfont` type
  
  rsx! {
      // Default standard font, not smooth
      Heading { "OSUI" }
  
      // Using a custom font and smoothing
      Heading, font: FIGfont::big().unwrap(), smooth: true, { "Big Title" }
  }
  Note that Heading expects String children (or (String, u32) children) for its text content. It concatenates all string children and renders them as one FIGlet text block.

These built-in elements provide a solid foundation for constructing diverse and interactive terminal user interfaces with OSUI.