koya-ui
Object-oriented Window and Element wrappers over the raw Koya engine APIs.
Import #
import { Window, Element, createWindow, createElement } from '/rom/std/koya-ui.js';koya-ui also re-exports InputText, Button, ScrollView, and blurAll from koya-controls, so a single import can cover everything.
Window #
Wraps a compositor surface. Create with the async factory; the constructor is private.
const win = await Window.create({
role: 'overlay',
anchor: 'top-left',
title: 'My App',
size: { x: 800, y: 600 },
keyboardInteractivity: 'on_demand'
});
const el = await win.createElement({ renderable: { type: 'box', colour: [1, 0.5, 0, 1] } });
await win.attach(el);
await win.render();Window functions #
Window.create
Creates a new compositor window and returns a
Window instance.options.role:'window' | 'bar' | 'overlay' | 'background' | 'lock' | 'raw'— Required surface role.options.title:string— Window title.options.appId:string— Application identifier for the window manager.options.size:{ x, y }— Initial dimensions in pixels.options.anchor:string— Layer-shell anchor string.options.offset:{ x, y }— Layer-shell offset.options.state:{ maximized?, fullscreen? }— Initial window state.options.keyboardInteractivity:'none' | 'exclusive' | 'on_demand'— Keyboard focus mode.options.acceptPointerEvents:boolean— Whether the surface accepts pointer input.options.deviceSelector:(request) => string | PromiseLike<string>— Per-window Vulkan device selection with a five-second deadline. Example:({ devices, preferredDeviceId }) => devices.find(d => d.type === 'discrete' && d.suitable)?.id ?? preferredDeviceId.
Window.create(options: WindowOptions): Promise<Window>render
Submits the current frame for rendering.
window.render(): Promise<boolean>destroy
Destroys the window and frees compositor resources.
window.destroy(): Promise<boolean>startDrag
Starts a MIME byte drag while a pointer or touch contact is held on this window.
window.startDrag(options: { data: Record<string, Uint8Array>, actions?: ('copy' | 'move')[] }): Promise<boolean>cancelDrag
Cancels a drag started by this window.
window.cancelDrag(): Promise<boolean>setDropTarget
Registers a window fallback drop target. Options include mimeTypes, actions and onEnter/onOver/onLeave/onDrop callbacks.
window.setDropTarget(options: DropTargetOptions | null): Promise<boolean>info
Returns compositor-level information about the window (size, output, scale).
window.info(): Promise<object>elevate
Raises the window above other surfaces.
window.elevate(): Promise<boolean>lower
Lowers the window below other surfaces.
window.lower(): Promise<boolean>attach
Attaches an element as the root of this window's UI tree.
window.attach(element: Element | number): Promise<boolean>getElementById
Looks up an element by its string or numeric ID. Returns
null if not found.window.getElementById(id: string | number): Promise<Element | null>createElement
Shorthand for
Element.create(window, options). Returns an Element bound to this window.window.createElement(options?: object): Promise<Element>setTitle
Updates the window title.
window.setTitle(value: string): Promise<boolean>setAppId
Sets the application identifier.
window.setAppId(value: string): Promise<boolean>setFullscreen
Toggles fullscreen mode.
window.setFullscreen(value: boolean): Promise<boolean>setMaximized
Toggles maximised state.
window.setMaximized(value: boolean): Promise<boolean>setSize
Resizes the window. Throws if value is not a valid
{ x, y } object.window.setSize(value: { x, y }): Promise<boolean>setKeyboardInteractivity
Sets keyboard focus mode:
'none', 'exclusive', or 'on_demand'.window.setKeyboardInteractivity(value: string): Promise<boolean>setPointerEvents
Enables or disables pointer event delivery to this surface.
window.setPointerEvents(value: boolean): Promise<boolean>setCursor
Sets the cursor shape for this window (e.g.
'pointer', 'text', 'default').window.setCursor(value: string): Promise<boolean>setRenderingEnabled
Pauses or resumes rendering for the window.
window.setRenderingEnabled(value: boolean): Promise<boolean>setClearColor
Sets the window background clear colour. Accepts an RGBA array or object.
window.setClearColor(value: [r,g,b,a] | { r, g, b, a? }): Promise<boolean>Element #
Wraps a UI element with its internal numeric ID and provides named animation management, handler registration, and property setters. Create via the async factory or from an existing ID.
const box = await win.createElement({
renderable: { type: 'box', colour: [0.2, 0.6, 1.0, 1.0] },
item: { size: { x: 100, y: 100 } }
});
await win.attach(box);
await box.addAnimation('pulse', [
{ time: 0.0, scale: { x: 1, y: 1 } },
{ time: 0.5, scale: { x: 1.2, y: 1.2 }, ease: 'inOutQuad' },
{ time: 1.0, scale: { x: 1, y: 1 }, ease: 'inOutQuad', looping: true }
]);
await box.startAnimation('pulse');Element construction #
Element.create
Creates a new element within the given window. If
options is a bare number, wraps an existing element ID instead.Element.create(window: Window | number, options?: object): Promise<Element>Element.fromId
Wraps an existing engine element ID as an
Element instance without creating a new element.Element.fromId(window: Window | number, id: number): Promise<Element>Tree and lifecycle #
attach
Attaches this element as a child of
parent.element.attach(parent: Element | number): Promise<boolean>detach
Detaches this element from
parent.element.detach(parent: Element | number): Promise<boolean>destroy
Destroys the element and releases engine resources.
element.destroy(): Promise<boolean>startDrag
Starts a MIME byte drag from the element's window during an active pointer or touch press.
element.startDrag(options: { data: Record<string, Uint8Array>, actions?: ('copy' | 'move')[] }): Promise<boolean>setDropTarget
Registers or clears this element as a drop target. Options include mimeTypes, actions and onEnter/onOver/onLeave/onDrop callbacks.
element.setDropTarget(options: DropTargetOptions | null): Promise<boolean>Queries #
getFrame
Returns the computed position and size of the element after layout.
element.getFrame(): Promise<{ x, y, w, h }>getRenderableSize
Returns the natural size of the element's renderable content.
element.getRenderableSize(): Promise<{ x, y }>Properties #
setEnabled
Shows or hides the element.
element.setEnabled(value: boolean): Promise<boolean>setClipToBounds
Enables or disables rectangular clipping to the element bounds.
element.setClipToBounds(value: boolean): Promise<boolean>setHitTarget
Marks the element as a pointer hit target. Automatically set when a mouse handler is assigned.
element.setHitTarget(value: boolean): Promise<boolean>setPosition
Sets the element position relative to its parent.
element.setPosition(value: { x, y }): Promise<boolean>setLayoutSize
Overrides the element's layout size.
element.setLayoutSize(value: { x, y }): Promise<boolean>setContentAlign
Sets content alignment within the element bounds. Values:
'start', 'centre', 'end'.element.setContentAlign(value: { x?, y? }): Promise<boolean>Text #
setTextString
Sets the displayed text on a text renderable.
element.setTextString(value: string): Promise<boolean>setTextSize
Sets the font size in pixels.
element.setTextSize(value: number): Promise<boolean>setTextLetterSpacing
Adjusts horizontal spacing between characters.
element.setTextLetterSpacing(value: number): Promise<boolean>setTextLineSpacing
Adjusts vertical spacing between lines.
element.setTextLineSpacing(value: number): Promise<boolean>setTextColour
Sets the text colour as an RGBA array.
element.setTextColour(value: [r,g,b,a]): Promise<boolean>addColourArea
Paints Unicode character indices in
[start, end) and returns a stable area ID. Newer overlapping areas take precedence.element.addColourArea(start: number, end: number, colour: Colour): Promise<number>listColourAreas
Lists the element's text colour areas in insertion order.
element.listColourAreas(): Promise<Array<{ id, start, end, colour }>>deleteColourArea
Deletes an area, revealing an earlier overlapping area or the animatable base colour.
element.deleteColourArea(areaId: number): Promise<boolean>setTextFont
Sets the font family name.
element.setTextFont(value: string): Promise<boolean>setTextJustify
Sets horizontal text justification:
'left', 'center', or 'right'.element.setTextJustify(value: string): Promise<boolean>setTextVerticalAlign
Sets vertical text alignment:
'top', 'middle', or 'bottom'.element.setTextVerticalAlign(value: string): Promise<boolean>Circle #
setCircleColour
Sets the tint colour on a circle renderable.
element.setCircleColour(value: [r,g,b,a]): Promise<boolean>setCircleInset
Sets the ring thickness.
0 = filled, > 0 = ring.element.setCircleInset(value: number): Promise<boolean>setCircleStart
Sets the start angle in degrees.
element.setCircleStart(value: number): Promise<boolean>setCircleEnd
Sets the end angle in degrees.
element.setCircleEnd(value: number): Promise<boolean>setCircleResolution
Sets the number of sides used to approximate the circle.
element.setCircleResolution(value: number): Promise<boolean>setCircleRect
Sets the outer bounds AABB. Square gives a circle; non-square gives an ellipse.
element.setCircleRect(value: { min: { x, y }, max: { x, y } }): Promise<boolean>Resources #
setPanelSlice
Sets the nine-slice border thicknesses on a panel renderable.
element.setPanelSlice(value: { top, right, bottom, left }): Promise<boolean>setPanelColour
Sets the panel tint, multiplying its frame colour. Accepts RGB/RGBA arrays, colour objects, and hex strings. Alias: setPanelColor.
element.setPanelColour(value): Promise<boolean>setTexture
Assigns a texture to the element. Pass
null or falsy to clear.element.setTexture(value: string | null): Promise<boolean>clearTexture
Removes the current texture from the element.
element.clearTexture(): Promise<boolean>setShader
Assigns a shader to the element. Pass
null or falsy to clear.element.setShader(value: string | null): Promise<boolean>clearShader
Removes the current shader from the element.
element.clearShader(): Promise<boolean>setShaderParams
Sets shader uniform parameters.
element.setShaderParams(value: object): Promise<boolean>Mouse handlers #
Each setter accepts a callback or null to remove the handler. Assigning a handler automatically enables hitTarget on the element. Move callbacks receive (window, local), button callbacks receive (window, local, button), and scroll callbacks receive (window, local, delta).
Animations #
Element maintains a local name-to-ID registry so you can refer to animations by name instead of tracking numeric IDs.
addAnimation
Registers an animation under
name and returns the engine animation ID. If an onAnimationEnd callback was previously bound to this name, it is automatically wired up.element.addAnimation(name: string, frames: AnimationFrame[]): Promise<number>updateAnimation
Replaces a named animation's complete keyframe definition and returns its unchanged engine ID. Active animations restart immediately, transitioning from the visible pose when no explicit zero-time frame is supplied.
element.updateAnimation(nameOrId: string | number, frames: AnimationFrame[]): Promise<number>startAnimation
Starts a previously added animation by name or engine ID. Pass
restart: false to skip restarting if the same animation is already running.element.startAnimation(nameOrId: string | number, restart?: boolean): Promise<number>stopAnimation
Stops the currently running animation on this element.
element.stopAnimation(): Promise<void>onAnimationEnd
Binds a callback that fires when the named animation completes. Pass
null to remove. Returns the engine animation ID.element.onAnimationEnd(nameOrId: string | number, callback: function | null): Promise<number>getAnimationId
Returns the engine animation ID for a given name, or
-1 if unknown. Synchronous.element.getAnimationId(name: string): numberhasAnimation
Returns
true if an animation with the given name has been added. Synchronous.element.hasAnimation(name: string): booleanlistAnimations
Returns an array of all registered animation names. Synchronous.
element.listAnimations(): string[]Convenience functions #
Top-level shortcuts exported alongside the classes.
createWindow
Alias for
Window.create(options).createWindow(options?: WindowOptions): Promise<Window>createElement
Alias for
Element.create(window, options).createElement(window: Window | number, options?: object): Promise<Element>Interop with raw APIs #
Both Window and Element expose a numeric .id property that maps directly to the engine handle. You can pass these IDs to any Koya/Compositor or Helix/UserInterface call when you need functionality not yet wrapped by the standard library.
import * as UI from 'Helix/UserInterface';
import { Window } from '/rom/std/koya-ui.js';
const win = await Window.create({ role: 'window', size: { x: 400, y: 300 } });
// Use the raw API with the wrapper's ID
const metrics = await UI.measureText(win.id, someElement.id);Virtual input setters are setOnPress, setOnActivate, setOnHover, setOnDrag, setOnScroll, setOnLongPress, setOnDoubleActivate, setOnTransform and setInputOptions. See /helix-input for their shared event contract.
Native scrolling #
Element creation accepts scroll: true or scroll: {axis: "y"}. element.setScroll(options), element.scrollTo({x,y}), element.stopScroll(), and element.getScrollOffset() return promises and use the native engine. Native scrolling documents options, units, and lifecycle events. For an owned viewport/content pair use the ScrollView standard control.