ItemId

The SceneItem trait and its supporting context types.

Lightweight items live in a Scene without arena overhead. Each carries its own bounds (in local item coordinates, origin at the item's anchor) and paints itself via SceneView's paint walk. Apps implement this trait directly for custom items; built-ins live in crate::items.

Coordinate model

An item is positioned in its parent's coordinate space by a local_pos: Point plus an optional transform: Transform2D (rotation/scale, applied around the local origin). The Scene composes those per-item transforms up the parent chain to produce a scene_transform (local→scene). Hit-test inverse-transforms a scene-coord point into local coords before calling SceneItem::shape_contains; paint pushes the scene transform onto the canvas before calling SceneItem::paint.

When to use

Implement SceneItem when you need a lightweight, paint-only decoration or connector that isn't interactive enough to warrant a full widget (no keyboard focus, no complex event handling). For anything that needs focus, animations, drag-and-drop, or AT by default, prefer the heavyweight tier (Scene::add_widget).

Custom item example

use teksilo_scene::{SceneItem, SceneItemPaintContext};
use teksilo_canvas::{Canvas, Point, Rect};
use teksilo_tokens::Color;

#[derive(Debug)]
struct DotItem { bounds: Rect }

impl SceneItem for DotItem {
    fn local_bounds(&self) -> Rect { self.bounds }
    fn set_local_bounds(&mut self, b: Rect) { self.bounds = b; }
    fn paint(&self, canvas: &mut Canvas, _ctx: &SceneItemPaintContext<'_>) {
        canvas.fill_rect(self.bounds, Color::RED);
    }
}

Builder methods at a glance

as_u64

API reference

📖 Full rustdoc API for this module

pub struct ItemId

Opaque identifier for a SceneItem inside a Scene.

Globally unique within a process, generated by ItemId::next. ItemIds are stable across the item's lifetime in a scene; removing an item retires its id permanently (Scene::remove does not reuse).

#![allow(unused)]
fn main() {
pub struct ItemId(pub(crate) u64);
}

Methods

pub fn as_u64(self) -> u64

Raw numeric value, used by AccessKit's synthetic-NodeId derivation.

pub struct SceneItemPaintContext

Context handed to SceneItem::paint.

view_transform is the composed pan/zoom/rotation of the SceneView that's painting this item; the canvas already has the item's scene_transform pushed, so paint methods work in local coords without further matrix math.

theme, window_active, and enabled mirror the widget-tier PaintContext so lightweight items can resolve theme-aware colours exactly like widgets do — call some_color_prop.resolve(ctx.theme, ctx.enabled) in paint. theme is already the fully-projected theme for this pass (the render walker swaps in the inactive-window / high-contrast variant before handing it here), so items never call Theme::for_inactive_window themselves; reading ctx.theme grants automatic window-blur desaturation of accent roles.

#![allow(unused)]
fn main() {
pub struct SceneItemPaintContext<'a> { /* fields */ }
}

Methods

pub fn new( view_transform: Transform2D, dirty_scene_rect: Option<Rect>, theme: &'a Theme, ) -> Self

Construct a paint context with the given view transform, optional dirty region, and the active theme. text_scale defaults to 1.0, window_active and enabled to true; use the with_* builders to carry the accessibility scale, window-active state, and per-item enabled state from the widget paint pass.

pub fn with_text_scale(mut self, text_scale: f32) -> Self

Set the global accessibility text-scale factor carried to opted-in items.

pub fn with_window_active(mut self, window_active: bool) -> Self

Set whether the host window is currently active (focused and unoccluded).

pub fn with_enabled(mut self, enabled: bool) -> Self

Set the effective enabled state of the item being painted.

pub struct SceneItemA11yContext

Context handed to SceneItem::accessibility.

Carries the item's screen-projected bounds (so items wanting to emit AT-relative coordinates can read them) and its ItemId so implementations can derive synthetic AT NodeIds for sub-elements.

#![allow(unused)]
fn main() {
pub struct SceneItemA11yContext { /* fields */ }
}