WidgetBase

Shared widget foundation for layout, StylePack lookup, state, rendering, events, and animation.

Overview

WidgetBase is the central abstract foundation for all UniGUI widgets. It unifies layout bounds, visual styles, input handling, invalidation tracking, focus traversal, transforms, animations, and render dispatch into a coherent fluent API.

Core Subsystem	Primary Methods	Role & Architecture
Hierarchy	parent(), children(), uiContext()	Manages parent/child widget tree relations, layout measurement propagation, and contextual host access.
Geometry & Layout	layout(), layoutStyle(), desiredSize()	Measures and positions the widget via LayoutStyle (flexbox, CSS grid, margins, padding, size constraints).
Visual Styling	style(), styleId(), styleClass()	Handles inline CSS declarations, StylePack theme lookups, class selectors, and scoped style isolation.
State & Interaction	visibility(), enabled(), mouseCursor()	Governs layout flow participation, hover detection, custom mouse cursor, and tab focus management.
Transforms & Animation	animate(), opacity(), rotationDegrees()	Interpolates properties, executes FLIP layout transitions, spring physics, and multi-track storyboards.
Rendering & Caching	renderer(), renderCached(), invalidate()	Dispatches draw commands, supports retained render cache for leaf widgets, and manages dirty flags.
Events	on(), emit(), handle()	Strongly typed event listening and bubbling throughout the widget hierarchy.

Abstract Base Implementation

WidgetBase provides core infrastructure and is abstract. Build user interfaces using concrete built-in widgets (such as Label, Button, VBox, ScrollView) or extend it to implement custom controls.

Style and layout

UniGUI cleanly separates Layout (geometry, positioning, and sizing) from Style (visual colors, borders, shadows, and textures).

Styling Mechanism	Method / Syntax	Description & Behavior
Inline CSS Declarations	style("color: #fff; padding: 8px;")	Parses property-value pairs into the widget's inline style. Parser warnings remain in styleDiagnostics().
StylePack Reference	styleId("card-primary")	References a pre-defined theme style rule declared in an active StylePack.
Style Classes	styleClass("btn primary") / addStyleClass("active")	Assigns CSS classes for conditional or state-based styling rules (:hover, :focused, :disabled).
Subtree Style Scope	styleScope(true)	Isolates the widget subtree, preventing inherited styles from propagating beyond this boundary.
Local Type Overrides	localStyle("Button", buttonStyle)	Replaces the default style for all descendant widgets of the given type within this subtree.
Layout Configuration	layout(style -> style.width(100).fill())	Configures geometry via batched LayoutStyle callback, avoiding redundant layout invalidations.

Performance Best Practice: Layout vs. Style

Mutating visual styles (e.g. changing color or opacity) only triggers a VISUAL invalidation (repaint). Changing geometry via layout(...) triggers a LAYOUT invalidation (remeasurement). Separating them ensures smooth 60+ FPS UI performance.

Visibility, focus, and interaction

Widget visibility, user interactivity, and focus navigation are managed via explicit state flags.

Visibility Mode	Layout Calculation	Visual Paint	Mouse / Input Events	Keyboard Focusable
Visibility.VISIBLE	Participates normally	Rendered	Receives events	Yes
Visibility.HIDDEN	Participates (preserves space)	Suppressed	Ignored	No
Visibility.COLLAPSED	Completely removed (zero size)	Suppressed	Ignored	No

Interaction Feature	Method	Purpose & Effect
Enablement	enabled(boolean)	Enables or disables interaction. Inactive widgets receive the :disabled style pseudo-class and ignore events.
Hover Query	hovered()	Returns whether the cursor is currently within the widget's bounds.
Custom Cursor	mouseCursor(MouseCursor)	Sets active cursor shape (HAND, TEXT, CROSSHAIR, etc.) while enabled and visible.
Focus Navigation	focusable(boolean)	Enables tab navigation and keyboard focus for this widget.
Focus Boundary	focusScope(true)	Traps tab cycling within this widget's subtree (crucial for modal dialogs and dropdown menus).
Tab Ordering	focusOrder(int)	Explicit relative index for tab-key sequence ordering (default: document flow).

Choosing HIDDEN vs. COLLAPSED

Use Visibility.HIDDEN when an element should temporarily vanish without causing sibling widgets to shift or recalculate positions. Use Visibility.COLLAPSED when the element should be removed from flow and yield its space.

Transforms and animation

UniGUI provides a unified animation engine supporting instant transforms, interpolated transitions, spring physics, layout movement, and choreographies.

Animation Technique	Method	Description
Direct Transform	opacity(val), rotationDegrees(deg), transformPivot(x, y)	Instantly updates visual transform properties without animation overhead.
Interpolated Transition	animate(property, target, spec), animateOpacity(...), animatePosition(...), animateScale(...)	Smoothly transitions a property using easing curves (TransitionSpec). In-flight transitions are smoothly retargeted.
Spring Physics	animateSpring(property, target, stiffness, damping)	Physically modeled damped harmonic oscillator motion with realistic bounce and overshoot.
Layout Movement (FLIP)	layoutTransition(duration, easing)	Animates positional changes caused by layout reflows using First-Last-Invert-Play (FLIP).
Attention Feedback	shake(amplitude, duration)	Oscillates the widget horizontally/vertically to indicate errors or invalid actions.
Choreographed Storyboards	playStoryboard(storyboard)	Complex, multi-target, multi-keyframe timelines managed by StoryboardPlayer.

Layout Transitions vs. Geometry Animation

layoutTransition(...) animates position displacement (X and Y coordinates) resulting from layout passes. It does not stretch or interpolate width/height dimensions.

Rendering, invalidation, and events

The render pipeline separates layout measurement, visual draw command recording, and subtree invalidation.

Invalidation Flag	Target Subsystem	When Triggered
InvalidationFlags.LAYOUT	Layout Engine	Size, padding, margin, or flex rules changed. Propagates dirty flags upward to root.
InvalidationFlags.VISUAL	Render Pipeline	Colors, text, borders, or opacity changed. Triggers repaint without remeasuring geometry.
InvalidationFlags.RETAINED_RENDER	Draw Cache	Internal retained draw command cache invalidated.

Pipeline Component	Method	Purpose & Usage
Custom Renderer	renderer(WidgetRender)	Replaces the widget's default drawing commands with a custom procedural renderer.
Retained Draw Cache	renderCachingEnabled(boolean)	Records draw calls for static leaf widgets into a reusable buffer, drastically reducing GPU overhead.
Event Subscription	on(EventType, listener)	Registers a typed listener for input, focus, or lifecycle events. Returns an EventSubscription for unregistering.
Event Dispatch	emit(Event)	Dispatches a typed event directly to the widget and triggers listener callbacks.

Child Traversal with Custom Renderers

Assigning a custom renderer(...) replaces background and content rendering of the target widget. Child widgets belonging to the container are still traversed and drawn automatically by the framework.

Configure a widget

Label greeting = new Label("Hello")
        .id("greeting")
        .styleId("card")
        .addStyleClass("interactive");

greeting.layout(style -> style
        .padding(12.0f)
        .width(240.0f)
        .flexNone());

Animate a visual property

greeting
        .opacity(0.0f)
        .animateOpacity(1.0f, 0.20f)
        .animateScale(1.0f, 1.0f, 0.20f);

API

Identity & Styling

Method	Description
id(String)	Assigns the unique runtime/editor identifier used for lookup and code-behind.
id()	Returns the identifier of this widget, or an empty string if none was assigned.
styleId(String)	Selects an explicit style rule from an active StylePack for this widget.
styleId()	Returns the explicit StylePack style id assigned to this widget.
style(String)	Applies inline declarations, or treats a bare token as a StylePack style id.
style(Consumer)	Applies typed inline style declarations through a mutable style builder callback.
styleClear()	Removes all inline style declarations and clears parser diagnostics.
styleDiagnostics()	Returns diagnostics and warnings collected while parsing inline style strings.
styleClass(String)	Replaces the widget's style classes with a space-separated class list.
addStyleClass(String)	Adds a normalized style class selector without removing existing classes.
removeStyleClass(String)	Removes a style class selector if it is currently assigned.
hasStyleClass(String)	Checks whether the specified style class is assigned to this widget.
styleClasses()	Returns an unmodifiable view of all normalized style classes assigned to this widget.
styleScope(boolean)	Limits local style inheritance to this widget subtree when enabled.
styleScope()	Checks whether this widget forms a local style scope boundary.
localStyle(String, Style)	Sets or clears a local style override for a specific widget type within this subtree.
localStyle(String)	Retrieves the local style override defined on this widget for a given widget type.

WidgetBase::id(String)

Set widget ID

Assigns the unique runtime/editor identifier used for lookup and code-behind.

Parameter	Type	Description
id	String	Unique identifier string.

Returns WidgetBase: this widget for fluent configuration.

WidgetBase::id()

Get widget ID

Returns the identifier of this widget, or an empty string if none was assigned.

Returns String: the widget identifier string.

WidgetBase::styleId(String)

Set style ID

Selects an explicit style rule from an active StylePack for this widget.

Parameter	Type	Description
styleId	String	StylePack style id token.

Returns WidgetBase: this widget for fluent configuration.

WidgetBase::styleId()

Get style ID

Returns the explicit StylePack style id assigned to this widget.

Returns String: the active StylePack style id, or empty string.

WidgetBase::style(String)

Inline style

Applies inline declarations, or treats a bare token as a StylePack style id.

A string without : or ; is passed to styleId. Otherwise it is parsed as property: value; declarations and merged into the widget inline style. Parser diagnostics stay in styleDiagnostics().

Parameter	Type	Description
declarations	String	Inline declarations, or a StylePack id when the string has no : or ;.

Returns WidgetBase: this widget for fluent configuration.

WidgetBase::style(Consumer)

Configure inline style

Applies typed inline style declarations through a mutable style builder callback.

Parameter	Type	Description
update	Consumer	Callback mutating properties on MutableStyle.

Returns WidgetBase: this widget for fluent configuration.

WidgetBase::styleClear()

Clear inline style

Removes all inline style declarations and clears parser diagnostics.

Returns WidgetBase: this widget for fluent configuration.

WidgetBase::styleDiagnostics()

Style diagnostics

Returns diagnostics and warnings collected while parsing inline style strings.

Returns List: list of style parser diagnostics.

WidgetBase::styleClass(String)

Set style classes

Replaces the widget's style classes with a space-separated class list.

Parameter	Type	Description
styleClasses	String	Space-separated style class tokens.

Returns WidgetBase: this widget for fluent configuration.

WidgetBase::addStyleClass(String)

Add style class

Adds a normalized style class selector without removing existing classes.

Parameter	Type	Description
styleClass	String	Class token to add.

Returns WidgetBase: this widget for fluent configuration.

WidgetBase::removeStyleClass(String)

Remove style class

Removes a style class selector if it is currently assigned.

Parameter	Type	Description
styleClass	String	Class token to remove.

Returns WidgetBase: this widget for fluent configuration.

WidgetBase::hasStyleClass(String)

Has style class

Checks whether the specified style class is assigned to this widget.

Parameter	Type	Description
styleClass	String	Class token to check.

Returns boolean: true if the class is present, false otherwise.

WidgetBase::styleClasses()

Get style classes

Returns an unmodifiable view of all normalized style classes assigned to this widget.

Returns List: list of style classes.

WidgetBase::styleScope(boolean)

Set style scope

Limits local style inheritance to this widget subtree when enabled.

Parameter	Type	Description
styleScope	boolean	True to isolate local style lookups to this subtree.

Returns WidgetBase: this widget for fluent configuration.

WidgetBase::styleScope()

Get style scope

Checks whether this widget forms a local style scope boundary.

Returns boolean: true if style scoping is active.

WidgetBase::localStyle(String, Style)

Define local style

Sets or clears a local style override for a specific widget type within this subtree.

Parameter	Type	Description
widgetType	String	Target widget type name.
style	Style	Style override to apply, or null to remove.

Returns WidgetBase: this widget for fluent configuration.

WidgetBase::localStyle(String)

Get local style

Retrieves the local style override defined on this widget for a given widget type.

Parameter	Type	Description
widgetType	String	Target widget type name.

Returns Style: the local style override, or null if none.

Layout & Geometry

Method	Description
layout(Consumer)	Updates the live LayoutStyle and batches the resulting layout invalidation.
layoutStyle()	Returns the live LayoutStyle instance governing this widget's geometry.
layoutBounds()	Returns the current arranged bounds of the widget in parent coordinates.
desiredSize()	Returns the dimensions requested during the most recent measurement pass.
layoutTransition(float)	Enables FLIP animation for subsequent layout-driven repositioning.
layoutTransition(float, Easing)	Enables FLIP movement animation with custom duration and easing curve.
layoutTransitionsEnabled(boolean)	Enables or disables automatic FLIP transitions when layout coordinates change.
layoutTransitionsEnabled()	Checks whether FLIP layout transitions are currently enabled.

WidgetBase::layout(Consumer)

Apply layout

Updates the live LayoutStyle and batches the resulting layout invalidation.

Parameter	Type	Description
update	Consumer	Callback that mutates layout size, spacing, flex, grid, or position. Null is a no-op.

Returns WidgetBase: this widget for fluent configuration.

WidgetBase::layoutStyle()

Get layout style

Returns the live LayoutStyle instance governing this widget's geometry.

Returns LayoutStyle: the live LayoutStyle.

WidgetBase::layoutBounds()

Get layout bounds

Returns the current arranged bounds of the widget in parent coordinates.

Returns RectView: current arranged bounds.

WidgetBase::desiredSize()

Get desired size

Returns the dimensions requested during the most recent measurement pass.

Returns LayoutSize: most recently measured desired size.

WidgetBase::layoutTransition(float)

Enable layout transition

Enables FLIP animation for subsequent layout-driven repositioning.

Parameter	Type	Description
durationSeconds	float	Transition duration in seconds.

Returns WidgetBase: this widget for fluent configuration.

WidgetBase::layoutTransition(float, Easing)

Enable layout transition with easing

Enables FLIP movement animation with custom duration and easing curve.

Parameter	Type	Description
durationSeconds	float	Transition duration in seconds.
easing	Easing	Easing curve for smooth movement.

Returns WidgetBase: this widget for fluent configuration.

WidgetBase::layoutTransitionsEnabled(boolean)

Toggle layout transitions

Enables or disables automatic FLIP transitions when layout coordinates change.

Parameter	Type	Description
enabled	boolean	True to animate layout changes.

Returns WidgetBase: this widget for fluent configuration.

WidgetBase::layoutTransitionsEnabled()

Layout transitions enabled

Checks whether FLIP layout transitions are currently enabled.

Returns boolean: true if layout transitions are active.

State & Interaction

Method	Description
visibility(Visibility)	Sets whether the widget is shown, hidden in place, or removed from layout.
visibility()	Returns the current Visibility mode (VISIBLE, HIDDEN, or COLLAPSED).
visible(boolean)	Convenience toggle setting VISIBLE when true, or HIDDEN when false.
visible()	Checks whether the widget's visibility mode is strictly VISIBLE.
enabled(boolean)	Enables or disables user interaction and applies the :disabled pseudo-class.
enabled()	Checks whether the widget accepts user interaction.
hovered()	Checks whether the mouse cursor is currently positioned over this widget.
mouseCursor(MouseCursor)	Sets the cursor icon displayed when hovering over this enabled, visible widget.
mouseCursor()	Returns the cursor shape configured on this widget.
mouseCursorAt(float, float)	Resolves the appropriate cursor shape for a specific local coordinate offset.
focusable(boolean)	Enables or disables keyboard tab navigation and focus for this widget.
focusable()	Checks whether the widget can receive keyboard focus.
focusScope(boolean)	Makes this widget a boundary that traps tab-key navigation within its children.
focusScope()	Checks whether this widget acts as an isolated focus scope boundary.
focusOrder(int)	Sets the explicit relative tab sequence index for keyboard navigation.
focusOrder()	Returns the relative tab index assigned to this widget.

WidgetBase::visibility(Visibility)

Visibility

Sets whether the widget is shown, hidden in place, or removed from layout.

VISIBLE participates in layout, rendering, input, and focus. HIDDEN keeps its layout space but skips rendering and input. COLLAPSED leaves the layout and invalidates both layout and visual state. Null becomes VISIBLE.

Parameter	Type	Description
visibility	Visibility	VISIBLE, HIDDEN, or COLLAPSED. Null means VISIBLE.

Returns WidgetBase: this widget for fluent configuration.

WidgetBase::visibility()

Get visibility

Returns the current Visibility mode (VISIBLE, HIDDEN, or COLLAPSED).

Returns Visibility: current visibility mode.

WidgetBase::visible(boolean)

Set visible

Convenience toggle setting VISIBLE when true, or HIDDEN when false.

Parameter	Type	Description
visible	boolean	True for VISIBLE; false for HIDDEN.

Returns WidgetBase: this widget for fluent configuration.

WidgetBase::visible()

Is visible

Checks whether the widget's visibility mode is strictly VISIBLE.

Returns boolean: true if VISIBLE.

WidgetBase::enabled(boolean)

Set enabled

Enables or disables user interaction and applies the :disabled pseudo-class.

Parameter	Type	Description
enabled	boolean	True to allow user interaction, false to disable.

Returns WidgetBase: this widget for fluent configuration.

WidgetBase::enabled()

Is enabled

Checks whether the widget accepts user interaction.

Returns boolean: true if enabled.

WidgetBase::hovered()

Is hovered

Checks whether the mouse cursor is currently positioned over this widget.

Returns boolean: true if mouse is over the widget.

WidgetBase::mouseCursor(MouseCursor)

Set mouse cursor

Sets the cursor icon displayed when hovering over this enabled, visible widget.

Parameter	Type	Description
mouseCursor	MouseCursor	Desired mouse cursor shape.

Returns WidgetBase: this widget for fluent configuration.

WidgetBase::mouseCursor()

Get mouse cursor

Returns the cursor shape configured on this widget.

Returns MouseCursor: the configured mouse cursor.

WidgetBase::mouseCursorAt(float, float)

Get mouse cursor at coordinates

Resolves the appropriate cursor shape for a specific local coordinate offset.

Parameter	Type	Description
localX	float	Local X coordinate.
localY	float	Local Y coordinate.

Returns MouseCursor: cursor shape at coordinates.

WidgetBase::focusable(boolean)

Set focusable

Enables or disables keyboard tab navigation and focus for this widget.

Parameter	Type	Description
focusable	boolean	True to participate in keyboard focus.

Returns WidgetBase: this widget for fluent configuration.

WidgetBase::focusable()

Is focusable

Checks whether the widget can receive keyboard focus.

Returns boolean: true if focusable.

WidgetBase::focusScope(boolean)

Set focus scope

Makes this widget a boundary that traps tab-key navigation within its children.

Parameter	Type	Description
focusScope	boolean	True to trap keyboard focus within this subtree.

Returns WidgetBase: this widget for fluent configuration.

WidgetBase::focusScope()

Is focus scope

Checks whether this widget acts as an isolated focus scope boundary.

Returns boolean: true if focus scope is active.

WidgetBase::focusOrder(int)

Set focus order

Sets the explicit relative tab sequence index for keyboard navigation.

Parameter	Type	Description
focusOrder	int	Relative index for tab ordering.

Returns WidgetBase: this widget for fluent configuration.

WidgetBase::focusOrder()

Get focus order

Returns the relative tab index assigned to this widget.

Returns int: relative tab index.

Transforms & Animation

Method	Description
opacity(float)	Sets the widget opacity immediately (clamped to 0.0 - 1.0) and repaints.
opacity()	Returns the current visual opacity of the widget.
rotationDegrees(float)	Sets the visual rotation angle immediately around the active pivot.
transformOrigin(TransformOrigin)	Selects a named preset pivot (e.g. CENTER, TOP_LEFT) for rotation and scaling.
transformPivot(float, float)	Sets a custom transform pivot point in local pixel coordinates.
transform()	Returns the live Transform model governing offsets, rotation, scale, and pivot.
animate(AnimatedProperty, float, float)	Smoothly transitions a built-in property to a target value over a duration in seconds.
animate(AnimatedProperty, float, TransitionSpec)	Transitions a built-in property to a target, or applies it immediately when duration is not positive.
animateOpacity(float, float)	Smoothly transitions opacity to a target value using standard easing.
animatePosition(float, float, float)	Animates visual transform displacement offsets along the X and Y axes.
animatePositionFrom(float, float, float, float, float)	Animates transform position starting explicitly from (startX, startY) to (endX, endY).
animateScale(float, float, float)	Smoothly transitions visual scale multipliers on both axes.
shake(float, float)	Oscillates the widget back and forth to provide visual error or rejection feedback.
stopShakeAnimations()	Cancels any active shake animations and restores the widget's resting position.
animateSpring(AnimatedProperty, float, float, float)	Runs a physically simulated harmonic oscillator animation with natural bounce and overshoot.
animateColor(MutableColor, ColorView, float)	Smoothly interpolates an RGBA color property to a target color value.
stopColorAnimations()	Stops all active color interpolation animations on this widget.
playStoryboard(Storyboard)	Executes a multi-keyframe timeline storyboard across this widget and its descendants.
playStoryboard(Object, Storyboard)	Plays a storyboard under an explicit key, canceling any previous storyboard with that key.
stopStoryboard(Object)	Stops and removes the active storyboard registered under the specified key.
stopAnimation(AnimatedProperty)	Stops running transitions specifically targeted at the given property.
stopAnimations()	Stops every running transition, spring, shake, and storyboard on this widget.
animationRunning(AnimatedProperty)	Checks whether an animation is currently running for a specific property.
animationsRunning()	Checks whether any animations are currently playing on this widget.

WidgetBase::opacity(float)

Set opacity

Sets the widget opacity immediately (clamped to 0.0 - 1.0) and repaints.

Parameter	Type	Description
opacity	float	Opacity value from 0.0 (transparent) to 1.0 (opaque).

Returns WidgetBase: this widget for fluent configuration.

WidgetBase::opacity()

Get opacity

Returns the current visual opacity of the widget.

Returns float: opacity value between 0.0 and 1.0.

WidgetBase::rotationDegrees(float)

Set rotation degrees

Sets the visual rotation angle immediately around the active pivot.

Parameter	Type	Description
degrees	float	Rotation angle in degrees.

Returns WidgetBase: this widget for fluent configuration.

WidgetBase::transformOrigin(TransformOrigin)

Set transform origin

Selects a named preset pivot (e.g. CENTER, TOP_LEFT) for rotation and scaling.

Parameter	Type	Description
origin	TransformOrigin	Named transform origin preset.

Returns WidgetBase: this widget for fluent configuration.

WidgetBase::transformPivot(float, float)

Set transform pivot

Sets a custom transform pivot point in local pixel coordinates.

Parameter	Type	Description
x	float	Pivot X in local pixels.
y	float	Pivot Y in local pixels.

Returns WidgetBase: this widget for fluent configuration.

WidgetBase::transform()

Get transform

Returns the live Transform model governing offsets, rotation, scale, and pivot.

Returns Transform: the active Transform instance.

WidgetBase::animate(AnimatedProperty, float, float)

Animate property with duration

Smoothly transitions a built-in property to a target value over a duration in seconds.

Parameter	Type	Description
property	AnimatedProperty	Built-in property such as opacity, position, scale, rotation, or pivot.
targetValue	float	Target value. Opacity is clamped to 0..1; non-finite values are sanitized.
durationSeconds	float	Transition duration in seconds.

Returns WidgetBase: this widget for fluent configuration.

WidgetBase::animate(AnimatedProperty, float, TransitionSpec)

Animate a property

Transitions a built-in property to a target, or applies it immediately when duration is not positive.

A matching in-flight transition is retargeted instead of restarted. Rotation uses the shortest angle path. A null property is ignored; a null spec uses TransitionSpec.DEFAULT.

Parameter	Type	Description
property	AnimatedProperty	Built-in property such as opacity, position, scale, rotation, or pivot.
targetValue	float	Target value. Opacity is clamped to 0..1; non-finite values are sanitized.
spec	TransitionSpec	Duration and easing. Null uses the default spec; non-positive duration snaps to the target.

Returns WidgetBase: this widget for fluent configuration.

WidgetBase::animateOpacity(float, float)

Animate opacity

Smoothly transitions opacity to a target value using standard easing.

Parameter	Type	Description
targetOpacity	float	Target opacity between 0.0 and 1.0.
durationSeconds	float	Transition duration in seconds.

Returns WidgetBase: this widget for fluent configuration.

WidgetBase::animatePosition(float, float, float)

Animate position

Animates visual transform displacement offsets along the X and Y axes.

Parameter	Type	Description
x	float	Target X offset in pixels.
y	float	Target Y offset in pixels.
durationSeconds	float	Transition duration in seconds.

Returns WidgetBase: this widget for fluent configuration.

WidgetBase::animatePositionFrom(float, float, float, float, float)

Animate position from start

Animates transform position starting explicitly from (startX, startY) to (endX, endY).

Parameter	Type	Description
startX	float	Starting X offset.
startY	float	Starting Y offset.
endX	float	Target ending X offset.
endY	float	Target ending Y offset.
durationSeconds	float	Transition duration in seconds.

Returns WidgetBase: this widget for fluent configuration.

WidgetBase::animateScale(float, float, float)

Animate scale

Smoothly transitions visual scale multipliers on both axes.

Parameter	Type	Description
x	float	Target scale multiplier on X axis.
y	float	Target scale multiplier on Y axis.
durationSeconds	float	Transition duration in seconds.

Returns WidgetBase: this widget for fluent configuration.

WidgetBase::shake(float, float)

Trigger shake animation

Oscillates the widget back and forth to provide visual error or rejection feedback.

Parameter	Type	Description
amplitude	float	Shake displacement amplitude in pixels.
durationSeconds	float	Transition duration in seconds.

Returns WidgetBase: this widget for fluent configuration.

WidgetBase::stopShakeAnimations()

Stop shake animations

Cancels any active shake animations and restores the widget's resting position.

Returns WidgetBase: this widget for fluent configuration.

WidgetBase::animateSpring(AnimatedProperty, float, float, float)

Animate spring physics

Runs a physically simulated harmonic oscillator animation with natural bounce and overshoot.

Parameter	Type	Description
property	AnimatedProperty	Built-in property such as opacity, position, scale, rotation, or pivot.
targetValue	float	Target value. Opacity is clamped to 0..1; non-finite values are sanitized.
stiffness	float	Spring stiffness coefficient (higher = faster pull).
damping	float	Damping coefficient (higher = less oscillation).

Returns WidgetBase: this widget for fluent configuration.

WidgetBase::animateColor(MutableColor, ColorView, float)

Animate color

Smoothly interpolates an RGBA color property to a target color value.

Parameter	Type	Description
color	MutableColor	MutableColor target to mutate.
targetColor	ColorView	Destination color value.
durationSeconds	float	Transition duration in seconds.

Returns WidgetBase: this widget for fluent configuration.

WidgetBase::stopColorAnimations()

Stop color animations

Stops all active color interpolation animations on this widget.

Returns WidgetBase: this widget for fluent configuration.

WidgetBase::playStoryboard(Storyboard)

Play storyboard

Executes a multi-keyframe timeline storyboard across this widget and its descendants.

Parameter	Type	Description
storyboard	Storyboard	Storyboard animation timeline to play.

Returns StoryboardPlayer: StoryboardPlayer controlling playback.

WidgetBase::playStoryboard(Object, Storyboard)

Play keyed storyboard

Plays a storyboard under an explicit key, canceling any previous storyboard with that key.

Parameter	Type	Description
key	Object	Unique tracking key.
storyboard	Storyboard	Storyboard animation timeline to play.

Returns StoryboardPlayer: StoryboardPlayer controlling playback.

WidgetBase::stopStoryboard(Object)

Stop storyboard

Stops and removes the active storyboard registered under the specified key.

Parameter	Type	Description
key	Object	Unique tracking key.

Returns WidgetBase: this widget for fluent configuration.

WidgetBase::stopAnimation(AnimatedProperty)

Stop animation for property

Stops running transitions specifically targeted at the given property.

Parameter	Type	Description
property	AnimatedProperty	Built-in property such as opacity, position, scale, rotation, or pivot.

Returns WidgetBase: this widget for fluent configuration.

WidgetBase::stopAnimations()

Stop all animations

Stops every running transition, spring, shake, and storyboard on this widget.

Returns WidgetBase: this widget for fluent configuration.

WidgetBase::animationRunning(AnimatedProperty)

Is property animating

Checks whether an animation is currently running for a specific property.

Parameter	Type	Description
property	AnimatedProperty	Built-in property such as opacity, position, scale, rotation, or pivot.

Returns boolean: true if property has an active animation.

WidgetBase::animationsRunning()

Are animations running

Checks whether any animations are currently playing on this widget.

Returns boolean: true if any animation is active.

Bindings

Method	Description
bind(BindingData, Object)	Connects a supported property key to a signal and returns this widget.

WidgetBase::bind(BindingData, Object)

Bind property to signal

Connects a supported property key to a signal and returns this widget.

Parameter	Type	Description
key	BindingData	Identity key naming the widget property and expected signal type.
signal	Object	Signal that supplies the property's value and receives widget changes.

Returns WidgetBase: This widget for fluent configuration.

Rendering & Caching

Method	Description
renderer(WidgetRender)	Replaces this widget's standard visual with one renderer instance.
renderer()	Returns the custom procedural renderer assigned to this widget, or null if using default drawing.
renderCachingEnabled(boolean)	Enables or disables retained draw command caching for this widget.
renderCachingEnabled()	Checks whether retained draw command caching is active.
invalidateRenderCache()	Marks the retained draw command buffer stale, forcing a record on the next paint pass.
render(RenderContext)	Executes drawing for this widget: evaluates custom renderer or standard content, then draws children.
renderCached(RenderContext)	Replays cached draw commands if valid; otherwise records new commands and caches them.
measure(LayoutContext)	Computes desiredSize based on widget content and LayoutContext constraints.
measureCached(LayoutContext)	Reuses cached desired dimensions if layout constraints match and subtree is not dirty.
arrange(RectView)	Assigns final positioned bounds to this widget and positions child elements.

WidgetBase::renderer(WidgetRender)

Custom renderer

Replaces this widget's standard visual with one renderer instance.

The renderer draws the widget background and content. Framework traversal still paints children. Null restores the standard visual. Style-declared renderers apply only when this slot is empty.

Parameter	Type	Description
renderer	WidgetRender	Per-instance WidgetRender, or null for the standard visual.

Returns WidgetBase: this widget for fluent configuration.

WidgetBase::renderer()

Get renderer

Returns the custom procedural renderer assigned to this widget, or null if using default drawing.

Returns WidgetRender: the active WidgetRender, or null.

WidgetBase::renderCachingEnabled(boolean)

Toggle render caching

Enables or disables retained draw command caching for this widget.

Parameter	Type	Description
enabled	boolean	True to enable retained caching.

Returns WidgetBase: this widget for fluent configuration.

WidgetBase::renderCachingEnabled()

Is render caching enabled

Checks whether retained draw command caching is active.

Returns boolean: true if caching is enabled.

WidgetBase::invalidateRenderCache()

Invalidate render cache

Marks the retained draw command buffer stale, forcing a record on the next paint pass.

Returns WidgetBase: this widget for fluent configuration.

WidgetBase::render(RenderContext)

Render widget

Executes drawing for this widget: evaluates custom renderer or standard content, then draws children.

Parameter	Type	Description
context	RenderContext	RenderContext providing draw canvas and state.

WidgetBase::renderCached(RenderContext)

Render with cache

Replays cached draw commands if valid; otherwise records new commands and caches them.

Parameter	Type	Description
context	RenderContext	RenderContext providing draw canvas and state.

WidgetBase::measure(LayoutContext)

Measure dimensions

Computes desiredSize based on widget content and LayoutContext constraints.

Parameter	Type	Description
context	LayoutContext	LayoutContext providing parent bounds and available space.

WidgetBase::measureCached(LayoutContext)

Measure with cache

Reuses cached desired dimensions if layout constraints match and subtree is not dirty.

Parameter	Type	Description
context	LayoutContext	LayoutContext providing parent bounds and available space.

WidgetBase::arrange(RectView)

Arrange layout bounds

Assigns final positioned bounds to this widget and positions child elements.

Parameter	Type	Description
bounds	RectView	Final positioned bounds rectangle.

Events & Lifecycle

Method	Description
on(EventType, EventListener)	Registers a typed event listener and returns a subscription handle to unregister.
on(EventType, boolean, EventListener)	Registers a typed listener with explicit control over whether cancelled events are received.
emit(Event)	Dispatches an event to listeners registered directly on this widget.
handle(Event)	Dispatches an event and handles standard input routing logic.
invalidate(int)	Marks layout or visual state dirty and bubbles the flags to ancestors.
clearInvalidation(int)	Clears dirty invalidation flags after layout or paint processing completes.
invalidationFlags()	Returns bitmask of pending invalidation flags on this specific widget.
subtreeInvalidationFlags()	Returns combined bitmask of pending invalidation flags in this widget's entire subtree.
tick(FrameContext)	Advances animations, transitions, and time-based state for this frame.
dispose()	Cleans up resources, terminates running animations, and unregisters event listeners.
parent()	Returns the parent container widget, or null if this is a root or unattached widget.
children()	Returns an unmodifiable list of child widgets contained within this widget.
uiContext()	Returns the active UIContext providing window access, scale factor, and input focus.

WidgetBase::on(EventType, EventListener)

Subscribe to event

Registers a typed event listener and returns a subscription handle to unregister.

Parameter	Type	Description
type	EventType	EventType token identifying event class.
listener	EventListener	Callback receiving event instances.

Returns EventSubscription: EventSubscription for cancellation.

WidgetBase::on(EventType, boolean, EventListener)

Subscribe with cancelled events

Registers a typed listener with explicit control over whether cancelled events are received.

Parameter	Type	Description
type	EventType	EventType token identifying event class.
receiveCancelled	boolean	True to receive cancelled events.
listener	EventListener	Callback receiving event instances.

Returns EventSubscription: EventSubscription for cancellation.

WidgetBase::emit(Event)

Emit event

Dispatches an event to listeners registered directly on this widget.

Parameter	Type	Description
event	Event	Event instance to dispatch.

WidgetBase::handle(Event)

Handle event

Dispatches an event and handles standard input routing logic.

Parameter	Type	Description
event	Event	Event instance to dispatch.

WidgetBase::invalidate(int)

Invalidate

Marks layout or visual state dirty and bubbles the flags to ancestors.

Use InvalidationFlags.LAYOUT when measurement or placement changes, and VISUAL for a paint-only change. The call also dirties the retained render cache. NONE does nothing.

Parameter	Type	Description
flags	int	Bit flags from InvalidationFlags, usually LAYOUT, VISUAL, or both.

WidgetBase::clearInvalidation(int)

Clear invalidation flags

Clears dirty invalidation flags after layout or paint processing completes.

Parameter	Type	Description
flags	int	Bit flags from InvalidationFlags, usually LAYOUT, VISUAL, or both.

WidgetBase::invalidationFlags()

Get invalidation flags

Returns bitmask of pending invalidation flags on this specific widget.

Returns int: bitmask of dirty flags.

WidgetBase::subtreeInvalidationFlags()

Get subtree invalidation flags

Returns combined bitmask of pending invalidation flags in this widget's entire subtree.

Returns int: combined bitmask of subtree dirty flags.

WidgetBase::tick(FrameContext)

Tick frame update

Advances animations, transitions, and time-based state for this frame.

Parameter	Type	Description
frame	FrameContext	FrameContext providing delta time and clock.

WidgetBase::dispose()

Dispose widget

Cleans up resources, terminates running animations, and unregisters event listeners.

WidgetBase::parent()

Get parent widget

Returns the parent container widget, or null if this is a root or unattached widget.

Returns Widget: the parent widget, or null.

WidgetBase::children()

Get child widgets

Returns an unmodifiable list of child widgets contained within this widget.

Returns List: list of child widgets.

WidgetBase::uiContext()

Get UI context

Returns the active UIContext providing window access, scale factor, and input focus.

Returns UIContext: active UIContext.