Enum kas_core::event::Event

#[non_exhaustive]
pub enum Event {
    Command(Command, Option<KeyCode>),
    Key(KeyEvent, bool),
    Scroll(ScrollDelta),
    Pan {
        alpha: DVec2,
        delta: DVec2,
    },
    CursorMove {
        press: Press,
    },
    PressStart {
        press: Press,
    },
    PressMove {
        press: Press,
        delta: Offset,
    },
    PressEnd {
        press: Press,
        success: bool,
    },
    TimerUpdate(u64),
    NavFocus(FocusSource),
    MouseHover(bool),
    LostNavFocus,
    LostKeyFocus,
    LostSelFocus,
}

Events addressed to a widget

Note that a few events are 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.

Command(Command, Option<KeyCode>)

Command input

A generic “command”. The source is often but not always a key press. In many cases (but not all) the target widget has navigation focus.

A KeyCode is attached when the command is caused by a key press. The recipient may use this to call EventState::depress_with_key.

If a widget has keyboard input focus (see EventState::request_key_focus) it will instead receive Event::Key for key presses (but may still receive Event::Command from other sources).

Key(KeyEvent, bool)

Keyboard input: event, is_synthetic

This is only received by a widget with character focus (see EventState::request_key_focus).

On some platforms, synthetic key events are generated when a window gains or loses focus with a key held (see documentation of winit::event::WindowEvent::KeyboardInput). This is indicated by the second parameter, is_synthetic. Unless you need to track key states it is advised only to match Event::Key(event, false).

Some key presses can be mapped to a Command. To do this (normally only when event.state == ElementState::Pressed && !is_synthetic), use cx.config().shortcuts(|s| s.try_match(cx.modifiers(), &event.logical_key) or (omitting shortcut matching) Command::new(event.logical_key). Note that if the handler returns Unused the widget might then receive Event::Command for the same key press, but this is not guaranteed (behaviour may change in future versions).

For standard text input, simply consume event.text when event.state == ElementState::Pressed && !is_synthetic. NOTE: unlike Winit, we force text = None for control chars and when Ctrl, Alt or Super modifier keys are pressed. This is subject to change.

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

This event is sent for certain types of grab (Press::grab), enabling two-finger scale/rotate gestures as well as translation.

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

CursorMove

Fields

press: Press

Movement of mouse cursor without press

This event is sent only when:

1. No Press::grab is active
2. A Popup is open

The parent (or an ancestor) of a Popup should handle or explicitly ignore this event.

PressStart

Fields

press: Press

A mouse button was pressed or touch event started

Call Press::grab in order to “grab” corresponding motion and release events.

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

1. When a Popup is open. A Popup will close itself if press.id is not a descendant of itself, but will still return Unused. The parent (or an ancestor) of the Popup should handle this event.
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.

PressMove

Fields

press: Press

delta: Offset

Movement of mouse or a touch press

This event is only sent when a (Press::grab) is active. Motion events for the grabbed mouse pointer or touched finger are sent.

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

PressEnd

Fields

press: Press

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 only sent when a (Press::grab) is active. Release/cancel events for the same mouse button or touched finger are 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_timer_update).

The u64 payload is copied from EventState::request_timer_update.

NavFocus(FocusSource)

Sent when a widget receives navigation focus

Navigation focus implies that the widget is highlighted and will be the primary target of Event::Command.

With FocusSource::Pointer the widget should already have received Event::PressStart.

With FocusSource::Key, EventCx::set_scroll is called automatically (to ensure that the widget is visible) and the response will be forced to Used.

The widget may wish to call EventState::request_key_focus, but likely only when FocusSource::key_or_synthetic.

MouseHover(bool)

Sent when a widget becomes the mouse hover target

The payload is true when focus is gained, false when lost.

LostNavFocus

Sent when a widget loses navigation focus

LostKeyFocus

Widget lost keyboard input focus

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

LostSelFocus

Widget lost selection focus

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

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

Implementations

impl Event

pub fn on_activate<F: FnOnce(&mut EventCx<'_>) -> IsUsed>( self, cx: &mut EventCx<'_>, id: WidgetId, f: F ) -> IsUsed

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

The method calls EventState::depress_with_key on activation.

pub fn pass_when_disabled(&self) -> bool

Pass to disabled widgets?

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

pub fn is_reusable(&self) -> bool

Can the event be received by Events::handle_event during unwinding?

Events which may be sent to the widget under the mouse or to the keyboard navigation target may be acted on by an ancestor if unused. Other events may not be; e.g. Event::PressMove and Event::PressEnd are only received by the widget requesting them while Event::LostKeyFocus (and similar events) are only sent to a specific widget.

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