final class UIRoot

package smidr

extends Sprite

@:directlyUsed@:build(openfl.utils._internal.AssetsMacro.initBinding())@:autoBuild(openfl.utils._internal.AssetsMacro.initBinding())

The library's stage-attached root: three layers (content < popupLayer < tooltipLayer), the invalidation scheduler, the pointer arbiter and the tween/tooltip driver.

One ENTER_FRAME handler flushes dirty widgets and steps tweens — an idle UI performs no work. Global mouse listeners (capture phase) maintain UIPointer.overUI/downOnUI so the host game layer can ignore pointer input that belongs to the UI, complete press-started clicks, and route drag capture. A key listener routes typing to UIFocus and consumes handled keys before they reach the host.

The host positions the root over its game viewport with setViewport (offset + scale) so UI coordinates match game coordinates under any letterboxing.

Static variables

@:value(null)staticread onlycurrent:UIRoot = null

The active root (one per state/screen).

staticread onlyoverlayOpen:Bool

true while any transient overlay (popup/menu/modal) is open.

@:value(500)statictooltipDelayMs:Float = 500

Hover-delay before a tooltip appears, in ms.

staticread onlytooltipTarget:UIComponent

The widget currently awaiting/showing a tooltip.

@:value(null)staticonTooltipHide:() ‑> Void = null

Fired when the hovered widget is left/pressed; assigned by the tooltip widget.

@:value(null)staticonTooltipShow:UIComponent ‑> Void = null

Fired when the hover delay elapses; assigned by the tooltip widget.

Static methods

staticaddTicker(fn:Float ‑> Void):Void

Registers a per-frame callback (held-repeat, caret blink). Keep these rare — an idle UI should have no tickers running.

Parameters:

fn

receives the elapsed milliseconds each frame

staticpushOverlayCloser(fn:() ‑> Void):Void

Pushes a closer for the topmost transient overlay (popup/menu/modal); Escape pops it.

Parameters:

fn

closes the overlay when invoked

staticremoveOverlayCloser(fn:() ‑> Void):Void

Removes a previously pushed overlay closer (call when the overlay closes itself).

Parameters:

fn

the same function passed to pushOverlayCloser

staticremoveTicker(fn:Float ‑> Void):Void

Removes a per-frame callback.

Parameters:

fn

the same function passed to addTicker

staticschedule(c:UIComponent):Void

Queues a widget repaint for the next frame (deduplicated).

Parameters:

c

the widget whose render() should run on the next flush

Constructor

new()

Variables

finalcontent:Sprite

Regular widget layer.

finalpopupLayer:Sprite

Dropdown popups, menus, modals — always above content.

finaltooltipLayer:Sprite

The shared tooltip — always on top.

Methods

@:value({ index : -1 })attach(parent:DisplayObjectContainer, index:Int = -1):Void

Adds the root to a display parent.

Parameters:

parent

the container to attach to (typically above the game view)

index

optional child depth; -1 appends on top

containsTarget(obj:DisplayObject):Bool

Whether a display object sits inside this UI tree (walks the parent chain).

Parameters:

obj

the event target to test

Returns:

true when obj is this root or one of its descendants

dispose():Void

Full teardown: listeners, layers, statics. Call from the host state's destroy.

invalidateAll():Void

Re-renders every live widget (theme/locale change).

setViewport(offsetX:Float, offsetY:Float, scaleX:Float, scaleY:Float):Void

Positions/scales the root over the host's content viewport, so UI coordinates match the host's coordinate space under any letterboxing.

Parameters:

offsetX

viewport left edge in stage pixels

offsetY

viewport top edge in stage pixels

scaleX

horizontal stage-pixels-per-unit factor

scaleY

vertical stage-pixels-per-unit factor