Mirrors/ratatui
2
0
Fork 0
mirror of https://github.com/ratatui-org/ratatui synced 2024-09-20 06:31:59 +00:00
Code Issues Projects Releases Packages Wiki Activity

docs(widgets): document stability of WidgetRef (#1288)

Browse source 
Addresses some confusion about when to implement `WidgetRef` vs `impl
Widget for &W`. Notes the stability rationale and links to an issue that
helps explain the context of where we're at in working this out.
This commit is contained in:
Josh McKinney 2024-08-05 17:29:14 -07:00 committed by GitHub
parent 82b70fd329
commit 2fd5ae64bf
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 19 additions and 11 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

30
src/widgets.rs
View file

@ -60,14 +60,22 @@ use crate::{buffer::Buffer, layout::Rect, style::Style};
/// during rendering. This meant that they were not meant to be stored but used as *commands* to
/// draw common figures in the UI.
///
/// Starting with Ratatui 0.26.0, we added a new [`WidgetRef`] trait and implemented this on all the
/// internal widgets. This allows you to store a reference to a widget and render it later. It also
/// Starting with Ratatui 0.26.0, all the internal widgets implement Widget for a reference to
/// themselves. This allows you to store a reference to a widget and render it later. Widget crates
/// should consider also doing this to allow for more flexibility in how widgets are used.
///
/// In Ratatui 0.26.0, we also added an unstable [`WidgetRef`] trait and implemented this on all the
/// internal widgets. In addition to the above benefit of rendering references to widgets, this also
/// allows you to render boxed widgets. 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.
/// See <https://github.com/ratatui-org/ratatui/issues/1287> for more information.
///
/// The `Widget` trait can still be implemented, however, it is recommended to implement `WidgetRef`
/// and add an implementation of `Widget` that calls `WidgetRef::render_ref`. This pattern should be
/// used where backwards compatibility is required (all the internal widgets use this approach).
/// In general where you expect a widget to immutably work on its data, we recommended to implement
/// `Widget` for a reference to the widget (`impl Widget for &MyWidget`). If you need to store state
/// between draw calls, implement `StatefulWidget` if you want the Widget to be immutable, or
/// implement `Widget` for a mutable reference to the widget (`impl Widget for &mut MyWidget`) if
/// you want the widget to be mutable. The mutable widget pattern is used infrequently in apps, but
/// can be quite useful.
///
/// A blanket implementation of `Widget` for `&W` where `W` implements `WidgetRef` is provided.
/// Widget is also implemented for `&str` and `String` types.
@ -235,9 +243,9 @@ pub trait StatefulWidget {
/// 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.
/// 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-org/ratatui/issues/1287> for more information.
///
/// A blanket implementation of `Widget` for `&W` where `W` implements `WidgetRef` is provided.
///
@ -359,9 +367,9 @@ impl<W: WidgetRef> WidgetRef for Option<W> {
/// 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. Implementors should prefer to implement this over the `StatefulWidget` trait and add an
/// implementation of `StatefulWidget` that calls `StatefulWidgetRef::render_ref` where backwards
/// compatibility is required.
/// 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-org/ratatui/issues/1287> for more
/// information.
///
/// A blanket implementation of `StatefulWidget` for `&W` where `W` implements `StatefulWidgetRef`
/// is provided.