Trait Component

pub trait Component: Send {
    // Required methods
    fn name(&self) -> &'static str;
    fn min_inline_height(&self) -> u16;
    fn render(&mut self, frame: &mut Frame<'_>, area: Rect);

    // Provided methods
    fn init<'life0, 'async_trait>(
        &'life0 mut self,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn peek<'life0, 'async_trait>(
        &'life0 mut self,
    ) -> Pin<Box<dyn Future<Output = Result<Action>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn tick(&mut self) -> Result<Action> { ... }
    fn exit(&mut self) -> Result<Option<ProcessOutput>> { ... }
    fn process_paste_event(&mut self, content: String) -> Result<Action> { ... }
    fn process_key_event<'life0, 'life1, 'async_trait>(
        &'life0 mut self,
        keybindings: &'life1 KeyBindingsConfig,
        key: KeyEvent,
    ) -> Pin<Box<dyn Future<Output = Result<Action>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn default_process_key_event<'life0, 'life1, 'async_trait>(
        &'life0 mut self,
        keybindings: &'life1 KeyBindingsConfig,
        key: KeyEvent,
    ) -> Pin<Box<dyn Future<Output = Result<Option<Action>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn process_mouse_event(&mut self, mouse: MouseEvent) -> Result<Action> { ... }
    fn focus_gained(&mut self) -> Result<Action> { ... }
    fn focus_lost(&mut self) -> Result<Action> { ... }
    fn resize(&mut self, width: u16, height: u16) -> Result<Action> { ... }
    fn move_up(&mut self) -> Result<Action> { ... }
    fn move_down(&mut self) -> Result<Action> { ... }
    fn move_left(&mut self, word: bool) -> Result<Action> { ... }
    fn move_right(&mut self, word: bool) -> Result<Action> { ... }
    fn move_prev(&mut self) -> Result<Action> { ... }
    fn move_next(&mut self) -> Result<Action> { ... }
    fn move_home(&mut self, absolute: bool) -> Result<Action> { ... }
    fn move_end(&mut self, absolute: bool) -> Result<Action> { ... }
    fn undo(&mut self) -> Result<Action> { ... }
    fn redo(&mut self) -> Result<Action> { ... }
    fn insert_text(&mut self, text: String) -> Result<Action> { ... }
    fn insert_char(&mut self, c: char) -> Result<Action> { ... }
    fn insert_newline(&mut self) -> Result<Action> { ... }
    fn delete(&mut self, backspace: bool, word: bool) -> Result<Action> { ... }
    fn selection_delete<'life0, 'async_trait>(
        &'life0 mut self,
    ) -> Pin<Box<dyn Future<Output = Result<Action>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn selection_update<'life0, 'async_trait>(
        &'life0 mut self,
    ) -> Pin<Box<dyn Future<Output = Result<Action>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn selection_confirm<'life0, 'async_trait>(
        &'life0 mut self,
    ) -> Pin<Box<dyn Future<Output = Result<Action>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn selection_execute<'life0, 'async_trait>(
        &'life0 mut self,
    ) -> Pin<Box<dyn Future<Output = Result<Action>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn toggle_search_mode(&mut self) -> Result<Action> { ... }
    fn toggle_search_user_only(&mut self) -> Result<Action> { ... }
}

Defines the behavior for a UI component within the application.

Components are responsible for rendering themselves, handling user input, and managing their internal state. They can also perform logic updates periodically via the tick method.

Required Methods

fn name(&self) -> &'static str

Retrieves the component name, for debugging purposes

fn min_inline_height(&self) -> u16

Calculates the minimum height required by this component to be rendered correctly when inline (in rows)

fn render(&mut self, frame: &mut Frame<'_>, area: Rect)

Renders the component’s UI within the given area of the frame

Provided Methods

fn init<'life0, 'async_trait>( &'life0 mut self, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Allows the component to initialize any internal state or resources it needs before being used.

It can be called multiple times, for example if a component is re-used after being switched out.

fn peek<'life0, 'async_trait>( &'life0 mut self, ) -> Pin<Box<dyn Future<Output = Result<Action>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Peeks into the component before rendering, for examplle to give a straight result, switch component or continue with the TUI

fn tick(&mut self) -> Result<Action>

Processes time-based logic, internal state updates, or background tasks for the component.

This method is called periodically by the application’s main loop and is not directly tied to rendering or user input events. It can be used for animations, polling asynchronous operations, or updating internal timers.

fn exit(&mut self) -> Result<Option<ProcessOutput>>

Finalizes the component’s current operation and returns its output with the current state.

This method is typically called when the user signals that they want to exit the command.

fn process_paste_event(&mut self, content: String) -> Result<Action>

Processes a paste event, typically from clipboard paste into the terminal.

This method is called when the application detects a paste action. The content parameter contains the string of text that was pasted.

The default implementation will just call insert_text.

fn process_key_event<'life0, 'life1, 'async_trait>( &'life0 mut self, keybindings: &'life1 KeyBindingsConfig, key: KeyEvent, ) -> Pin<Box<dyn Future<Output = Result<Action>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Processes a key press event.

This method is the primary handler for keyboard input. It receives a KeyEvent and is responsible for translating it into component-specific behaviors or application-level Actions by consulting the provided keybindings or using hardcoded defaults.

Implementors can override this method to provide entirely custom key handling, optionally calling default_process_key_event first and checking its result.

fn default_process_key_event<'life0, 'life1, 'async_trait>( &'life0 mut self, keybindings: &'life1 KeyBindingsConfig, key: KeyEvent, ) -> Pin<Box<dyn Future<Output = Result<Option<Action>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

The default behavior for process_key_event with a baseline set of key mappings by matching against the event. It calls other granular methods of this trait (e.g., move_up, insert_char).

• If this default method returns Ok(Some(action)), it means the key was recognized and mapped to an Action.
• If it returns Ok(None), it means the specific key event was not handled by this default logic, allowing an overriding implementation to then process it.

fn process_mouse_event(&mut self, mouse: MouseEvent) -> Result<Action>

Processes a mouse event.

This method is called when a mouse action (like click, scroll, move) occurs within the terminal, provided mouse capture is enabled.

Returns Some if the event was processed or None if not (the default).

fn focus_gained(&mut self) -> Result<Action>

Called when the component gains focus within the application.

Components can implement this method to change their appearance (e.g., show a highlight border), enable input handling, initialize internal state specific to being active, or perform other setup tasks.

fn focus_lost(&mut self) -> Result<Action>

Called when the component loses focus within the application.

Components can implement this method to change their appearance (e.g., remove a highlight border), disable input handling, persist any temporary state, or perform other cleanup tasks.

fn resize(&mut self, width: u16, height: u16) -> Result<Action>

Handles a terminal resize event, informing the component of the new global terminal dimensions.

This method is called when the overall terminal window size changes. Components can use this notification to adapt internal state, pre-calculate layout-dependent values, or invalidate caches before a subsequent render call, which will likely provide a new drawing area (Rect) based on these new terminal dimensions.

Note: The width and height parameters typically represent the total new dimensions of the terminal in columns and rows, not necessarily the area allocated to this specific component.

fn move_up(&mut self) -> Result<Action>

Handles a request to move the selection or focus upwards within the component.

The exact behavior depends on the component’s nature (e.g., moving up in a list, focusing an element above the current one).

fn move_down(&mut self) -> Result<Action>

Handles a request to move the selection or focus downwards within the component.

The exact behavior depends on the component’s nature (e.g., moving down in a list, focusing an element below the current one).

fn move_left(&mut self, word: bool) -> Result<Action>

Handles a request to move the selection or focus to the left within the component.

The word parameter indicates whether the movement should be applied to a whole word or just a single character.

The exact behavior depends on the component’s nature (e.g., moving left in a text input, focusing an element to the left of the current one).

fn move_right(&mut self, word: bool) -> Result<Action>

Handles a request to move the selection or focus to the right within the component.

The word parameter indicates whether the movement should be applied to a whole word or just a single character.

The exact behavior depends on the component’s nature (e.g., moving right in a text input, focusing an element to the right of the current one).

fn move_prev(&mut self) -> Result<Action>

Handles a request to move the selection to the previous logical item or element.

This is often used for navigating backwards in a sequence (e.g., previous tab, previous item in a wizard) that may not map directly to simple directional moves.

fn move_next(&mut self) -> Result<Action>

Handles a request to move the selection to the next logical item or element.

This is often used for navigating forwards in a sequence (e.g., next tab, next item in a wizard) that may not map directly to simple directional moves.

fn move_home(&mut self, absolute: bool) -> Result<Action>

Handles a request to move the selection to the beginning (e.g., “Home” key).

The absolute parameter indicates whether the movement should be absolute (to the very start of the component) or relative (to the start of the current logical section).

This typically moves the selection to the first item in a list, the start of a text input, or the first element in a navigable group.

fn move_end(&mut self, absolute: bool) -> Result<Action>

Handles a request to move the selection to the end (e.g., “End” key).

The absolute parameter indicates whether the movement should be absolute (to the very end of the component) or relative (to the end of the current logical section).

This typically moves the selection to the last item in a list, the end of a text input, or the last element in a navigable group.

fn undo(&mut self) -> Result<Action>

Handles a request to undo the last action performed in the component.

The specific behavior depends on the component’s nature (e.g., undoing a text edit, reverting a selection change).

fn redo(&mut self) -> Result<Action>

Handles a request to redo the last undone action in the component.

The specific behavior depends on the component’s nature (e.g., redoing a text edit, restoring a selection change).

fn insert_text(&mut self, text: String) -> Result<Action>

Handles the insertion of a block of text into the component.

This is typically used for pasting text into a focused input field. If the component or its currently focused element does not support text input, this method may do nothing.

fn insert_char(&mut self, c: char) -> Result<Action>

Handles the insertion of a single character into the component.

This is typically used for typing into a focused input field. If the component or its currently focused element does not support text input, this method may do nothing.

fn insert_newline(&mut self) -> Result<Action>

Handles a request to insert a newline character into the component.

This is typically used for multiline text inputs or text areas where pressing “Shift+Enter” should create a new line.

fn delete(&mut self, backspace: bool, word: bool) -> Result<Action>

Handles the deletion key from the component, typically from a focused input field.

The backspace parameter distinguishes between deleting the character before the cursor (backspace) and deleting the character at/after the cursor (delete).

The word parameter indicates whether the deletion should be applied to a whole word or just a single character.

fn selection_delete<'life0, 'async_trait>( &'life0 mut self, ) -> Pin<Box<dyn Future<Output = Result<Action>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Handles a request to delete the currently selected item or element within the component.

The exact behavior depends on the component (e.g., deleting an item from a list, clearing a field).

fn selection_update<'life0, 'async_trait>( &'life0 mut self, ) -> Pin<Box<dyn Future<Output = Result<Action>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Handles a request to update or modify the currently selected item or element.

This could mean initiating an edit mode for an item, toggling a state, or triggering some other modification.

fn selection_confirm<'life0, 'async_trait>( &'life0 mut self, ) -> Pin<Box<dyn Future<Output = Result<Action>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Handles a request to confirm the currently selected item or element.

This is often equivalent to an “Enter” key press on a selected item, triggering its primary action (e.g., executing a command, submitting a form item, navigating into a sub-menu).

fn selection_execute<'life0, 'async_trait>( &'life0 mut self, ) -> Pin<Box<dyn Future<Output = Result<Action>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Handles a request to execute the primary action associated with the currently selected item or element within the component.

This method is typically invoked when the user wants to “run” or “activate” the selected item. For example, this could mean:

• Executing a shell command that is currently selected in a list.
• Starting a process associated with the selected item.
• Triggering a significant, non-trivial operation.

The specific behavior is determined by the component and the nature of its items.

fn toggle_search_mode(&mut self) -> Result<Action>

For the search command only, toggle the search mode

fn toggle_search_user_only(&mut self) -> Result<Action>

For the search command only, toggle the user-only mode

Implementors

impl Component for EditCommandComponent

impl Component for SearchCommandsComponent

impl Component for EmptyComponent

impl Component for VariableReplacementComponent