WidgetComponent class Widgets

A live widget subtree on a scene surface.

The component owns the capture pipeline (through a WidgetTextureController) and the binding of the captured texture to a material; SceneView hosts the widget subtree invisibly (state, tickers, and animations run normally) and re-captures it per the update policy.

Three setup tiers share this one component:

  1. Zero config: the component creates an aspect-correct unlit alpha-blended quad (worldHeight world units tall).
  2. Your geometry (any surface with 0..1 UVs): the component still owns the material and mesh.
  3. Your material and/or a bind callback: the component only calls bind when the texture changes. With WidgetComponent.bindOnly no mesh is created at all (for surfaces that already exist, like a screen inside an imported model).

Each capture wraps the rasterized image's backing texture directly, so the texture object is replaced across captures and bind re-fires per capture (on the readback fallback path it is overwritten in place and bind re-fires only when the capture size changes).

Inheritance

Constructors

WidgetComponent({required Widget child, required Size size, double pixelRatio = 1.0, double worldHeight = 1.0, WidgetUpdatePolicy update = WidgetUpdatePolicy.everyFrame, WidgetInput input = WidgetInput.automatic, bool occlusionHiding = false, Geometry? geometry, Material? material, void bind(Texture texture)?})
Creates a widget surface. With no geometry an aspect-correct quad is created; with no material and no bind, an unlit alpha-blended material bound to the capture is created.
WidgetComponent.bindOnly({required Widget child, required Size size, required void bind(Texture texture), double pixelRatio = 1.0, WidgetUpdatePolicy update = WidgetUpdatePolicy.everyFrame, WidgetInput input = WidgetInput.automatic, bool occlusionHiding = false})
Creates a capture-and-bind-only component: no geometry or mesh is created, and every texture change is delivered to bind (which typically assigns a texture slot on an existing material).

Properties

child → Widget
The widget subtree this component shows (hosted by SceneView).
no setter
controller → WidgetTextureController
The capture controller: read WidgetTextureController.texture, listen for changes, forward pointer input, or trigger manual captures.
final
enabled ↔ bool
Whether this component's update hook runs each frame.
getter/setter pairinherited
hashCode → int
The hash code for this object.
no setterinherited
input → WidgetInput
How this surface receives pointer input.
final
isAttached → bool
Whether this component is currently attached to a node.
no setterinherited
isLoaded → bool
Whether onLoad has completed.
no setterinherited
isMounted → bool
Whether the owning node is part of a live scene graph.
no setterinherited
node → Node
The node this component is attached to.
no setterinherited
occlusionHiding → bool
Whether the surface's hosted subtree leaves the semantics tree while scene geometry occludes it from the camera. Defaults to false (an occluded surface keeps its semantics, matching a partially obscured widget). When true, an occlusion raycast toward the surface center each semantics update drops the whole subtree while it is hidden, so assistive technology cannot reach controls the viewer cannot see (matching how WidgetInput.automatic pointer input is already blocked by the occluder). Only consulted while assistive technology is active.
final
pixelRatio → double
Texels per logical pixel.
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
size → Size
The child's logical layout size.
no setter
updatePolicy → WidgetUpdatePolicy
The capture policy (see WidgetUpdatePolicy).
no setter

Methods

cloneFor(Node cloneOwner) → Component?
Returns a copy of this component for cloneOwner, the Node.clone counterpart of the owning node, or null to not carry the component to clones (the default).
inherited
fixedUpdate(double fixedDt) → void
Called once per fixed physics step while the component is mounted, enabled, and loaded. fixedDt is the fixed timestep of the surrounding PhysicsWorld, not the frame interval.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
onAttach() → void
Called when this component is added to a node.
override
onDetach() → void
Called when this component is removed from a node.
override
onLoad() → Future<void>
Optional asynchronous setup, such as loading an asset.
inherited
onMount() → void
Called when the owning node enters a live scene graph.
override
onUnmount() → void
Called when the owning node leaves a live scene graph.
override
toString() → String
A string representation of this object.
inherited
update(double deltaSeconds) → void
Called once per frame while the component is mounted, enabled, and loaded. deltaSeconds is the elapsed time since the previous tick.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited