Trait ratatui::widgets::WidgetRef

pub trait WidgetRef {
    // Required method
    fn render_ref(&self, area: Rect, buf: &mut Buffer);
}

Available on crate feature unstable-widget-ref only.

A WidgetRef is a trait that allows rendering a widget by reference.

This trait is useful when you want to store a reference to a widget and render it later. It also allows you to render boxed widgets.

Boxed widgets allow you to store widgets with a type that is not known at compile time. This is useful when you want to store a collection of widgets with different types. You can then iterate over the collection and render each widget.

This trait was introduced in Ratatui 0.26.0 and is implemented for all the internal widgets. Implementors should prefer to implement this over the Widget trait and add an implementation of Widget that calls WidgetRef::render_ref where backwards compatibility is required.

A blanket implementation of Widget for &W where W implements WidgetRef is provided.

A blanket implementation of WidgetRef for Option<W> where W implements WidgetRef is provided. This is a convenience approach to make it easier to attach child widgets to parent widgets. It allows you to render an optional widget by reference.

Examples

use ratatui::{prelude::*, widgets::*};

struct Greeting;

struct Farewell;

impl WidgetRef for Greeting {
    fn render_ref(&self, area: Rect, buf: &mut Buffer) {
        Line::raw("Hello").render(area, buf);
    }
}

/// Only needed for backwards compatibility
impl Widget for Greeting {
    fn render(self, area: Rect, buf: &mut Buffer) {
        self.render_ref(area, buf);
    }
}

impl WidgetRef for Farewell {
    fn render_ref(&self, area: Rect, buf: &mut Buffer) {
        Line::raw("Goodbye").right_aligned().render(area, buf);
    }
}

/// Only needed for backwards compatibility
impl Widget for Farewell {
    fn render(self, area: Rect, buf: &mut Buffer) {
        self.render_ref(area, buf);
    }
}

let greeting = Greeting;
let farewell = Farewell;

// these calls do not consume the widgets, so they can be used again later
greeting.render_ref(area, buf);
farewell.render_ref(area, buf);

// a collection of widgets with different types
let widgets: Vec<Box<dyn WidgetRef>> = vec![Box::new(greeting), Box::new(farewell)];
for widget in widgets {
    widget.render_ref(area, buf);
}

Availability

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.

Required Methods

fn render_ref(&self, area: Rect, buf: &mut Buffer)

Draws the current state of the widget in the given buffer. That is the only method required to implement a custom widget.

Implementations on Foreign Types

impl WidgetRef for &str

Provides the ability to render a string slice by reference.

This trait implementation ensures that a string slice, which is an immutable view over a String, can be drawn on demand without requiring ownership of the string itself. It utilizes the default text style when rendering onto the provided Buffer at the position defined by Rect.

fn render_ref(&self, area: Rect, buf: &mut Buffer)

Available on crate feature unstable-widget-ref only.

impl WidgetRef for String

Provides the ability to render a String by reference.

This trait allows for a String to be rendered onto the Buffer, similarly using the default style settings. It ensures that an owned String can be rendered efficiently by reference, without the need to give up ownership of the underlying text.

fn render_ref(&self, area: Rect, buf: &mut Buffer)

Available on crate feature unstable-widget-ref only.

impl<W: WidgetRef> WidgetRef for Option<W>

A blanket implementation of WidgetExt for Option<W> where W implements WidgetRef.

This is a convenience implementation that makes it easy to attach child widgets to parent widgets. It allows you to render an optional widget by reference.

The internal widgets use this pattern to render the optional Block widgets that are included on most widgets. Blanket implementation of WidgetExt for Option<W> where W implements WidgetRef.

Examples

use ratatui::{prelude::*, widgets::*};

struct Parent {
    child: Option<Child>,
}

struct Child;

impl WidgetRef for Child {
    fn render_ref(&self, area: Rect, buf: &mut Buffer) {
        Line::raw("Hello from child").render(area, buf);
    }
}

impl WidgetRef for Parent {
    fn render_ref(&self, area: Rect, buf: &mut Buffer) {
        self.child.render_ref(area, buf);
    }
}

fn render_ref(&self, area: Rect, buf: &mut Buffer)

Available on crate feature unstable-widget-ref only.

Implementors

impl WidgetRef for Line<'_>

impl WidgetRef for Span<'_>

impl WidgetRef for Text<'_>

impl WidgetRef for Block<'_>

impl WidgetRef for BarChart<'_>

impl WidgetRef for Chart<'_>

impl WidgetRef for Clear

impl WidgetRef for Gauge<'_>

impl WidgetRef for LineGauge<'_>

impl WidgetRef for List<'_>

impl WidgetRef for Paragraph<'_>

impl WidgetRef for Sparkline<'_>

impl WidgetRef for Table<'_>

impl WidgetRef for Tabs<'_>

impl<DS: DateStyler> WidgetRef for Monthly<'_, DS>

Available on crate feature widget-calendar only.

impl<F> WidgetRef for Canvas<'_, F>

where F: Fn(&mut Context<'_>),