1681-engine / ui / UiRoot

Class: UiRoot

Defined in: src/ui/UiRoot.ts:49

The canvas UI's root, on the stage's screen layer above the world: it pins HUD pieces to screen corners and keeps them there on resize, owns keyboard/gamepad focus, ticks only the widgets that are moving, opens modals with a focus trap, and keeps presses on widgets from reaching the world (UiPointerGate).

const ui = new UiRoot(engine.stage, { parent: scene.hud }); // goes when the scene does
ui.pin(healthBar, 'top-left', 8);
// in a fixed step, between actions.poll() and endStep():
if (!ui.handleInput(actions) && !ui.capturesInput) movePlayer();

Extends

• Container

Implements

• UiHost

Constructors

Constructor

new UiRoot(stage, options?): UiRoot;

Defined in: src/ui/UiRoot.ts:60

Parameters

Parameter	Type
stage	Stage
options	UiRootOptions

Returns

UiRoot

Overrides

Container.constructor

Properties

focus

readonly focus: FocusManager;

Defined in: src/ui/UiRoot.ts:52

---

isUiHost

readonly isUiHost: true = true;

Defined in: src/ui/UiRoot.ts:50

Implementation of

UiHost.isUiHost

---

pixelPerfect

readonly pixelPerfect: boolean;

Defined in: src/ui/UiRoot.ts:51

Lay out and draw on whole pixels.

Implementation of

UiHost.pixelPerfect

Accessors

capturesInput

Get Signature

get capturesInput(): boolean;

Defined in: src/ui/UiRoot.ts:80

A modal is open or a widget has focus: the game should leave its own actions alone this step.

Returns

boolean

---

viewport

Get Signature

get viewport(): Size;

Defined in: src/ui/UiRoot.ts:75

The screen's size in screen pixels.

Returns

Size

Methods

animate()

animate(t): void;

Defined in: src/ui/UiRoot.ts:138

Ticks t every frame until it reports it has settled: only what moves costs a frame.

Parameters

Parameter	Type
t	UiTicking

Returns

void

Implementation of

UiHost.animate

---

closeModal()

closeModal(modal): void;

Defined in: src/ui/UiRoot.ts:121

Parameters

Parameter	Type
modal	UiModal

Returns

void

---

destroy()

destroy(): void;

Defined in: src/ui/UiRoot.ts:148

Removes all internal references and listeners as well as removes children from the display list. Do not use a Container after calling destroy.

Returns

void

Example

container.destroy();
container.destroy(true);
container.destroy({ children: true });
container.destroy({ children: true, texture: true, textureSource: true });

Overrides

Container.destroy

---

handleInput()

handleInput(input): boolean;

Defined in: src/ui/UiRoot.ts:130

Reads one step of navigation input (call between actions.poll() and endStep()); true when the UI used it.

Parameters

Parameter	Type
input	NavInput

Returns

boolean

---

invalidateFocus()

invalidateFocus(): void;

Defined in: src/ui/UiRoot.ts:134

A widget became focusable or stopped being (added, removed, enabled, hidden): the focus list is stale.

Returns

void

Implementation of

UiHost.invalidateFocus

---

layout()

layout(): void;

Defined in: src/ui/UiRoot.ts:102

Places every pinned piece and open modal again (after one changed size; resizes do it by themselves).

Returns

void

---

openModal()

openModal(modal): void;

Defined in: src/ui/UiRoot.ts:113

Opens a modal over everything: focus is trapped inside it until it closes.

Parameters

Parameter	Type
modal	UiModal

Returns

void

---

pin()

pin(
   child, 
   anchor, 
   margin?
): this;

Defined in: src/ui/UiRoot.ts:85

Adds child and keeps it pinned to a screen anchor, margin in from the edges, through every resize.

Parameters

Parameter	Type	Default value
child	Container	undefined
anchor	ScreenAnchor	undefined
margin	number | Partial<Insets>	0

Returns

this

---

unpin()

unpin(child): this;

Defined in: src/ui/UiRoot.ts:95

Parameters

Parameter	Type
child	Container

Returns

this

---

update()

update(dtMs): void;

Defined in: src/ui/UiRoot.ts:143

Ticks what is moving; called by the ticker, or by a game driving the UI itself.

Parameters

Parameter	Type
dtMs	number

Returns

void