Struct Container 

pub struct Container { /* private fields */ }

Container is a data structure used to store and organize UI components, including Header, Option, Text, Separator, and Selector. It is created using a ContainerBuilder.

Usage

• Handle UI events with the looper method.
• Render the UI using a Renderer (recommended).
• Alternatively, use the draw or draw_fullscreen methods.
• Access Option components by ID using option and option_mut.
• Access Text components by ID using text and text_mut.
• Navigate using selector_up, selector_down, and selector_select.

Implementations

impl Container

pub fn looper(&mut self) -> FtuiResult<bool>

Updates the container and returns whether a change occurred.

Returns

• Ok(bool): Returns whether an update occurred.
• Err(FtuiError): Returns an error.

Example

fn render() {
    todo!();
}

// Re-render the UI if an update occurred.
if container.looper()? {
    render();
}

pub fn draw(&mut self, width: u16, height: u16) -> FtuiResult<()>

Renders the Container using a temporary Renderer. This method is ideal for quick, one-off renderings where performance isn’t critical. Internally, it creates a new Renderer with the given dimensions and uses it to draw the Container. If you need to render multiple times, consider using a persistent Renderer for better performance.

Parameters

• width: The width of the rendering area.
• height: The height of the rendering area.

Returns

• Ok(()): Returns nothing.
• Err(FtuiError): Returns an error.

Example

// Good for quick one-off rendering like this.
fn render_ui() -> FtuiResult<()> {
    ContainerBuilder::new()
        .header(...)?
        .text(...)?
        .build()
        .draw(40, 20)?; // Render with dimensions 40x20.

    Ok(())
}

pub fn draw_fullscreen(&mut self) -> FtuiResult<()>

Renders the Container using a temporary Renderer. This method is ideal for quick, one-off renderings where performance isn’t critical. Internally, it creates a new fullscreen Renderer and uses it to draw the Container. If you need to render multiple times, consider using a persistent Renderer for better performance.

Returns

• Ok(()): Returns nothing.
• Err(FtuiError): Returns an error.

Example

// Good for quick one-off rendering like this.
fn render_ui() -> FtuiResult<()> {
    ContainerBuilder::new()
        .header(...)?
        .text(...)?
        .build()
        .draw_fullscreen()?; // Render in fullscreen.

    Ok(())
}

pub fn option(&self, id: u16) -> FtuiResult<&Option>

Query an Option component by its ID (O(n) lookup).

Parameters

• id: The ID of the Option component to query.

Returns

• Ok(&Option): A reference to the Option component.
• Err(FtuiError): Returns an error.

Example

// A mutable `u16` to store the ID of a `Option` component.
let mut option_id = 0;

let container = ContainerBuilder::new()
    .option_id(..., &mut option_id)?
    .build();

// Query the option by its ID.
container.option(option_id)?;

pub fn option_mut(&mut self, id: u16) -> FtuiResult<&mut Option>

Query an Option component by its ID (O(n) lookup).

Parameters

• id: The ID of the Option component to query.

Returns

• Ok(&Option): A mutable reference to the Option component.
• Err(FtuiError): Returns an error.

Example

// A mutable `u16` to store the ID of a `Option` component.
let mut option_id = 0;

let container = ContainerBuilder::new()
    .option_id(..., &mut option_id)?
    .build();

// Query the option by its ID.
container.option_mut(option_id)?;

pub fn text(&self, id: u16) -> FtuiResult<&Text>

Query an Text component by its ID (O(n) lookup).

Parameters

• id: The ID of the Text component to query.

Returns

• Ok(&Option): A reference to the Text component.
• Err(FtuiError): Returns an error.

Example

// A mutable `u16` to store the ID of a `Text` component.
let mut text_id: u16 = 0;

let container = ContainerBuilder::new()
    .text_id(..., &mut text_id)?
    .build();

// Query the option by its ID.
container.text(text_id)?;

pub fn text_mut(&mut self, id: u16) -> FtuiResult<&mut Text>

Query an Text component by its ID (O(n) lookup).

Parameters

• id: The ID of the Text component to query.

Returns

• Ok(&Option): A mutable reference to the Text component.
• Err(FtuiError): Returns an error.

Example

// A mutable `u16` to store the ID of a `Text` component.
let mut text_id: u16 = 0;

let container = ContainerBuilder::new()
    .text_id(..., &mut text_id)?
    .build();

// Query the option by its ID.
container.text_mut(text_id)?;

pub fn selector_mut(&mut self) -> FtuiResult<&mut Selector>

Returns a mutable reference to the Selector component, if the Container has one.

Returns

• Ok(&mut Selector): A mutable reference to the Selector component.
• Err(FtuiError): Return an error.

Example

// Create a container with a `Selector`.
let mut container = ContainerBuilder::new()
    .selector_no_triggers()
    .build();

// Get a mutable reference to the `Selector`.
container.selector_mut()?;

pub fn selector_up(&mut self) -> FtuiResult<bool>

Attempts to move the Selector up by one position, if possible.

Returns

• Ok(true): The selector moved up successfully.
• Ok(false): The selector could not move (already at the top).
• Err(FtuiError): Returns an error.

Example

// Create a container with two `Option`s component and a `Selector`.
let mut container = ContainerBuilder::new()
    .option(...)? // This is where the `Selector` will be when initialize.
    .option(...)?
    .selector_no_triggers()
    .build();

// The `Selector` cannot move up since it is at the top.
assert_eq!(container.selector_up()?, false);

pub fn selector_down(&mut self) -> FtuiResult<bool>

Attempts to move the Selector down by one position, if possible.

Returns

• Ok(true): The selector moved down successfully.
• Ok(false): The selector could not move (already at the bottom).
• Err(FtuiError): Returns an error.

Example

// Create a container with two `Option`s component and a `Selector`.
let mut container = ContainerBuilder::new()
    .option(...)? // This is where the `Selector` will be when initialize.
    .option(...)?
    .selector_no_triggers()
    .build();

// The `Selector` can move up since it is not at the bottom.
assert_eq!(container.selector_up()?, true);

pub fn selector_select(&mut self) -> FtuiResult<bool>

Attempts to select the Option that the Selector is currently on. This operation should always succeed unless an error occurs internally.

Returns

• Ok(true): The selection was successful.
• Err(FtuiError): An error occurred during selection.

Example

// Create a container with on `Option` components and a `Selector`.
let mut container = ContainerBuilder::new()
    .option(...)? // The `Selector` starts at this `Option`.
    .selector_no_triggers()
    .build();

// Selecting the current `Option` is always possible unless an error occurs.
assert_eq!(container.selector_select()?, true);