VoxelEngine/doc/en/scripting/ui.md

UI properties and methods

UI elements in scripts are accessed through a Document instance (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

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)

* - 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

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
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