Skip to main content

Component

tui

Trait Component 

Source 
pub trait Component {
    type Message;

    // Required methods
    fn on_event(
        &mut self,
        event: &Event,
    ) -> impl Future<Output = Option<Vec<Self::Message>>>;
    fn render(&mut self, ctx: &ViewContext) -> Frame;
}
Expand description

The core abstraction for all interactive widgets. Every built-in widget implements this trait, and parent components compose children through it.

The trait follows an event-message design: on_event receives input and optionally produces typed messages that bubble up to the parent. render produces a Frame from the current state.

§Event handling contract

on_event returns one of three outcomes:

  • None — the event was not recognized. The parent should propagate it elsewhere.
  • Some(vec![]) — the event was consumed but produced no messages (e.g. internal cursor movement).
  • Some(vec![msg, ...]) — the event was consumed and produced one or more messages for the parent to handle.

Use merge to combine outcomes from multiple children.

§Rendering

render receives a ViewContext (terminal size + theme) and returns a Frame — a vector of Lines plus an optional Cursor position. The parent is responsible for composing child frames (see Layout).

§Usage

use tui::{Component, Event, Frame, KeyCode, Line, ViewContext};

struct Counter { count: i32 }

impl Component for Counter {
    type Message = ();
    async fn on_event(&mut self, event: &Event) -> Option<Vec<()>> {
        if let Event::Key(key) = event {
            match key.code {
                KeyCode::Up => self.count += 1,
                KeyCode::Down => self.count -= 1,
                _ => return None,
            }
            return Some(vec![]);
        }
        None
    }
    fn render(&mut self, _ctx: &ViewContext) -> Frame {
        Frame::new(vec![Line::new(format!("Count: {}", self.count))])
    }
}

§See also

  • Event — the input events passed to on_event.
  • Frame — the output of render.
  • ViewContext — the environment passed to render.
  • merge — combine event outcomes from multiple children.

Required Associated Types§

Source

type Message

The message type emitted by this widget.

Required Methods§

Source

fn on_event( &mut self, event: &Event, ) -> impl Future<Output = Option<Vec<Self::Message>>>

Process an event and return the outcome.

  • None — event not recognized, propagate to parent
  • Some(vec![]) — event consumed, no messages
  • Some(vec![msg, ...]) — event consumed, emit messages
Source

fn render(&mut self, ctx: &ViewContext) -> Frame

Render the current state to a frame.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors§