Trait Widget

pub trait Widget<A>: 'static {
    // Required methods
    fn debug_name(&self) -> &'static str;
    fn layout(
        &self,
        engine: &mut LayoutEngine<'_, A>,
        ctx: &mut LayoutCtx<'_>,
        children: &mut [LayoutChild],
        constraints: Constraints,
    ) -> LayoutResult;
    fn paint(&self, ctx: &mut PaintCtx<'_>, bounds: Rect, layout: &LayoutResult);

    // Provided methods
    fn layout_dependency_revision(&self) -> u64 { ... }
    fn layout_committed(
        &self,
        _ctx: &mut LayoutCtx<'_>,
        _bounds: Rect,
        _layout: &LayoutResult,
    ) { ... }
    fn paint_overlay(
        &self,
        _ctx: &mut PaintCtx<'_>,
        _bounds: Rect,
        _layout: &LayoutResult,
    ) { ... }
    fn event(
        &self,
        _ctx: &mut EventCtx<A>,
        _event: &Event,
        _bounds: Rect,
        _layout: &LayoutResult,
    ) { ... }
    fn focus_policy(&self) -> FocusPolicy { ... }
    fn activation_policy(&self) -> ActivationPolicy { ... }
    fn input_role(&self) -> InputRole { ... }
    fn hover_cursor_role(&self) -> HoverCursorRole { ... }
    fn hover_cursor_role_at(
        &self,
        _bounds: Rect,
        _layout: &LayoutResult,
        _pos: Point,
    ) -> HoverCursorRole { ... }
    fn ime_cursor_rect(
        &self,
        _bounds: Rect,
        _layout: &LayoutResult,
    ) -> Option<Rect> { ... }
}

Widget contract for the View tree (separate from layout::Widget retained nodes).

Callbacks run synchronously on the UI thread and panics propagate. Layout and paint use logical pixels. Implementations must not retain borrowed engines, contexts, child slices, events, bounds, or results. Reactive reads made by successful layout and paint callbacks are observed automatically; event-callback reads are passive unless the state also has an owner-provided invalidator. Reconciliation preserves a mount for a fresh payload of the same concrete widget type and starts a new mount generation when that type changes.

Examples

use ailloli_ui_core::{Constraints, Rect};
use ailloli_ui_runtime::component::Widget;
use ailloli_ui_runtime::layout::{LayoutChild, LayoutCtx, LayoutEngine, LayoutResult};
use ailloli_ui_runtime::scene::PaintCtx;
struct Spacer;
impl Widget<()> for Spacer {
    fn debug_name(&self) -> &'static str { "Spacer" }
    fn layout(&self, _: &mut LayoutEngine<'_, ()>, _: &mut LayoutCtx<'_>, _: &mut [LayoutChild], _: Constraints) -> LayoutResult { LayoutResult::empty() }
    fn paint(&self, _: &mut PaintCtx<'_>, _: Rect, _: &LayoutResult) {}
}
assert_eq!(Spacer.debug_name(), "Spacer");

Required Methods

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

Returns a stable, non-sensitive static name for diagnostics.

Examples

use ailloli_ui_core::{Constraints, Rect};
use ailloli_ui_runtime::component::Widget;
use ailloli_ui_runtime::layout::{LayoutChild, LayoutCtx, LayoutEngine, LayoutResult};
use ailloli_ui_runtime::scene::PaintCtx;
struct W;
impl Widget<()> for W {
    fn debug_name(&self) -> &'static str { "W" }
    fn layout(&self, _: &mut LayoutEngine<'_, ()>, _: &mut LayoutCtx<'_>, _: &mut [LayoutChild], _: Constraints) -> LayoutResult { LayoutResult::empty() }
    fn paint(&self, _: &mut PaintCtx<'_>, _: Rect, _: &LayoutResult) {}
}
assert_eq!(W.debug_name(), "W");

fn layout( &self, engine: &mut LayoutEngine<'_, A>, ctx: &mut LayoutCtx<'_>, children: &mut [LayoutChild], constraints: Constraints, ) -> LayoutResult

Measures and positions this widget’s direct retained children.

The returned child vector must correspond by index to children for commit, paint, and hit testing. Implementations define constraint and non-finite handling and may recursively call LayoutChild::layout. LayoutCtx::layout_pass distinguishes speculative measurement from authoritative allocation. Implementations must not persist effects derived from geometry during a measurement pass.

Reactive reads from measurement are staged for the current layout attempt. Reads from measurements that contribute to the accepted result are combined with reads from authoritative allocation and published only after the attempt succeeds. Abandoned alternatives and panicking attempts do not replace the previous dependency set.

Examples

let mut tree = ElementTree::<()>::new();
let mut engine = LayoutEngine::new(&mut tree);
let mut ctx = LayoutCtx::new(Scale::new(1.0));
assert_eq!(W.layout(&mut engine, &mut ctx, &mut [], Constraints::tight(1.0, 1.0)).size.w, 0.0);

fn paint(&self, ctx: &mut PaintCtx<'_>, bounds: Rect, layout: &LayoutResult)

Emits base draw commands for absolute logical-pixel bounds.

Base paint runs before descendants. layout is the cached result from this element’s committed layout pass and may contain a reusable artifact. Geometry-dependent drawing must use that committed result; a widget must not reshape newly read content into bounds computed for older content. When geometry dependencies are stale, the runtime schedules layout for a later traversal and does not invoke unsafe paint against stale geometry.

Reactive reads from base and overlay paint form one dependency set. It replaces the prior paint set only after the element’s paint traversal succeeds; a panic preserves the prior set.

Examples

let mut ctx = PaintCtx::new();
W.paint(&mut ctx, Rect::new(0.0, 0.0, 1.0, 1.0), &LayoutResult::empty());
assert_eq!(ctx.layers[0].cmds.len(), 0);

Provided Methods

fn layout_dependency_revision(&self) -> u64

Revision of widget-owned inputs that can change its layout result.

Runtime-created signals normally invalidate their owning element. This hook also covers externally created reactive bindings when a layout pass is requested for another reason, without invalidating stable siblings. Implementations must return a cheap, stable and monotone value. The default is the zero sentinel for no external dependency.

Examples

assert_eq!(W.layout_dependency_revision(), 0);

fn layout_committed( &self, _ctx: &mut LayoutCtx<'_>, _bounds: Rect, _layout: &LayoutResult, )

Observes newly committed absolute bounds after layout.

The default does nothing. It runs after a real authoritative layout callback, or when committed bounds or retained hook inputs changed. Stable cache hits do not rerun it. The complete visited subtree already has authoritative bounds; the hook should not mutate tree topology. Reactive reads are combined with the successful authoritative layout observations. This callback is not run for speculative measurement. If it panics, the authoritative geometry remains committed and the previously published hook dependencies remain active. Reactive writes performed before the panic are not rolled back; any invalidation they emit remains queued for a later frame rather than re-entering layout.

Examples

let mut ctx = LayoutCtx::new(Scale::new(1.0));
W.layout_committed(&mut ctx, Rect::new(0.0, 0.0, 1.0, 1.0), &LayoutResult::empty());

fn paint_overlay( &self, _ctx: &mut PaintCtx<'_>, _bounds: Rect, _layout: &LayoutResult, )

Emits top-level paint commands after this widget’s descendants.

The default does nothing. Use PaintCtx::push_overlay for commands that must be globally ordered after base content.

Examples

let mut ctx = PaintCtx::new();
W.paint_overlay(&mut ctx, Rect::new(0.0, 0.0, 1.0, 1.0), &LayoutResult::empty());
assert!(ctx.overlay_layers.is_empty());

fn event( &self, _ctx: &mut EventCtx<A>, _event: &Event, _bounds: Rect, _layout: &LayoutResult, )

Handles one routed event for absolute bounds and cached layout.

The default does nothing and leaves propagation enabled. Implementations may dispatch actions, invalidate work, or stop bubbling through ctx.

Examples

let mut ctx = EventCtx::new(RuntimeHandle::new(), ElementId(1));
W.event(&mut ctx, &Event::Focus(FocusEvent::new(true)), Rect::new(0.0,0.0,1.0,1.0), &LayoutResult::empty());
assert!(!ctx.is_propagation_stopped());

fn focus_policy(&self) -> FocusPolicy

Returns whether the widget may receive keyboard focus.

The default is FocusPolicy::NotFocusable.

Examples

assert_eq!(W.focus_policy(), FocusPolicy::NotFocusable);

fn activation_policy(&self) -> ActivationPolicy

Policy used for provider-neutral focus-only pointer gestures.

The default inherits from the parent; the input router falls back to suppression at the root so custom action widgets are safe by default.

Examples

assert_eq!(W.activation_policy(), ActivationPolicy::Inherit);

fn input_role(&self) -> InputRole

Returns provider-neutral text-input semantics.

The default is InputRole::None and does not imply focusability.

Examples

assert_eq!(W.input_role(), InputRole::None);

fn hover_cursor_role(&self) -> HoverCursorRole

Returns the widget-wide hover cursor role.

By default text input roles map to Text and None maps to Inherit.

Examples

assert_eq!(W.hover_cursor_role(), HoverCursorRole::Inherit);

fn hover_cursor_role_at( &self, _bounds: Rect, _layout: &LayoutResult, _pos: Point, ) -> HoverCursorRole

Returns the hover cursor role at an absolute logical-pixel position.

The default ignores position/bounds/layout and delegates to Self::hover_cursor_role.

Examples

assert_eq!(W.hover_cursor_role_at(Rect::new(0.0,0.0,1.0,1.0), &LayoutResult::empty(), Point::new(0.5,0.5)), HoverCursorRole::Inherit);

fn ime_cursor_rect(&self, _bounds: Rect, _layout: &LayoutResult) -> Option<Rect>

Returns the absolute logical-pixel IME candidate/caret rectangle.

None, the default, means the widget does not expose an IME cursor.

Examples

assert_eq!(W.ime_cursor_rect(Rect::new(0.0,0.0,1.0,1.0), &LayoutResult::empty()), None);

Implementors