UI/Foundations - Koya Documentation

What this page covers #

UI/Foundations is the conceptual map for the UI reference set. Read this first if you are unsure which page controls a specific behaviour.

By task #

Build or attach UI trees: see Helix/UserInterface
Make elements line up or fill space: see Layout ownership
Align content inside a slot: see Content alignment ownership
Animate visuals without affecting layout: see Animation ownership
Debug pointer/click behaviour: see Event ownership

Import + API page #

Helix/UserInterface is the import-mapped API page:

API reference: Helix/UserInterface

Ownership model #

The easiest way to reason about UI is to ask: which layer owns this behaviour?

Layout ownership #

Parent layout owns child slot placement (row, column, grid, none).
Child item owns participation in parent layout (size, margin, order, grow/shrink, grid placement).
Visual transforms (position, scale, rotation) are applied after layout and do not change flow decisions.

Deep dive: UI/Layout

Content alignment ownership #

contentAlign controls where the renderable sits inside the child slot.
contentPositioning controls whether renderable placement is clamped (contain) or raw.
Text has glyph alignment (justify, vAlign) which is separate from slot alignment.

Deep dive: UI/Renderable: Shared properties

Animation ownership #

Animation keys modify renderable channels over time (position/origin/scale/rotation/colour/opacity/frame/noise/shader params).
Animation is visual and compositional; it does not redefine parent layout rules.

Deep dive: UI/Animation

Event ownership #

Pointer/mouse callbacks are element-level.
Adding handlers enables hit-testing for that element.
Window-level pointer acceptance is still required (Koya/Compositor pointer settings).

Event APIs: Helix/UserInterface

Practical reading order #

UserInterface Guide
UI/Foundations
Helix/UserInterface
Domain deep-dives (UI/Layout, UI/Animation, UI/Renderable:*)

<- Store UI/Animation ->