`tecs.ui`

Retained interfaces made from Tecs entities, with layout computed by Taffy.

Style and ChildOf describe a tree. Root supplies its available size; Paint(true) stretches a drawing leaf to its computed box. Shapes, sprites and text draw through the ordinary graphics pipeline. Keep containers at unit scale and put stretched paint on leaves. Write component fields through world:getMut so layout and rendering observe the edit.

tecs.ui.install(world, {width = 800, height = 450})
const root = world:spawn(tecs.ui.Root(), tecs.ui.Style({padding = 16, gap = 12}))
world:spawn(tecs.ecs.ChildOf(root), tecs.ui.Style({width = 120, height = 40}),
    tecs.ui.Paint(true), tecs.gfx.Tint(0.3, 0.6, 1, 1), tecs.gfx.Renderable2D,
    tecs.ui.Interaction())

Layout retains its native tree, measures intrinsic text and images without foreign callbacks, and returns changed boxes. Scrolling clips descendants; interaction supports pointer capture, dragging, focus scopes and activation. Screen roots follow resize, and plugin(app) connects window size and input.

Module contents

Types

Type	Kind	Description
`Dimension`	type	A logical length: pixels, a percent string, or "auto".
`Edges`	type	Per-edge logical lengths; missing edges are automatic.
`Event`	record	A semantic interaction delivered first to its target, then its ancestors.
`Interaction`	type	The value stored by Interaction.
`InteractionOptions`	type	Constructor options for Interaction.
`InteractionState`	type	The value stored by InteractionState.
`InteractionStateOptions`	type	Constructor options for InteractionState.
`Intrinsic`	type	The value stored by Intrinsic.
`IntrinsicOptions`	type	Constructor options for Intrinsic.
`Layout`	type	The value stored by Layout.
`LayoutOptions`	type	Constructor options for Layout.
`Options`	type	Settings for layout, clipping and interaction.
`Paint`	type	The value stored by Paint.
`Root`	type	The value stored by Root.
`RootOptions`	type	Constructor options for Root.
`Scroll`	type	The value stored by Scroll.
`Scrollbar`	type	The value stored by Scrollbar.
`ScrollbarOptions`	type	Constructor options for Scrollbar.
`ScrollOptions`	type	Constructor options for Scroll.
`Style`	type	The value stored by Style.
`StyleOptions`	type	Taffy layout properties.

Functions

Function	Kind	Description
`blur`	function	Clears focus and reports whether an entity was focused.
`focus`	function	Focuses an enabled, focusable entity in the active scope.
`focused`	function	Returns the focused entity, or zero.
`install`	function	Installs retained layout and observes platform events; repeated installation is harmless.
`layouts`	function	Reports native synchronization calls, useful for checking idle layout work.
`plugin`	function	Installs UI using the application's viewport and input.
`popFocusScope`	function	Pops the top scope and restores its previous focus when still valid.
`pushFocusScope`	function	Restricts focus and hit testing to a subtree until popped.
`resize`	function	Updates the logical viewport used by automatic screen roots.
`reveal`	function	Reveals a descendant by scrolling every ancestor viewport.
`update`	function	Runs layout, geometry and pending interaction for the current world state.

Values

Value	Kind	Description
`FocusScope`	variable	Marks a subtree that can own a modal focus scope.
`Interaction`	variable	Constructs Interaction with its default values for omitted fields.
`InteractionState`	variable	Constructs InteractionState with its default values for omitted fields.
`Intrinsic`	variable	Constructs Intrinsic with its default values for omitted fields.
`Layout`	variable	Constructs Layout with its default values for omitted fields.
`Node`	variable	Marks a retained UI node.
`Paint`	variable	Constructs Paint with its default values for omitted fields.
`Root`	variable	Constructs Root with its default values for omitted fields.
`Scroll`	variable	Constructs Scroll with its default values for omitted fields.
`Scrollbar`	variable	Constructs Scrollbar with its default values for omitted fields.
`Style`	variable	Constructs Style with its default values for omitted fields.

Types#

`Dimension`type#

type Dimension = number | string

A logical length: pixels, a percent string, or "auto".

`Edges`type#

type Edges = {
    left: Dimension?,
    right: Dimension?,
    top: Dimension?,
    bottom: Dimension?
}

Per-edge logical lengths; missing edges are automatic.

`Event`record#

record Event
    kind: string
    target: integer
    currentTarget: integer
    x: number
    y: number
    button: integer
    pointerId: string
    pointerType: string
    deltaX: number
    deltaY: number
    source: string
    consumed: boolean
end

@derive(nupp.events.Event)@event(name="tecs.ui.Event")

A semantic interaction delivered first to its target, then its ancestors.

Observed at an entity address, or at address zero after bubbling.

Fields

`kind`#

kind: string

Read-only. Identifies the interaction.

`target`#

target: integer

Read-only. Identifies the original target.

`currentTarget`#

currentTarget: integer

Read-only. Identifies the current bubbling recipient.

`x`#

x: number

Read-only. Reports the pointer position in target pixels.

`y`#

y: number

Read-only. Reports the pointer position in target pixels.

`button`#

button: integer

Read-only. Reports the pointer button.

`pointerId`#

pointerId: string

Read-only. Identifies the pointer, including a touch contact.

`pointerType`#

pointerType: string

Read-only. Identifies mouse, touch, or none.

`deltaX`#

deltaX: number

Read-only. Reports horizontal movement or wheel delta.

`deltaY`#

deltaY: number

Read-only. Reports vertical movement or wheel delta.

`source`#

source: string

Read-only. Identifies pointer, keyboard, controller, or programmatic input.

`consumed`#

consumed: boolean

Caller-writable. Stops bubbling when true.

`Interaction`type#

type Interaction = InteractionValue

The value stored by Interaction.

`InteractionOptions`type#

type InteractionOptions = {
    enabled: (boolean)?,
    focusable: (boolean)?,
    tabIndex: (integer)?,
    order: (integer)?,
    draggable: (boolean)?
}

Constructor options for Interaction.

`InteractionState`type#

type InteractionState = InteractionStateValue

The value stored by InteractionState.

`InteractionStateOptions`type#

type InteractionStateOptions = {
    hovered: (boolean)?,
    pressed: (boolean)?,
    focused: (boolean)?,
    dragging: (boolean)?
}

Constructor options for InteractionState.

`Intrinsic`type#

type Intrinsic = IntrinsicValue

The value stored by Intrinsic.

`IntrinsicOptions`type#

type IntrinsicOptions = {
    source: ("custom" | "text" | "image")?,
    width: (number)?,
    height: (number)?,
    minWidth: (number)?,
    scale: (number)?,
    wrap: (boolean)?
}

Constructor options for Intrinsic.

`Layout`type#

type Layout = LayoutValue

The value stored by Layout.

`LayoutOptions`type#

type LayoutOptions = {
    x: (number)?,
    y: (number)?,
    width: (number)?,
    height: (number)?,
    contentWidth: (number)?,
    contentHeight: (number)?
}

Constructor options for Layout.

`Options`type#

type Options = {
    width: number?,
    height: number?,
    pixelDensity: number?,
    firstClip: integer?,
    lastClip: integer?,
    layer: integer?,
    wheelStep: number?,
    dragThreshold: number?,
    input: Input?,
    inputLayer: Layer?
}

Settings for layout, clipping and interaction.

`Paint`type#

type Paint = PaintValue

The value stored by Paint.

`Root`type#

type Root = RootValue

The value stored by Root.

`RootOptions`type#

type RootOptions = {
    space: ("screen" | "world")?,
    width: (number)?,
    height: (number)?,
    pixelDensity: (number)?,
    sizing: ("auto" | "manual" | "camera")?
}

Constructor options for Root.

`Scroll`type#

type Scroll = ScrollValue

The value stored by Scroll.

`Scrollbar`type#

type Scrollbar = ScrollbarValue

The value stored by Scrollbar.

`ScrollbarOptions`type#

type ScrollbarOptions = {
    axis: ("horizontal" | "vertical")?,
    thickness: (number)?,
    inset: (number)?,
    minLength: (number)?
}

Constructor options for Scrollbar.

`ScrollOptions`type#

type ScrollOptions = {
    x: (number)?,
    y: (number)?,
    contentWidth: (number)?,
    contentHeight: (number)?
}

Constructor options for Scroll.

`Style`type#

type Style = StyleValue

The value stored by Style.

`StyleOptions`type#

type StyleOptions = {
    display: ("flex" | "none" | "grid" | "block")?,
    position: ("relative" | "absolute")?,
    flexDirection: ("row" | "rowReverse" | "column" | "columnReverse")?,
    flexWrap: ("nowrap" | "wrap")?,
    justifyContent: ("start" | "center" | "end" | "spaceBetween" | "spaceAround" | "spaceEvenly")?,
    alignItems: ("stretch" | "center" | "end" | "baseline" | "start")?,
    alignContent: ("stretch" | "center" | "end" | "spaceBetween" | "spaceAround" | "spaceEvenly" | "start")?,
    flexGrow: number?,
    flexShrink: number?,
    flexBasis: Dimension?,
    width: Dimension?,
    height: Dimension?,
    minWidth: Dimension?,
    minHeight: Dimension?,
    maxWidth: Dimension?,
    maxHeight: Dimension?,
    margin: (Dimension | Edges)?,
    padding: (Dimension | Edges)?,
    border: (Dimension | Edges)?,
    gap: Dimension?,
    rowGap: Dimension?,
    inset: (Dimension | Edges)?,
    order: integer?
}

Taffy layout properties. Omitted values use Taffy's flex defaults.

Functions#

`blur`function#

function blur(exclusive world: World): boolean

Clears focus and reports whether an entity was focused.

Arguments

Name	Type	Description
`exclusive world`	`World`	the installed world

Returns

Type	Description
`boolean`	whether focus changed

`focus`function#

function focus(exclusive world: World, entity: integer): boolean

Focuses an enabled, focusable entity in the active scope.

Arguments

Name	Type	Description
`exclusive world`	`World`	the installed world
`entity`	`integer`	the requested entity

Returns

Type	Description
`boolean`	whether focus moved

`focused`function#

function focused(borrows world: World): integer

Returns the focused entity, or zero.

Arguments

Name	Type	Description
`borrows world`	`World`	the installed world

Returns

Type	Description
`integer`	the focused entity

`install`function#

function install(exclusive world: World, options: Options?): nil

Installs retained layout and observes platform events; repeated installation is harmless.

Arguments

Name	Type	Description
`exclusive world`	`World`	the world to install into
`options`	`Options?`	viewport, clip allocation and input settings

Returns

Type	Description
`nil`

`layouts`function#

function layouts(borrows world: World): integer

Reports native synchronization calls, useful for checking idle layout work.

Arguments

Name	Type	Description
`borrows world`	`World`	the installed world

Returns

Type	Description
`integer`	the synchronization count

`plugin`function#

function plugin(exclusive app: Application, options: Options?): nil

Installs UI using the application's viewport and input.

Arguments

Name	Type	Description
`exclusive app`	`Application`	the application whose world hosts the UI
`options`	`Options?`	optional layout and interaction settings

Returns

Type	Description
`nil`

`popFocusScope`function#

function popFocusScope(exclusive world: World, entity: integer?): boolean

Pops the top scope and restores its previous focus when still valid.

Arguments

Name	Type	Description
`exclusive world`	`World`	the installed world
`entity`	`integer?`	the expected scope, or nil

Returns

Type	Description
`boolean`	whether a scope was popped

`pushFocusScope`function#

function pushFocusScope(exclusive world: World, entity: integer): boolean

Restricts focus and hit testing to a subtree until popped.

Arguments

Name	Type	Description
`exclusive world`	`World`	the installed world
`entity`	`integer`	an entity carrying FocusScope

Returns

Type	Description
`boolean`	whether the scope was pushed

`resize`function#

function resize(exclusive world: World, width: number, height: number, density: number?): nil

Updates the logical viewport used by automatic screen roots.

Arguments

Name	Type	Description
`exclusive world`	`World`	the installed world
`width`	`number`	the logical viewport width
`height`	`number`	the logical viewport height
`density`	`number?`	the target pixels per logical point

Returns

Type	Description
`nil`

`reveal`function#

function reveal(exclusive world: World, entity: integer, align: string?): boolean

Reveals a descendant by scrolling every ancestor viewport.

Arguments

Name	Type	Description
`exclusive world`	`World`	the installed world
`entity`	`integer`	the descendant to reveal
`align`	`string?`	nearest, start, center, or end; omitted means nearest

Returns

Type	Description
`boolean`	whether an ancestor scrolled

`update`function#

function update(exclusive world: World): nil

Runs layout, geometry and pending interaction for the current world state.

Arguments

Name	Type	Description
`exclusive world`	`World`	the installed world

Returns

Type	Description
`nil`

Values#

`FocusScope`variable#

const FocusScope

Marks a subtree that can own a modal focus scope.

`Interaction`variable#

const Interaction: ComponentDefinition<InteractionValue>

Constructs Interaction with its default values for omitted fields.

`InteractionState`variable#

const InteractionState: ComponentDefinition<InteractionStateValue>

Constructs InteractionState with its default values for omitted fields.

`Intrinsic`variable#

const Intrinsic: ComponentDefinition<IntrinsicValue>

Constructs Intrinsic with its default values for omitted fields.

`Layout`variable#

const Layout: ComponentDefinition<LayoutValue>

Constructs Layout with its default values for omitted fields.

`Node`variable#

const Node

Marks a retained UI node. The persisted name is UiNode.

`Paint`variable#

const Paint: ComponentDefinition<PaintValue>

Constructs Paint with its default values for omitted fields.

`Root`variable#

const Root: ComponentDefinition<RootValue>

Constructs Root with its default values for omitted fields.

`Scroll`variable#

const Scroll: ComponentDefinition<ScrollValue>

Constructs Scroll with its default values for omitted fields.

`Scrollbar`variable#

const Scrollbar: ComponentDefinition<ScrollbarValue>

Constructs Scrollbar with its default values for omitted fields.

`Style`variable#

const Style: ComponentDefinition<StyleValue>

Constructs Style with its default values for omitted fields.

tecs.ui

Module contents

Types

Functions

Values

Types#

Dimensiontype#

Edgestype#

Eventrecord#

Fields

kind#

target#

currentTarget#

x#

y#

button#

pointerId#

pointerType#

deltaX#

deltaY#

source#

consumed#

Interactiontype#

InteractionOptionstype#

InteractionStatetype#

InteractionStateOptionstype#

Intrinsictype#

IntrinsicOptionstype#

Layouttype#

LayoutOptionstype#

Optionstype#

Painttype#

Roottype#

RootOptionstype#

Scrolltype#

Scrollbartype#

ScrollbarOptionstype#

ScrollOptionstype#

Styletype#

StyleOptionstype#

Functions#

blurfunction#

Arguments

Returns

focusfunction#

Arguments

Returns

focusedfunction#

Arguments

Returns

installfunction#

Arguments

Returns

layoutsfunction#

Arguments

Returns

pluginfunction#

Arguments

Returns

popFocusScopefunction#

Arguments

Returns

pushFocusScopefunction#

Arguments

Returns

resizefunction#

Arguments

Returns

revealfunction#

Arguments

Returns

updatefunction#

Arguments

Returns

Values#

FocusScopevariable#

Interactionvariable#

InteractionStatevariable#

Intrinsicvariable#

Layoutvariable#

`tecs.ui`

`Dimension`type#

`Edges`type#

`Event`record#

`kind`#

`target`#

`currentTarget`#

`x`#

`y`#

`button`#

`pointerId`#

`pointerType`#

`deltaX`#

`deltaY`#

`source`#

`consumed`#

`Interaction`type#

`InteractionOptions`type#

`InteractionState`type#

`InteractionStateOptions`type#

`Intrinsic`type#

`IntrinsicOptions`type#

`Layout`type#

`LayoutOptions`type#

`Options`type#

`Paint`type#

`Root`type#

`RootOptions`type#

`Scroll`type#

`Scrollbar`type#

`ScrollbarOptions`type#

`ScrollOptions`type#

`Style`type#

`StyleOptions`type#

`blur`function#

`focus`function#

`focused`function#

`install`function#

`layouts`function#

`plugin`function#

`popFocusScope`function#

`pushFocusScope`function#

`resize`function#

`reveal`function#

`update`function#

`FocusScope`variable#

`Interaction`variable#

`InteractionState`variable#

`Intrinsic`variable#

`Layout`variable#

`Node`variable#

`Paint`variable#

`Root`variable#

`Scroll`variable#

`Scrollbar`variable#

`Style`variable#