Trait Events 

pub trait Events: Widget + Sized {
    const REDRAW_ON_MOUSE_OVER: bool = false;

    // Provided methods
    fn mouse_over_icon(&self) -> Option<CursorIcon> { ... }
    fn make_child_id(&mut self, index: usize) -> Id { ... }
    fn probe(&self, coord: Coord) -> Id { ... }
    fn configure(&mut self, cx: &mut ConfigCx<'_>) { ... }
    fn post_configure(&mut self, cx: &mut ConfigCx<'_>) { ... }
    fn update(&mut self, cx: &mut ConfigCx<'_>, data: &Self::Data) { ... }
    fn recurse_indices(&self) -> ChildIndices { ... }
    fn handle_mouse_over(&mut self, cx: &mut EventCx<'_>, state: bool) { ... }
    fn child_nav_focus(&mut self, cx: &mut EventCx<'_>, id: Id) { ... }
    fn handle_event(
        &mut self,
        cx: &mut EventCx<'_>,
        data: &Self::Data,
        event: Event<'_>,
    ) -> IsUsed { ... }
    fn handle_messages(&mut self, cx: &mut EventCx<'_>, data: &Self::Data) { ... }
    fn handle_resize(
        &mut self,
        cx: &mut ConfigCx<'_>,
        data: &Self::Data,
    ) -> Option<ActionResize> { ... }
    fn handle_scroll(
        &mut self,
        cx: &mut EventCx<'_>,
        data: &Self::Data,
        scroll: Scroll,
    ) { ... }
}

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.

Implementation

The implementation of this trait may be omitted where no event-handling is required. All methods have a default implementation.

Foreign items

The #widget macro permits implementation of the following items within impl Events:

• type Widget::Data

Call order

Configuration

It is required that widgets are configured before other methods are called. This is invoked by calling ConfigCx::configure and involves the following operations:

1. Set the widget Id, as returned by Tile::id
2. Call Events::configure
3. Call Events::update
4. Recurse configuration to children (see Events::recurse_indices)
5. Call Events::post_configure

Note that both configure and update may be called before child widgets have been configured. This is important to ensure that parent widgets are always updated before their children. Any logic using child identifiers should be placed in post_configure.

Configuration may be repeated at any time.

Update

Widgets must be updated during configure (see above), since Events::update must be called before sizing and before other widget methods.

Widgets must also be updated after their input data (see Widget::Data) changes (unless not visible, in which case the update may be postponed until they become visible). Updates may happen at other times (mostly because data-change-detection has false positives). Note that custom widgets with state must explicitly update affected children when their state changes.

An update is invoked by calling ConfigCx::update, resulting in the following operations:

1. Call Events::update
2. Recurse the update to children (see Events::recurse_indices)

Sizing

Sizing must happen after initial configuration but is not necessarily repeated after reconfiguration. See Layout.

Provided Associated Constants

const REDRAW_ON_MOUSE_OVER: bool = false

Does this widget have a different appearance on mouse over?

If true, then the mouse moving over and leaving the widget will cause a redraw. (Note that Layout::draw can infer the mouse-over state and start animations.)

Provided Methods

fn mouse_over_icon(&self) -> Option<CursorIcon>

The mouse pointer icon to use on mouse over

Defaults to None.

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 Tile::find_child_index must be too.

Default impl: self.id_ref().make_child(index)

fn probe(&self, coord: Coord) -> Id

Probe a coordinate for a widget’s Id

Returns the Id of the widget expected to handle clicks and touch events at the given coord. Typically this is the lowest descendant in the widget tree at the given coord, but it is not required to be; e.g. a Button may use an inner widget as a label but return its own Id to indicate that the button (not the inner label) handles clicks.

Calling

This method may only be called after the widget is sized.

Call Tile::try_probe instead.

Implementation

The callee may usually assume that it occupies coord and may thus return its own Id when no child occupies the input coord. If there are cases where a click within Layout::rect should be considered a miss (non-rectangular hit-testing) then Tile::try_probe must be implemented instead.

If the Tile::translation is non-zero for any child, then the coordinate passed to that child must be translated: coord + translation.

Default implementation

The default implementation returns self.id() and may be used for childless widgets. If the layout attribute macro is used or an explicit implementation of Tile::try_probe is provided, these are used instead of the default implementation of this method.

fn configure(&mut self, cx: &mut ConfigCx<'_>)

Configure self

Calling

This method is called as part of configuration. This method is called before children are assigned identifiers; see also post_configure.

Invoke by calling ConfigCx::configure.

Implementation

The window’s scale factor (and thus any sizes available through ConfigCx::size_cx) may change at run-time; this is common since some platforms require sizing with scale factor 1 before . Such changes require resizing (calling Layout::size_rules again) but do not require reconfiguration.

The default implementation does nothing.

fn post_configure(&mut self, cx: &mut ConfigCx<'_>)

Configure self (post-child-configuration actions)

Calling

This method is called as part of configuration.

The default implementation does nothing.

fn update(&mut self, cx: &mut ConfigCx<'_>, data: &Self::Data)

Update self using input data

Calling

This method is called as part of configuration and update.

Invoke by calling ConfigCx::update.

Implementation

The default implementation does nothing.

fn recurse_indices(&self) -> ChildIndices

Recursion control

Configuration and update normally recurse to all children listed by Tile::child_indices; this recursion is controlled by this method.

Calling

This method is called after Self::update.

Implementation

The default implementation returns the result of Tile::child_indices.

fn handle_mouse_over(&mut self, cx: &mut EventCx<'_>, state: bool)

Mouse focus handler

Calling

This method may only be called after the widget is sized.

Called when mouse moves over or leaves this widget. (This is a low-level alternative to Self::REDRAW_ON_MOUSE_OVER and Self::mouse_over_icon.)

Implementation

state is true when the mouse is over this widget.

fn child_nav_focus(&mut self, cx: &mut EventCx<'_>, id: Id)

Notification that a child received navigation focus

This is received after the child id receives Event::NavFocus, hence EventCx::last_child should be set.

Calling

This method may only be called after the widget is sized.

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).

Calling

This method may only be called after the widget is sized.

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.

Implementation

Default implementation of handle_event: do nothing; return Unused.

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).

Calling

This method may only be called after the widget is configured. The widget may or may not be sized.

Implementation

It is implied that the stack contains at least one message. Use EventCx::try_pop and/or EventCx::try_peek to handle known messages. It is sufficient to handle a single message excepting where a sender pushes multiple messages at once using EventCx::push. (Note that messages sent using EventState::send are sent individually.)

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.

fn handle_resize( &mut self, cx: &mut ConfigCx<'_>, data: &Self::Data, ) -> Option<ActionResize>

Handler for resize requests

Calling

This method may only be called after the widget is sized.

This method is called during event handling whenever a resize action is required (see ConfigCx::resize).

Implementation

Some widgets (for example, a scroll region) are able to handle resizes locally and should implement this method to do so (thus avoiding the need for a full-window resize).

Return Some(ActionResize) if further resizing is needed, or None if resizing is complete.

The default implementation simply returns Some(ActionResize).

fn handle_scroll( &mut self, cx: &mut EventCx<'_>, data: &Self::Data, scroll: Scroll, )

Handler for scrolling

Calling

This method may only be called after the widget is sized.

This method is called during event handling whenever the scroll action is not Scroll::None (see EventCx::set_scroll).

Implementation

Widgets should implement this if they support scrolling of children, have translation of children or would isolate parents from the scrolling of a child.

This method is expected to deal with scrolling only; if the content size has changed and cx.resize() is called by the affected child, then Self::handle_resize should be called before this method.

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.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl Events for Mark

impl Events for TitleBar

impl Events for TitleBarButtons

impl<Data: AppData> Events for Window<Data>

impl<M: Clone + Debug + 'static> Events for MarkButton<M>

const REDRAW_ON_MOUSE_OVER: bool = true

impl<T: FormattableText + 'static> Events for Label<T>

impl<W: Widget> Events for Popup<W>