v0.7.1 (build 925)
Koya home

Helix/UserInterface

Reference for element creation, layout, resources, text, animation, measurement, and events.

Import #

import * as UI from 'Helix/UserInterface';
Note

All runtime UI calls are promise-based. Use await UI.*(...). The return types below describe the resolved value (Promise<...> at call site).

Types #

Layout
Parent-driven placement configuration for element children.
  • type 'row' | 'column' | 'grid' | 'none' optional
  • wrap boolean optional
  • wrapLimit number optional
  • gap number optional
  • padding { t?: number, r?: number, b?: number, l?: number } optional
  • justifyContent 'start' | 'center' | 'end' | 'space-between' optional
  • alignItems 'start' | 'center' | 'end' optional
  • gridColumns number optional
  • gridRows number optional
  • columnGap number optional
  • rowGap number optional
  • gridFlowByRow boolean optional
  • gridAlignItems 'start' | 'center' | 'end' optional
  • gridJustifyItems 'start' | 'center' | 'end' | 'space-between' optional
Item
Child sizing and spacing rules inside a parent layout.
  • size { x?: number | 'auto', y?: number | 'auto' } optional
  • margin { t?: number, r?: number, b?: number, l?: number } optional
  • minWidth number optional
  • minHeight number optional
  • maxWidth number optional
  • maxHeight number optional
  • order number optional
  • flexGrow number optional
  • flexShrink number optional
  • alignSelf 'start' | 'center' | 'end' optional
  • gridColumn number optional
  • gridRow number optional
  • gridColumnSpan number optional
  • gridRowSpan number optional

Create, attach, destroy #

createElement
Creates a new UI element. Returns the numeric element id.
  • options accepts layout/renderable settings, child elements, inputOptions, and virtual handlers: onPress, onActivate, onHover, onDrag, onScroll, onLongPress, onDoubleActivate and onTransform.
createElement(windowId, options): Promise<number>
attachRoot
Attaches an element as the root of the window's UI tree.
attachRoot(windowId, id): Promise<boolean>
attach
Attaches a child element to a parent.
attach(windowId, parent, id): Promise<boolean>
detach
Detaches a child element from its parent.
detach(windowId, parent, id): Promise<boolean>
destroyElement
Destroys the subtree rooted at id.
destroyElement(windowId, id): Promise<boolean>
setEnabled
Skips layout, hit-test, and draw when false.
setEnabled(windowId, id, enabled): Promise<boolean>
getRenderable
Returns an opaque handle for the element's renderable. Particle controls in Helix/Renderable require this handle.
getRenderable(windowId, id): Promise<number>

Naming and lookup #

getElementById
Returns numeric id, or -1 when not found.
getElementById(windowId, name): Promise<number>
setElementId
Sets or changes the string name of an element.
setElementId(windowId, id, name): Promise<boolean>

Clipping and masking #

setClipToBounds
Enables or disables rectangular clipping.
setClipToBounds(windowId, id, enabled): Promise<boolean>
setClipToMask
Enables or disables alpha-shape clipping using the element's own renderable.
setClipToMask(windowId, id, enabled): Promise<boolean>
setClipMaskAlphaThreshold
Sets the alpha threshold for mask clipping.
setClipMaskAlphaThreshold(windowId, id, threshold): Promise<boolean>
Note

opacityMode: 'composite' and clipToMask: true on the same element currently falls back to propagate behaviour.

Opacity mode #

setOpacityMode
Sets the opacity blending mode.
  • mode: 'propagate' | 'composite'
  • propagate: parent opacity multiplies descendants before blending.
  • composite: subtree renders to an offscreen target, then parent opacity is applied once to the composited result.
setOpacityMode(windowId, id, mode): Promise<boolean>
Note

Prefer propagate for simple trees when children do not visually overlap (cheaper, avoids extra offscreen pass). Prefer composite when children overlap or self-layer, especially during fades (avoids self-blend artifacts, but more expensive due to offscreen rendering and texture sampling).

Resources and shaders #

setPanelSlice
Sets the nine-slice border thicknesses on a panel renderable. Missing or negative edges become zero.
setPanelSlice(windowId, id, { top, right, bottom, left }): Promise<boolean>
setPanelColour
Sets a panel tint at runtime. Alias: setPanelColor.
  • Accepts RGB/RGBA arrays, { r, g, b, a? } objects, or hex colour strings.
  • Multiplies the frame colour and inherited opacity in stretched, sliced, and cover modes. Use [1,1,1,1] to clear the tint.
  • Resolves true on success; rejects invalid targets. Invalid colour formats throw RangeError.
setPanelColour(windowId, id, colour): Promise<boolean>
setTexture
Sets a texture on an element.
setTexture(windowId, id, path): Promise<boolean>
clearTexture
Removes the texture from an element.
clearTexture(windowId, id): Promise<boolean>
setShader
Sets a custom shader on an element.
  • blend may also be provided as blendMode.
  • Supported blend modes: 'premultiplied-alpha' (default), 'opaque', 'additive', and 'alpha'.
setShader(windowId, id, { vert: string, frag: string, blend?: BlendMode }): Promise<boolean>
clearShader
Removes the custom shader from an element.
clearShader(windowId, id): Promise<boolean>
setShaderParams
Sets per-window global shader parameters.
  • params: { v0?: [x,y,z,w], v1?: [x,y,z,w] }
setShaderParams(windowId, params): Promise<boolean>
setElementShaderParams
Sets per-element shader parameter overrides.
  • params: { v0?: [x,y,z,w], v1?: [x,y,z,w] }
setElementShaderParams(windowId, id, params): Promise<boolean>

Text helpers #

setTextString
Sets the text content of a text renderable.
setTextString(windowId, id, text): Promise<boolean>
setTextSize
Sets the font size in pixels.
setTextSize(windowId, id, px): Promise<boolean>
setTextLetterSpacing
Sets the letter spacing factor.
setTextLetterSpacing(windowId, id, factor): Promise<boolean>
setTextLineSpacing
Sets the line spacing factor.
setTextLineSpacing(windowId, id, factor): Promise<boolean>
setTextColour
Sets the text colour.
setTextColour(windowId, id, colour): Promise<boolean>
addColourArea
Paints the half-open Unicode character range [start, end) and returns a stable area ID. The latest overlapping area wins.
addColourArea(windowId, id, start, end, colour): Promise<number>
listColourAreas
Lists text colour areas in insertion order.
listColourAreas(windowId, id): Promise<Array<{ id, start, end, colour }>>
deleteColourArea
Deletes a text colour area, revealing any earlier overlap or the base colour.
deleteColourArea(windowId, id, areaId): Promise<boolean>
setTextFont
Sets the font by file path.
setTextFont(windowId, id, fontPath): Promise<boolean>
setTextJustify
Sets horizontal text justification.
  • justify: 'left' | 'center' | 'right'
setTextJustify(windowId, id, justify): Promise<boolean>
setTextVerticalAlign
Sets vertical text alignment.
  • align: 'start' | 'center' | 'end'
setTextVerticalAlign(windowId, id, align): Promise<boolean>
setTextMetricsBasis
Sets which bounds basis content alignment uses for text.
  • basis: 'line' | 'ink'
  • ink (default): tighter visual glyph bounds for static labels.
  • line: stable line-box metrics for editable/input text.
setTextMetricsBasis(windowId, id, basis): Promise<boolean>
setFontOptions
Sets font rendering options.
  • options: { mipmaps?: boolean, lightHinting?: boolean }
setFontOptions(windowId, fontKey, options): Promise<boolean>

Content alignment and positioning #

setContentAlign
Sets where the renderable sits inside the layout slot.
  • align: { x?: 'start' | 'center' | 'end', y?: 'start' | 'center' | 'end' } | 'fill'
setContentAlign(windowId, id, align): Promise<boolean>
setContentPositioning
Sets the content positioning mode.
  • mode: 'raw' | 'contain'
setContentPositioning(windowId, id, mode): Promise<boolean>

Layout placement #

setLayoutPosition
Sets the element's child-layout absolute position (item.absolutePosition) in pixels.
setLayoutPosition(windowId, id, point): Promise<boolean>
setLayoutAABB
Sets the element's child-layout absolute rectangle (item.absoluteAABB).
setLayoutAABB(windowId, id, bounds): Promise<boolean>
Note

setPosition() updates renderable transform only. Use setLayoutPosition() / setLayoutAABB() when you need layout-space placement.

Animation #

addAnimation
Adds a keyframe animation to an element. Returns the animation id.
addAnimation(windowId, elementId, frames): Promise<number>
updateAnimation
Replaces an animation's full keyframe definition without changing its id or completion callback. An active animation restarts immediately, using its current visible pose when the replacement has no explicit zero-time frame.
updateAnimation(windowId, elementId, animationId, frames): Promise<boolean>
startAnimation
Starts a previously added animation.
startAnimation(windowId, elementId, animationId): Promise<boolean>
stopAnimation
Stops the running animation on an element.
stopAnimation(windowId, elementId): Promise<boolean>
onAnimationEnd
Registers a callback invoked when the given animation finishes.
onAnimationEnd(windowId, elementId, animationId, cb): Promise<boolean>
Note

Supported easing: inQuad, outQuad, inOutQuad, inCubic, outCubic, inOutCubic, inQuart, outQuart, inOutQuart, inQuint, outQuint, inOutQuint. Easing is destination-based: ease on a keyframe controls the transition from the previous keyframe into that keyframe.

Dynamic t:0 behaviour: if an animation has no keyframe at time: 0.0, startAnimation injects a runtime t:0 frame from the element's current visual state so clip-to-clip transitions remain continuous. If a keyframe at time: 0.0 is authored, the authored frame is used and no dynamic capture is applied.

Measurement #

getRenderableBounds
Returns the local AABB: { min, max, centre, size }.
getRenderableBounds(windowId, id): Promise<Rect>
getRenderableSize
Returns { x: width, y: height }.
getRenderableSize(windowId, id): Promise<Point>
measureText
Returns metrics for the text currently rendered by a text element.
  • Uses the existing text renderable state (string, font, spacing, style).
  • id must reference a text renderable.
measureText(windowId, id): Promise<{ size: Point, lineAdvance: number, lineCount: number }>
getTextCaretPosition
Returns local caret position for a codepoint index in the currently rendered text.
  • index is clamped to valid codepoint range.
  • id must reference a text renderable.
getTextCaretPosition(windowId, id, index): Promise<Point>
hitTestText
Returns the nearest caret codepoint index for a local point in the currently rendered text.
  • localPoint: { x, y } in element-local coordinates.
  • id must reference a text renderable.
hitTestText(windowId, id, localPoint): Promise<number>
getElementFrame
Returns the layout-computed bounds.
getElementFrame(windowId, id): Promise<Rect>

Event handlers (runtime) #

setHitTarget
Enables or disables hit-testing for the element.
setHitTarget(windowId, id, enabled): Promise<boolean>
Note

Virtual handlers enable hit testing and receive one event object. See /helix-input for recognition and ownership.

Virtual handlers receive one typed interaction event. See /helix-input for phases, capture, coordinates, recognition options and cancellation.

Virtual input setters are setOnPress, setOnActivate, setOnHover, setOnDrag, setOnScroll, setOnLongPress, setOnDoubleActivate, setOnTransform and setInputOptions. See /helix-input for their shared event contract.

<- Native scrollingHelix/Geometry ->