diff --git a/src/ui/widget.rs b/src/ui/widget.rs index 6b4a39e6..e07e4165 100644 --- a/src/ui/widget.rs +++ b/src/ui/widget.rs @@ -21,23 +21,37 @@ pub type BoxedWidget = Box>; pub type UpdateCallback = fn(&S) -> Box; pub type EventCallback = fn(&dyn Any, UnboundedSender); +/// Main trait defining a `View` behaviour. +/// +/// This is the first trait that you should implement to define a custom `Widget`. pub trait View { + /// Should return a new view with props build from state (if type is known) and a + /// message sender set. fn new(state: &S, action_tx: UnboundedSender) -> Self where Self: Sized; + /// Should set the optional custom event handler. fn on_change(self, callback: EventCallback) -> Self where Self: Sized; + /// Should set the optional update handler. fn on_update(self, callback: UpdateCallback) -> Self where Self: Sized; + /// Should handle key events and call `handle_key_event` on all children. + /// + /// After key events have been handled, the custom event handler `on_change` should + /// be called fn handle_key_event(&mut self, key: Key); + /// Should update internal props by calling the custom update handler `on_update` + /// and call `update` on all children. fn update(&mut self, state: &S); + /// Returns a boxed `View` fn to_boxed(self) -> Box where Self: Sized, @@ -46,17 +60,26 @@ pub trait View { } } +/// A `Widget` is a `View` that can be rendered using a specific backend. +/// +/// This is the second trait that you should implement to define a custom `Widget`. pub trait Widget: View where B: Backend, { + /// Renders a widget to the given frame in the given area. + /// + /// Will try to downcast the given props object to the internally used one. + /// If successful, these props take precedence over the internal ones. fn render(&self, frame: &mut Frame, area: Rect, props: &dyn Any); } +/// Needs to be implemented for items that are supposed to be rendering in tables. pub trait ToRow { fn to_row(&self) -> Vec; } +/// Common trait for view properties. pub trait Properties { fn to_boxed(self) -> Box where