UI/Renderable: Panel

What this page covers #

panel is a framed/stretched renderable useful for UI containers, cards, and panel-like surfaces.

By task #

Define panel frame/atlas options: see Definition
Understand panel frame semantics: see Notes
Place panels inside layout slots: see Top-level element options

Nine-slice style stretched panel with optional texture and shader. Currently uses a single frame definition.

Import #

Definition #

PanelRenderable

Nine-slice stretched panel with optional texture and shader.

type 'panel' - Renderable type identifier.
mode 'stretched' | 'sliced' | 'cover' optional - Panel draw mode. Default 'stretched'. Use 'sliced' for nine-slice behaviour.
slice { top, right, bottom, left } optional - 9-slice border thicknesses in pixels.
texture string optional - Path to texture atlas.
frame object optional - Frame definition. If omitted, a default stretched panel is created.
frame.size { x, y } optional - Frame display size.
frame.origin { x, y } optional - Panel frame metadata origin.
frame.aabb { min: { x, y }, max: { x, y } } optional - Sub-rect of the texture atlas.
frame.colour [r, g, b, a] optional - Frame tint colour.
shader { vert: string, frag: string } optional - Optional SPIR-V shader override.

Notes #

If frame is omitted, a default stretched panel is created.
mode defaults to stretched. Use sliced for nine-slice behaviour.
slice defines the 9-slice border thicknesses in pixels (top/right/bottom/left).
frame.aabb selects the sub-rect of the texture atlas.
frame.origin is panel frame metadata.
Element-level pivot is renderable.origin in UI.createElement (or UI.setOrigin at runtime).
Use UI.setPanelSlice, UI.setTexture, and UI.setShader to update after creation.
Set the runtime tint with await UI.setPanelColour(win, id, [1, 0.5, 0.25, 1]) (alias: setPanelColor). Tint multiplies frame.colour and inherited opacity in all panel modes. Pass [1,1,1,1] to clear it.

Top-level element options #

Pass these alongside renderable in UI.createElement (see also UI/Renderable: Shared properties):

UI.createElement(win, {
  renderable: {
    type: 'panel',
    origin?: { x, y },
    position?: { x, y },
    scale?: { x, y },
    rotation?: number
  },
  contentAlign?: { x?: 'start'|'center'|'end', y?: 'start'|'center'|'end' }
})

Example #

Creates a textured panel using a frame sub-rectangle from an atlas image. This is the typical setup for UI card backgrounds, dialog frames, or any surface that should stretch with its container.

import * as UI from 'Helix/UserInterface';

const id = await UI.createElement(win, {
  renderable: {
    type: 'panel',
    mode: 'sliced',
    texture: '/rom/arch.png',
    position: { x: 10, y: 4 },
    origin: { x: 0, y: 0 },
    frame: {
      size: { x: 20, y: 20 },
      origin: { x: 0, y: 0 },
      aabb: { min: { x: 0, y: 0 }, max: { x: 128, y: 128 } }
    }
  }
});
await UI.attachRoot(win, id);
await UI.setPanelSlice(win, id, { top: 8, right: 8, bottom: 8, left: 8 });

<- UI/Renderable: Circle UI/Renderable: Sprite ->