Element

Base class for everything visible in Basalt 2.

Types

ElementPositionMode

ElementPositionMode = "flow"|"absolute"

ElementAlignment

ElementAlignment = "start"|"center"|"end"|"stretch"

ElementEventHandler<T>

ElementEventHandler<T> = fun(self: T, ...: any)

ElementBindingOptions

Field	Type	Description
fromState (optional)	fun(value: any, element: Element): any	State-to-property transform
toState (optional)	fun(value: any, element: Element, ...: any): any	Property-to-state transform
event (optional)	string	Event used for two-way updates
twoWay (optional)	boolean	Whether writable state is updated from the element

Properties

Property	Type	Default	Description
x	number	1	horizontal position, parent-local, 1-based
y	number	1	vertical position, parent-local, 1-based
z	number	0	Stacking order among siblings; higher z renders on top
width	number	1	number, basalt.auto/fill/percent or dynamic
height	number	1	number, basalt.auto/fill/percent or dynamic
minWidth	number|false	false	layout constraint, false = none
maxWidth	number|false	false	layout constraint, false = none
minHeight	number|false	false	layout constraint, false = none
maxHeight	number|false	false	layout constraint, false = none
position	ElementPositionMode	"flow"	"flow" or "absolute" (flex layouts)
alignSelf	ElementAlignment|false	false	per-child cross-axis override
shrink	number|false	false	may shrink below its desired size
visible	boolean	true	Hidden elements are neither rendered nor hit by events
background	number|false	false	colors.*, basalt.rgb or false = transparent
foreground	number	colors.white	text color
name	string	""	lookup key for find() and reactive refs
disabled	boolean	false	Disabled elements ignore all input; mirrored to the "disabled" state

Events

Event	Registrar	Description
click	:onClick(fn)	Fired on mouse press with (button, x, y) in local coordinates
clickUp	:onClickUp(fn)	Fired on mouse release with (button, x, y), also when released outside
drag	:onDrag(fn)	Fired while dragging with (button, x, y) relative to the element
scroll	:onScroll(fn)	Fired on mouse wheel with (direction, x, y)
focus	:onFocus(fn)	Fired when the element gains keyboard focus
blur	:onBlur(fn)	Fired when the element loses keyboard focus
key	:onKey(fn)	Fired on key press with the key code (while focused)
keyUp	:onKeyUp(fn)	Fired on key release with the key code
char	:onChar(fn)	Fired on character input with the typed character
paste	:onPaste(fn)	Fired on ctrl+v with the pasted text
stateChange	:onStateChange(fn)	Fired when a named state toggles, with (stateName, active)
mouseEnter	:onMouseEnter(fn)	Fired when the pointer moves onto the element
mouseLeave	:onMouseLeave(fn)	Fired when the pointer leaves the element
layout	:onLayout(fn)	Fired before children are laid out, with (width, height)

Methods

Element:setup()

Per-instance initialization; subclasses override and call Element.setup.

Element:setState(stateName, active)

Activates or deactivates a named state. State changes are idempotent.

• stateName (string) The state name (e.g. "hover", "checked")

• active (boolean, optional) false or nil deactivates the state

• returns (self)

Element:hasState(stateName)

Returns whether a named state is active.

• stateName (string) State name

• returns active (boolean)

Element:toggleState(stateName)

Toggles a named state.

• stateName (string) State name

• returns (self)

Element:getStates()

Returns active state names sorted alphabetically.

• returns states (string[])

Element:setStateStyle(stateName, props, priority)

Defines per-element property overrides for a state.

• stateName (string) The state the style applies to

• props (table<string, any>) Property overrides while the state is active

• priority (number, optional) Optional state priority override

• returns (self)

btn:setStateStyle("hover", { background = colors.blue })

Element:setStatePriority(stateName, priority)

Overrides the resolution priority of a named state.

• stateName (string) State name

• priority (number) Higher priorities win

• returns (self)

Element:apply(props)

Applies properties and onX callback entries from a table.

• props (table<string, any>) Property/callback map

• returns (self)

Element:raw(propName)

Returns an authored property without resolving state/functions/signals.

• propName (string) Property name

• returns value (any)

Element:on(eventName, fn)

Registers an event handler; fn(self, ...) runs on every fire.

• self (T)

• eventName (string) The event name (e.g. "click", "change")

• fn (ElementEventHandler<T>) The handler

• returns self (T)

Element:off(eventName, fn)

Removes one registered event handler.

• self (T)

• eventName (string) Event name

• fn (ElementEventHandler<T>) Previously registered handler

• returns self (T)

Element:bind(propName, source, options)

Binds a property to a State/Computed value with optional two-way mapping.

• propName (string) Property name

• source (Signal|Computed) State or computed value

• options (ElementBindingOptions|fun(value: any, element: Element): any, optional) Binding options or fromState transform

• returns (self)

Element:unbind(propName, keepCurrent)

Removes a property binding.

• propName (string) Property name

• keepCurrent (boolean, optional) false restores the class/default value

• returns (self)

Element:fire(eventName, ...)

Fires an event synchronously on all registered handlers.

• eventName (string) Event name

• ... (any) Event arguments

• returns handled (boolean) True when handlers existed

Element:markDirty()

Marks the UI tree this element belongs to as needing a redraw. Only the root's flag matters: the tree is redrawn as a whole and the line diff in the render buffer keeps the actual terminal IO minimal.

• returns (self)

Element:markRenderDirty()

Marks only the retained render tree dirty. Scrolling and paint-only state changes use this path so cached layout remains valid.

• returns (self)

Element:invalidateLayout(propName)

Invalidates cached layout/content bounds for this element's container chain. Paint-only properties deliberately skip this expensive path.

• propName (string, optional) Changed property, if known

• returns (self)

Element:markLayoutDirty()

Invalidates layout and marks the retained render tree dirty.

• returns (self)

Element:contains(px, py)

Tests parent-local coordinates against this element's bounds.

• px (number) Parent-local x

• py (number) Parent-local y

• returns inside (boolean)

Element:getRoot()

Returns the root element of this UI tree.

• returns root (Element)

Element:getAbsolutePosition()

Returns terminal-local coordinates after ancestor scroll offsets.

• returns x (number)
• returns y (number)

Element:measure(_availableWidth, _availableHeight)

Returns the intrinsic size used by basalt.auto(). Elements with content override this; the base implementation keeps numeric authored dimensions.

• _availableWidth (number, optional) Space offered by the parent

• _availableHeight (number, optional) Space offered by the parent

• returns width (number)

• returns height (number)

Element:focus()

Gives this element keyboard focus.

• returns (self)

Element:setCursor(x, y, blink, color)

Requests a cursor using element-local coordinates.

• x (number) Local x

• y (number) Local y

• blink (boolean) Cursor blink state

• color (number, optional) Cursor color

• returns (self)

Element:destroy()

Removes this element from its parent.

• returns (self)

Element:render(buf)

Draws the element into the buffer (local coordinates, pre-clipped).

• buf (Render) Render buffer

Element:handleMouse(event, btn, x, y)

Handles a positional mouse event in local coordinates. Returns the consuming element, or nil to let it pass through.

• event (string) Mouse event name

• btn (number) Mouse button or scroll direction

• x (number) Local x coordinate

• y (number) Local y coordinate

• returns consumer (Element|nil)

Element:handleKey(event, a, b)

Handles a keyboard event (element must be focused).

• event (string) Keyboard event name
• a (any) Key code or text
• b (any, optional) Secondary event value