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 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 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 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_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_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>

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 build(&mut self, ctx: &mut BuildContext<'_>) -> Vec<WidgetId>

Compose child widgets. Called once after the widget is placed in the arena, and again on environment change (theme switch, locale switch). 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 accessibility(&self, builder: &mut AccessNodeBuilder)

Declare this widget’s accessibility identity.

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

Return the child widget IDs that this widget manages.

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 take_handler_set(&mut self) -> Option<HandlerSet>

Extract attached handler set from a WidgetWithHandlers wrapper. Called during arena insertion to transfer handlers to the WidgetNode. Default: returns None (no attached handlers).

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

Concrete type name of this widget (e.g. "teksilo_widgets::button::Button"). The default implementation resolves at the impl site via std::any::type_name::<Self>(), so calls through &dyn Widget correctly dispatch to the monomorphized fn for the concrete type — getting the concrete name through the vtable without per-impl boilerplate.

fn cacheable_layout(&self) -> bool

Whether this widget’s layout_response may be memoized by the per-pass layout cache. Defaults to true.

fn wants_after_paint(&self) -> bool

Whether this widget wants its after_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 aggregate descendant geometry.

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 wants_descendant_redirects(&self) -> bool

Whether this widget wants the AT walker to consult its a11y_redirect_descendant hook for every descendant during AT tree emission, not just its direct arena children.

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 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 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 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 hit_shape(&self, _local_point: Point, _bounds: Rect) -> bool

Whether the point lies inside this widget’s actual shape, not just its rectangular bounds. Consulted by hit-testing right after the bounds check: returning false for a point that is inside the bounding box makes the widget transparent to the click there, so it falls through to whatever sibling is painted underneath (the same machinery as a fully pass-through node, but shape-aware).

fn preserves_children_on_rebuild(&self) -> bool

How rebuild_single_widget treats this widget’s existing children when re-running its build().

fn tooltip_has_content(&self) -> bool

Whether this widget, used as tooltip content, currently has anything worth showing.

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

Declare the rebindable keyboard shortcuts this widget exposes, without installing handlers. The framework calls this at arena insertion time (before build()) and at certain lazy boundaries (e.g. Switcher walks declarations on its not-yet-mounted Pending slots), so settings UIs and the ShortcutRegistry see the keystrokes the moment the owning container mounts — even if build() hasn’t run.