Enum Event 

#[non_exhaustive]
pub enum Event<'a> {
    Command(Command, Option<PhysicalKey>),
    Key(&'a KeyEvent, bool),
    Ime(Ime<'a>),
    Scroll(ScrollDelta),
    Pan(Affine),
    PointerMove {
        press: Press,
    },
    PressStart(PressStart),
    PressMove {
        press: Press,
        delta: Vec2,
    },
    PressEnd {
        press: Press,
        success: bool,
    },
    Timer(TimerHandle),
    NavFocus(FocusSource),
    LostNavFocus,
    SelFocus(FocusSource),
    LostSelFocus,
    KeyFocus,
    LostKeyFocus,
    MouseOver(bool),
}

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

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 PhysicalKey is attached when the command is caused by a key press. The recipient may use this to call EventCx::depress_with_key.

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

Key(&'a KeyEvent, bool)

Keyboard input: event, is_synthetic

This is only received by a widget with keyboard 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.

Ime(Ime<'a>)

An Input Method Editor event

IME events are only received with IME focus.

On Ime::Enabled, the widget should call EventState::set_ime_cursor_area immediately and each time the area changes (relative to the widget’s coordinate space), until Ime::Disabled is received. Failure to do so will result in the widget’s entire rect being used as the IME cursor area.

Scroll(ScrollDelta)

A mouse or touchpad scroll event

Pan(Affine)

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

This event is sent for certain types of grab (PressStart::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.

PointerMove

Movement of mouse pointer without press

This event is only sent one case: when the mouse is moved while a Popup is open and there is not an active PressStart::grab on the mouse pointer.

This event may be sent 10+ times per frame, thus it is important that the handler be fast. It may be useful to schedule a pre-draw update with EventState::request_frame_timer to handle any post-move updates.

Fields

press: Press

PressStart(PressStart)

A mouse button was pressed or touch event started

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

This event is sent to the widget under the mouse or touch position. If no such widget is found, this event is not sent.

PressMove

Movement of mouse or a touch press

This event is only sent when a (PressStart::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::Tile::try_probe failed).

This event may be sent 10+ times per frame, thus it is important that the handler be fast. It may be useful to schedule a pre-draw update with EventState::request_frame_timer to handle any post-move updates.

Fields

press: Press

delta: Vec2

PressEnd

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 (PressStart::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::Tile::try_probe failed).

Fields

press: Press

success: bool

Timer(TimerHandle)

Update from a timer

This event must be requested by EventState::request_timer.

NavFocus(FocusSource)

Notification that a widget has gained navigation focus

Navigation focus implies that the widget is highlighted and will be the primary target of Event::Command, and is thus able to receive basic keyboard input (e.g. arrow keys). To receive full keyboard input (Event::Key), call EventCx::request_key_focus.

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.

LostNavFocus

Notification that a widget has lost navigation focus

SelFocus(FocusSource)

Notification that a widget has gained selection focus

This focus must be requested by calling EventCx::request_sel_focus or EventCx::request_key_focus.

LostSelFocus

Notification that a widget has lost selection focus

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

KeyFocus

Notification that a widget has gained keyboard input focus

This focus must be requested by calling EventCx::request_key_focus.

This is always preceeded by Event::SelFocus and is received prior to Event::Key events.

LostKeyFocus

Notification that a widget has lost keyboard input focus

MouseOver(bool)

Notification that the mouse moves over or leaves a widget

The state is true on mouse over, false when the mouse leaves.

Implementations

impl<'a> Event<'a>

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

Call f on “click” or any “activation” event

This is a convenience method which calls f on any of the following:

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

This method has some side effects:

• Event::PressStart is grabbed using GrabMode::Click
• Event::Command with a key will cause id to be depressed until that key is released (see EventCx::depress_with_key).

pub fn pass_when_disabled(&self) -> bool

Pass to disabled widgets?

When a widget is disabled:

• New input events (Command, PressStart, Scroll) are not passed
• Continuing input actions (PressMove, PressEnd) are passed (or the input sequence may be terminated).
• New focus notifications are not passed
• Focus-loss notifications are passed
• Requested events like Timer are passed

pub fn is_reusable(&self) -> bool

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

Some events are sent to the widget with navigation focus (e.g. Event::Command). Others are sent to the widget under the mouse (e.g. Event::PressStart). All these events may be “reused” by an ancestor widget if not Used by the original target.

Other events are sent to a specific widget as a result of a request (e.g. Event::Key, Event::PressEnd), or as a notification of focus change (e.g. Event::LostKeyFocus). These events may never be “reused”.

Note: this could alternatively be seen as a property of the addressing mechanism, currently just an Id.

Trait Implementations

impl<'a> Add<Offset> for Event<'a>

type Output = Event<'a>

The resulting type after applying the + operator.

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

Performs the + operation.

impl<'a> AddAssign<Offset> for Event<'a>

fn add_assign(&mut self, offset: Offset)

Performs the += operation.

impl<'a> Clone for Event<'a>

fn clone(&self) -> Event<'a>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'a> Debug for Event<'a>

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

Formats the value using the given formatter.

impl<'a> PartialEq for Event<'a>

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

Tests for self and other values to be equal, and is used by ==.

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

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

impl<'a> StructuralPartialEq for Event<'a>