Trait StatefulWidgetRef

Source

pub trait StatefulWidgetRef {
    type State;

    // Required method
    fn render_ref(&self, area: Rect, buf: &mut Buffer, state: &mut Self::State);
}

Expand description

A StatefulWidgetRef is a trait that allows rendering a stateful widget by reference.

This is the stateful equivalent of WidgetRef. It is useful when you want to store a reference to a stateful widget and render it later. It also allows you to render boxed stateful widgets.

This trait was introduced in Ratatui 0.26.0 and is implemented for all the internal stateful widgets. It is currently marked as unstable as we are still evaluating the API and may make changes in the future. See https://github.com/ratatui/ratatui/issues/1287 for more information.

A blanket implementation of StatefulWidget for &W where W implements StatefulWidgetRef is provided.

See the documentation for WidgetRef for more information on boxed widgets. See the documentation for StatefulWidget for more information on stateful widgets.

§Examples

use ratatui::{
    buffer::Buffer,
    layout::Rect,
    style::Stylize,
    text::Line,
    widgets::{StatefulWidget, StatefulWidgetRef, Widget},
};

struct PersonalGreeting;

impl StatefulWidgetRef for PersonalGreeting {
    type State = String;
    fn render_ref(&self, area: Rect, buf: &mut Buffer, state: &mut Self::State) {
        Line::raw(format!("Hello {}", state)).render(area, buf);
    }
}

impl StatefulWidget for PersonalGreeting {
    type State = String;
    fn render(self, area: Rect, buf: &mut Buffer, state: &mut Self::State) {
        (&self).render_ref(area, buf, state);
    }
}

fn render(area: Rect, buf: &mut Buffer) {
    let widget = PersonalGreeting;
    let mut state = "world".to_string();
    widget.render(area, buf, &mut state);
}

§Stability

This API is marked as unstable and is only available when the unstable-widget-ref crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.