Struct EventCtx 

pub struct EventCtx { /* private fields */ }

Capabilities granted to a widget while it handles an event.

Widgets do not mutate the runtime directly: they set request flags here, and the runtime applies them after dispatch completes.

Implementations

impl EventCtx

pub fn is_consumed(&self) -> bool

Returns true if a widget has called Self::consume_event during this dispatch. Used by parent containers to decide whether to keep routing the event.

pub fn consume_event(&mut self)

Mark the current event as handled. Parent containers stop routing once they see this flag, so the same keystroke doesn’t fire two actions (e.g., a default button’s Enter accelerator stopping the focused list from also reacting to the keypress).

pub fn swallow_key_until_release(&mut self)

Ask the runtime to discard the remainder of the current key press: any text (Char) it still produces and every later event for the same key — autorepeats and the release — up to and including that release.

Unlike Self::consume_event, which only stops routing this event, this reaches across the separate KeyDown / Char / KeyUp events a single press generates. A menu item fired by its mnemonic uses it: the keystroke that picked the item must not also land in whatever the item opens on the spot — e.g. the freshly focused field of a dialog — which otherwise receives the trailing Char and types the letter.

pub fn request_paint(&mut self)

Mark the window dirty so the runtime repaints on the next idle tick.

pub fn request_tick(&mut self)

Ask the runtime to deliver at least one more Event::Tick soon.

This is the push counterpart to Widget::wants_ticks: where wants_ticks is a steady-state flag the runtime pulls by walking the widget tree (so every container in the path must forward it), this request rides the shared EventCtx straight back to the runtime — no ancestor has to know or forward anything, exactly like Self::request_paint. A widget buried under custom wrappers can thus drive an animation without its parents cooperating.

It is one-shot: it guarantees the next tick, not a stream. A widget that needs continuous ticks (e.g. a scrollbar auto-repeating while its arrow button is held) simply calls this again each time it handles a Event::Tick, for as long as it still needs them; the moment it stops re-requesting, the ticks wind down on their own.

pub fn close(&mut self)

Ask the runtime to close the window after this dispatch completes.

pub fn is_focus_requested(&self) -> bool

true if a widget called Self::request_focus during this dispatch. Custom container widgets (outside saudade) read this after forwarding an event to a child to learn the child wants focus, then call Self::clear_focus_flags and move focus to it — the same protocol the built-in Container / Column use internally.

pub fn is_focus_released(&self) -> bool

true if a widget called Self::release_focus during this dispatch.

pub fn clear_focus_flags(&mut self)

Reset both focus-change flags after a custom container has acted on them.

pub fn request_focus(&mut self)

The widget asks to become the keyboard-focused widget. Parent containers observe this flag during pointer dispatch and route subsequent keyboard events here.

pub fn release_focus(&mut self)

The widget asks to drop keyboard focus. Useful when an editor wants the window to stop sending it characters.

pub fn request_focus_next(&mut self)

A mnemonic-bearing widget (typically a FocusLabel) asks its parent container to move keyboard focus to the next focusable sibling after it — the classic buddy-label behaviour, where "Last &name:" hands focus to the text field that follows it. Call this from the widget’s event handler when its accelerator letter is pressed; the container performs the move once dispatch unwinds. The requesting widget needs no knowledge of its own position in the tree.

pub fn is_focus_next_requested(&self) -> bool

true if a widget called Self::request_focus_next during this dispatch. Read by container widgets — including custom ones outside saudade — to learn a buddy label’s accelerator was matched, so they can move focus to the next focusable child after the requester.

pub fn request_dismiss(&mut self)

Content inside a modal dialog calls this to ask the hosting Modal to close — e.g. from an OK / Close button’s on_click. The modal runs its on_dismiss handler and dismisses after the current event finishes dispatching.

pub fn is_dismiss_requested(&self) -> bool

true if a widget called Self::request_dismiss during this dispatch. Read by Modal after forwarding an event to its content.

pub fn request_window_size(&mut self, width: i32, height: i32)

Ask the runtime to resize the window to width × height logical pixels, applied after the current event finishes dispatching (and followed by a repaint, so callers needn’t also call Self::request_paint). Handy for a window that should grow or shrink to fit a mode the user just toggled. The window’s size is the app’s to set — unlike the logical→physical scale factor, which only the OS controls.

pub fn start_drag(&mut self, data: DragData)

Begin dragging data out of this window as an OS drag-and-drop operation — the mirror of receiving a Event::Drop. Call this from a widget’s event handler once a press-then-move gesture is recognized (typically on Event::PointerMove after the pointer has travelled a few pixels from a Event::PointerDown), so a plain click still reads as a click rather than starting a drag.

Wayland only. The winit backends (macOS, Windows, X11) expose no API to initiate a drag, so this is a no-op there; only the Wayland backend turns it into a real drag whose text/uri-list payload other applications can drop. Receiving drops, by contrast, works on every backend. The drag copies (never moves) the referenced files.

pub fn accept_drop(&mut self)

Signal, while handling an incoming Event::DragEnter or Event::DragMove, that this widget will accept a drop at the current position. A drop target must call this to receive drops: the runtime treats a widget that doesn’t as not interested, so the drag falls through it. Re-evaluated on every move, so a target can accept only over its hot region and decline elsewhere in the same window.

On Wayland this is what tells the source app the spot is a valid target (its drag cursor / feedback reflects it) and is the prerequisite for a later Event::Drop landing here. On the winit backends the OS has already committed to offering the drop, so this is advisory there — Event::Drop arrives regardless — but calling it keeps drop targets portable.

pub fn set_cursor(&mut self, cursor: Cursor)

Ask the runtime to show cursor as the mouse-pointer shape while it rests over this widget. Call it while handling a pointer event — almost always Event::PointerMove.

The runtime reconciles the pointer shape after every move: whatever a widget requests during that move’s dispatch becomes the cursor, and a move no widget answers falls back to Cursor::Default (the arrow). A widget that wants a non-default cursor therefore simply re-requests it on each PointerMove it receives — the cost is one enum write, and there’s nothing to “unset” on the way out: moving onto another widget, or off this one, re-runs the reconciliation. Because only moves drive it, a request made while handling a press, key, or tick is ignored.

Buttons request Cursor::Hand and text fields Cursor::Text this way; a widget that never calls this keeps the normal arrow.