Struct HandlerSet 

pub struct HandlerSet { /* private fields */ }

Temporary storage for handlers and metadata accumulated via builder methods. Transferred to the WidgetNode during arena insertion.

Implementations

impl HandlerSet

pub fn merge_under(&mut self, base: HandlerSet)

Absorb base’s declarations wherever self is silent.

self is the later declaration and wins on conflict, so this reads left to right like the builder chain that produced the two sets. It is Compose’s Modifier.then, expressed on the value Teksilo already has.

The accessibility block is merged, not assigned: an overrides block carries lists (controls, described_by, custom_actions, …) that a plain assignment would drop. WidgetArena makes the same point at its own merge site.

pub fn new() -> Self

Create an empty handler set for use in BuildContext::apply_self_handlers().

pub fn on_tap( self, f: impl FnMut(&TapEvent, &mut EventContext<'_>) + 'static, ) -> Self

Set the on_tap handler. The closure receives a borrowed TapEvent carrying the position in widget-local coordinates, the finalising mouse button, and the modifier state at that moment.

Default acceptance is ButtonMask::PRIMARY — left-click only. Use accept_tap_buttons to widen the set if you need right-click, middle-click, or auxiliary buttons to fire this handler.

pub fn on_double_tap( self, f: impl FnMut(&TapEvent, &mut EventContext<'_>) + 'static, ) -> Self

Set the on_double_tap handler. See on_tap for the callback contract.

pub fn on_triple_tap( self, f: impl FnMut(&TapEvent, &mut EventContext<'_>) + 'static, ) -> Self

Set the on_triple_tap handler — fires on the third click within the recognizer’s window (same 300 ms / 10 px defaults as double tap). Runs independently of on_double_tap via cooperative gesture recognizers (GestureRecognizer::resets_on_peer_recognition).

pub fn on_long_press( self, f: impl FnMut(&TapEvent, &mut EventContext<'_>) + 'static, ) -> Self

Set the on_long_press handler. The callback receives a borrowed TapEvent whose modifiers are captured from the held Down (since long-press recognises on a timer before any Up).

pub fn accept_tap_buttons(self, mask: impl Into<ButtonMask>) -> Self

Restrict (or extend) the set of pointer buttons that fire on_tap. Default is ButtonMask::PRIMARY (left-click only). Pass ButtonMask::ALL or ButtonMask::PRIMARY | ButtonMask::SECONDARY, etc.

pub fn accept_double_tap_buttons(self, mask: impl Into<ButtonMask>) -> Self

Restrict (or extend) the set of pointer buttons that fire on_double_tap. Default ButtonMask::PRIMARY.

pub fn accept_triple_tap_buttons(self, mask: impl Into<ButtonMask>) -> Self

Restrict (or extend) the set of pointer buttons that fire on_triple_tap. Default ButtonMask::PRIMARY.

pub fn accept_long_press_buttons(self, mask: impl Into<ButtonMask>) -> Self

Restrict (or extend) the set of pointer buttons that fire on_long_press. Default ButtonMask::PRIMARY.

pub fn on_hover( self, f: impl FnMut(bool, &mut EventContext<'_>) + 'static, ) -> Self

Set the on_hover handler.

pub fn on_key( self, f: impl FnMut(&WidgetEvent, &mut EventContext<'_>) -> EventResponse + 'static, ) -> Self

Set the on_key handler.

pub fn on_key_preview( self, f: impl FnMut(&WidgetEvent, &mut EventContext<'_>) -> EventResponse + 'static, ) -> Self

Set the strict-ancestor key preview handler. Fires on every ancestor of the focused widget (root → parent-of-target) before the focused widget’s on_key runs. Return EventResponse::Handled to consume the event.

pub fn on_drag( self, f: impl FnMut(DragPhase, &mut EventContext<'_>) + 'static, ) -> Self

Set the on_drag handler (gesture-based drag). The closure receives a DragPhase — Started, then zero or more Moved, then Ended.

pub fn on_swipe( self, f: impl FnMut(SwipeDirection, f32, &mut EventContext<'_>) + 'static, ) -> Self

Set the on_swipe handler. Fires once per swipe with the direction and velocity (pixels/second).

pub fn on_pinch( self, f: impl FnMut(PinchPhase, &mut EventContext<'_>) + 'static, ) -> Self

Set the on_pinch handler. On desktop the phases are produced from OS trackpad gestures (winit TouchpadMagnify / RotationGesture).

pub fn on_focus( self, f: impl FnMut(bool, &mut EventContext<'_>) + 'static, ) -> Self

Set the on_focus handler. f is called with true on focus gain and false on focus loss.

WCAG 3.2.1 (On Focus). Use this only to update local visual or reactive state. Do NOT open a window, navigate, submit, or otherwise change context from here: a context change triggered merely by a control receiving focus is a Success Criterion 3.2.1 failure — keyboard users tabbing through the UI would trigger it unexpectedly. (A debug-only guard warns if ctx.open_window(...) / ctx.focus_window(...) is called from inside focus dispatch.)

pub fn on_pointer_event( self, f: impl FnMut(&WidgetEvent, &mut EventContext<'_>) -> EventResponse + 'static, ) -> Self

Set the on_pointer_event handler (low-level escape hatch).

pub fn on_scroll( self, f: impl FnMut(&WidgetEvent, &mut EventContext<'_>) -> EventResponse + 'static, ) -> Self

Set the on_scroll handler.

pub fn on_access_action( self, f: impl FnMut(Action, &mut EventContext<'_>) -> EventResponse + 'static, ) -> Self

Set the on_access_action handler.

pub fn on_access_action_request( self, f: impl FnMut(Action, NodeId, Option<ActionData>, &mut EventContext<'_>) -> EventResponse + 'static, ) -> Self

Set the full AccessKit action-request handler. Receives the action, target NodeId (may be a synthetic widget-emitted child), and optional ActionData payload (e.g. SetTextSelection(TextSelection) or Value(Box<str>)).

Layered with on_access_action rather than replacing it: both fire for the same dispatched action, and it counts as handled if either says so.

pub fn focusable(self, focusable: bool) -> Self

Set the focusable flag.

pub fn cursor(self, cursor: CursorIcon) -> Self

Set the cursor icon.

pub fn clips_children(self, clips: bool) -> Self

Set the clips_children flag.

pub fn ime_input(self, ctx: ImeContext) -> Self

Declare this node a text-input surface, enabling the OS input method (with ctx’s purpose) while it is focused. Leaving it unset (the default) means no OS IME. The platform reads the focused node’s descriptor at focus-change time. See crate::ime.

pub fn event_pass_through(self, pass_through: bool) -> Self

Make the widget invisible to pointer hit-testing. With pass_through = true, pointer events traverse this node as if it were not there — useful for purely decorative overlays that must not absorb clicks (the debug inspector’s HighlightLayer and HoverProbe use this).

pub fn gesture_dead_zone(self, dead_zone: bool) -> Self

Mark this widget’s subtree a gesture dead zone: a pointer press inside it must not arm a drag/swipe recognizer on any ancestor above it. Use to let interactive controls (buttons, a ⋮ menu) sit inside a draggable / swipeable container (a dock-panel header, a card, a list row) without a few px of click jitter starting the ancestor’s drag. The container’s own drag still works everywhere else. Honored by PointerSequence member enrolment; see the DeadZone wrapper widget.

pub fn long_press_role(self, role: LongPressRole) -> Self

Select what a hold on this widget’s subtree means, for the tree-owned long-press route.

Only ever consulted for a pointer that cannot hover, and only where the widget installs no on_long_press of its own — that always wins. See crate::widget_tree::touch_route for the precedence and for what each variant selects.

pub fn touch_action(self, action: TouchAction) -> Self

Override what a direct pointer (touch, pen) is permitted to do to this widget’s subtree — the CSS touch-action model. Intersected with every ancestor’s declaration on the way down; a mouse never consults this. See super::arena::WidgetNode::touch_action.

pub fn scroll_container(self, axes: PanAxes) -> Self

Declare this widget a pan surface on axes for direct pointers, with kinetic (fling/settle) hand-off on release. Sugar for .pan_claim(PanClaim { axes, devices: PointerKindMask::DIRECT, kinetic: true }) — the shape every scrollable declares. See super::arena::WidgetNode::pan_claim.

pub fn pan_claim(self, claim: PanClaim) -> Self

Declare this widget a pan surface with an explicit PanClaim — the escape hatch behind scroll_container for a claim that isn’t kinetic, or that widens/narrows the device mask. See super::arena::WidgetNode::pan_claim.

pub fn overscroll_behavior(self, behavior: OverscrollBehavior) -> Self

Whether this widget absorbs a scroll it cannot use (Contain) or lets it chain outward at its boundary (Chain, the default). The CSS overscroll-behavior model, read by the pan claimant chain. See super::arena::WidgetNode::overscroll_behavior.

pub fn drag_activation(self, activation: DragActivation) -> Self

When a drag on this widget may begin relative to the press that starts it.

DragActivation::Auto — the default — is Immediate for a precise pointer, which is exactly today’s behaviour, and AfterLongPress for a coarse pointer whose axis a pan surface has already claimed. Declare Immediate for a control whose drag is the interaction (a slider thumb, a splitter handle) and AfterLongPress for one that must not steal a scroll (a reorderable list row). See super::arena::WidgetNode::drag_activation.

pub fn multi_contact(self, policy: MultiContact) -> Self

How many simultaneous contacts this node serves. Default MultiContact::First. See super::arena::WidgetNode::multi_contact.

pub fn keyboard_capture(self, capture: bool) -> Self

Mark this widget a keyboard capture surface: while it holds focus, every KeyDown is delivered straight to its on_key handler, bypassing shortcut → intent → action resolution. Use for a terminal emulator that must forward Ctrl+C / Ctrl+W / Alt+<letter> to a child process instead of triggering the host app’s shortcuts, a game viewport, or a modal text surface.

The escape contract

Ctrl+Tab / Ctrl+Shift+Tab are reserved and always move focus out. The dispatcher cycles focus on that chord before the capture node is consulted, so a capture surface cannot become a keyboard trap (WCAG 2.1.2) however greedily its on_key behaves. Do not bind them.

Nothing else is reserved. In particular Escape is not: overlay back-navigation runs first only while an overlay is actually open, so a focused capture surface with no overlay above it does receive Escape and may consume it. See super::arena::WidgetNode::keyboard_capture.

pub fn hit_transparent(self, transparent: bool) -> Self

Make this widget AND its whole subtree invisible to pointer hit-testing. Stronger than event_pass_through: that one keeps descendants hittable, this one excludes them too. For purely decorative composite overlays (a count badge over a button, a watermark) whose own children would otherwise swallow the click meant for the control underneath.

pub fn hit_slop(self, slop: HitSlop) -> Self

Override how far a missed press may be re-attributed to this node, and up to what size it is topped up.

Second link of the precedence chain: no_hit_slop beats this, this beats the widget’s own Widget::hit_slop, and that beats the density default. Use it for a control the framework cannot recognise as small — a hand-drawn handle, a custom mark in a chart — or to raise up_to beyond the density’s target_size for one especially fiddly target.

Hit-only: no layout moves and nothing repaints differently.

pub fn no_hit_slop(self) -> Self

Take this node out of both hit-widening mechanisms: it earns no slop outset, and its Widget::hit_outset is ignored.

Head of the precedence chain, and the right switch for a node whose exact rectangle is the contract — a surface hosting foreign content (a WebView, an embedded engine) that must receive precisely the presses that land on it and no others, or a modal scrim, which must never re-attribute a press to something under it.

Per-node, not per-subtree: descendants may still widen. To take a whole subtree out of hit-testing use hit_transparent.

pub fn focus_within(self, signal: Signal<bool>) -> Self

Bind a user-owned Signal<bool> that the framework will set to true whenever the focused widget is a strict descendant of this node, and false otherwise. Useful for unified focus halos around composite widgets (a chat composer that highlights when its RichTextEditor or “Send” button is focused, a Panel wrapping a SpinBox, etc).

Strict-ancestors only — a widget that is itself focused does not also see its own focus_within signal flipped to true. Combine with on_focus if you want both behaviours.

pub fn hover_within(self, signal: Signal<bool>) -> Self

Bind a user-owned Signal<bool> that the framework will set to true whenever the hovered widget is a strict descendant of this node. Symmetric to focus_within.

pub fn visible_when(self, state: impl Into<Prop<bool>>) -> Self

Bind this node’s visibility to a bool / Signal<bool> / Prop<bool>. A bound value shows/hides the node reactively (registered at Relayout). Equivalent to ctx.visible_when(id, ..); exposed as a builder method so teksu! can write visible_when: sig as a property.

pub fn context_menu( self, factory: impl Fn(Point, &mut EventContext<'_>) -> Option<Box<dyn Widget>> + 'static, ) -> Self

Set a context-menu factory. See ContextMenuFactory for the full contract: the closure receives the click position (widget-local) and a full EventContext, and returns Some(menu) to mount or None to decline (falling through to the nearest ancestor with a factory).

pub fn on_drag_hover( self, f: impl FnMut(&DragPayload, Point, &mut EventContext<'_>) -> DropFeedback + 'static, ) -> Self

Set the drag hover handler. Called when a drag payload hovers over this widget. Return DropFeedback to indicate acceptance and visual feedback.

pub fn on_drag_leave( self, f: impl FnMut(&mut EventContext<'_>) + 'static, ) -> Self

Set the drag-leave handler. Fires when a drag that was over this widget moves to another target, completes (drop on any target), or is cancelled. Widgets that stash transient feedback state in on_drag_hover must clear it here.

pub fn on_pointer_cancel( self, f: impl FnMut(&PointerInfo, CancelReason, &mut EventContext<'_>) + 'static, ) -> Self

Set the pointer-cancel handler. Fires when a pointer interaction on this widget is taken away — the window lost focus, a modal opened, the subtree was parked, a peer won the arbitration.

Terminal: no PointerUp follows. Release anything the press latched; the framework releases its own state but never widget-owned state.

pub fn on_drag_tick( self, f: impl FnMut(Point, &mut EventContext<'_>) + 'static, ) -> Self

Set the per-frame drag-tick handler. Fires once per frame while a drag is active and this widget is the current drop target. The closure receives the current pointer position in widget-local coordinates. Use for behaviours that must keep running even when the pointer is stationary — viewport-edge auto-scroll and spring-loaded folders.

pub fn on_drop( self, f: impl FnMut(DragPayload, Point, &mut EventContext<'_>) -> bool + 'static, ) -> Self

Set the drop handler. Called when a payload is dropped on this widget. Return true if the drop was accepted.

pub fn on_drag_ended( self, f: impl FnMut(DropOutcome, &mut EventContext<'_>) + 'static, ) -> Self

Set the drag-ended handler on a drag source. Fires when a drag this widget started ends — dropped on an in-app target, exported to another application via the OS (copy / move), or cancelled. Use it to react to the outcome, e.g. remove the dragged item on a DropOutcome::OsMove.

pub fn access_custom_action<F>( self, label: impl Into<Prop<String>>, handler: F, ) -> Self

where F: FnMut(&mut EventContext<'_>) + 'static,

Advertise a named custom action on this node and register its callback.

The WidgetWithHandlers twin (access_custom_action) is how an application adds one from outside. This is how a widget adds one to a node it builds itself — a virtualized row, a rail item, a header cell — where there is no builder chain to hang it on because the node is reached through BuildContext::apply_handlers.

Actions are dispatched by declaration order, so a node’s callbacks and its advertised list cannot drift apart.

Trait Implementations

impl Debug for HandlerSet

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

Formats the value using the given formatter.

impl Default for HandlerSet

fn default() -> Self

Returns the “default value” for a type.