diff --git a/src/widgets.rs b/src/widgets.rs index a837a6ef..8e7d0ce5 100644 --- a/src/widgets.rs +++ b/src/widgets.rs @@ -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 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 for more information. /// /// A blanket implementation of `Widget` for `&W` where `W` implements `WidgetRef` is provided. /// @@ -359,9 +367,9 @@ impl WidgetRef for Option { /// 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 for more +/// information. /// /// A blanket implementation of `StatefulWidget` for `&W` where `W` implements `StatefulWidgetRef` /// is provided.