pub trait Component: Sized {
type State;
type Message;
type Output;
// Required methods
fn init() -> Self::State;
fn update(
state: &mut Self::State,
msg: Self::Message,
) -> Option<Self::Output>;
fn view(state: &Self::State, ctx: &mut RenderContext<'_, '_>);
// Provided methods
fn traced_view(state: &Self::State, ctx: &mut RenderContext<'_, '_>) { ... }
fn handle_event(
state: &Self::State,
event: &Event,
ctx: &EventContext,
) -> Option<Self::Message> { ... }
fn dispatch_event(
state: &mut Self::State,
event: &Event,
ctx: &EventContext,
) -> 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, ctx: &mut RenderContext<'_, '_>)
fn view(state: &Self::State, ctx: &mut RenderContext<'_, '_>)
Render the component to the given area.
Unlike App::view which renders to the full
frame, components render to a specific area carried by the
RenderContext. The context bundles the frame, render area, theme,
and focus/disabled state.
Provided Methods§
Sourcefn traced_view(state: &Self::State, ctx: &mut RenderContext<'_, '_>)
fn traced_view(state: &Self::State, ctx: &mut RenderContext<'_, '_>)
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,
ctx: &EventContext,
) -> Option<Self::Message>
fn handle_event( state: &Self::State, event: &Event, ctx: &EventContext, ) -> 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, the incoming event, and the EventContext
(which carries focused/disabled state from the parent), and
returns an appropriate message if the event is relevant.
Components should check ctx.focused and ctx.disabled to
decide whether to process the event. The same focus/disabled
state should be passed to both handle_event and
view (via the RenderContext) so that
visual state and event routing are always consistent.
The default implementation returns None (ignores all events).
Sourcefn dispatch_event(
state: &mut Self::State,
event: &Event,
ctx: &EventContext,
) -> Option<Self::Output>
fn dispatch_event( state: &mut Self::State, event: &Event, ctx: &EventContext, ) -> 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.