Enum kas_core::event::Event

#[non_exhaustive]
pub enum Event {
    None,
    Command(Command),
    ReceivedCharacter(char),
    Scroll(ScrollDelta),
    Pan {
        alpha: DVec2,
        delta: DVec2,
    },
    PressStart {
        source: PressSource,
        start_id: Option<WidgetId>,
        coord: Coord,
    },
    PressMove {
        source: PressSource,
        cur_id: Option<WidgetId>,
        coord: Coord,
        delta: Offset,
    },
    PressEnd {
        source: PressSource,
        end_id: Option<WidgetId>,
        coord: Coord,
        success: bool,
    },
    TimerUpdate(u64),
    Update {
        id: UpdateId,
        payload: u64,
    },
    PopupRemoved(WindowId),
    NavFocus(bool),
    MouseHover,
    LostNavFocus,
    LostMouseHover,
    LostCharFocus,
    LostSelFocus,
}

Events addressed to a widget

Note regarding disabled widgets: Event::Update, Event::PopupRemoved and Lost.. events are received regardless of status; other events are not received by disabled widgets. See Event::pass_when_disabled.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

None

No event

Command(Command)

(Keyboard) command input

This represents a control or navigation action, usually from the keyboard. It is sent to whichever widget is “most appropriate”, then potentially to the “next most appropriate” target if the first returns Response::Unused, until handled or no more appropriate targets are available (the exact logic is encoded in EventMgr::start_key_event).

In some cases keys are remapped, e.g. a widget with selection focus but not character or navigation focus may receive Command::Deselect when the Esc key is pressed.

ReceivedCharacter(char)

Widget receives a character of text input

This is only received by a widget with character focus (see EventState::request_char_focus). There is no overlap with Event::Command: key presses result in at most one of these events being sent to a widget.

Scroll(ScrollDelta)

A mouse or touchpad scroll event

Pan

Fields

alpha: DVec2

Rotation and scale component

delta: DVec2

Translation component

A mouse or touch-screen move/zoom/rotate event

Mouse-grabs generate translation (delta component) only. Touch grabs optionally also generate rotation and scaling components, depending on the GrabMode.

In general, a point p on the screen should be transformed as follows:

let mut p = Coord::ZERO; // or whatever
p = (alpha.complex_mul(p.cast()) + delta).cast_nearest();

When it is known that there is no rotational component, one can use a simpler transformation: alpha.0 * p + delta. When there is also no scaling component, we just have a translation: p + delta. Note however that if events are generated with rotation and/or scaling components, these simplifications are invalid.

Two such transforms may be combined as follows:

let alpha = alpha2.complex_mul(alpha1);
let delta = alpha2.complex_mul(delta1) + delta2;

If instead one uses a transform to map screen-space to world-space, this transform should be adjusted as follows:

world_alpha = world_alpha.complex_div(alpha.into());
world_delta = world_delta - world_alpha.complex_mul(delta.into());

Those familiar with complex numbers may recognise that alpha = a * e^{i*t} where a is the scale component and t is the angle of rotation. Calculate these components as follows:

let a = (alpha.0 * alpha.0 + alpha.1 * alpha.1).sqrt();
let t = (alpha.1).atan2(alpha.0);

PressStart

Fields

source: PressSource

start_id: Option<WidgetId>

coord: Coord

A mouse button was pressed or touch event started

This event is sent in exactly two cases, in this order:

1. When a pop-up layer is active (EventMgr::add_popup), the owner of the top-most layer will receive this event. If the event is not used, then the pop-up will be closed and the event sent again.
2. If a widget is found under the mouse when pressed or where a touch event starts, this event is sent to the widget.

If start_id is None, then no widget was found at the coordinate and the event will only be delivered to pop-up layer owners.

When handling, it may be desirable to call EventMgr::grab_press in order to receive corresponding Move and End events from this source.

PressMove

Fields

source: PressSource

cur_id: Option<WidgetId>

coord: Coord

delta: Offset

Movement of mouse or a touch press

This event is sent in exactly two cases, in this order:

1. Given a grab (EventMgr::grab_press), motion events for the grabbed mouse pointer or touched finger will be sent.
2. When a pop-up layer is active (EventMgr::add_popup), the owner of the top-most layer will receive this event. If the event is not used, then the pop-up will be closed and the event sent again.

If cur_id is None, no widget was found at the coordinate (either outside the window or crate::Layout::find_id failed).

PressEnd

Fields

source: PressSource

end_id: Option<WidgetId>

coord: Coord

success: bool

End of a click/touch press

If success, this is a button-release or touch finish; otherwise this is a cancelled/interrupted grab. “Activation events” (e.g. clicking of a button or menu item) should only happen on success. “Movement events” such as panning, moving a slider or opening a menu should not be undone when cancelling: the panned item or slider should be released as is, or the menu should remain open.

This event is sent in exactly one case:

1. Given a grab (EventMgr::grab_press), release/cancel events for the same mouse button or touched finger will be sent.

If cur_id is None, no widget was found at the coordinate (either outside the window or crate::Layout::find_id failed).

TimerUpdate(u64)

Update from a timer

This event is received after requesting timed wake-up(s) (see EventState::request_update).

The u64 payload is copied from EventState::request_update.

Update

Fields

id: UpdateId

payload: u64

Update triggerred via an UpdateId

This event is received by all widgets when EventMgr::update_all is called.

Note that this event is only received by Widget::handle_event and not by Widget::steal_event or Widget::handle_unused. Messages and scroll actions will not be handled by parent’s Widget::handle_message or Widget::handle_scroll methods.

PopupRemoved(WindowId)

Notification that a popup has been destroyed

This is sent to the popup’s parent after a popup has been removed. Since popups may be removed directly by the EventMgr, the parent should clean up any associated state here.

NavFocus(bool)

Sent when a widget receives (keyboard) navigation focus

When the payload, key_focus, is true when the focus was triggered by the keyboard, not the mouse or a touch event. This event may be used e.g. to request char focus or to steal focus from a child.

Note: when NavFocus(true) is sent to a widget, the sender automatically sets Scroll::Rect(widget.rect()) to EventMgr::set_scroll and considers the event used.

MouseHover

Sent when a widget becomes the mouse hover target

LostNavFocus

Sent when a widget loses navigation focus

LostMouseHover

Sent when a widget is no longer the mouse hover target

LostCharFocus

Widget lost keyboard input focus

This focus is gained through the widget calling EventState::request_char_focus.

LostSelFocus

Widget lost selection focus

This focus is gained through the widget calling EventState::request_sel_focus or EventState::request_char_focus.

In the case the widget also had character focus, Event::LostCharFocus is received first.

Implementations

impl Event

pub fn on_activate<F: FnOnce(&mut EventMgr<'_>) -> Response>(
    self,
    mgr: &mut EventMgr<'_>,
    id: WidgetId,
    f: F
) -> Response

Call f on any “activation” event

Activation is considered:

• Mouse click and release on the same widget
• Touchscreen press and release on the same widget
• Event::Command(cmd, _) where cmd.is_activate()

pub fn pass_when_disabled(&self) -> bool

Pass to disabled widgets?

Disabled status should disable input handling but not prevent other notifications.

Examples found in repository

src/event/manager/mgr_pub.rs (line 488)

    pub fn send(&mut self, widget: &mut dyn Widget, mut id: WidgetId, event: Event) -> Response {
        log::trace!(target: "kas_core::event::manager", "send: id={id}: {event:?}");

        // TODO(opt): we should be able to use binary search here
        let mut disabled = false;
        if !event.pass_when_disabled() {
            for d in &self.disabled {
                if d.is_ancestor_of(&id) {
                    id = d.clone();
                    disabled = true;
                }
            }
            if disabled {
                log::trace!(target: "kas_core::event::manager", "target is disabled; sending to ancestor {id}");
            }
        }

        self.scroll = Scroll::None;
        self.send_recurse(widget, id, disabled, event)
    }

Trait Implementations

impl Add<Offset> for Event

type Output = Event

The resulting type after applying the + operator.

fn add(self, offset: Offset) -> Event

Performs the + operation.

impl AddAssign<Offset> for Event

fn add_assign(&mut self, offset: Offset)

Performs the += operation.

impl Clone for Event

fn clone(&self) -> Event

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Event

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq<Event> for Event

fn eq(&self, other: &Event) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for Event