Struct EventContext 

pub struct EventContext<'ops> { /* private fields */ }

Context available during event handling.

Implementations

impl<'ops> EventContext<'ops>

pub fn layout_direction(&self) -> LayoutDirection

Layout direction of the hosting tree at dispatch time.

pub fn is_rtl(&self) -> bool

Whether the hosting tree is laid out right-to-left. Mirrors LayoutContext::is_rtl for the event-dispatch side.

pub fn drag_is_external(&self) -> bool

Whether a drag is currently in flight that was started by an external (OS) drag-and-drop (files / text / URLs from another application), rather than by an in-app start_drag. Useful in on_drag_leave / on_drag_tick handlers, which don’t receive the payload directly; in on_drag_hover / on_drop prefer payload.is_external().

pub fn app_state<T: 'static>(&self) -> Option<&T>

Look up an application-scoped value by type. Mirrors BuildContext::app_state. Returns None when the handler was invoked without a registry (hand-constructed EventContext in tests, or when no value of that type was registered).

pub fn poster(&self) -> Option<&Arc<dyn AppEventPoster>>

Borrow the AppEventPoster installed by the framework. Used by integrations that need to post typed payloads back to the UI loop from a worker thread (teksilo_platform::file_dialog’s RfdAsyncBackend, future async-result features). Returns None for hand-constructed EventContexts in tests.

pub fn request_frame(&mut self)

Ask the tree to pump one more frame after this handler returns. Use from event handlers that kick off per-frame work (pending document events to drain, drag-select auto-scroll, caret blink restart on focus). See WidgetTree::request_frame for the draw-when-needed contract.

pub fn send_intent(&mut self, intent: impl Into<Intent>)

Dispatch an Intent as if the source widget pressed its keyboard shortcut. The framework walks source-widget → root after the current handler returns, invoking any matching Action it finds. Unmatched intents are silently dropped.

The intent’s source is overridden by the dispatcher’s current handler-source label (current_source) when one is active. This is how the framework distinguishes IntentSource::Handler (button taps, generic on_tap) from IntentSource::Menu, IntentSource::Accessibility, etc. Programmatic callers outside any handler pass through with IntentSource::Programmatic (the default).

pub fn with_intent_source<R>( &mut self, source: IntentSource, f: impl FnOnce(&mut Self) -> R, ) -> R

Run a closure with the given IntentSource active. Any ctx.send_intent(...) issued from within the closure will be tagged with this source instead of the dispatcher’s default (Handler / Shortcut / Accessibility).

The previous source is restored after the closure returns. Panic during the closure unwinds the dispatcher’s whole frame, so the EventContext is destroyed before the next dispatch — no need for a panic-safe drop guard.

Used by framework widgets that want a more specific source label than the default — MenuItem wraps its activation handler to emit IntentSource::Menu, etc.

pub fn begin_key_capture( &mut self, callback: impl FnOnce(KeyStroke, &mut ShortcutRegistry, &mut EventContext<'_>) + 'static, ) -> CaptureHandle

Arm a one-shot key-capture callback, returning a CaptureHandle whose Drop cancels the capture if it hasn’t fired yet. The next KeyDown bypasses shortcut resolution and invokes the callback with:

• the captured KeyStroke
• mutable access to the registry (rebinds in-place)
• a mutable EventContext (emit commands, send intents, dismiss overlays, …)

The handle must be stored somewhere with an appropriate lifetime (typically in the calling widget’s state) or the capture will be cancelled immediately when the returned handle drops at end of scope.

pub fn cancel_key_capture(&mut self)

Cancel any key capture armed earlier in this handler or via WidgetTree::begin_key_capture before the handler ran.

pub fn rebind_shortcut_primary( &mut self, id: impl Into<String>, keystroke: Option<KeyStroke>, )

Queue a deferred rebind of the primary keystroke for the registered shortcut with the given id. Applied by the tree after the current handler returns. Use None to explicitly unbind the slot.

pub fn rebind_shortcut_secondary( &mut self, id: impl Into<String>, keystroke: Option<KeyStroke>, )

Queue a deferred rebind of the secondary keystroke for the registered shortcut with the given id.

pub fn clear_shortcut_override(&mut self, id: impl Into<String>)

Queue a deferred clear of any user override for the given shortcut id, restoring its declared defaults.

pub fn close_window(&mut self)

Request that the application close the window this tree belongs to. Drained by the app event loop after the handler returns. Typical use: title-bar close button handlers.

This is a guarded close: if the window declared a close guard via WindowConfig::on_close_requested or can_close, that guard runs first and may veto the close. To skip the guard (e.g. from the confirmation dialog the guard itself opened), use close_window_forced.

pub fn close_window_forced(&mut self)

Request that the application close this tree’s window unconditionally, bypassing any close guard declared via WindowConfig::on_close_requested / can_close.

This is the second half of the veto-then-reissue pattern: the guard returns CloseResponse::Veto and opens a confirmation dialog; the dialog’s “close anyway” button calls close_window_forced so the window actually closes without re-triggering the guard.

pub fn tree_pointer_position(&self) -> Option<Point>

The WindowState for the window hosting this handler. None only for handlers run outside of an app (hand-constructed EventContext in tests). Cursor position at the moment this handler was invoked. None when no PointerMove has reached the tree yet, or when the context was constructed without a tree-side snapshot (e.g. hand-built EventContexts in tests). Used by the safe-triangle submenu hover gate.

pub fn press_claimed_by_interactive_child(&self) -> bool

True when the in-flight pointer press’s hit target is a strict descendant of THIS handler’s widget that carries its own tap gesture (chevron, checkbox, inline button). A row/container that selects on press should early-return EventResponse::Ignored when this is set, so the press belongs to the inner control, not the row. Only meaningful inside on_pointer_event handlers for PointerDown/PointerUp.

pub fn overlay_bounds_for_content(&self, content_id: WidgetId) -> Option<Rect>

Look up the bounds rect of an open overlay by its root content widget id. Returns None when no such overlay is currently active. The snapshot is taken once per dispatch; mid-handler show_overlay calls will not appear here. Used by the safe-triangle submenu hover gate.

pub fn window(&self) -> Option<&WindowState>

pub fn window_active(&self) -> bool

Whether the host window is currently active (focused AND not occluded) — the occlusion-aware companion to self.window().map(|w| w.focused()) (raw OS focus). Snapshotted at context construction. Matches BuildContext::window_active.

pub fn open_window(&mut self, config: WindowConfig) -> TeksiloWindowId

Open a new window, creating the winit-level surface synchronously. The returned id is immediately valid for focus_window, window_state, and find_window.

Panics when called from a handler on a standalone WidgetTree (no app context) — tests should not invoke this method.

pub fn find_window(&self, string_id: &str) -> Option<TeksiloWindowId>

Find a window by the string id assigned via WindowConfig::id. Returns None if no open window carries that id.

pub fn window_state(&self, id: TeksiloWindowId) -> Option<WindowState>

Read the WindowState for a specific window.

pub fn windows(&self) -> Vec<WindowState>

Snapshot of every live window’s state.

pub fn focus_window(&mut self, id: TeksiloWindowId)

Raise a window to the front and give it keyboard focus.

pub fn request_activation_token( &mut self, id: TeksiloWindowId, cb: Box<dyn FnOnce(Option<String>)>, )

Request an xdg-activation token for id (see WindowOps::request_activation_token). cb fires once with the token string, or None where the platform can’t provide one — used to hand a token to a child process (“open in new window”) or an IPC peer that will raise itself on Wayland.

pub fn request_activation_token_self( &mut self, cb: Box<dyn FnOnce(Option<String>)>, )

Request an activation token for the current window (see WindowOps::request_activation_token_self). Use this from a widget handler to mint a token from this focused window to hand to another window or process — it works mid-dispatch, unlike the id-based variant.

pub fn close_window_by_id(&mut self, id: TeksiloWindowId)

Close a specific window by id. Equivalent to close_window when id is the current window’s id.

pub fn set_ime_cursor_area(&mut self, area: Rect)

Report the focused text widget’s caret rectangle (window-logical pixels) so the platform can position the OS IME candidate window at the insertion point. Text-editing widgets call this whenever the caret moves. No-op outside a dispatch / on a standalone tree.

pub fn parent_window_handle(&self) -> Option<ParentHandle>

Resolve the platform parent handle of the window currently dispatching the event. Used by native-dialog integrations (teksilo_platform::file_dialog) to parent OS dialogs to the originating Teksilo window.

Returns None when called from a standalone WidgetTree (no app-level WindowOps sink), or when the platform refuses to surface a handle (rare; mostly during teardown).

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

Request a cursor icon change.

pub fn set_dormant(&mut self, id: WidgetId)

Set a widget subtree as dormant (preserves state, releases rendering).

pub fn activate(&mut self, id: WidgetId)

Activate a dormant widget subtree.

pub fn destroy(&mut self, id: WidgetId)

Destroy a widget subtree (removes from arena entirely, state is gone).

pub fn with_widget_mut<W: 'static>( &mut self, id: WidgetId, dirty: BindingLevel, f: impl FnOnce(&mut W) + 'static, )

Imperatively mutate a mounted widget by id, downcasting to the concrete type W.

The mutation is deferred: the closure runs after the handler returns, inside apply_tree_mutations, where the framework holds &mut arena access (a handler cannot re-borrow the arena to reach another node, so this is the only safe channel — the same model as destroy). After the closure runs, the target is dirty-marked at dirty so the mutation takes visual effect.

The target widget must override Widget::as_any_mut to return Some(self). If the id is gone or is not a W, the closure is a no-op in release and a debug_assert failure in debug — it never silently mutates the wrong widget.

Use it for per-view state a handler can’t otherwise reach — e.g. SceneView::ensure_visible(...) (camera) after the view is mounted:

ctx.with_widget_mut::<SceneView>(view_id, BindingLevel::Relayout, |v| {
    v.ensure_visible(card_rect, 40.0);
});

For scene content, prefer the shared SceneModel handle (view.model()) — its mutators are &self, so a handler holding a clone can drive the scene directly and every attached view reconciles, no with_widget_mut needed.

pub fn materialize_now(&mut self, id: WidgetId)

Re-run one widget’s build() during this handler’s drain, before overlays are shown and before focus requests are applied — rather than dirty-marking it for the next layout pass, which is what every other rebuild trigger does.

It exists for one shape: DeferredSubtree content that a handler is about to depend on. Opening a popover activates its content, shows an overlay anchored to it, and moves focus into it — all three inside the same drain (see collect_from_ctx). A deferred panel marked for rebuild would not exist yet at any of those points: the overlay would be measured against an empty node and first_focusable_descendant would find nothing to focus, so the popover would open in the wrong place and swallow the keyboard. Materializing here closes that window, and makes deferred content behave exactly like the eagerly-built content it replaces.

Cheap to call redundantly: a DeferredSubtree that is already materialized returns its existing child, so a second open costs one build() of the host and nothing below it.

Not a general “rebuild this widget now” door — reach for with_widget_mut or a Rebuild binding for ordinary reactive updates, which are correctly served by the next layout pass.

pub fn request_accessibility_update(&mut self)

Request that the AccessKit tree be re-walked after this handler returns. Use after a mutation that changes the accessibility tree shape in a way the framework doesn’t already detect (relayout alone no longer re-walks AT; only events that change the AT tree — focus, overlays, locale/shortcut rebinds — set the dirty flag). The companion BuildContext::request_accessibility_update covers the build-time path.

pub fn show_overlay(&mut self, request: OverlayRequest)

Show an overlay (tooltip, menu, popover).

pub fn show_overlay_with_reveal( &mut self, request: OverlayRequest, progress: Signal<f32>, duration: Duration, )

Show an overlay whose reveal/dismiss is animated by a caller-owned progress signal.

progress must be an animated Signal<f32> (created with Signal::new_animated or BuildContext::animated_signal). The framework shows the overlay, tweens progress 0 → 1 over duration, and on any dismiss path tweens it 1 → 0 while deferring the overlay’s removal (and its content’s dormancy) until the roll-back completes — the same window the fade path uses, but with no opacity applied. The caller binds progress to whatever paints the reveal (e.g. an Unroll width), and is responsible for resetting it to 0.0 before the show if a prior reveal left it at 1.0.

Under prefers-reduced-motion, skip this and use show_overlay with the progress pinned at 1.0 so there is no tween and dismissal is immediate.

pub fn show_overlay_for(&mut self, request: OverlayRequest, duration: Duration)

Show an overlay that dismisses automatically after duration.

pub fn dismiss_overlay(&mut self, id: OverlayId)

Dismiss an overlay by ID.

pub fn dismiss_overlay_by_content(&mut self, content_id: WidgetId)

Dismiss the currently-shown overlay whose content root is content_id, if one is active. No-op when no overlay is showing that content. Use this to dismiss an overlay you can only name by its content widget — the symmetric companion to cancel_delayed_overlay, which cancels a pending delayed show for the same content. Together they let a caller fully retract a reusable tooltip surface (shown or pending) without tracking the OverlayId.

pub fn pause_overlay_auto_dismiss(&mut self, id: OverlayId)

Queue a request to pause an overlay’s auto_dismiss_after timer. Drained by the framework after this handler returns — equivalent to calling OverlayManager::pause_auto_dismiss at the next safe point. Idempotent.

Used by ToastHost for hover-pause: on pointer-enter the host queues pause_overlay_auto_dismiss(id) for every live toast; on pointer-leave it queues resume_overlay_auto_dismiss.

pub fn resume_overlay_auto_dismiss(&mut self, id: OverlayId)

Queue a request to resume an overlay’s auto_dismiss_after timer paused via pause_overlay_auto_dismiss. Idempotent on un-paused overlays.

pub fn dismiss_all_overlays(&mut self)

Dismiss all active overlays (e.g., after a menu item is activated).

pub fn dismiss_self_overlay_chain(&mut self)

Dismiss the source widget’s containing overlay and any ancestor overlays in the chain that are menu-like (anything that isn’t a Role::Tooltip, Role::Dialog, or Role::AlertDialog), preserving an outer composite tooltip or modal hosting the popover. Use for menu / dropdown item activation that wants to close the menu cascade without disturbing the host surface.

pub fn dismiss_all_except_hosts(&mut self)

Dismiss every overlay whose content is not a host surface (Role::Tooltip, Role::Dialog, Role::AlertDialog), preserving an outer composite tooltip or modal hosting the trigger. Use for popover triggers and pre-show cleanup that want to close stale popovers / menus without taking a hosting surface with them.

pub fn dismiss_top_overlay(&mut self)

Dismiss the topmost overlay only (e.g., closing a submenu while keeping the parent menu open).

pub fn dismiss_child_overlays(&mut self)

Dismiss descendant overlays of the source widget’s containing overlay. Useful for closing sibling submenu branches while keeping the current parent menu open.

pub fn dismiss_child_overlays_except(&mut self, content_id: WidgetId)

Dismiss descendant overlays of the source widget’s containing overlay, preserving the subtree rooted at content_id if it is already open.

pub fn request_idle_callback( &mut self, callback: impl FnOnce(IdleDeadline) + 'static, )

Request an idle callback to be run during the next idle period. Use this for incremental work that takes 5-50ms — too short for a background thread, too long for a single frame.

pub fn present_modal(&mut self, request: ModalRequest)

Request framework-owned modal presentation.

The widget tree records the request together with the originating widget, and the application layer can later resolve Auto into a concrete presentation backend.

pub fn open_modal(&mut self, request: ModalRequest) -> Option<TeksiloWindowId>

Synchronously open a modal as a native window — the single unified path for native-window modals. Callers that don’t care whether the modal lands in-tree or in a native window use present_modal, which routes ModalPresentation::Auto through the framework’s picker.

Returns the new window’s id, or None when called outside a dispatch context (standalone trees). The window’s parent is the current window; focus target and title / size from the request are honored.

Only ModalContent::Deferred is supported here — an ExistingWidget id wouldn’t make sense in a fresh tree.

pub fn dismiss_modal(&mut self)

Dismiss the current framework-owned modal presentation.

pub fn show_overlay_after(&mut self, request: OverlayRequest, delay: Duration)

Show an overlay after a delay. The widget tree checks pending delayed overlays during layout() and shows them once the delay elapses. Use this for submenu hover-open delays.

The content widget should already be added to the tree (typically dormant). It will be activated automatically when the delay elapses.

pub fn show_overlay_after_with_focus( &mut self, request: OverlayRequest, delay: Duration, focus_target: WidgetId, )

Show an overlay after a delay and move focus when it opens.

pub fn request_repaint(&mut self, id: WidgetId)

Request a repaint on a specific widget. Use this when an event handler on one widget changes state that affects a different widget’s appearance (e.g., keyboard navigation highlighting items in an overlay).

pub fn synthetic_click(&mut self, id: WidgetId)

Programmatically click a widget (synthetic PointerDown + PointerUp at its center). Use this for keyboard activation of a child widget, e.g., Enter on a keyboard-focused menu item.

pub fn request_focus(&mut self, id: WidgetId)

Transfer focus to a specific widget. Use this when opening overlay content (menus, dialogs) that should receive keyboard events.

pub fn request_focus_into(&mut self, id: WidgetId)

Move focus into the content of id: focus its first focusable descendant in tab order. Unlike request_focus, this does not fall back to focusing id itself when the subtree has no focusable descendant — it is a no-op in that case, so an empty region never traps focus on a non-interactive container.

Use this for “dive into this region” gestures, e.g. pressing Enter on a focused tab header to move focus into the tab’s content panel. A panel with focusable content lands on its first control; a panel that opted into focusability itself (no inner controls) lands on the panel; a bare panel with neither leaves focus where it was.

pub fn ensure_visible(&mut self, rect: Rect)

Scroll the given rectangle into view inside every enclosing scroll container, walking outward from the widget whose handler is running.

rect is in absolute tree (window) coordinates — the same space the arena stores widget bounds in. After the handler returns, the framework walks the current widget’s ancestors and, for each clips_children scroll container whose viewport does not already fully contain rect, dispatches WidgetEvent::ScrollIntoView so the container adjusts its offset. Nested scroll areas each get a turn (outermost included), exactly like the focus-driven path.

Unlike the automatic focus follow — which can only reveal a focused widget’s own bounds — this lets a widget reveal an arbitrary interior rectangle it computed itself: a text caret, a virtualized list/table row (which is not a distinct focusable node), or a scrolled-off tab header. The widget remains responsible for scrolling its own interior viewport; ensure_visible handles the enclosing containers. It is a no-op when there is no scroll container above the widget, or when every container already shows the rect.

See ensure_visible_with_margin to keep breathing room around the target.

pub fn ensure_visible_from(&mut self, owner: WidgetId, rect: Rect)

ensure_visible, for a rect that belongs to another widget.

The framework walks owner’s ancestors rather than the handling widget’s. That distinction is the whole of it, and getting it wrong fails silently: a find banner’s Next button sits beside the scrolling page, not inside it, so a reveal walked from the button climbs out through the banner and never meets the scroll container the match is in. The match is selected, the counter moves, and the viewport does not follow.

The same reasoning ensure_widget_visible already records for the id-based form; this is its rect-based twin, for a target that is an interior span rather than a mounted child.

rect is in absolute tree (window) coordinates.

pub fn ensure_visible_with_margin(&mut self, rect: Rect, margin: f32)

Like ensure_visible, but keeps margin logical pixels of breathing room around rect on every edge, so the target does not sit flush against the viewport boundary (the caret at the bottom line, the selected row at the fold). rect is in absolute tree (window) coordinates.

pub fn ensure_visible_aligned( &mut self, rect: Rect, fraction: f32, motion: ScrollMotion, )

Pin rect at fraction of the way down the innermost enclosing scroll container — 0.0 flush with the top, 0.5 centred, 1.0 flush with the bottom — instead of merely revealing it.

The difference from ensure_visible is that this scrolls even when the target is already visible. That is what makes it usable for typewriter scrolling: a caret that only moved the view once it fell off the edge would not be pinned to anything.

Only the innermost clipping ancestor aligns; any further ancestors out fall back to a minimal reveal, since an outer container’s job is to bring the inner viewport on screen, not to align a rectangle it does not own.

fraction is clamped to 0.0..=1.0. The container additionally clamps to its own scroll range, so a target near the start or end of the content lands as close to fraction as the range permits — see the scroll container’s scroll_past_end for buying range past the content’s end so the last line can still reach the pin.

rect is in absolute tree (window) coordinates.

pub fn ensure_visible_aligned_from( &mut self, owner: WidgetId, rect: Rect, fraction: f32, motion: ScrollMotion, )

ensure_visible_aligned, for a rect that belongs to another widget — see ensure_visible_from for why the distinction exists and how it fails when it is missed.

pub fn ensure_widget_visible(&mut self, id: WidgetId)

Scroll a specific mounted widget into view inside every enclosing scroll container — the id-based companion to ensure_visible.

The framework resolves id to its current absolute bounds after the handler returns and walks that widget’s ancestors (never id itself), dispatching WidgetEvent::ScrollIntoView to each clips_children container that doesn’t already show it.

Use this when the target you want revealed is a real, non-virtualized child whose bounds the arena already knows — a selected radio tile, a tab header — so you don’t have to compute a rect. For a target that has no distinct node (a text caret) or that may not be realized (a virtualized list/table row), use ensure_visible with an analytic rect instead. No-op if id is not currently mounted.

pub fn ensure_widget_visible_with_margin(&mut self, id: WidgetId, margin: f32)

Like ensure_widget_visible, but keeps margin logical pixels of breathing room around the widget.

pub fn show_highlight_tooltip(&mut self, id: WidgetId)

Surface the tooltip of a keyboard-highlighted item immediately (no dwell), dismissing the previously-highlighted item’s tooltip. Used by MenuList on arrow-key navigation so a menu item’s rich/composite tooltip is reachable by keyboard — real focus stays on the menu panel, so this is keyed on the item id rather than on focus. Pass the item’s own widget id; a tooltip-less item simply dismisses the previous one.

pub fn cancel_delayed_overlay(&mut self, content_id: WidgetId)

Cancel a pending delayed overlay by its content widget ID. Call this when the hover ends before the delay elapses.

pub fn capture_pointer(&mut self)

Capture the pointer: all subsequent PointerMove and PointerUp events will be routed to the capturing widget until the capture is released. Use this when starting a drag operation.

pub fn release_pointer(&mut self)

Release a previously captured pointer. Pointer events resume normal hit-test dispatch.

pub fn start_drag(&mut self, source_widget: WidgetId, payload: DragPayload)

Start a drag-and-drop operation from the given source widget.

The payload carries the data being dragged. During the drag:

• PointerMove events update the drag position and fire on_drag_hover on widgets under the pointer that have drop handlers
• PointerUp fires on_drop on the target widget (if any)
• Escape cancels the drag

pub fn start_drag_with_preview( &mut self, source_widget: WidgetId, payload: DragPayload, preview: Box<dyn Widget>, )

Start a drag-and-drop with a preview widget that follows the pointer.

pub fn cancel_drag(&mut self)

Cancel the active drag-and-drop session (if any).

pub fn set_theme(&mut self, theme: Theme)

Replace the tree-level theme. Composite widgets are rebuilt so any derived values they captured at build time pick up the new tokens, and all widgets are marked dirty for repaint.

An explicit theme also turns off OS-following: the app’s theme mode is reset to manual, so a later OS light/dark change won’t override the chosen theme.

pub fn follow_system_theme(&mut self)

Switch the application to follow the OS theme (native / system mode): the app adopts the OS’s colours and tracks OS light/dark changes at runtime. On platforms without OS-colour support it falls back to following the built-in light/dark presets.

This is the counterpart to set_theme: calling set_theme pins a fixed theme (manual mode), while this resumes OS-following. Parameterless by design, so widgets need not reference the app-layer theme-mode enum.

pub fn set_locale(&mut self, locale: impl Into<String>)

Replace the tree-level locale identifier. Composite widgets are rebuilt so any tr! lookups picked up at build time are re-evaluated against the new locale.

pub fn set_text_scale(&mut self, factor: f32)

Set the user-controlled global text-scale factor (1.0 = 100 %).

The change is applied app-wide (every window) after the handler returns, mirroring set_theme / set_locale. All text grows uniformly without a rebuild. Persist the value through ctx.settings() (e.g. teksilo_settings::TEXT_SCALE_KEY) so it survives a restart — the TextScaleControl widget does both for you.