Crate teksilo_scene

Expand description

teksilo-scene — pannable / zoomable scene viewport for Teksilo.

A sub-toolkit for scene-based applications — story corkboards, mind maps, node-graph editors, timeline views — where content is free-positioned at scene coordinates instead of placed by a layout algorithm. Two tiers of content coexist under one view transform:

Heavyweight tier: any Widget (Button, TextInput, Panel, composite components) at a parent-relative position, fully interactive and accessible, with full event / focus / animation / a11y machinery intact.
Lightweight tier: SceneItems (paths, rects, images, custom paint) without arena overhead — for the “background furniture” of a scene where thousands of items render cheaply.

The crate is built on top of teksilo-core’s per-node set_transform scope (which composes through hit-test, paint, and a11y) and the platform’s pinch / scroll / animated-Signal<f32> infrastructure — so OS gestures, reduced-motion snapping, and the four-gate idle scheduler fall out for free.

See docs/teksilo-scene.md for the user-facing reference and docs/teksilo-scene-a11y.md for the accessibility-shaping API.

§Quick start

use teksilo_scene::{ItemId, RectItem, Scene, SceneView};
use teksilo_canvas::{Point, Rect};

let mut scene = Scene::new();
let _w: ItemId = scene.add_widget(
    my_card_widget(),
    Rect::new(0.0, 0.0, 200.0, 120.0),
);
scene.add_item(
    RectItem::new(Rect::new(0.0, 0.0, 50.0, 50.0)).fill(teksilo_tokens::Color::RED),
    Point::new(220.0, 0.0),
);
let view = SceneView::new(scene);
tree.add(view);

Structs§

A11yCategory: App-defined category tag for AT rotor / quick-nav navigation. Surfaced to AT clients that support categorized navigation (VoiceOver rotor on macOS, NVDA quick-nav). Apps coin their own tag values like "node", "connector", "comment".
A11yGroup: A logical AT group. Pure structure — no visual counterpart, no hit-test, no paint. Declares AT-shape that diverges from visual scene layout (Acts containing Scene cards, Subgraphs containing Nodes, Layers containing Components).
A11yGroupBuilder: Builder for an A11yGroup. Returned by A11yGroup::builder; consumed by Scene::add_a11y_group.
A11yGroupId: Opaque identifier for a logical AT group declared via Scene::add_a11y_group. Stable across the lifetime of the process; safe to hash, compare, store.
DebugOverlay: Visual debug overlays painted on top of normal scene rendering.
GridHashIndex: Uniform grid spatial hash. Each item is bucketed into every cell its AABB overlaps; queries union all items from the cells the query rect overlaps. Items whose AABB would span more than MAX_CELLS_PER_ITEM cells are NOT bucketed — see oversized below and the module doc’s “Oversized items” section.
GroupItem: A group container with optional fill / stroke / inline label, in local item coordinates.
ImageItem: A raster image in a local-coord rectangle.
ItemFlags: A bitset of per-item behavior flags.
ItemId: Opaque identifier for a SceneItem inside a Scene.
Magnet: A magnetism anchor attached to a scene item.
MagnetConnection: A formed connection between two magnets, delivered to the consumer’s on_connect handler on release (mouse) or confirm (keyboard).
MagnetFeedback: Everything the magnetism feedback renderer needs for one frame, in scene coordinates (the canvas is already in the view-transform scope). The built-in renderer draws markers plus a connector; a custom MagnetismConfig::feedback closure receives the same data.
MagnetId: Opaque identifier for a Magnet inside a Scene.
MagnetMarker: One magnet’s render data, handed to the feedback renderer.
MagnetRef: An owned, borrow-free snapshot of one magnet, handed to the accept/reject predicate and carried in a MagnetConnection.
MagnetSnap: The chosen snap when a dragged item’s magnet aligns onto another item’s magnet. Returned by Scene::compute_item_snap.
MagnetismConfig: Per-view magnetism configuration, installed via SceneView::magnetism.
PathItem: An arbitrary vector path with optional fill and stroke, in local item coordinates.
RectItem: A rectangle with optional fill and stroke, in local item coordinates.
Scene: The data model behind a SceneView: a flat list of entries in a parent-relative scene-graph plus a SpatialIndex for rectangular queries.
SceneConstraints: Reactive interaction-policy bundle owned by Scene. Apps configure pan/zoom behaviour by writing to these signals; gesture closures in SceneView read them live, so runtime mode switches (e.g. a toolbar toggling pan locks) take effect on the next event without rebuilding the view.
SceneItemA11yContext: Context handed to SceneItem::accessibility.
SceneItemHandlerSet: Per-item event closures + cursor + tooltip + drop acceptance.
SceneItemPaintContext: Context handed to SceneItem::paint.
SceneListAdapter: Keeps a set of lightweight SceneItems in sync with a teksilo_data::ListModel<T> / ListDataSource<Item = T>.
SceneMinimap: A small thumbnail rendering of a Scene’s content, with the live viewport rectangle highlighted.
SceneModel: A shared, cloneable handle to a Scene.
SceneScrollView: A SceneView with draggable scroll bars.
SceneSelection: Reactive selection state for a Scene.
SceneTapEvent: Click-style gesture envelope for scene items. Mirrors the widget-tier [teksilo_core::gesture::TapEvent] but with the position in scene coordinates instead of widget-local. Used by the tap / double-tap / triple-tap / long-press / context-menu handlers on SceneItemHandlerSet.
SceneView: 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.
SceneViewState: Snapshot of a SceneView’s view transform: pan offset, zoom factor, and rotation in radians. Use SceneView::state to capture the current values; SceneView::restore_state to apply a saved snapshot.
TextItem: Text in a local-coord rectangle, with optional alignment and rotation.

Enums§

A11yBoundsSpace: Coordinate space the AT walker reports SceneItem bounds in.
A11yMode: AT-emission strategy for SceneView. Decides whether items / widgets that have not been placed in the app-declared logical tree appear in the AT tree by default, or are suppressed.
A11yNode: Address of a node in the parallel logical AT tree. Lets apps uniformly target scene entries, virtual groups, and ad-hoc widgets when declaring relationships, parents, or rotor categories.
A11yOffScreenMode: Off-screen visibility policy for the AT walker. Decides which scene items get emitted as synthetic AT nodes per AT-rebuild.
A11yRelation: AT relationship kind, applied via Scene::add_a11y_relation. Maps to AccessKit’s relationship arrays.
AccessSubtreeMode: How the AT walker treats descendants of an item.
CacheMode: Per-item paint caching strategy.
DragMode: What a SceneView’s on-canvas pointer drag does in empty space.
FocusDirection: Direction passed to a SceneView::focus_order callback when the app wants to override the default Tab cycle.
ItemChange: A change to an item’s state, fired through Scene::item_change_signal for every mutation. Apps observe to wire snap-to-grid, validation, side effects, etc. The model is “fire after the change has been applied” — by the time the observer sees the event, the Scene already reflects it.
MagnetRole: The direction a magnet faces in a connection.
MagnetVerdict: The result of running the accept/reject predicate on a candidate magnet pair. “Both payloads in, reject or accept-with-payload out.”
MagnetVisualState: The visual state of a magnet as the feedback renderer sees it.
MarkerVisibility: When the SceneView paints magnet markers.
PanAxes: Which axes a SceneView is allowed to pan along. Set on the Scene (not the View) because a given scene model often makes sense at one orientation only — a horizontal timeline, a vertical timeline, a fixed-extent diagram. All views of the same scene inherit the constraint.
SceneLayer: Which paint band a lightweight SceneItem sits in, relative to the heavyweight widget tier.
SceneSelectionMode: Selection-mode discriminator. Mirrors teksilo_data::SelectionMode.
ScrollBarMode: How the scroll bar is presented relative to the viewport content.
ScrollBarPolicy: Controls when the scroll bar appears for a given axis.
TextAlign: Horizontal alignment of a TextItem within its local_bounds.

Traits§

SceneItem: A lightweight, paint-only scene-graph item.
SpatialIndex: A spatial index over ItemIds keyed by axis-aligned scene rectangles. Used by Scene for items_in_rect queries and by SceneView for viewport culling.

Functions§

pulse_once: One-shot ease-out tween from the signal’s current value to target over duration. The standard “fire on click, dismiss” / “flash a highlight” pattern. The signal must already be registered with register_animated_item_signal (or directly via ctx.register_animated_signal) for the tween to participate in idle gating.
register_animated_item_signal: Register an item-owned Signal<f32> with the SceneView’s animation scheduler. Call this from inside SceneItem::register_bindings for every animated signal the item exposes.