Struct SceneView 

pub struct SceneView { /* private fields */ }

A pannable/zoomable viewport that renders a Scene’s items at scene coordinates and routes user input (scroll, pinch, drag, keyboard) back into the camera signals.

Construct with SceneView::new (single-view sugar: wraps a Scene in a fresh SceneModel) or SceneView::with_model (multi-view: several viewports share one SceneModel and each reconcile independently on every mutation). Install a heavyweight builder for delegated items via delegate_typed. Add to a WidgetTree like any other widget; gestures and camera animations are wired automatically during build.

See the module-level documentation for the full composition model and docs/teksilo-scene.md for an end-to-end guide.

Implementations

impl SceneView

pub fn new(scene: Scene) -> Self

Wrap a Scene in a viewport (single-view sugar). The scene is moved into a fresh SceneModel; for multi-view, build a SceneModel yourself and use with_model.

pub fn with_model(model: SceneModel) -> Self

Attach a viewport to a (possibly shared) SceneModel. Clone one model into several SceneView::with_model(model.clone()) to render the same scene in multiple panes, each with its own camera and delegate.

pub fn selection_mode(self, mode: SceneSelectionMode) -> Self

Configure selection behavior. Default SceneSelectionMode::None — click and marquee do nothing. Set to Single for at-most-one selection (click replaces) or Multi for multi-select with marquee box-select, Ctrl+click toggle, and Ctrl+drag additive marquee.

pub fn selection(&self) -> &SceneSelection

Borrow the SceneView’s SceneSelection. Use this from external code to bind to the selection signal, query selected ids, or call select_one / clear / replace programmatically.

pub fn delegate( self, f: impl Fn(&dyn Any, ItemId) -> Box<dyn Widget> + 'static, ) -> Self

Install the per-view heavyweight builder for Delegated items (those added via SceneModel::add_widget_item). The closure receives the item’s type-erased payload and its ItemId and returns the widget to materialise in this view’s arena. Prefer the typed delegate_typed wrapper.

pub fn delegate_typed<P: 'static>( self, f: impl Fn(&P, ItemId) -> Box<dyn Widget> + 'static, ) -> Self

Typed convenience over delegate: downcasts the payload to P before calling f. A downcast miss debug-asserts and skips the item (no widget is materialised) in release.

pub fn selection_model(self, selection: SceneSelection) -> Self

Replace this view’s selection with a (typically shared) one. Pass the same SceneSelection clone to several views so they select together; capture its selection_signal() in your delegate to highlight selected items reactively (no rebuild). Distinct from the selection() getter; supersedes any selection_mode set earlier.

pub fn model(&self) -> SceneModel

A clone of this view’s SceneModel handle — for handler closures that mutate the scene (every mutator is &self) or wire additional views.

pub fn model_ref(&self) -> &SceneModel

Borrow this view’s SceneModel handle.

pub fn flush_marquee_commit(&self) -> bool

Drain any pending marquee commit synchronously. Normal per-frame use never needs this — place_children consumes the pending commit at the start of every layout pass. Tests that drive on_drag without a follow-up layout call this to materialise the box-select result.

pub fn flush_pending_item_move(&mut self) -> bool

Drain any pending drag-to-move commit by translating the dragged item’s local_pos by the queued delta. Descendants follow automatically: their local_pos is unchanged but their scene_pos derives from the parent’s chain.

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

Disable user-driven navigation: scroll, pinch, and keyboard handlers are not registered, and the SceneView is not made focusable. Programmatic pan_to / zoom_to / fit_to_content still work — this gates only user input.

Use this for outer SceneViews in nested chart-style patterns: an outer locked SceneView holds axis chrome (TextItems reading the inner’s pan/zoom signals via view_transform_signal), an inner interactive SceneView holds the data and accepts pan/zoom from the user. Default: interactive (true).

pub fn nested_a11y(self, nested: bool) -> Self

Mark this SceneView as logically nested inside another SceneView. Affects only the AT walker — the inner SceneView reports Role::Region instead of the default Role::Pane, so screen readers don’t announce a redundant top-level landmark for what’s logically a sub- region. Pair with a11y_label to give the inner region a useful announce name.

Use case: chart-style nested scenes (outer SceneView holds axis chrome, inner SceneView holds data) — the inner one should announce as “Data area” or similar, not as another “Pane” sibling to the outer.

Default false. Apps explicitly set this when they know they’re nesting; the framework doesn’t introspect the widget tree to detect nesting automatically (deliberately kept declarative — the visual layout doesn’t always match logical nesting).

pub fn a11y_label(self, label: impl Into<LocalizedString>) -> Self

Set the AT label announced as this SceneView’s own name. Particularly useful for nested SceneViews via nested_a11y, where the inner region should have a domain-specific name (e.g. “Chart data area”). Default None — the SceneView has no explicit AT name.

pub fn is_nested(&self) -> bool

Whether the SceneView is currently marked as logically nested. Read-only accessor for tests / diagnostics.

pub fn a11y_bounds_space(self, space: A11yBoundsSpace) -> Self

Coordinate space for SceneItem bounds reported to AT. Default A11yBoundsSpace::Screen (view-projected, matches the framework’s standard widget behavior). Switch to A11yBoundsSpace::Scene for apps where AT users reason about scene topology rather than viewport position (CAD canvases, blueprint editors).

pub fn current_a11y_bounds_space(&self) -> A11yBoundsSpace

Read-only accessor for the configured a11y bounds space.

pub fn debug_overlay(self, overlay: DebugOverlay) -> Self

Configure visual debug overlays. Default: all flags off. Pass DebugOverlay::ALL to enable every overlay or construct a custom config:

let _view = SceneView::new(scene)
    .debug_overlay(DebugOverlay {
        item_bounds: true,
        viewport: true,
        ..Default::default()
    });

Intended for development only — overlay paint is cheap but not free; ship with the default (off) config.

pub fn current_debug_overlay(&self) -> DebugOverlay

Read-only accessor for the active debug overlay config.

pub fn focus_order<F>(self, callback: F) -> Self

where F: Fn(&Scene, FocusDirection, Option<ItemId>) -> Option<ItemId> + 'static,

Install a custom focus-order callback. When set, next_focus / previous_focus route through the closure instead of falling back to scene insertion order.

Apps wire this to a Tab / Shift+Tab handler in their root shortcut/action map. Typical implementations:

• Graph editor: walk outgoing-port connections from the current node, return the connected-node ItemId.
• Corkboard with Acts: walk a parallel BTreeMap<ActId, Vec<CardId>> declared by the app and Tab through cards in story order, not reading order.
• Timeline: sort items by start_time, return the next.

The callback receives the full Scene (read-only), the requested FocusDirection, and the currently focused item (None on the first Tab into the scene). Return None to signal “no next item” (the framework can then advance focus outside the SceneView).

Calling next_focus / previous_focus without a callback installed walks scene insertion order — adequate for simple scenes; replace as needed.

pub fn focus_in_direction( &self, direction: FocusDirection, current: Option<ItemId>, ) -> Option<ItemId>

Compute the next item the focus should advance to in the given direction. If a focus_order callback is installed, routes through it; otherwise falls back to scene insertion order — Forward returns the item after current (or the first if current is None), Backward returns the previous (or the last if current is None).

pub fn next_focus(&self, current: Option<ItemId>) -> Option<ItemId>

Convenience: forward-Tab traversal. See focus_in_direction.

pub fn previous_focus(&self, current: Option<ItemId>) -> Option<ItemId>

Convenience: backward-Tab (Shift+Tab) traversal. See focus_in_direction.

pub fn pan_x_signal(&self) -> Signal<f32>

Live Signal<f32> for the X pan offset. Use this from a parent scene (or any reactive consumer) to derive values that follow the SceneView’s pan — typically axis-label text in a chart-style outer SceneView.

pub fn pan_y_signal(&self) -> Signal<f32>

Live Signal<f32> for the Y pan offset.

pub fn zoom_signal(&self) -> Signal<f32>

Live Signal<f32> for the zoom factor.

pub fn rotation_signal(&self) -> Signal<f32>

Live Signal<f32> for the rotation in radians.

pub fn view_transform_signal(&self) -> Signal<Transform2D>

Live Signal<Transform2D> for the composed view transform (pan + zoom + rotation + bounds-origin). Folds in the bounds.origin contribution so reactive consumers see the exact transform the renderer applies. Updated whenever any of the underlying signals change. Use this when the consumer needs the full matrix (e.g. converting a screen point to scene coords from outside the SceneView).

pub fn a11y_mode(self, mode: A11yMode) -> Self

Override the A11yMode for this SceneView. Default is Cooperative — the visual scene layout drives AT emission unless explicitly overridden via Scene::set_a11y_parent. Switch to StrictlyParallel when your app’s AT shape is fundamentally different from its visual layout: items without a declared logical parent are then suppressed from the AT tree, and the app declares every node it wants AT users to reach.

pub fn a11y_off_screen_mode(self, mode: A11yOffScreenMode) -> Self

Override the off-screen visibility policy for the AT walker. Default: ViewportPlusN { n: 1 } — items inside the viewport plus a one-screen margin appear in the AT tree. AllItems for small scenes where AT users want a complete table of contents; ViewportOnly for very large scenes where listing off-screen content would overwhelm AT clients.

pub fn default_size(self, w: f32, h: f32) -> Self

Override the size used when the parent doesn’t propose one on an axis. Defaults to 800×600 logical pixels.

pub fn adopt_scene_size(self, on: bool) -> Self

When set, the view’s layout_response returns the scene’s scene_rect_extent as its own wanted size — the view sizes itself to its scene rather than to default_size. Pairs naturally with Scene::pan_axes / Scene::zoomable to embed bounded, non-navigable scenes inline (mini diagrams, fixed corkboards). Default false.

pub fn drag_mode(self, mode: impl Into<Prop<DragMode>>) -> Self

Configure how left-mouse drag-on-canvas behaves. Default DragMode::RubberBand — drag-on-an-item moves it (when IS_DRAGGABLE), drag-on-empty-space creates a marquee. DragMode::ScrollHandDrag makes left-drag pan the view unconditionally; DragMode::NoDrag disables the on-drag handler entirely.

Accepts a static DragMode — which sets the current value on the view’s internal signal — or a Signal<DragMode> (via impl Into<Prop<DragMode>>), which replaces the internal signal with the app-owned one so a toolbar can hold the same handle and toggle Hand vs Select vs NoDrag at runtime. To stop sharing, pass a fresh Signal::new(mode).

pub fn view_state( self, pan_x: Signal<f32>, pan_y: Signal<f32>, zoom: Signal<f32>, rotation: Signal<f32>, ) -> Self

Replace the view’s pan / zoom / rotation signals with app-owned ones.

The four view-state signals become the app’s to hold, share, and persist — so view state survives a rebuild-from-state (a wrapper that reconstructs the Scene + SceneView keeps the same signals and the viewport doesn’t jump back to the origin), a “Reset View” button can snap them, and two views could share one camera. The derived view_transform_signal is recomposed from the injected signals.

Must be called before the view is added to the tree (like the other builder methods) — build() reads view_transform_signal once.

pub fn initial_pan(self, x: f32, y: f32) -> Self

Seed the initial pan offset (logical pixels). The view keeps ownership of the signals; for app-owned signals use view_state.

pub fn initial_zoom(self, zoom: f32) -> Self

Seed the initial zoom factor (clamped to the active zoom range).

pub fn initial_rotation(self, radians: f32) -> Self

Seed the initial rotation (radians).

pub fn drag_mode_signal(&self) -> Signal<DragMode>

Reactive accessor for the drag mode. Useful for toolbars that need to read the current mode (e.g. to highlight the active tool button) and write to it.

pub fn background<F>(self, paint: F) -> Self

where F: Fn(&mut Canvas, &PaintContext<'_>, Rect) + 'static,

Install a closure painted before the items walk. The canvas already has the view-transform scope pushed, so the closure paints in scene coords. The Rect argument is the scene-coord visible region — useful for tiled backgrounds (graph-paper grids, ruled lines, dot grids) so the closure only emits geometry the user can actually see.

SceneView::new(scene).background(|canvas, _ctx, region| {
    // Draw a 50-unit grid covering only the visible region.
    let step = 50.0;
    let x0 = (region.x / step).floor() * step;
    let mut x = x0;
    while x < region.x + region.width {
        canvas.draw_line(/* ... */);
        x += step;
    }
})

pub fn foreground<F>(self, paint: F) -> Self

where F: Fn(&mut Canvas, &PaintContext<'_>, Rect) + 'static,

Install a closure painted after the items walk and the marquee, but before any debug overlay. Same coordinate conventions as background. Used for scene-coord chrome that should ride over content (rulers, snap-line indicators, drop hints).

pub fn magnetism(self, config: MagnetismConfig) -> Self

Enable magnetism on this view with the given MagnetismConfig.

Once installed, this view’s lightweight item drags snap their magnets onto compatible magnets on other items, magnet handles become grabbable for port-drag wires, the keyboard connect flow (the config’s connect key) is available while the view is focused, magnet markers paint, and each enabled magnet is emitted as a synthetic AT node. A view with no magnetism config ignores magnets entirely.

pub fn magnetism_enabled_signal(&self) -> Option<Signal<bool>>

The reactive enabled signal of the installed magnetism config, if any — for a toolbar to read or bind a magnetism on/off toggle.

pub fn invalidate_item_cache(&self, id: ItemId)

Drop the cached paint output for id. Apps that mutate item-internal state without going through a Scene mutator (e.g. a custom item whose paint depends on a private Signal<Color> that doesn’t drive local_bounds) call this to invalidate. The cache is otherwise dropped automatically on LocalBoundsChanged / OpacityChanged / Removed.

pub fn item_cache_len(&self) -> usize

Number of cached entries currently held. Diagnostic / test hook — apps shouldn’t normally need this.

pub fn min_zoom(self, v: f32) -> Self

Minimum zoom factor (default 0.1×). Applied as a clamp to all programmatic and gesture-driven zoom changes via the view-level zoom_range_override. Shim — updates the lower bound of the override range. The effective clamp is the intersection of Scene-level Scene::set_zoom_range and this override (tightening-only — neither side can loosen).

pub fn max_zoom(self, v: f32) -> Self

Maximum zoom factor (default 10×). Shim — updates the upper bound of the override range. See min_zoom.

pub fn zoom_range_override(self, range: Option<RangeInclusive<f32>>) -> Self

Replace the view-level zoom-range override wholesale. None clears the override so this view imposes no zoom clamp of its own (Scene-level constraints still apply). Tightening rule: the effective clamp is the intersection with Scene::current_zoom_range() — neither can loosen.

pub fn zoom_range_override_signal(&self) -> Signal<Option<RangeInclusive<f32>>>

Reactive accessor for the view-level zoom-range override. Use this to mutate the override at runtime (e.g. from a toolbar). Mutations take effect on the next gesture.

pub fn pan_bounds_override(self, bounds: Option<Rect>) -> Self

View-level tightening override on pan bounds, in scene coords. The effective clamp at gesture-time is the rect intersection with Scene::current_pan_bounds() — view overrides cannot loosen what the Scene declares. None (default) means no view-side clamp.

pub fn pan_bounds_override_signal(&self) -> Signal<Option<Rect>>

Reactive accessor for the view-level pan-bounds override. Use this to mutate the override at runtime (e.g. dynamically shrinking the navigable area). Mutations take effect on the next gesture.

pub fn line_height(self, px: f32) -> Self

Logical pixels of pan applied per scroll-wheel line notch. Defaults to 16 px (matches ScrollArea).

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

Whether a wheel the scene can’t absorb (already clamped at its pan_bounds) chains to an ancestor scrollable ([OverscrollBehavior::Chain], the default — matches the widget scrollables) or is contained ([OverscrollBehavior::Contain]). Use Contain for a tightly-bounded scene embedded in a scroll view that should never steal the scene’s wheel.

pub fn with_scroll_bars(self) -> SceneScrollView

Wrap this view in a SceneScrollView, adding draggable scroll bars with the widget-tier ScrollArea’s options (mode, per-axis policy, thickness). The bars track the camera and drive panning; native wheel / drag panning — and its smoothing — keeps working.

Configure the result with the SceneScrollView builder methods:

let scrollable = SceneView::new(Scene::new())
    .with_scroll_bars()
    .scroll_bar_mode(ScrollBarMode::Overlay)
    .vertical_policy(ScrollBarPolicy::AsNeeded);

impl SceneView

pub fn scene(&self) -> Ref<'_, Scene>

Read access to the underlying scene, as a borrow guard.

Prefer the cloneable model handle for multi-view wiring and scene mutation (its methods are &self); this guard is the single-view escape hatch for ad-hoc reads.

pub fn scene_mut(&mut self) -> RefMut<'_, Scene>

Mutable access to the underlying scene, as a borrow guard.

Single-view escape hatch. For multi-view, mutate through the shared SceneModel handle (model) — every mutator is &self, so a handler holding a clone can drive the scene directly (no with_widget_mut needed) and all views reconcile:

let model = view.model();          // cheap handle clone
model.add_widget_item(card_data, rect);   // every view rebuilds it

The view self-reconciles on every mutation: add_widget_item / add_item materialise on the next rebuild, remove destroys the orphaned arena widget and cleans its maps, set_payload rebuilds an item’s widget, and both the visual tree and the separate AccessKit tree re-walk (geometry, reparents, and pure-a11y mutations all reach assistive tech — build() requests an AT re-walk, since a relayout no longer does so on its own).

pub fn widget_id_for(&self, id: ItemId) -> Option<WidgetId>

The WidgetId an item was materialised as, if known.

pub fn pan(&self) -> Vec2

Current pan offset (logical pixels).

pub fn zoom(&self) -> f32

Current zoom factor.

pub fn rotation(&self) -> f32

Current rotation in radians.

pub fn pan_x_animation_target(&self) -> Option<f32>

In-flight animation target for the X pan signal, or None if the signal is at rest. Useful for tests that want to observe a tween before it lands without spinning the scheduler.

pub fn pan_y_animation_target(&self) -> Option<f32>

In-flight animation target for the Y pan signal.

pub fn zoom_animation_target(&self) -> Option<f32>

In-flight animation target for the zoom signal.

pub fn view_transform(&self) -> Transform2D

The composed view transform the render walker has on its stack while painting this view’s subtree. Includes the bounds.origin offset captured during the last place_children call, so this is the exact transform applied to scene-coord points by the renderer.

pub fn map_to_scene(&self, view_pt: Point) -> Point

Project a point in view space (screen-pixel coords — the same frame pointer events arrive in) into scene coordinates. Inverse of map_from_scene. Returns the scene origin when the view transform is degenerate (e.g. zoom = 0).

pub fn map_from_scene(&self, scene_pt: Point) -> Point

Project a point in scene coords to view space (screen pixels). Inverse of map_to_scene.

pub fn map_rect_to_scene(&self, view_rect: Rect) -> Rect

Project a rectangle in view space into scene coordinates. Returns the AABB of the four projected corners under rotation. Empty rect when the view transform is degenerate.

pub fn map_rect_from_scene(&self, scene_rect: Rect) -> Rect

Project a rectangle in scene coords into view space.

pub fn viewport_in_scene_signal(&self) -> Signal<Rect>

Reactive signal of the visible scene region — the portion of scene space currently inside the SceneView’s viewport. Fires whenever pan / zoom / rotation / bounds_origin / viewport-size changes.

Use to drive a minimap viewport indicator, lazy-load only the visible scene region, or implement “scroll into view” guards. The value is the AABB of the viewport rectangle projected through view_transform.inverse().

pub fn viewport_size_signal(&self) -> Signal<Size>

Reactive signal of the SceneView’s resolved viewport size. Fires whenever layout_response resolves a new size that differs from the previous.

pub fn pan_to(&self, target: Vec2, duration: Duration)

Animate pan to target over duration. Bounded by Easing::EaseOut. Honours prefers-reduced-motion only indirectly: the scheduler pauses animation on window-inactive and the test seam allows snapping. For an explicit snap, call SceneView::set_pan.

pub fn set_pan(&self, target: Vec2)

Snap pan to target without animation. Gated by the scene’s PanAxes policy.

pub fn zoom_to(&self, target: f32, duration: Duration)

Animate zoom to target over duration, clamped to [min_zoom, max_zoom]. No-op when the scene declares Scene::zoomable(false).

pub fn set_zoom(&self, target: f32)

Snap zoom to target without animation, clamped. No-op when the scene declares zoom disabled.

pub fn ensure_visible(&self, scene_rect: Rect, margin: f32)

Pan (without changing zoom) so scene_rect.expand(margin) fits inside the current visible scene region. If the expanded target rect already fits, this is a no-op.

Pairs with focus traversal: when an off-viewport item gains focus, the SceneView’s default focus traversal calls this automatically. Apps wanting to scroll a specific area into view (e.g. on search-result selection) call it directly.

Pan is gated by Scene::pan_axes: if a scene declares PanAxes::None, this is a no-op; if it declares a single axis, only that axis pans. Items can’t be scrolled into view if the policy doesn’t permit panning toward them.

pub fn rotate_to(&self, target_radians: f32, duration: Duration)

Animate rotation to target over duration (radians).

pub fn set_rotation(&self, target_radians: f32)

Snap rotation to target without animation.

pub fn state(&self) -> SceneViewState

Snapshot the current pan / zoom / rotation as a SceneViewState. Designed for persistence: store the snapshot in your settings layer on app exit, restore it via restore_state on next launch.

The snapshot reflects the current signal values — if a pan/zoom animation is in flight, the captured values are the in-flight tween position, not the eventual target. Apps that want to capture the target should query pan_x_animation_target / friends manually.

pub fn restore_state(&self, state: SceneViewState)

Restore a previously captured SceneViewState. Snaps each signal to the saved value (no animation — pan/zoom/rotation jump to the persisted state immediately). Zoom is clamped to [min_zoom, max_zoom].

pub fn viewport_size(&self) -> Size

Latest viewport size observed during layout. Useful for imperative fit_* calls.

pub fn scene_content_bounds(&self) -> Option<Rect>

Compute the bounding rectangle (in scene coords) that encloses every item in the scene. Returns None for an empty scene.

pub fn fit_to_content(&self)

Animate pan + zoom so the scene’s content bounding box fits the current viewport with a small margin. No-op for an empty scene. Resets rotation to 0.

pub fn fit_to_items(&self, ids: &[ItemId])

Animate pan + zoom so the union of the given items’ bounds fits the current viewport. Ids not currently in the scene are skipped silently. No-op if ids is empty or all ids are stale. Resets rotation to 0.

Use this for “zoom to selection” / “frame this subset” UX.

pub fn fit_to_selection(&self)

Animate pan + zoom so the bounds of the currently selected items fit the viewport. No-op when nothing is selected. Convenience for the common “F to focus selection” hotkey.

Trait Implementations

impl Debug for SceneView

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

Formats the value using the given formatter.

impl Widget for SceneView

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

Whether this widget clips its children to its bounds.

fn preserves_children_on_rebuild(&self) -> bool

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

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 accessibility(&self, builder: &mut AccessNodeBuilder)

Declare this widget’s accessibility identity.

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 as_any_mut(&mut self) -> Option<&mut dyn Any>

Mutable counterpart of as_any. Default returns None; widgets that want to expose mutable state to tests (e.g. so a test can mutate a Scene inside a SceneView post-layout) override with Some(self). Should follow the same opt-in pattern as as_any: only widgets that opt into & introspection should opt into &mut.

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

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).