pub trait Events: Widget + Sized {
// Provided methods
fn make_child_id(&mut self, index: usize) -> Id { ... }
fn configure(&mut self, cx: &mut ConfigCx<'_>) { ... }
fn configure_recurse(&mut self, cx: &mut ConfigCx<'_>, data: &Self::Data) { ... }
fn update(&mut self, cx: &mut ConfigCx<'_>, data: &Self::Data) { ... }
fn update_recurse(&mut self, cx: &mut ConfigCx<'_>, data: &Self::Data) { ... }
fn navigable(&self) -> bool { ... }
fn handle_hover(&mut self, cx: &mut EventCx<'_>, state: bool) -> IsUsed { ... }
fn handle_event(
&mut self,
cx: &mut EventCx<'_>,
data: &Self::Data,
event: Event
) -> IsUsed { ... }
fn steal_event(
&mut self,
cx: &mut EventCx<'_>,
data: &Self::Data,
id: &Id,
event: &Event
) -> IsUsed { ... }
fn handle_messages(&mut self, cx: &mut EventCx<'_>, data: &Self::Data) { ... }
fn handle_scroll(
&mut self,
cx: &mut EventCx<'_>,
data: &Self::Data,
scroll: Scroll
) { ... }
}Expand description
Widget event-handling
This trait governs event handling as part of a Widget implementation.
It is used by the #widget macro to generate hidden Widget methods.
The implementation of this method may be omitted where no event-handling is required. All methods have a default implementation.
Widget lifecycle
- The widget is configured (
Events::configure) and immediately updated (Events::update). - The widget has its size-requirements checked by calling
Layout::size_rulesfor each axis. Layout::set_rectis called to position elements. This may use data cached bysize_rules.- The widget is updated again after any data change (see
ConfigCx::update). - The widget is ready for event-handling and drawing
(
Events::handle_event,Layout::find_id,Layout::draw).
Widgets are responsible for ensuring that their children may observe this lifecycle. Usually this simply involves inclusion of the child in layout operations. Steps of the lifecycle may be postponed until a widget becomes visible.
Provided Methods§
sourcefn make_child_id(&mut self, index: usize) -> Id
fn make_child_id(&mut self, index: usize) -> Id
Make an identifier for a child
This is used to assign children identifiers. It may return
Id::default in order to avoid configuring the child, but in
this case the widget must configure via another means.
If this is implemented explicitly then Layout::find_child_index must
be too.
Default impl: self.id_ref().make_child(index)
sourcefn configure(&mut self, cx: &mut ConfigCx<'_>)
fn configure(&mut self, cx: &mut ConfigCx<'_>)
Configure self
Widgets are configured before sizing, drawing and event handling (see widget lifecycle). Configuration may be repeated at any time.
Self::update is always called immediately after this method,
followed by Self::configure_recurse.
The window’s scale factor (and thus any sizes available through
ConfigCx::size_cx) may not be correct initially (some platforms
construct all windows using scale factor 1) and/or may change in the
future. Changes to the scale factor result in recalculation of
Layout::size_rules but not repeated configuration.
The default implementation does nothing.
sourcefn configure_recurse(&mut self, cx: &mut ConfigCx<'_>, data: &Self::Data)
fn configure_recurse(&mut self, cx: &mut ConfigCx<'_>, data: &Self::Data)
Configure children
This method is called after Self::configure.
It usually configures all children.
The default implementation suffices except where children should not be configured (for example, to delay configuration of hidden children).
Use Events::make_child_id and ConfigCx::configure.
sourcefn update(&mut self, cx: &mut ConfigCx<'_>, data: &Self::Data)
fn update(&mut self, cx: &mut ConfigCx<'_>, data: &Self::Data)
Update self using input data
This method is called immediately after Self::configure and after
any input data is updated, before Layout::draw is called.
Typically this method is called immediately after the data is updated
but the call may be delayed until when the widget becomes visible.
This method is called before Self::update_recurse.
The default implementation does nothing.
sourcefn update_recurse(&mut self, cx: &mut ConfigCx<'_>, data: &Self::Data)
fn update_recurse(&mut self, cx: &mut ConfigCx<'_>, data: &Self::Data)
Update children
This method is called after Self::update. It usually configures all
children. Children should be updated even if their data is () or is
unchanged.
The default implementation suffices except where children should not be updated (for example, to delay update of hidden children).
Use ConfigCx::update.
Is this widget navigable via Tab key?
Note that when this method returns false the widget will not receive
navigation focus via the Tab key, but it may still receive
navigation focus through some other means, for example a keyboard
shortcut or a mouse click.
Defaults to false. May instead be set via the navigable property of
the #[widget] macro.
sourcefn handle_hover(&mut self, cx: &mut EventCx<'_>, state: bool) -> IsUsed
fn handle_hover(&mut self, cx: &mut EventCx<'_>, state: bool) -> IsUsed
Mouse focus handler
Called on Event::MouseHover before Self::handle_event.
state is true when hovered.
When the #widget macro properties hover_highlight or cursor_icon
are used, an instance of this method is generated. Otherwise, the
default implementation of this method does nothing and equivalent
functionality could be implemented in Events::handle_event instead.
Note: to implement hover_highlight, simply request a redraw on
focus gain and loss. To implement cursor_icon, call
cx.set_hover_cursor(EXPR); on focus gain.
sourcefn handle_event(
&mut self,
cx: &mut EventCx<'_>,
data: &Self::Data,
event: Event
) -> IsUsed
fn handle_event( &mut self, cx: &mut EventCx<'_>, data: &Self::Data, event: Event ) -> IsUsed
Handle an Event
This is the primary event handler (see documentation).
This method is called on the primary event target. In this case,
EventCx::last_child returns None.
This method may also be called on ancestors during unwinding (if the
event remains unused and the event
is reusable). In this case,
EventCx::last_child returns Some(index) with the index of the
child being unwound from.
Default implementation of handle_event: do nothing; return
Unused.
sourcefn steal_event(
&mut self,
cx: &mut EventCx<'_>,
data: &Self::Data,
id: &Id,
event: &Event
) -> IsUsed
fn steal_event( &mut self, cx: &mut EventCx<'_>, data: &Self::Data, id: &Id, event: &Event ) -> IsUsed
Potentially steal an event before it reaches a child
This is an optional event handler (see documentation).
The method should either return Used or return Unused without
modifying cx; attempting to do otherwise (e.g. by calling
EventCx::set_scroll or leaving a message on the stack when returning
Unused) will result in a panic.
Default implementation: return Unused.
sourcefn handle_messages(&mut self, cx: &mut EventCx<'_>, data: &Self::Data)
fn handle_messages(&mut self, cx: &mut EventCx<'_>, data: &Self::Data)
Handler for messages from children/descendants
This is the secondary event handler (see documentation).
It is implied that the stack contains at least one message.
Use EventCx::try_pop and/or EventCx::try_observe.
EventCx::last_child may be called to find the message’s sender.
This may return None (if no child was visited, which implies that
the message was sent by self).
The default implementation does nothing.
sourcefn handle_scroll(
&mut self,
cx: &mut EventCx<'_>,
data: &Self::Data,
scroll: Scroll
)
fn handle_scroll( &mut self, cx: &mut EventCx<'_>, data: &Self::Data, scroll: Scroll )
Handler for scrolling
When, during event handling, a widget which is a strict
descendant of self (i.e. not self) calls EventCx::set_scroll
with a value other than Scroll::None, this method is called.
Note that Scroll::Rect values are in the child’s coordinate space,
and must be translated to the widget’s own coordinate space by this
method (this is not done by the default implementation since any widget
with non-zero translation very likely wants to implement this method
anyway).
If the child is in an independent coordinate space, then this method
should call cx.set_scroll(Scroll::None) to avoid any reactions to
child’s scroll requests.
EventCx::last_child may be called to find the child responsible,
and should never return None (when called from this method).
The default implementation does nothing.
