pub trait Component: Sized {
type State;
type Message: Clone;
type Output: Clone;
// Required methods
fn init() -> Self::State;
fn update(
state: &mut Self::State,
msg: Self::Message,
) -> Option<Self::Output>;
fn view(
state: &Self::State,
frame: &mut Frame<'_>,
area: Rect,
theme: &Theme,
);
// Provided methods
fn traced_view(
state: &Self::State,
frame: &mut Frame<'_>,
area: Rect,
theme: &Theme,
) { ... }
fn handle_event(state: &Self::State, event: &Event) -> Option<Self::Message> { ... }
fn dispatch_event(
state: &mut Self::State,
event: &Event,
) -> Option<Self::Output> { ... }
}Expand description
A composable UI component with its own state and message handling.
Components are the building blocks of complex TUI applications. Each component manages its own state, handles its own messages, and renders to a specific area of the screen.
§Associated Types
State: The component’s internal state. DeriveCloneif you need snapshots.Message: Messages the component can receive from its parent or from user interaction.Output: Messages the component emits to communicate with its parent. Use()if the component doesn’t need to communicate outward.
§Design Pattern
Components follow the same TEA pattern as App, but
at a smaller scale:
- Parent sends
Messageto component - Component updates its
State - Component optionally emits
Outputto parent - Component renders itself to its designated area
Required Associated Types§
Sourcetype State
type State
The component’s internal state type.
This should contain all data needed to render the component.
Deriving Clone is recommended but not required.
Required Methods§
Sourcefn init() -> Self::State
fn init() -> Self::State
Initialize the component state.
Returns the initial state for this component.
Sourcefn update(state: &mut Self::State, msg: Self::Message) -> Option<Self::Output>
fn update(state: &mut Self::State, msg: Self::Message) -> Option<Self::Output>
Update component state based on a message.
Returns an optional output message for the parent to handle.
Return None if no parent notification is needed.
Sourcefn view(state: &Self::State, frame: &mut Frame<'_>, area: Rect, theme: &Theme)
fn view(state: &Self::State, frame: &mut Frame<'_>, area: Rect, theme: &Theme)
Render the component to the given area.
Unlike App::view which renders to the full
frame, components render to a specific Rect area provided by their
parent.
The theme parameter provides the color scheme to use for rendering.
Use Theme::default() for the standard color scheme, or
Theme::nord() for the Nord color palette.
Provided Methods§
Sourcefn traced_view(
state: &Self::State,
frame: &mut Frame<'_>,
area: Rect,
theme: &Theme,
)
fn traced_view( state: &Self::State, frame: &mut Frame<'_>, area: Rect, theme: &Theme, )
Renders the component with optional tracing instrumentation.
When the tracing feature is enabled, this emits a trace-level span
around the view call with the component type name
and render area dimensions. When the feature is disabled, this is
identical to calling view directly.
Sourcefn handle_event(state: &Self::State, event: &Event) -> Option<Self::Message>
fn handle_event(state: &Self::State, event: &Event) -> Option<Self::Message>
Maps an input event to a component message.
This is the read-only half of event handling. It inspects the component’s state and the incoming event, and returns an appropriate message if the event is relevant to this component.
The default implementation returns None (ignores all events).
Components should override this to handle keyboard input when focused.
Sourcefn dispatch_event(
state: &mut Self::State,
event: &Event,
) -> Option<Self::Output>
fn dispatch_event( state: &mut Self::State, event: &Event, ) -> Option<Self::Output>
Dispatches an event by mapping it to a message and updating state.
This combines handle_event and
update into a single call. If the event
produces a message, the message is passed to update and the
output is returned.
This is the primary method users should call for event routing.
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.