pub trait Widget: AsAny {
Show 13 methods
// Required methods
fn on_pointer_event(&mut self, ctx: &mut EventCtx<'_>, event: &PointerEvent);
fn on_text_event(&mut self, ctx: &mut EventCtx<'_>, event: &TextEvent);
fn on_access_event(&mut self, ctx: &mut EventCtx<'_>, event: &AccessEvent);
fn on_status_change(
&mut self,
ctx: &mut LifeCycleCtx<'_>,
event: &StatusChange
);
fn lifecycle(&mut self, ctx: &mut LifeCycleCtx<'_>, event: &LifeCycle);
fn layout(&mut self, ctx: &mut LayoutCtx<'_>, bc: &BoxConstraints) -> Size;
fn paint(&mut self, ctx: &mut PaintCtx<'_>, scene: &mut Scene);
fn accessibility_role(&self) -> Role;
fn accessibility(&mut self, ctx: &mut AccessCtx<'_>);
fn children(&self) -> SmallVec<[WidgetRef<'_, dyn Widget>; 16]>;
// Provided methods
fn make_trace_span(&self) -> Span { ... }
fn get_debug_text(&self) -> Option<String> { ... }
fn get_child_at_pos(&self, pos: Point) -> Option<WidgetRef<'_, dyn Widget>> { ... }
}
Expand description
The trait implemented by all widgets.
For details on how to implement this trait, see tutorial (TODO)
Whenever external events affect the given widget, methods [on_event
],
on_status_change
and lifecycle
are called. Later on, when the widget is laid out and displayed, methods
layout
and paint
are called.
These trait methods are provided with a corresponding context. The widget can request things and cause actions by calling methods on that context.
Widgets also have a children
method. Leaf widgets return an empty array,
whereas container widgets return an array of WidgetRef
. Container widgets
have some validity invariants to maintain regarding their children. See TUTORIAL_2
for details (TODO).
Generally speaking, widgets aren’t used directly. They are stored in
WidgetPods
. Widget methods are called by WidgetPods, and the
widget is mutated either during a method call (eg on_event
or lifecycle
) or
through a WidgetMut
. See tutorials for details.
Required Methods§
sourcefn on_pointer_event(&mut self, ctx: &mut EventCtx<'_>, event: &PointerEvent)
fn on_pointer_event(&mut self, ctx: &mut EventCtx<'_>, event: &PointerEvent)
fn on_text_event(&mut self, ctx: &mut EventCtx<'_>, event: &TextEvent)
sourcefn on_access_event(&mut self, ctx: &mut EventCtx<'_>, event: &AccessEvent)
fn on_access_event(&mut self, ctx: &mut EventCtx<'_>, event: &AccessEvent)
Handle an event from the platform’s accessibility API.
fn on_status_change(&mut self, ctx: &mut LifeCycleCtx<'_>, event: &StatusChange)
sourcefn lifecycle(&mut self, ctx: &mut LifeCycleCtx<'_>, event: &LifeCycle)
fn lifecycle(&mut self, ctx: &mut LifeCycleCtx<'_>, event: &LifeCycle)
Handle a lifecycle notification.
This method is called to notify your widget of certain special events,
(available in the LifeCycle
enum) that are generally related to
changes in the widget graph or in the state of your specific widget.
sourcefn layout(&mut self, ctx: &mut LayoutCtx<'_>, bc: &BoxConstraints) -> Size
fn layout(&mut self, ctx: &mut LayoutCtx<'_>, bc: &BoxConstraints) -> Size
Compute layout.
A leaf widget should determine its size (subject to the provided constraints) and return it.
A container widget will recursively call WidgetPod::layout
on its
child widgets, providing each of them an appropriate box constraint,
compute layout, then call LayoutCtx::place_child
on each of its children.
Finally, it should return the size of the container. The container
can recurse in any order, which can be helpful to, for example, compute
the size of non-flex widgets first, to determine the amount of space
available for the flex widgets.
For efficiency, a container should only invoke layout of a child widget once, though there is nothing enforcing this.
The layout strategy is strongly inspired by Flutter.
sourcefn paint(&mut self, ctx: &mut PaintCtx<'_>, scene: &mut Scene)
fn paint(&mut self, ctx: &mut PaintCtx<'_>, scene: &mut Scene)
Paint the widget appearance.
Container widgets can paint a background before recursing to their children, or annotations (for example, scrollbars) by painting afterwards. In addition, they can apply masks and transforms on the render context, which is especially useful for scrolling.
fn accessibility_role(&self) -> Role
fn accessibility(&mut self, ctx: &mut AccessCtx<'_>)
sourcefn children(&self) -> SmallVec<[WidgetRef<'_, dyn Widget>; 16]>
fn children(&self) -> SmallVec<[WidgetRef<'_, dyn Widget>; 16]>
Return references to this widget’s children.
Leaf widgets return an empty array. Container widgets return references to their children.
This methods has some validity invariants. A widget’s children list must be
consistent. If children are added or removed, the parent widget should call
children_changed
on one of the Ctx parameters. Container widgets are also
responsible for calling the main methods (on_event, lifecycle, layout, paint)
on their children.
Provided Methods§
sourcefn make_trace_span(&self) -> Span
fn make_trace_span(&self) -> Span
Return a span for tracing.
As methods recurse through the widget tree, trace spans are added for each child widget visited, and popped when control flow goes back to the parent. This method returns a static span (that you can use to filter traces and logs).
sourcefn get_debug_text(&self) -> Option<String>
fn get_debug_text(&self) -> Option<String>
Return a small string representing important info about this widget instance.
When using WidgetRef
’s Debug
implementation, widgets
will be displayed as a tree of values. Widgets which return a non-null value in
get_debug_text
will appear with that text next to their type name. This can
be eg a label’s text, or whether a checkbox is checked.
sourcefn get_child_at_pos(&self, pos: Point) -> Option<WidgetRef<'_, dyn Widget>>
fn get_child_at_pos(&self, pos: Point) -> Option<WidgetRef<'_, dyn Widget>>
Return which child, if any, has the given pos
in its layout rect.
The child return is a direct child, not eg a grand-child. The position is in
relative coordinates. (Eg (0,0)
is the top-left corner of self
).
Has a default implementation, that can be overridden to search children more efficiently.