voxelcore/doc/en/scripting/ui.md

UI properties and methods

UI elements in scripts are accessed through a Document instance (global document variable) by id specified in xml.

Example: print the pos property of an element with id: "worlds-panel" to the console:

print(document["worlds-panel"].pos)
-- or
local worldsPanel = document["worlds-panel"]
print(worldsPanel.pos)

The IDs of the elements are global for the document, that is, worlds-panel can be located either in the root element, and in a nested container.

The element id cannot be changed from a script.

The following tables will use abbreviated type descriptions, such as:

• vec2 - an array of two numbers.
• ivec2 - an array of two integers.
• rgba - an array of four integers in the range [0..255] denoting RGBA constituent colors.

Element methods, according to OOP features in Lua, are called using the : operator instead of .

For example:

document["worlds-panel"]:clear()

Access to nested elements is performed by index (starting from one).

General properties and methods

Properties that apply to all elements:

Name	Type	Read	Write	Description
id	string	yes	no	element id
exists	bool	yes	no	checks if element exists
pos	vec2	yes	yes	element position inside a container
wpos	vec2	yes	yes	element position inside the window
size	vec2	yes	yes	element size
interactive	bool	yes	yes	ability to interact with the element
enabled	bool	yes	yes	visually indicated version of interactive
visible	bool	yes	yes	element visibility
focused	bool	yes	yes	focus on element
color	rgba	yes	yes	element color
hoverColor	rgba	yes	yes	hover color
pressedColor	rgba	yes	yes	color when pressed
tooltip	string	yes	yes	tooltip text
tooltipDelay	float	yes	yes	tooltip delay
contentOffset	vec2	yes	no	element content offset
cursor	string	yes	yes	cursor displayed on hover
parent	Element	yes	no	parent element or nil
zIndex	int	yes	no	z-index value. In panel, it determines the order

Common element methods:

Method	Description
moveInto(container)	moves the element to the specified container (the element is specified, not the id)
destruct()	removes element
reposition()	updates the element position based on the positionfunc

Containers

Common properties for containers (elements: container, panel, button, pagebox):

Name	Type	Read	Write	Description
scroll	string	yes	yes	scroll contents

Common methods:

Method	Description
clear()	clears content
add(xml)	adds an element, creating it using xml code. Example: container:add("<image src='test'/>")
add(xml, data)	overload with table, which in events declared in xml will be available as DATA
setInterval(interval, callback)	assigns a function to be executed repeatedly at an interval specified in milliseconds

Textbox

Properties:

Name	Type	Read	Write	Description
text	string	yes	yes	entered text or placeholder
placeholder	string	yes	yes	placeholder (used if nothing has been entered)
hint	string	yes	yes	text to display when nothing is entered
caret	int	yes	yes	carriage position. textbox.caret = -1 will set the position to the end of the text
editable	bool	yes	yes	text mutability
edited	bool	yes	yes*	is text edited since the last set / edited status reset
multiline	bool	yes	yes	multiline support
lineNumbers	bool	yes	yes	display line numbers
textWrap	bool	yes	yes	automatic text wrapping (only with multiline: "true")
valid	bool	yes	no	is the entered text correct
textColor	vec4	yes	yes	text color
syntax	string	yes	yes	syntax highlighting ("lua" - Lua)
markup	string	yes	yes	text markup language ("md" - Markdown)
selection	ivec2	yes	yes	selection anchor and caret; see below
externalRendering	bool	yes	yes	external text rendering (default: false)
textLayout	table	yes	no	snapshot of visible text layout; see below

* - false only

Methods:

Method	Description
paste(text: str)	inserts the specified text at the caret position
lineAt(pos: int) -> int	determines the line number by position in the text
linePos(line: int) -> int	determines the position of the beginning of the line in the text

Selection and external rendering

• selection (read/write): {anchor, caret}, preserving direction. Indices are zero-based native caret character units, not UTF-8 byte offsets. Setters require finite integers, clamp to the text length and reveal the caret, including immediately after replacing text. Setting selection does not edit text or reset undo history.
• externalRendering (read/write boolean, default false): hides native text, caret, selection and current-line highlight. Input, hit testing, layout, scrolling, background, line numbers and scrollbar remain native. Setting it back to false restores native rendering without replacing the textbox. Markup and external rendering cannot be combined: either setter rejects it.
• textLayout (read-only table): a snapshot of the current visible layout. ready=false means the font is unavailable or markup is active. Otherwise:
  • text: the value of textbox.text, including placeholder when input is empty; font: font name.
  • lineHeight: row pitch; textHeight: height to use for a label displaying a row.
  • caretRect: {x,y,cellWidth,rowHeight} at the moving selection endpoint; at end-of-line the cell width is the space advance. This is geometry, independent of focus, editability and blink phase.
  • selectionRects: {x, y, width, height} rectangles for visible selected rows, including selected newline cells.
  • lines: visible rows {start, text, pos={x,y}, advances={...}}; start is a native caret index, text excludes the trailing newline, advances contains the native width of each character. Empty input may expose the hint as display rows; it does not replace text in the snapshot.

Coordinates are relative to the textbox, include scrolling and alignment, and may extend outside its bounds. External painters must clip to the field. Snapshots are independent Lua tables; modifying them does not modify the box. Read them again after input, resizing or scrolling. Syntax colors are not exported; the external painter supplies its own colors. Indexing and text input follow the existing textbox behavior.

local field = document.input
field.text = "abcdef"
field.selection = {5, 2}
local anchor, caret = unpack(field.selection)

field.externalRendering = true
local layout = field.textLayout
if layout.ready then
    for _, line in ipairs(layout.lines) do
        print(line.start, line.text, line.pos[1], line.pos[2])
    end
end

In this example the caret is at position 2 and the selection anchor is at position 5. A negative selection index is clamped to zero; unlike caret, it does not address characters from the end of the text.

Slider (trackbar)

Properties:

Name	Type	Read	Write	Description
value	float	yes	yes	current value
min	float	yes	yes	minimum value
max	float	yes	yes	maximum value
step	float	yes	yes	division step
trackWidth	float	yes	yes	control element width
trackColor	rgba	yes	yes	control element color

Menu (pagebox)

Properties:

Name	Type	Read	Write	Description
page	string	yes	yes	current page

Methods:

Method	Description
back()	switches to previous page
reset()	resets page and switching history

Checkbox

Properties:

Name	Type	Read	Write	Description
checked	bool	yes	yes	mark status

Button

Properties:

Name	Type	Read	Write	Description
text	string	yes	yes	button text

Label

Properties:

Name	Type	Read	Write	Description
text	string	yes	yes	label text
markup	string	yes	yes	text markup language ("md" - Markdown)

Image

Properties:

Name	Type	Read	Write	Description
src	string	yes	yes	texture name
fallback	string	yes	yes	fallback texture
region	vec4	yes	yes	image sub-region

Canvas

Properties:

Title	Type	Read	Write	Description
data	Canvas	yes	no	canvas data

Methods:

Here, color can be specified in the following ways:

• rgba: int
• r: int, g: int, b: int
• r: int, g: int, b: int, a: int

Method	Description
data:at(x: int, y: int)	returns an RGBA pixel at the given coordinates
data:set(x: int, y: int, color)	updates an RGBA pixel at the given coordinates
data:line(x1: int, y1: int, x2: int, y2: int, color)	draws a line with the specified RGBA color
data:blit(src: Canvas, dst_x: int, dst_y: int)	draws the src canvas at the specified coordinates
data:clear()	clears the canvas
data:clear(color)	fills the canvas with the specified RGBA color
data:rect(x: int, y: int, w: int, h: int, color)	fills the rectangle with the specified RGBA color
data:update()	applies changes to the canvas and uploads it to the GPU
data:set_data(data: Bytearray	table)
data:get_data()	creates a Bytearray object with the image's pixel data
data:create_texture(name: str)	creates and shares texture to renderer
data:unbind_texture()	unbinds the texture from the canvas
data:mul(color or Canvas)	multiplies a color by the specified color or canvas
data:add(color or Canvas)	adds a color or another canvas to a color
data:sub(color or Canvas)	subtracts a color or another canvas to a color
data:encode(format: str)	encodes image to specified format and returns bytearray

To decode a byte array into a Canvas, use the static method:

Canvas.decode(data: Bytearray, format: str) -> Canvas

Currently, only png is supported.

Inline frame (iframe)

Name	Type	Read	Write	Description
src	string	yes	yes	id of the embedded document

Select

Derived from button with access to properties such as the text to display.

Properties:

Name	Type	Read	Write	Description
value	string	yes	yes	Selected value
options	table	yes	yes	List of options (tables {value=..., text=...})

Inventory

Properties:

Name	Type	Read	Write	Description
inventory	int	yes	yes	id of the inventory to which the element is bound

Slot

Properties:

Name	Type	Read	Write	Description
inventory	int	yes	no	id of the inventory to which the element is bound
slotIndex	int	yes	no	index of the slot to which the element is attached