Skip to content

Widget reference

This page lists each widget's role, defaults, full property table, and states/events. For usage tutorials, see DSL widgets.

Widget overview

Widget Role Default size Accepts
Container Layout container that can paint a background 0×0 (grows as needed) Any widget
Panel Purely decorative box 0×0 Part only
Label Single-line / multi-line text Width 0, height 14×font size Part only
Button Clickable button 120×20 Part only
Image Texture 16×16 Part only
Checkbox Checkbox / switch Height 18 Part only
Slider Numeric slider Height 20 Part only
TextBox Single-line input Height 22 Part only
Dropdown Drop-down selection 160×24 Part only
ScrollView Vertically scrolling, clipping viewport 0×0 Any widget (goes into the inner content container)
ForEach Array repeater 0×0 (height adapts) Any widget (as a row template)
Part Decoration layer attached to a widget Follows the anchor None

Only containers can hold arbitrary child widgets

Panel, Button, Label, Image, Checkbox, Slider, TextBox, and Dropdown accept only Part as a child node. Putting any other widget inside raises the error 'X' cannot contain 'Y'.

Common properties

All widgets accept the following properties:

Property Type Description
name / id text Node name, used by FindByName
x / y number Absolute position coordinates (a layout container overrides them)
width / height number Size; 0 means the layout decides
margin number Trailing spacing (bottom of a column, right of a row)
margin-top / margin-right / margin-bottom / margin-left number Per-side spacing; use margin-top/margin-left for the leading side
visible boolean Excluded from layout, not rendered, not interactive
disabled / enabled boolean Disabled state; child widgets inherit the disabled state
z-order / z / layer / z-index number Draw and hit testing order; larger values are on top
opacity 0-1 Overall opacity, takes part in transitions
background / bg color/gradient Fill
color / text-color color Text color; also the tint of images
radius / border-radius number Corner radius
border-width number Stroke width
border-color color Stroke color
border width [color] Sets the stroke as well
shadow ... Shadow; see Images
gradient / bg-gradient gradient Background gradient
border-image / nine-slice texture slice... Nine-slice border
font-family text Font name or default/smooth/unicode/rune/ui
text-align / align left/center/right Text alignment
transition list Color/opacity transitions
animation name duration [count] Keyframe animation
class / style list of style names Applies global styles
on<event> / <event>: script or handler name See Events

padding only matters for container layout (Container, ScrollView, ForEach); leaf widgets use their own text padding properties.

Container

Layout container. Defaults to absolute and can paint a background, stroke, and corner radius.

Property Type Description
layout / direction vertical/column/v, horizontal/row/h, absolute/none Arrangement, default absolute
padding number Padding on all four sides
Container {
    layout: vertical;
    padding: 8;
    width: 200;

    Label { text: "Title"; height: 20; }
    Label { text: "Description"; height: 16; }
}
  • In a vertical layout, a child widget with width 0 stretches to the content width.
  • In a horizontal layout, a child widget with height 0 stretches to the content height.
  • When the container size on the main axis is 0, it is computed from the accumulated child sizes.
  • Hidden child widgets take no space.

Panel

A pure box that paints a background, stroke, corner radius, shadow, and nine-slice border; it cannot lay out child widgets.

Property Description
Common appearance properties All available
Child nodes Part only
Panel {
    x: 10; y: 10;
    width: 120; height: 60;
    background: #2C2F33;
    radius: 6;
}

Label

Text widget. Single-line by default, truncating text wider than the widget; with wrap enabled it wraps automatically.

Property Type Default Description
text / value text/binding empty Displayed content
font-size / font number 1 Font size multiplier
wrap / word-wrap boolean false Multi-line wrapping
color color near white Text color
text-align enum left Alignment
  • Height 0: single-line mode uses 14×font size; wrapping mode uses the height of three lines (30×font size).
  • Wrapping breaks at spaces first; without spaces (Chinese text, long words) it breaks between characters.
  • For {{ }} text templates, see Reactive bindings.

Button

Button, using UIStyle::PrimaryButton() by default. A click (mouse released inside it, or the activate key pressed while focused) fires click.

Property Type Default Description
text / value text empty Button label
font-size number 1 Font size
onClick / on-click / action handler name none C++ named handler
onClick: { ... } script none The script takes precedence over the named handler
State appearance hover-background/pressed-background/disabled-*

Without state colors set, hover blends in 10% white and press blends in 18% black.

Image

See Images. Main properties:

Property Type Default Description
src / source / texture text empty Game texture path or image file path
width / height number 16 Stretched to the rectangle; 0 falls back to 16
color color white Multiplicative tint

Checkbox

Checkbox. Click, space, or Enter toggles it, and change reports the new state.

Property Type Default Description
text / label text empty Caption
checked / value boolean false Checked state (a single-identifier binding can write back)
accent / check-color color green Check mark color
box-size number 0 (follows font size) Box side length; 0 uses max(14, 14×font size)
text-gap / gap number 8 Gap between box and text
check-inset number -1 Check mark inset; negative values are proportional
show-box boolean true Hides the built-in box and leaves drawing to a Part
font-size number .9 Font size
onChange handler name none Receives "true"/"false"
onChange: { ... } script none Takes precedence over the handler

States: checked/on/selected, unchecked/off, plus the common hovered, pressed, focused, and disabled.

Slider

Numeric slider; clicking jumps to a position and dragging updates continuously, quantized to step if set.

Property Type Default Description
min number 0 Lower bound
max number 100 Upper bound
value number 50 Current value (a single-identifier binding can write back)
step number 0 0 means continuous
knob-size number 12 Knob diameter
accent / fill-color color green Color of the filled track
track-height number 4 Track height
track-color color dark gray Track background color
knob-color color light gray Knob color
knob-active-color color near white Knob color while dragging
smooth / animate boolean false The knob eases toward the target value (dragging eases too)
smoothing / smooth-speed number 20 Easing rate (approach factor per second)
onChange handler name none Receives the formatted value
onChange: { ... } script none Takes precedence over the handler

TextBox

Single-line input box. Click to focus, then type and backspace; Esc drops focus and Enter submits.

Property Type Default Description
text / value text empty Content (a single-identifier binding can write back)
placeholder / hint text empty Placeholder hint
max-length number 32 Maximum number of characters
font-size number .9 Font size
text-padding / padding-x number 5 Horizontal text padding
caret-color color white Caret color
caret-width number 1.5 Caret width
placeholder-color color gray Placeholder text color
onChange handler name none On every text change
onSubmit / onEnter handler name none Submitted with Enter
onChange: { ... } / onSubmit: { ... } script none Take precedence over the handlers

States: empty/blank, filled/has-text, editing, plus the common states.

Drop-down selection box. Click to expand; choosing an option collapses it and reports the index through change.

Property Type Default Description
options / items / choices comma-separated text empty Options; an option cannot contain a comma
selected / index / value number 0 Current index (a single-identifier binding can write back)
item-height number 20 List row height
item-padding number 8 Horizontal padding inside a row
font-size number .9 Font size
accent color green Also sets the selected background
selection-color color translucent green Selected row background
arrow one or two glyphs v Collapsed state, expanded state
arrow-closed / arrow-open text v Set the arrows separately
arrow-color color light gray Arrow color
list-background color dark Expanded list background
open / expanded boolean false Initial expanded state
onChange handler name none Receives the index
onChange: { ... } script none Takes precedence over the handler
  • Default z-order: 100, so the expanded list covers sibling nodes behind it.
  • While expanded, the hit test area includes the list area.
  • Clicking elsewhere or losing focus collapses it.
  • States: expanded/open, collapsed/closed.

ScrollView

Vertically clipping scrolling viewport. Child widgets go into an inner content container (arranged vertically); content outside the viewport is neither drawn nor clickable.

Property Type Default Description
scroll-step / wheel-step number 24 Distance per wheel notch
smooth-scroll boolean true Whether scrolling eases
scroll-smoothing / scroll-easing number 22 Easing rate
show-scrollbar / scrollbar boolean true Show the scrollbar
scrollbar-width number 3 Scrollbar width
scrollbar-inset number 3 Distance from the right edge
scrollbar-radius number 0 Scrollbar corner radius
scrollbar-color color 10% white Track color
scrollbar-thumb-color color 38% white Thumb color
offset / scroll-y number 0 Initial scroll offset
padding number 0 Viewport padding
  • The layout property is accepted but ignored: content is always arranged vertically.
  • scrollOffsetY eases toward scrollTargetY; the wheel and the scrollbar only change the target value.
  • The scrollbar can be grabbed and dragged.
  • The content height accumulates from child widgets; you do not need to set it manually.
ScrollView {
    width: 240;
    height: 180;
    scroll-step: 32;

    ForEach (data: @items, item: @item) {
        Label { text: @item.name; height: 24; }
    }
}

ForEach

Array repeater; see Lists and loops for details.

Parameter Required Description
data Yes Expression that produces an array
item No Row element variable name, default item
index No Row index variable name, default index
Property Default Description
layout vertical How rows are arranged
height 0 0 means accumulate over rows; an explicit value wins
Other container properties Apply to the repeater itself
  • At most 512 rows per pass; the excess is dropped and logged.
  • After a data change, all rows are rebuilt on the next Update.

Part

A decoration layer attached to any widget; it implements skins such as hover, selected, and switch states with structure instead of images.

Property Type Default Description
anchor / attach see the table below fill Position relative to the host
inset 1-4 numbers 0 Inset: all sides / vertical and horizontal
inset-x / inset-y number 0 Horizontal/vertical inset
inset-top / inset-right / inset-bottom / inset-left number 0 Single-side inset
offset-x / offset-y number 0 Fine position adjustment
layer under/over over Draw beneath or above the host
when / if condition string empty Space-separated; ! negates
src text empty Texture
tint color white Texture tint
text text empty Centered text
font-size number 1 Text font size
width / height number follows the anchor Actual size when the anchor is not fill
visible / show / enabled boolean true Static enable/disable
Common appearance properties background, radius, border-*, and so on

Anchor values:

Value Position
fill / stretch Fills the host inner box, ignoring width and height
top Top edge, full width by default
bottom Bottom edge, full width by default
left Left side, vertically centered
right Right side, vertically centered
center Centered
top-left / top-right / bottom-left / bottom-right The four corners

Host states available to when:

Host States
All hovered/hover, pressed/active, focused/focus, visible, disabled
Checkbox checked/on/selected, unchecked/off
Dropdown expanded/open, collapsed/closed
TextBox empty/blank, filled/has-text, editing
Checkbox {
    text: "Night mode";
    box-size: 40;
    show-box: false;

    Part { anchor: left; width: 40; height: 20; radius: 10; background: #33363A; when: "!checked"; }
    Part { anchor: left; width: 40; height: 20; radius: 10; background: #498FC3; when: "checked"; }
}

A Part does not receive mouse events; hover and pressed states follow the host.

Events

Event key Fires on Payload
onClick: Button click event.name = "click"
onChange: Value change event.name/value/text/checked/index, filled in per widget
onSubmit: Enter in an input box event.name = "submit", with event.text/value as the text

Event keys must have the on prefix (action is an alias for onClick), and differences in case and hyphens are ignored: onChange = on-change = ONCHANGE. When the value is { ... }, it runs as a script; otherwise it is registered as a C++ named handler name. When a script is present, the C++ handler is no longer called.

For script syntax, payload fields, and write-back rules, see Event scripts.

Next steps