ui

A module for creating basic UI elements in scenes

class ui.canvas

Provides a 2D layer for rendering UI elements within a scene

Canvas Entities

Child entities created with ui.canvas, are 2D elements that use an automatic layout system

Canvas children have additional properties and methods:

  • entity.size, vec2 - the 2D size of the entity in canvas units

  • entity.pivot, vec2 - the centre privot point of the entity

  • entity.anchorX, enum - the horizontal alignment of the entity

  • entity.anchorY, enum - the vertical alignment of the entity

  • entity:anchor(x, y) - shortcut for setting anchorX, anchorY

Anchors

Canvas entities are laid out using an anchor and pivot system

For horizontal alignment use:

  • LEFT - Align relative to the left side of the parent entity

  • RIGHT - Align relative to the right side of the parent entity

  • CENTER - Align relative to the center of the parent entity

For vertical alignment use:

  • BOTTOM - Align relative to the bottom of the parent entity

  • MODDLE - Align relative to the middle of the parent entity

  • TOP - Align relative to the top of the parent entity

Both horizonal and vertical alignment can be stretched

  • STRETCH - Stretch the component relative to it’s parent

scn = scene()

-- Create an entity to contain the button
ent = scn.canvas:child("button")

-- Adjust the button size
ent.size = vec2(300, 150)

-- Add a button component
btn = ent:add(ui.button)
btn.label.text = "Press Me!"

-- Add a callback function to react to button taps
function ent:tapped()
   print("Tapped!")
end
entity: entity

The entity for this canvas

scale: number

Scale factor for canvas drawing

class ui.label: component

Draws text on a canvas entity

text: string

The text to render on the label

color: color

The label’s text color

fontSize: number

The label’s font size

align: flags

The label’s text alignment

style: flags

The label’s text style

shadowOffset: vec2

The offset of the labels text shadow

shadowSoftner: number

The softness of the labels text shadow

class ui.image: component

Draws an image on a canvas entity

image: image

The image to draw

class ui.button: component

Makes a canvas entity into an interactive button

style: table

The button’s style. Background image and color tint can be set for each button state

Button table structure
btn.style =
{
   normal = { sprite = ..., color = ... },
   pressed = { sprite = ..., color = ... },
   disabled = { sprite = ..., color = ... },
   selected = { sprite = ..., color = ... }
}
class ui.vstack: component

Lays out child entities in a vertical stack

padding: number

The outer padding for the stack, used to create a border around the edge

spacing: number

The spacing between each item in the stack

class ui.hstack: component

Lays out child entities in a horizontal stack

padding: number

The outer padding for the stack, used to create a border around the edge

spacing: number

The spacing between each item in the stack