Enum kas::event::Event

#[non_exhaustive]
pub enum Event {
    None,
    Activate,
    Command(Command, bool),
    LostCharFocus,
    LostSelFocus,
    ReceivedCharacter(char),
    Scroll(ScrollDelta),
    Pan {
        alpha: DVec2,
        delta: DVec2,
    },
    PressStart {
        source: PressSource,
        start_id: WidgetId,
        coord: Coord,
    },
    PressMove {
        source: PressSource,
        cur_id: Option<WidgetId>,
        coord: Coord,
        delta: Offset,
    },
    PressEnd {
        source: PressSource,
        end_id: Option<WidgetId>,
        coord: Coord,
    },
    TimerUpdate(u64),
    HandleUpdate {
        handle: UpdateHandle,
        payload: u64,
    },
    NewPopup(WidgetId),
    PopupRemoved(WindowId),
    NavFocus(bool),
}

Events addressed to a widget

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

Activate

Widget activation

“Activate” is triggered e.g. by clicking on a control or using keyboard navigation to trigger a control. It should then perform the widget’s primary function, e.g. a button or menu action, toggle a checkbox, etc.

Command(Command, bool)

(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::Unhandled, until handled or no more appropriate targets are available (the exact logic is encoded in Manager::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.

The state of the shift key is included (true = pressed).

Tuple Fields of Command

0: Command1: bool

LostCharFocus

Widget lost keyboard input focus

LostSelFocus

Widget lost selection focus

Selection focus implies character focus, so this event implies that the widget has already received Event::LostCharFocus.

ReceivedCharacter(char)

Widget receives a character of text input

This is only received by a widget with character focus (see Manager::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.

Tuple Fields of ReceivedCharacter

0: char

Scroll(ScrollDelta)

A mouse or touchpad scroll event

Tuple Fields of Scroll

0: ScrollDelta

Pan

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:

// Works for Coord type; for DVec2 type-conversions are unnecessary:
p = (alpha.complex_mul(p.into()) + delta).into();

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

Fields of Pan

alpha: DVec2

Rotation and scale component

delta: DVec2

Translation component

PressStart

A mouse button was pressed or touch event started

Fields of PressStart

source: PressSourcestart_id: WidgetIdcoord: Coord

PressMove

Movement of mouse or a touch press

Received only given a press grab.

Fields of PressMove

source: PressSourcecur_id: Option<WidgetId>coord: Coorddelta: Offset

PressEnd

End of a click/touch press

Received only given a press grab.

When end_id == None, this is a “cancelled press”: the end of the press is outside the application window.

Fields of PressEnd

source: PressSourceend_id: Option<WidgetId>coord: Coord

TimerUpdate(u64)

Update from a timer

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

The u64 payload may be used to identify the corresponding Manager::update_on_timer call.

Tuple Fields of TimerUpdate

0: u64

HandleUpdate

Update triggerred via an UpdateHandle

This event may be received after registering an UpdateHandle via Manager::update_on_handle.

A user-defined payload is passed. Interpretation of this payload is user-defined and unfortunately not type safe.

Fields of HandleUpdate

handle: UpdateHandlepayload: u64

NewPopup(WidgetId)

Notification that a new popup has been created

This is sent to the parent of each open popup when a new popup is created. This enables parents to close their popups when the new popup is not a descendant of itself. The WidgetId is that of the popup.

Tuple Fields of NewPopup

0: WidgetId

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 Manager, the parent should clean up any associated state here.

Tuple Fields of PopupRemoved

0: WindowId

NavFocus(bool)

Sent when a widget receives keyboard navigation focus

This event may be used to react (e.g. by requesting char focus) or to steal focus from a child.

When the payload, key_focus, is true when the focus was triggered by the keyboard, not the mouse or a touch event. When true, the widget should reply with Response::Focus in order to ensure visibility. This should not be done when key_focus is false to avoid moving widgets during interaction via mouse or finger.

Widgets using Manager::handle_generic should note that this event is trapped and responded to (in line with the above recommendation). If the widget needs to react to NavFocus, the event must be matched before calling handle_generic, which might require a custom implementation of SendEvent.

Tuple Fields of NavFocus

0: bool

Trait Implementations

impl Clone for Event

pub 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

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

Formats the value using the given formatter.

impl PartialEq<Event> for Event

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

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

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

This method tests for !=.

impl StructuralPartialEq for Event