Enum WidgetEvent 

pub enum WidgetEvent {
    PointerDown {
        position: Point,
        button: PointerButton,
        modifiers: Modifiers,
        pointer: PointerInfo,
    },
    PointerUp {
        position: Point,
        button: PointerButton,
        modifiers: Modifiers,
        pointer: PointerInfo,
    },
    PointerMove {
        position: Point,
        modifiers: Modifiers,
        pointer: PointerInfo,
    },
    PointerEnter {
        pointer: PointerInfo,
    },
    PointerLeave {
        pointer: PointerInfo,
    },
    Scroll {
        delta: ScrollDelta,
        modifiers: Modifiers,
        window_position: Option<Point>,
        phase: ScrollPhase,
        pointer: PointerInfo,
    },
    PointerCancel {
        window_position: Option<Point>,
        reason: CancelReason,
        pointer: PointerInfo,
    },
    KeyDown {
        key: Key,
        modifiers: Modifiers,
        text: Option<String>,
    },
    KeyUp {
        key: Key,
        modifiers: Modifiers,
    },
    ImeComposition {
        text: String,
        cursor: Option<Range<usize>>,
        replacement: Option<Range<usize>>,
    },
    ImeCommit {
        text: String,
        origin: ImeOrigin,
        replacement: Option<Range<usize>>,
    },
    FocusGained {
        origin: FocusOrigin,
    },
    FocusLost,
    AccessAction {
        action: Action,
        target: Option<WidgetId>,
        target_node: NodeId,
        data: Option<ActionData>,
    },
    ScrollIntoView {
        target_bounds: Rect,
        margin: f32,
        align: ScrollAlign,
        motion: ScrollMotion,
        applied_scroll: Option<Arc<Mutex<Point>>>,
    },
    Gesture {
        gesture: GestureEvent,
    },
}

Events dispatched to widgets.

Variants

PointerDown

A button went down.

Fields

position: Point

Where, in the receiving widget’s own coordinate space (the router localises it on delivery — see WidgetTree::dispatch_pointer).

button: PointerButton

Which button. A direct pointer reports PointerButton::Primary for a contact.

modifiers: Modifiers

Modifier keys held when the press landed.

pointer: PointerInfo

Who pressed — identity, kind, buttons, axes and timestamp.

Read it through EventContext::pointer or its pointer_kind() shorthand rather than by destructuring, so a widget that only needs “was this a finger?” does not have to name the whole struct. Defaults to PointerInfo::mouse at the epoch for every legacy construction site and for pointer_down, so a site that says nothing about pointers keeps meaning what it meant before the touch programme.

PointerUp

A button came up.

Fields

position: Point

Where, in the receiving widget’s own coordinate space.

button: PointerButton

Which button was released.

modifiers: Modifiers

Modifier keys held when the release landed.

pointer: PointerInfo

Who released. See PointerDown::pointer.

PointerMove

A pointer moved. Sent whether or not a button is held; a contact only ever moves with its button held, since a finger cannot hover.

Fields

position: Point

Where, in the receiving widget’s own coordinate space.

modifiers: Modifiers

Modifier keys held during the move.

A drag decides what it means from the modifiers at the move, not at the press — Shift extends a selection and Ctrl makes a marquee additive from the moment the key goes down, mid-drag included. Defaults to Modifiers::NONE for pointer_move and for a producer that tracks no modifier state.

pointer: PointerInfo

Who moved. See PointerDown::pointer.

PointerEnter

The hover owner came onto this widget. Never sent for a contact: a finger writes no hover (see PointerTable::hover_owner).

Fields

pointer: PointerInfo

Who entered — a mouse, or a pen in proximity.

PointerLeave

The hover owner left this widget.

Fields

pointer: PointerInfo

Who left. See PointerEnter.

Scroll

Fields

delta: ScrollDelta

modifiers: Modifiers

Modifier keys held at the time of the scroll event. Defaults to Modifiers::NONE for synthesized events (tests, keyboard-driven scroll requests). Real-platform scroll events populate this from the platform’s tracked modifier state — apps detect Ctrl-wheel-to-zoom by inspecting modifiers.ctrl().

window_position: Option<Point>

Where the pointer was when the scroll happened, in window-logical coordinates, or None when the producer has no position for it.

The frame is in the name because it is the one positional field a handler receives that is not localised to the receiving widget (localize_event deliberately has no Scroll arm), and a widget that reads it as a local point silently lands a cell or a row out. Convert with the receiver’s own bounds before using it as content coordinates.

It is window-space because both of its frame-sensitive uses need it to be. The router routes by it — Some hit-tests, None falls back to the hovered (else focused) widget — and hit-testing is necessarily window-space. And common/scrollable.rs’s handle_scroll_event feeds it to pan_step → KineticScroller::pan, whose tracker follows the pointer: localisation resolves against the captor’s current bounds on every event, so a localised position would feed that tracker samples polluted by the motion of the very widget being measured.

A mouse wheel has always been positionless and stays so — hover is under the cursor, so hit-testing would find the same widget anyway. A pan synthesised from a direct pointer must carry one, because a contact never writes hover and a positionless pan would route nowhere.

phase: ScrollPhase

Where in a continuous scroll gesture this sample sits. ScrollPhase::Discrete — a self-contained wheel notch — for everything Teksilo produced before the touch programme.

pointer: PointerInfo

Who scrolled. Defaults to PointerInfo::mouse at the epoch for every legacy construction site; a real sample carries the pointer’s identity, kind and timestamp.

PointerCancel

A pointer interaction was revoked by the system rather than completed by the user — see CancelReason.

Distinct from PointerUp on purpose: an Up means the user finished, so a drag drops and a tap fires; a cancel means the interaction is being taken away, so state must be unwound and nothing may activate.

Terminal: no PointerUp follows for that pointer, and one that arrives anyway is swallowed. Delivered by the cancel funnel, WidgetTree::cancel_pointer, to the widget holding the pointer — or, failing that, to the last one that accepted an event from it. A widget receives it through .on_pointer_cancel(..) or through its raw on_pointer_event hook.

Fields

window_position: Option<Point>

Where the pointer was last seen, in window-logical coordinates, when the revoking path knows. A platform cancel usually carries no position at all.

Window-space, and named for it, for the same reason as Scroll::window_position — but kept there by a different mechanism, worth knowing before “fixing” either. The cancel funnel delivers through the router’s non-localising route (dispatch_to_widget_direct), so what puts this value in window space is simply that the funnel records the pointer table’s own position verbatim; localize_event having no PointerCancel arm is true but would not matter on this path. A widget whose PointerDown/Move/Up handling works in local coordinates must convert before feeding this to the same sink.

reason: CancelReason

Why the interaction was revoked.

pointer: PointerInfo

Which pointer was revoked.

KeyDown

A key press.

Fields

key: Key

The key the chord names, on every platform: Alt+A is Key::A. On macOS a press with Option (and neither Control nor Command) names the key without Option too, though Option composed a character from it, so an Alt+A shortcut fires there as elsewhere. One exception: Option and Shift with any key but an ASCII letter (a digit, punctuation, a Cyrillic or Greek letter) keep the composed character as their key.

modifiers: Modifiers

The modifiers held.

text: Option<String>

What the press typed, if anything: on macOS the character Option composed (“å” for Option+A). None for a command chord (Control without Alt, Super) and for a key that types nothing.

KeyUp

A key release.

Fields

key: Key

The key the chord names, as for WidgetEvent::KeyDown.

modifiers: Modifiers

The modifiers held.

ImeComposition

One update of the platform input method’s composition (preedit).

Fields

text: String

The composition’s current text. Empty ends the composition.

cursor: Option<Range<usize>>

The caret or selection inside text, in byte offsets of text.

replacement: Option<Range<usize>>

The range of the focused field’s text (its character offsets) the composition takes the place of, when the input method re-marks text already in the field (Korean Hanja conversion, reconversion). Sent with the composition’s first update; the field removes that text and shows the composition where it was, and puts it back if the composition is cancelled. None shows the composition at the selection.

ImeCommit

Text the platform’s input system committed into the focused field.

Fields

text: String

The committed text.

origin: ImeOrigin

Which part of the input system committed it.

replacement: Option<Range<usize>>

The range of the focused field’s text this commit replaces, in that field’s character (Unicode scalar) offsets, when the input system named one (a dictation correction, a Writing Tools replacement). None replaces the selection, or inserts at the caret when there is none.

FocusGained

Fields

origin: FocusOrigin

FocusLost

AccessAction

Fields

action: Action

target: Option<WidgetId>

target_node: NodeId

Raw AccessKit NodeId from the original ActionRequest. May be a synthetic (widget-emitted child) NodeId — use crate::accessibility::is_synthetic to distinguish it from a widget-derived NodeId. The widget that registered the parent (retrieved via tree.widget_for_synthetic) is the one set in target.

data: Option<ActionData>

Payload carried by the ActionRequest. For Action::SetTextSelection this is ActionData::SetTextSelection(TextSelection), for Action::SetValue it’s ActionData::Value(Box<str>), for scroll actions it carries scroll offsets, etc. Widgets that declare these actions must read the payload to honour screen-reader-initiated requests.

ScrollIntoView

Dispatched by the framework to a clipping ancestor when a child gains focus but is outside the viewport. The scroll area adjusts its offset to make the target bounds visible, with an optional margin around the target.

target_bounds is where the last layout put the target (arena bounds), so a handler converts it to content space with the offset that layout placed its content at, and compares it with its live viewport (or the offset a running tween is heading for). The two differ when something scrolled the container since that layout: the focus follow ahead of a handler’s own ensure_visible, a wheel notch, an offset written by the application, a glide. A container that marks itself with BuildContext::judge_reveals_live is sent the event even when the target looks visible from the laid-out bounds, so it must move only as far as the target needs, and answer Ignored when it does not move. ScrollArea and GridView are marked. A SceneView is not: the walk tests its target through the live camera transform already. The horizontal conversion assumes left-to-right placement; ScrollArea does not mirror it for right-to-left content.

Fields

target_bounds: Rect

margin: f32

Extra margin (in logical pixels) to keep around the target when scrolling it into view. Defaults to 0.0.

align: ScrollAlign

Where the target should end up on the scroll container’s vertical axis. ScrollAlign::Minimal (the default, and what every focus-driven reveal uses) only scrolls when the target is not already fully visible; ScrollAlign::Fraction pins it to a fixed height in the viewport whether or not it was already visible.

motion: ScrollMotion

Whether the container should jump to the new offset or glide to it. See ScrollMotion.

applied_scroll: Option<Arc<Mutex<Point>>>

Optional back-channel for the handling scroll container to report how far the target moves from where target_bounds puts it ((dx, dy) in content pixels): the move from the offset the last layout placed its content at, which includes a move earlier in the same turn even when this one moves nothing. When several nested scroll containers must each reveal the same target, the ancestor walk (scroll_rect_into_view) reads this after dispatching to an inner container and shifts target_bounds by the negated delta before asking the next (outer) one — so the outer sees where the target will land once the inner’s (deferred) scroll applies, not its pre-scroll position. None disables reporting (the nested-reveal refinement is unavailable). A handler that ignores it still works for the common single-container case.

Arc<Mutex<..>> (not Rc<Cell<..>>) so WidgetEvent stays Send — some events are posted across threads. This one is only ever touched on the dispatch thread, so the lock is always uncontended.

Gesture

A recognized gesture event, routed through the same preview/bubble system.

Fields

gesture: GestureEvent

Implementations

impl WidgetEvent

pub fn ime_commit(text: impl Into<String>) -> Self

An ImeCommit of text from a composition (ImeOrigin::Composition) that names no range to replace.

pub fn ime_composition( text: impl Into<String>, cursor: Option<Range<usize>>, ) -> Self

An ImeComposition update that takes the place of no existing text (replacement is None).

pub fn scroll(delta: ScrollDelta, modifiers: Modifiers) -> Self

A wheel notch with no position — routed by the hovered (else focused) widget, exactly as every scroll in Teksilo was before the touch programme.

It exists so that the three fields Scroll gained cost each of its construction sites one line rather than five. The pointer defaults to PointerInfo::mouse at EventTime::ZERO: a free constructor has no tree and therefore no clock, and nothing reads the timestamp of a legacy-constructed event. A sample that has a real time enters through WidgetTree::dispatch_scroll instead.

pub fn scroll_at( delta: ScrollDelta, modifiers: Modifiers, position: Point, ) -> Self

A wheel notch routed by hit test at position rather than by hover.

Use this where the producer genuinely knows where the pointer was; a mouse-wheel translator should keep using scroll, whose hover routing is what it has always had.

pub fn pointer_down( position: Point, button: PointerButton, modifiers: Modifiers, ) -> Self

A mouse press: PointerInfo::mouse at the epoch.

This and its siblings are why adding pointer to the five Pointer* variants was a one-line-per-site sweep rather than a rewrite. Use them wherever the producer genuinely describes a mouse — every test that is pinning mouse behaviour, and every synthesizer that has no pointer of its own. A producer that does know which pointer it speaks for must write the variant out and thread the real PointerInfo, or ctx.pointer_kind() reads Mouse for a finger and every direct-pointer branch in the framework silently takes the indirect path.

pub fn pointer_up( position: Point, button: PointerButton, modifiers: Modifiers, ) -> Self

A mouse release. See pointer_down.

pub fn pointer_move(position: Point) -> Self

A mouse move with no modifiers held. See pointer_down; use pointer_move_with where the producer tracks modifier state, since a drag reads Shift and Ctrl from the move.

pub fn pointer_move_with(position: Point, modifiers: Modifiers) -> Self

A mouse move carrying tracked modifier state. See pointer_down.

pub fn pointer_enter() -> Self

The mouse entered a widget. See pointer_down.

pub fn pointer_leave() -> Self

The mouse left a widget. See pointer_down.

Trait Implementations

impl Clone for WidgetEvent

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for WidgetEvent

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

Formats the value using the given formatter.