Struct WidgetWithHandlers 

pub struct WidgetWithHandlers<W: Widget> { /* private fields */ }

A widget wrapped with attached event handlers and framework metadata. Created by calling builder methods from WidgetBuilder on any widget.

Implementations

impl<W: Widget> WidgetWithHandlers<W>

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

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

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

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

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.

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_drag( self, f: impl FnMut(DragPhase, &mut EventContext<'_>) + 'static, ) -> Self

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

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

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

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

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

Set the strict-ancestor key preview handler. See HandlerSet::on_key_preview.

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

pub fn tab_index(self, index: i32) -> Self

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

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

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

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

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

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

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

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

WidgetBuilder::clips_children_on’s inherent twin.

The trait spells it clips_children_on because clips_children is already taken on Widget as a &self query. Without this twin the trait method applies to an already-wrapped widget and wraps it a second time; Widget::take_handler_set now merges through that, so it is a wasted node rather than lost behaviour, but the twin avoids both.

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. See crate::ime.

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

Make the widget invisible to pointer hit-testing. See HandlerSet::event_pass_through.

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

Mark this widget’s subtree a gesture dead zone. See HandlerSet::gesture_dead_zone.

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

Select what a hold on this widget’s subtree means. See HandlerSet::long_press_role.

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

Override what a direct pointer may do to this widget’s subtree. See HandlerSet::touch_action.

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

Declare this widget a pan surface on axes, kinetic, direct pointers only. See HandlerSet::scroll_container.

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

Declare this widget a pan surface with an explicit PanClaim. See HandlerSet::pan_claim.

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

Whether this widget absorbs a boundary scroll or chains it outward. See HandlerSet::overscroll_behavior.

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

When a drag on this widget may begin. See HandlerSet::drag_activation.

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

HandlerSet::multi_contact.

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

Mark this widget a keyboard capture surface: while focused, every KeyDown bypasses shortcut resolution and reaches its on_key handler (terminals, game viewports). See HandlerSet::keyboard_capture.

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

Make this widget and its whole subtree invisible to pointer hit-testing. See HandlerSet::hit_transparent.

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

Override the miss-only hit slop for this node. See HandlerSet::hit_slop.

pub fn no_hit_slop(self) -> Self

Take this node out of both hit-widening mechanisms. See HandlerSet::no_hit_slop.

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

Set a context-menu factory. See HandlerSet::context_menu for the full contract.

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

Bind a Signal<bool> the framework writes when a strict descendant has focus. See HandlerSet::focus_within.

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

Bind a Signal<bool> the framework writes when a strict descendant is hovered. See HandlerSet::hover_within.

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

Bind this node’s visibility. See HandlerSet::visible_when.

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.

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

Set the drag-leave handler. See HandlerSet::on_drag_leave.

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

Set the pointer-cancel handler. See HandlerSet::on_pointer_cancel.

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

Set the per-frame drag-tick handler. See HandlerSet::on_drag_tick.

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.

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

Set the drag-ended handler on a drag source. See HandlerSet::on_drag_ended.

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

Override the accessibility label (Node::label) of this widget. Replaces whatever the inner widget emitted via set_name.

Accepts any impl Into<Prop<String>>. With the i18n feature, LocalizedString (produced by tr!(...)) implements From<LocalizedString> for Prop<String>, so .access_label(tr!(save())) stays reactive — the announced value re-resolves on locale change (the accessibility tree re-walks via sync_accessibility).

pub fn access_description(self, description: impl Into<Prop<String>>) -> Self

Override the accessibility description (Node::description). Same conversion rules as access_label.

pub fn access_hint(self, hint: impl Into<Prop<String>>) -> Self

Long-form context hint. Alias of access_description — AccessKit has no separate hint slot (SwiftUI’s split is VoiceOver-specific). Provided for SwiftUI parity.

pub fn access_value(self, value: impl Into<Prop<String>>) -> Self

Override the accessibility value (Node::value). Same conversion rules as access_label.

pub fn access_role(self, role: Role) -> Self

Override the accessibility role.

pub fn access_hidden(self, hidden: impl Into<Prop<bool>>) -> Self

Hide (or un-hide) this node from assistive technologies. Accepts a plain bool, a Signal<bool>, or a Prop<bool>: a bound value makes the node appear/disappear from the AT tree reactively (the binding is registered at AccessibilityOnly, so the tree re-walks on change). false un-sets a hidden state the inner widget may have emitted unconditionally (e.g. Panel::a11y_presentational).

pub fn access_disabled(self, disabled: bool) -> Self

Mark (or un-mark) this widget as disabled for AT. false clears both widget-emitted disabled state AND the framework’s arena-driven disabled gate at accessibility_emit_impl::build_accessibility_recursive.

pub fn access_identifier(self, id: impl Into<String>) -> Self

Stable test/debug identifier (Node::author_id). Not user-visible — used by accessibility inspectors and UI tests.

pub fn access_controls(self, target: WidgetId) -> Self

Append a controls relationship. The target widget’s NodeId is included in this node’s aria-controls-equivalent list.

pub fn access_described_by(self, target: WidgetId) -> Self

Append a described_by relationship.

pub fn access_labelled_by(self, target: WidgetId) -> Self

Append a labelled_by relationship.

pub fn access_live(self, mode: Live) -> Self

Set the live-region politeness (Node::live).

pub fn access_current(self, current: AriaCurrent) -> Self

Mark this node as the current item within its container (aria-current).

pub fn access_shortcut_literal(self, shortcut: impl Into<String>) -> Self

Pre-formatted shortcut announcement (e.g. "Ctrl+S"). Used for chords NOT routed through the Shortcut system — platform-native keys, app-internal hotkeys not exposed to user rebinding. For Shortcut-registered chords prefer access_shortcut_id, which tracks rebinds automatically.

pub fn access_shortcut_id(self, id: impl Into<String>) -> Self

Bind the announced shortcut to a registered Shortcut id (the same id you pass to Shortcut::new("app.save")). The accessibility tree walker resolves the current keystroke from WidgetTree::shortcut_registry() at AT-build time, formats it via KeyStroke::Display ("Ctrl+S"), and writes it to Node::keyboard_shortcut. Auto-refreshes on rebind.

If the registry has no entry for id (no widget registered the shortcut yet), the announcement is omitted — same fallback as MenuItem::for_shortcut(...).

pub fn access_has_popup(self, kind: HasPopup) -> Self

Indicate that activating this widget pops up a menu / listbox / dialog (aria-haspopup).

pub fn access_orientation(self, orientation: Orientation) -> Self

Override orientation (Node::orientation) — used on sliders, scrollbars, separators.

pub fn access_exclude_subtree(self) -> Self

Prune all descendants from the accessibility tree. The widget’s own AT node is still emitted; only children disappear. Use for purely decorative composites. Flutter’s excludeSemantics: true.

pub fn access_merge_subtree(self) -> Self

Lift descendants’ labels / descriptions / values / actions into this widget’s AT node, then prune the descendants. The whole composite reads as a single AT element. Flutter’s mergeAllDescendants: true and SwiftUI’s .accessibilityElement(children: .combine).

pub fn access_subtree(self, mode: AccessSubtreeMode) -> Self

Set an explicit subtree mode.

pub fn access_numeric_value(self, value: f64) -> Self

Override Node::numeric_value.

pub fn access_numeric_range(self, min: f64, max: f64) -> Self

Override Node::min_numeric_value and max_numeric_value.

pub fn access_numeric_step(self, step: f64) -> Self

Override Node::numeric_value_step.

pub fn access_action<F>(self, action: Action, handler: F) -> Self

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

Advertise an accessibility action and the callback that fires when AT software invokes it. Multiple access_action calls register separate callbacks for distinct actions; calling twice with the same action records both — they fire in order.

pub fn access_remove_action(self, action: Action) -> Self

Suppress an action the inner widget emitted (e.g. neutralize Action::Click on a Button used purely as a layout shim). Applied after the widget’s accessibility() runs but before override-advertised actions, so a subsequent access_action for the same action re-advertises it with the override-installed callback.

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

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

Advertise a custom-named action (SwiftUI parity: .accessibilityAction(named:_:)). The label is exposed verbatim by AT software (e.g. VoiceOver’s Actions rotor). Accepts tr!(...) via From<LocalizedString> for Prop<String> in teksilo-i18n, so the announced name follows the locale.

pub fn access_customize<F>(self, f: F) -> Self

where F: Fn(&mut AccessNodeBuilder) + 'static,

Final escape hatch — invoked after all typed override setters, with full &mut AccessNodeBuilder access (including inner_mut()). Use for synthetic-child surgery (rich text paragraphs, text runs) or any AccessKit field the typed surface doesn’t cover.

Trait Implementations

impl<W: Widget> Debug for WidgetWithHandlers<W>

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

Formats the value using the given formatter.

impl<W: Widget + 'static> Widget for WidgetWithHandlers<W>

Every method of Widget, forwarded to the wrapped widget.

WidgetWithHandlers<W> replaces W at W’s own arena node — the tree never sees W again. So a hook this impl does not forward is not overridden, it is gone: the trait’s default answers in its place, for every widget any builder method has ever touched. Nothing warns, nothing fails to compile, and the widget goes on building, painting and hit-testing; only the behaviour behind the dropped hook stops, at a call site nowhere near the .on_tap(..) that silenced it. A test that drives the hook on a bare widget cannot see this, which is why every hook is also driven through a builder method in the wrapper_forwarding_tests module below, and why missing_trait_methods is denied here: a method added to Widget must fail this impl’s lint before it can quietly fail a user’s app.

The methods appear in the order the trait declares them, so the two can be read side by side.

fn type_name(&self) -> &'static str

Forwarded so the name is the widget’s. The wrapper’s own name identifies the wrapper, which is never what a census bucket or an inspector row is asking about.

fn cacheable_layout(&self) -> bool

Forwarded because the opt-out exists to protect a widget whose layout_response is not idempotent. Answering the default here caches such a widget anyway, and a memoized non-idempotent measure is wrong in a way no layout assertion localizes.

fn wants_after_paint(&self) -> bool

The two paint hooks and their wants_* gates are forwarded as pairs: the walker consults the gate and skips the hook when it answers false, so a forwarded hook behind an unforwarded gate never runs, and the widget reads as having no hook at all rather than as having lost one.

fn wants_descendant_redirects(&self) -> bool

Gate and hook again — see Widget::wants_after_paint.

fn as_any_mut(&mut self) -> Option<&mut dyn Any>

Mutable counterpart of as_any, forwarded for the same reason it is.

A composing container that reads a child’s concrete type must see the same widget whether or not a builder method wrapped it. MenuList reads a MenuItem this way for its mnemonic, its type-ahead label, its radio group and its safe-triangle state; without this forward, MenuItem::new(..).context_menu(..) silently stops being a MenuItem to its parent — no error, just a row that lost all four.

fn hit_shape(&self, local_point: Point, bounds: Rect) -> bool

The hit-shape family, forwarded for the same reason as_any is: a widget must not stop being itself to the hit test because a builder method wrapped it.

A round control that answers hit_shape and hit_distance loses both the moment someone writes .on_tap(..) on it if these are not forwarded — and loses them silently, which is the worst way to lose a hit test. The node-level .hit_slop(..) / .no_hit_slop() overrides need no forwarding: they ride the HandlerSet onto the node.

fn preserves_children_on_rebuild(&self) -> bool

Forwarded because the default is the destructive answer. A container that keeps memoized panes across a rebuild loses them to a builder method otherwise, and the loss reads as content that vanishes on an unrelated state change rather than as a dropped forward.

fn tooltip_has_content(&self) -> bool

Forwarded so tooltip content that knows itself to be empty can still say so. The default is true, which shows an empty bubble instead.

fn declare_shortcuts(&self) -> Vec<Shortcut>

Forwarded because a declaration is how the registry and the rebinding UI learn a keystroke exists. Dropped, the shortcut is not overridden by anything — it is simply never registered.

fn take_handler_set(&mut self) -> Option<HandlerSet>

The one method here that is not a forward, deliberately: it exists so the arena can lift off the handlers the builder chain just attached, and those live on the wrapper, not on the widget. Forwarding it would hand the arena the wrapped widget’s set instead and the attached handlers would never reach the node — which is the whole point of the wrapper.

The call is the inherent WidgetWithHandlers::take_handler_set, not this one.

fn build(&mut self, ctx: &mut BuildContext<'_>) -> Vec<WidgetId>

Compose child widgets. Called once after the widget is placed in the arena, and again whenever the widget is marked for rebuild — a BindingLevel::Rebuild binding, rebuild_single_widget, or a density switch. A theme or locale switch does not rebuild: set_theme and set_locale mark layout + paint dirty and leave the built subtree standing, so anything derived from the theme or the locale must be read per pass or bound to a signal rather than captured here. Takes &mut self — store child IDs, signal handles, any state needed later. Returns the list of root child IDs (empty for leaf widgets).

fn layout_response( &self, proposal: SizeProposal, ctx: &LayoutContext<'_>, ) -> LayoutResponse

Respond to the parent’s size proposal with this widget’s wanted size, grow/shrink weights, and compression floor (see LayoutResponse).

fn place_children( &self, bounds: Rect, proposal: SizeProposal, children: &mut [WidgetPlacement], ctx: &LayoutContext<'_>, )

Position children within the allocated bounds.

fn paint(&self, bounds: Rect, canvas: &mut Canvas, ctx: &PaintContext<'_>)

Draw the widget’s visual representation.

fn after_paint(&self, view: &WidgetTreeView<'_>, ctx: &PaintContext<'_>)

Called once per frame after this widget’s subtree has finished painting. Receives a read-only view of the layout-resolved arena so a parent can read its descendants’ final bounds — e.g. TitleBar aggregates its drag region and control-button rects into a single HitRegions payload for the Windows backend’s WM_NCHITTEST.

fn wants_post_paint(&self) -> bool

Whether this widget wants its post_paint hook to fire each frame. Returning false (the default) saves a virtual call per widget per frame for the vast majority of widgets that don’t draw a foreground over their children.

fn post_paint(&self, bounds: Rect, canvas: &mut Canvas, ctx: &PaintContext<'_>)

Draw a foreground layer over this widget’s children.

fn accessibility(&self, builder: &mut AccessNodeBuilder)

Declare this widget’s accessibility identity.

fn culls_children(&self) -> bool

Whether this widget decides, on every layout pass, which of its children exist at all.

fn a11y_redirect_descendant( &self, self_id: WidgetId, descendant: WidgetId, ) -> Option<NodeId>

Optional redirection hook for AT-tree placement of a child.

fn accessible_title_hint(&self) -> Option<String>

Suggest an accessible title to an enclosing container that wraps this widget as content — typically a modal / dialog shell that wants to propagate the inner content’s visible title as the shell’s own accessible name.

fn accessible_title_node(&self) -> Option<WidgetId>

The widget that paints this one’s title, when it has one.

fn initial_focus_hint(&self) -> Option<WidgetId>

Optional hint that directs initial focus to a specific descendant when this widget is the root of a deferred-built modal surface.

fn context_menu_key_target(&self) -> Option<WidgetId>

Which descendant a keyboard request for a context menu should target.

fn children(&self) -> Vec<WidgetId>

Return the child widget IDs that this widget manages.

fn accessibility_children(&self) -> Option<Vec<WidgetId>>

Optional override for the child ORDER presented to assistive technology, when it must differ from the paint / z-order child order returned by children.

fn as_any(&self) -> Option<&dyn Any>

Downcast hook. Default implementation returns None; concrete widgets override with Some(self) when they want to expose their concrete type to test-level introspection or reflection. The trait already bounds on std::any::Any so concrete types satisfy the 'static requirement.

fn clips_children(&self) -> bool

Whether this widget clips its children to its bounds.

fn focus_reveal_rect(&self, bounds: Rect) -> Option<Rect>

The rectangle (in absolute tree coordinates) that best represents this widget when the framework reveals it into an ancestor scroll area on focus gain. Returning None (the default) reveals the widget’s whole bounds — correct for most controls.

fn accepts_child_hit(&self, child: WidgetId, point: Point) -> bool

Veto a hit on one of this widget’s direct children, per point.

fn hit_outset(&self, kind: PointerKind, tokens: &InputTokens) -> EdgeInsets

How far outside its own bounds this widget still absorbs a press, per edge, for the pointer that is asking.

fn hit_slop(&self, kind: PointerKind, tokens: &InputTokens) -> Option<HitSlop>

This widget’s own say in the miss-only slop pass, overriding the density default for its node.

fn hit_distance(&self, local_point: Point, bounds: Rect) -> Option<f32>

How far a missed press is from this widget’s actual silhouette, in the widget’s own bounds space.

fn target_regions(&self, bounds: Rect) -> Vec<TargetRegion>

The interactive sub-regions this widget paints inside its own single node — a scroll bar’s thumb, a slider’s knob, a header cell’s filter affordance.