Events

kas_core

Trait Events 

Source 
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 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 handle_mouse_over(&mut self, cx: &mut EventCx<'_>, state: bool) { ... }
    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_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.

Type Widget::Data may be specified in impl Events { ... } instead of in impl Widget { ... } (this is permitted since it allows may #[widget] definitions to omit impl Widget { ... } altogether).

§Widget lifecycle

  1. The widget is configured (Events::configure, Events::configure_recurse) and immediately updated (Events::update).

    The widget may be re-configured at any time without expectation that the layout will be resized / set again.

  2. The widget is updated by calling Events::update immediately after it is configured and also after any update to input data (or other data which may have changed, such as that exposed by EventState::config).

  3. The widget is “sized” by calling Layout::size_rules for the horizontal axis then for the vertical axis.

    These methods may be called again at any time without expectation that the layout will be set again.

  4. Layout::set_rect is called to “set” layout.

    This method may be called again at any time.

  5. The widget is ready for event-handling and drawing (Events::handle_event, Layout::try_probe, 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 Associated Constants§

Source

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§

Source

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

The mouse cursor icon to use on mouse over

Defaults to None.

Source

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)

Source

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. If id changes, children must be assigned new/updated identifiers.

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.

Source

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

Configure children

This method is called after Self::configure. The default implementation configures all children.

An explicit implementation is required in cases where not all children should be configured immediately (for example, a stack or paged list may choose not to configure hidden children until just before they become visible). To configure children explicitly, generate an Id by calling Events::make_child_id on self then pass this id to ConfigCx::configure.

The default implementation configures children in the range Tile::child_indices. In cases where Tile::child_indices hides some children, a custom implementation of this method might be needed.

Source

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.

Source

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 updates children in the range Tile::child_indices. This is usually sufficient.

Use ConfigCx::update.

Source

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

Mouse focus handler

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

state is true when the mouse is over this widget.

Source

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.

Source

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

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.

Source

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.

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§