pub trait WidgetRef {
// Required method
fn render_ref(&self, area: Rect, buf: &mut Buffer);
}Expand description
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. 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 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::{
buffer::Buffer,
layout::Rect,
text::Line,
widgets::{Widget, WidgetRef},
};
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);
}§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.
Required Methods§
Sourcefn render_ref(&self, area: Rect, buf: &mut Buffer)
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§
Source§impl WidgetRef for &str
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)
Source§impl WidgetRef for String
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)
Source§impl<W: WidgetRef> WidgetRef for Option<W>
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::{
buffer::Buffer,
layout::Rect,
text::Line,
widgets::{Widget, WidgetRef},
};
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);
}
}