Trait SceneItem 

pub trait SceneItem: Debug + 'static {
    // Required methods
    fn local_bounds(&self) -> Rect;
    fn set_local_bounds(&mut self, bounds: Rect);
    fn paint(&self, canvas: &mut Canvas, ctx: &SceneItemPaintContext<'_>);

    // Provided methods
    fn set_fill(&mut self, fill: Option<ColorProp>) -> bool { ... }
    fn set_stroke(&mut self, stroke: Option<(ColorProp, StrokeStyle)>) -> bool { ... }
    fn shape_contains(&self, local_pt: Point) -> bool { ... }
    fn clone_shape_test(&self) -> Box<dyn Fn(Point, f32) -> bool + 'static> { ... }
    fn thumbnail_color(&self) -> Color { ... }
    fn initial_flags(&self) -> ItemFlags { ... }
    fn label(&self) -> Option<String> { ... }
    fn access_subtree_mode(&self) -> AccessSubtreeMode { ... }
    fn cache_mode(&self) -> CacheMode { ... }
    fn register_bindings(&self, _ctx: &mut BuildContext<'_>, _view_id: WidgetId) { ... }
    fn accessibility(
        &self,
        builder: &mut AccessNodeBuilder,
        _ctx: &SceneItemA11yContext,
    ) { ... }
}

A lightweight, paint-only scene-graph item.

Implementations carry their own bounds (in local coords, anchored at the origin) and provide a paint method that draws into a [Canvas]. The Scene takes care of positioning, transform-chain composition, hit-test, accessibility, and repaint scheduling.

Required methods

• SceneItem::local_bounds — AABB in local item coords.
• SceneItem::set_local_bounds — write back the bounds field when the Scene mutates it.
• SceneItem::paint — draw the item into the canvas. The canvas already has the item’s scene_transform pushed, so coordinates are in local item space.

Optional methods

• SceneItem::shape_contains — exact-shape hit-test in local coords. Default is AABB containment.
• SceneItem::label — human-readable label for AT and debug.
• SceneItem::register_bindings — bind reactive signals to the SceneView’s repaint machinery.
• SceneItem::accessibility — populate the AccessKit node.

Required Methods

fn local_bounds(&self) -> Rect

AABB in local item coordinates (origin at the item’s anchor). The Scene composes this with the item’s scene_transform to compute its scene-space AABB for the spatial index.

fn set_local_bounds(&mut self, bounds: Rect)

Write back new bounds. Called by Scene::set_local_bounds when the bounds change. Implementations update their stored bounds field; geometry-bearing items (e.g. crate::PathItem) must keep their geometry consistent with the new bounds.

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

Paint the item into the canvas. The canvas already has this item’s scene_transform (parent chain × view) pushed, so coordinates are in local item space — (0, 0) is the item’s anchor.

ctx carries the active [Theme], window_active, and per-item enabled state, so colour-bearing items resolve their [ColorProp] fills/strokes with prop.resolve(ctx.theme, ctx.enabled).

Provided Methods

fn set_fill(&mut self, fill: Option<ColorProp>) -> bool

Replace the primary fill colour, returning true if this item kind has a fill slot that accepted the change. Backs SceneModel::set_item_fill / clear_item_fill. Rectangles, paths, and groups set their fill; text items map it onto their foreground colour (so a None is rejected — text always has a colour); image items have no fill and return false. Default: no-op.

fn set_stroke(&mut self, stroke: Option<(ColorProp, StrokeStyle)>) -> bool

Replace the stroke (colour + [StrokeStyle]), returning true if this item kind has a stroke slot that accepted the change. Backs SceneModel::set_item_stroke / clear_item_stroke. Rectangles, paths, and groups accept it; text and image items return false. Default: no-op.

fn shape_contains(&self, local_pt: Point) -> bool

Exact-shape hit-test in local coordinates. Default: AABB containment via SceneItem::local_bounds. Path-based items override this to do per-segment distance checks so users can click along a stroke even when the AABB is huge.

fn clone_shape_test(&self) -> Box<dyn Fn(Point, f32) -> bool + 'static>

Produce a stand-alone Fn(Point, f32) -> bool that closes over whatever state this item needs to answer shape_contains without retaining a borrow on self. The SceneView snapshots one of these for every item at layout time and consults it on every pointer event — direct calls to shape_contains(&self, ...) can’t be cached because &dyn SceneItem is not Clone.

The closure’s second argument is the view scale (zoom) active when the pointer event arrives — passed at call time (not baked at snapshot time) because zoom changes without rebuilding the snapshot. Most items ignore it; stroke-distance hit-testing (PathItem) uses it so a cosmetic stroke (constant device-pixel width) keeps a proportionate hit band in scene coordinates at any zoom.

Default: AABB containment of local_bounds(). Items with a non-AABB shape (notably crate::items::PathItem for stroke-only paths and crate::items::GroupItem for the logical-only / pass-through case) override this so dispatch hits along the actual painted geometry. Returning the default for an item with a custom shape_contains is a silent dispatch bug — the eager Scene::item_at path still calls shape_contains correctly, but pointer-event routing goes through the snapshot.

fn thumbnail_color(&self) -> Color

Dominant color to draw as the item’s representation in minimap-style thumbnails. Default: an opaque mid-grey, which gives a recognisable but neutral marker for any item. Built-in items override: RectItem returns its fill, PathItem returns stroke or fill, ImageItem returns the image’s dominant tint placeholder.

Consumed by Scene::item_thumbnails — the typical minimap input. Apps with non-standard items can override on their own SceneItem impls.

fn initial_flags(&self) -> ItemFlags

The flags this item should carry into the Scene at insert time. Default: ItemFlags::default() — visible, enabled, selectable. Built-ins read their accumulated builder state (e.g. .draggable(true) flips IS_DRAGGABLE); custom items override this to opt into hover acceptance, focus, clipping, or IGNORES_TRANSFORMATIONS.

Read once by Scene::add_item and stored on the entry. Subsequent flag changes go through Scene::set_flag / Scene::set_flags.

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

Optional human-readable label, surfaced in debug introspection and used by the default SceneItem::accessibility impl as the AT name when an item author hasn’t overridden it via the per-item .access_label(...) chain.

fn access_subtree_mode(&self) -> AccessSubtreeMode

AT subtree treatment for descendants.

Inherit (default) — descendants emit AT nodes normally. Exclude — descendants are pruned from the AT tree. Merge — descendants’ labels concatenate into this item’s AT name and they’re pruned from individual emission, so the subtree reads as a single AT element. Built-ins read this from their per-item .access_subtree(...) chain.

fn cache_mode(&self) -> CacheMode

Per-item paint caching strategy. Default CacheMode::None: the item’s paint runs every frame.

Returning CacheMode::ItemCoordinate asks the SceneView to record the item’s paint output in local item coordinates as a RenderFrame and replay it on subsequent frames instead of re-running paint. Only suitable for items whose visual depends solely on data the Scene knows about (geometry, flags, opacity) — not on arbitrary signal state outside local_bounds. The cache for an id is evicted on ItemChange::LocalBoundsChanged for that id.

fn register_bindings(&self, _ctx: &mut BuildContext<'_>, _view_id: WidgetId)

Register reactive bindings the item depends on. Called once per SceneView::build for every item in the scene, with the SceneView’s WidgetId as view_id. Items with signal-bound state bind their signals here at the appropriate BindingLevel.

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

Populate the AccessKit node for this item. Default: role [Role::GraphicsObject] plus the SceneItem::label as the AT name if set. The per-item .access_* builder chain layers overrides on top of whatever this method writes.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl SceneItem for GroupItem

impl SceneItem for ImageItem

impl SceneItem for PathItem

impl SceneItem for RectItem

impl SceneItem for TextItem