UI

Look up ui calls and properties.

`control.key`

Read or set the Script key.

Arguments: No call arguments. Assign string to change it.
Returns: string. Readable and writable.
Works with: control handles.
Missing values and errors: Removed objects and unsupported handle kinds cannot supply this property.

Also available as: ui.key.

Changes during Play do not modify the saved UI document.

const control = ui.new("Button")
debug.log(control.key)

`control.anchor`

Choose the point used for layout.

Arguments: No call arguments. Assign anchor name string to change it.
Returns: anchor name string. Readable and writable.
Works with: control handles.
Missing values and errors: Removed objects and unsupported handle kinds cannot supply this property.

Also available as: ui.anchor.

Names: TopLeft, TopCenter, TopRight, CenterLeft, Center, CenterRight, BottomLeft, BottomCenter, BottomRight, Stretch. Stretch treats position as left/top margins and size as right/bottom margins.

const control = ui.new("Button")
debug.log(control.anchor)

`control.position`

Read or change position in viewport pixels.

Arguments: No call arguments. Assign [x, y] numbers to change it.
Returns: [x, y] numbers. Readable and writable.
Works with: control handles.
Missing values and errors: Removed objects and unsupported handle kinds cannot supply this property.

Also available as: ui.position.

Changes during Play do not modify the saved UI document.

const control = ui.new("Button")
debug.log(control.position)

`control.size`

Read or change control size.

Arguments: No call arguments. Assign [width, height] numbers to change it.
Returns: [width, height] numbers. Readable and writable.
Works with: control handles.
Missing values and errors: Removed objects and unsupported handle kinds cannot supply this property.

Also available as: ui.size.

Changes during Play do not modify the saved UI document.

const control = ui.new("Button")
debug.log(control.size)

`control.visible`

Show or hide the control.

Arguments: No call arguments. Assign bool to change it.
Returns: bool. Readable and writable.
Works with: control handles.
Missing values and errors: Removed objects and unsupported handle kinds cannot supply this property.

Also available as: ui.visible.

Changes during Play do not modify the saved UI document.

const control = ui.new("Button")
debug.log(control.visible)

`control.enabled`

Enable or disable interaction.

Arguments: No call arguments. Assign bool to change it.
Returns: bool. Readable and writable.
Works with: control handles.
Missing values and errors: Removed objects and unsupported handle kinds cannot supply this property.

Also available as: ui.enabled.

Changes during Play do not modify the saved UI document.

const control = ui.new("Button")
debug.log(control.enabled)

`control.color`

Read or change the control color.

Arguments: No call arguments. Assign [r, g, b, a] numbers to change it.
Returns: [r, g, b, a] numbers. Readable and writable.
Works with: control handles.
Missing values and errors: Removed objects and unsupported handle kinds cannot supply this property.

Also available as: ui.color.

Changes during Play do not modify the saved UI document.

const control = ui.new("Button")
debug.log(control.color)

`control.parent`

Choose a parent control.

Arguments: No call arguments. Assign another Ui handle or nil.
Returns: Ui handle or nil. Readable and writable.
Works with: control handles.
Missing values and errors: Removed objects and unsupported handle kinds cannot supply this property.

Also available as: ui.parent.

Use another Ui handle or nil. Parent cycles are rejected.

Parent handles [BETA]

Ui handles returned by creation and lookup can be assigned directly to parent.

const control = ui.new("Button")
debug.log(control.parent)

`control.z_index`

Choose the drawing order.

Arguments: No call arguments. Assign number to change it.
Returns: number. Readable and writable.
Works with: control handles.
Missing values and errors: Removed objects and unsupported handle kinds cannot supply this property.

Also available as: ui.z_index.

Changes during Play do not modify the saved UI document.

const control = ui.new("Button")
debug.log(control.z_index)

`control.corner_radius`

Round the control corners.

Arguments: No call arguments. Assign number to change it.
Returns: number. Readable and writable.
Works with: control handles.
Missing values and errors: Removed objects and unsupported handle kinds cannot supply this property.

Also available as: ui.corner_radius.

Changes during Play do not modify the saved UI document.

const control = ui.new("Button")
debug.log(control.corner_radius)

`control.border_width`

Choose the border width.

Arguments: No call arguments. Assign number to change it.
Returns: number. Readable and writable.
Works with: control handles.
Missing values and errors: Removed objects and unsupported handle kinds cannot supply this property.

Also available as: ui.border_width.

Changes during Play do not modify the saved UI document.

const control = ui.new("Button")
debug.log(control.border_width)

`control.border_color`

Choose the border color.

Arguments: No call arguments. Assign [r, g, b, a] numbers to change it.
Returns: [r, g, b, a] numbers. Readable and writable.
Works with: control handles.
Missing values and errors: Removed objects and unsupported handle kinds cannot supply this property.

Also available as: ui.border_color.

Changes during Play do not modify the saved UI document.

const control = ui.new("Button")
debug.log(control.border_color)

`control.text`

Read or change the label text.

Arguments: No call arguments. Assign string to change it.
Returns: string. Readable and writable.
Works with: control handles.
Missing values and errors: Removed objects and unsupported handle kinds cannot supply this property.

Also available as: ui.text.

Works on Text and Button controls.

const control = ui.new("Button")
debug.log(control.text)

`control.font_size` [BETA]

Choose the font size.

Arguments: No call arguments. Assign number to change it.
Returns: number. Readable and writable.
Works with: control handles.
Missing values and errors: Removed objects and unsupported handle kinds cannot supply this property.

Also available as: ui.font_size.

Works on Text and Button controls.

const control = ui.new("Button")
debug.log(control.font_size)

`control.horizontal_align` [BETA]

Align text horizontally.

Arguments: No call arguments. Assign Left, Center, or Right string to change it.
Returns: Left, Center, or Right string. Readable and writable.
Works with: control handles.
Missing values and errors: Removed objects and unsupported handle kinds cannot supply this property.

Also available as: ui.horizontal_align.

Works on Text and Button controls.

const control = ui.new("Button")
debug.log(control.horizontal_align)

`control.vertical_align` [BETA]

Align text vertically.

Arguments: No call arguments. Assign Top, Center, or Bottom string to change it.
Returns: Top, Center, or Bottom string. Readable and writable.
Works with: control handles.
Missing values and errors: Removed objects and unsupported handle kinds cannot supply this property.

Also available as: ui.vertical_align.

Works on Text and Button controls.

const control = ui.new("Button")
debug.log(control.vertical_align)

`control.wrap` [BETA]

Choose whether text wraps.

Arguments: No call arguments. Assign bool to change it.
Returns: bool. Readable and writable.
Works with: control handles.
Missing values and errors: Removed objects and unsupported handle kinds cannot supply this property.

Also available as: ui.wrap.

Works on Text and Button controls.

const control = ui.new("Button")
debug.log(control.wrap)

`control.padding` [BETA]

Set space around the text.

Arguments: No call arguments. Assign [left, top, right, bottom] numbers to change it.
Returns: [left, top, right, bottom] numbers. Readable and writable.
Works with: control handles.
Missing values and errors: Removed objects and unsupported handle kinds cannot supply this property.

Also available as: ui.padding.

Works on Text and Button controls.

const control = ui.new("Button")
debug.log(control.padding)

`control.line_spacing` [BETA]

Set extra space between lines.

Arguments: No call arguments. Assign number to change it.
Returns: number. Readable and writable.
Works with: control handles.
Missing values and errors: Removed objects and unsupported handle kinds cannot supply this property.

Also available as: ui.line_spacing.

Works on Text and Button controls.

const control = ui.new("Button")
debug.log(control.line_spacing)

`control.on_click`

Set the function called when a Button is clicked.

Arguments: No call arguments. Assign function or nil to change it.
Returns: function or nil. Readable and writable.
Works with: control handles.
Missing values and errors: Removed objects and unsupported handle kinds cannot supply this property.

Also available as: ui.on_click.

Works on Buttons. The callback takes no arguments.

const control = ui.new("Button")
debug.log(control.on_click)

`ui.find(key) or ui.find(document_key, key)`

Find a UI control by Script key.

Arguments: key: string. Optional document_key: string matching the document loaded for Play.
Returns: Ui handle, or nil if missing.
Works with: Controls in the active Play document, including keyed runtime controls.
Missing values and errors: Missing keys return nil. Keys are case-sensitive. Display names are not Script keys. A different document key does not load that document.

const health = ui.find("health_text")
if health != nil {
    health.text = "75 / 100"
}

`ui.get(key) or ui.get(document_key, key)`

Find a UI control by Script key.

Arguments: key: string. Optional document_key: string matching the document loaded for Play.
Returns: Ui handle.
Works with: Controls in the active Play document, including keyed runtime controls.
Missing values and errors: Missing keys report an error. Keys are case-sensitive. Display names are not Script keys. A different document key does not load that document.

const health = ui.get("health_text")
health.text = "75 / 100"

`ui.new(element_type)`

Create a temporary UI control.

Arguments: element_type: "Panel", "Text", or "Button".
Returns: Ui handle.
Works with: Runtime UI.
Missing values and errors: Unsupported element types report an error. Controls are discarded when Play stops.

const label = ui.new("Text")
label.text = "Hello"
label.position = [20, 20]
label.size = [200, 40]

`ui.delete(handle)`

Remove a control during Play.

Arguments: handle: Ui handle.
Returns: nil.
Works with: Runtime and instantiated authored UI controls.
Missing values and errors: Other handle kinds and invalid IDs report an error. This does not delete the saved authored control.

const label = ui.new("Text")
ui.delete(label)

`ui.get_viewport_size()`

Read the playable viewport size.

Arguments: No arguments.
Returns: [width, height] in pixels.
Works with: The current gameplay viewport.
Missing values and errors: Wrong argument counts or types report an error.

debug.log(ui.get_viewport_size())

[BETA] marks features newer than the current public release. Current release: 0.8.0.

Parent handles [BETA]

control.font_size [BETA]

control.horizontal_align [BETA]

control.vertical_align [BETA]

control.wrap [BETA]

control.padding [BETA]

control.line_spacing [BETA]

`control.font_size` [BETA]

`control.horizontal_align` [BETA]

`control.vertical_align` [BETA]

`control.wrap` [BETA]

`control.padding` [BETA]

`control.line_spacing` [BETA]