VoxelEngine/doc/en/xml-ui-layouts.md

XML UI Building

See also ui elements in scripting.

Specific types

2D vector - pair of numbers separated with comma. Examples:

• "500,200"
• "0.4,53.01"
• "0,0"

3D vector - three numbers separated with comma. Examples:

• "60,30,53"
• "0.4,0.1,0.753"

4D vector - four numbers separated with comma. Examples:

• "10,5,10,3"
• "0.1,0.5,0.0,0.0"

RGBA color - only HEX notation available Examples:

• "#FF8000" - opaque orange
• "#FFFFFF80" - semi-transparent white
• "#000000FF" - opaque black

Common element attributes

• id - element identifier. Type: string.
• pos - element position. Type: 2D vector.
• size - element size. Type: 2D vector.
• color - element color. Type: RGBA color.
• margin - element margin. Type: 4D vector left, top, right, bottom
• visible - element visibility. Type: boolean (true/false)
• min-size - minimal element size. Type: 2D vector.
• position-func - position supplier for an element (two numbers), called on every parent container size update or on element adding on a container. May be called before on_hud_open
• size-func - element size provider (two numbers), called when the size of the container in which the element is located changes, or when an element is added to the container. Can be called before on_hud_open is called.
• onclick - lua function called when an element is clicked.
• ondoubleclick - lua function called when you double click on an element.
• onfocus - lua function called when focusing on an element.
• ondefocus - lua function called when the element loses focus.
• onmouseover - lua function called when the cursor enters an element.
• onmouseover - lua function called when the cursor exits an element.
• tooltip - tooltip text
• tooltip-delay - tooltip show-up delay
• gravity - automatic positioning of the element in the container. (Does not work in automatic containers like panel). Values: top-left, top-center, top-right, center-left, center-center, center-right, bottom-left, bottom-center, bottom-right.
• z-index - determines the order of elements, with a larger value it will overlap elements with a smaller one.
• interactive - if false, hovering over the element and all sub-elements will be ignored.
• cursor - the cursor displayed when hovering over the element (arrow/text/pointer/crosshair/ew-resize/ns-resize/...).

Template attributes

• if with values ​​('', 'false', 'nil') the element will be ignored, including sub-elements.
• ifnot is the same as if, but with the opposite condition.

Common container attributes

Buttons and panels are also containers.

• scrollable - element scrollability. Type: boolean.
• scroll-step - scrolling step. Type: integer.

Common panel attributes

Buttons are also panels.

• padding - element padding. Type: 4D vector. left, top, right, bottom
• max-length - maximal length of panel stretching before scrolling (if scrollable = true). Type: number.
• min-length - minimal length of panel. Type: number.
• orientation - panel orientation: horizontal/vertical.
• interval - space between elements. Type: number.

Common elements

container

A primitive container. Use static positions / gravity / script to position elements.

panel

A simple panel. Arranges elements in the order defined by the orientation attribute, adjusting the width (vertical) or height (horizontal) to the panel width.

splitbox (splitter)

A panel that controls the size and position of two elements. Allows the user to move the splitter, changing the size of the elements.

• split-pos - the initial position of the splitter from 0.0 to 1.0.

button

Inner text is a button text.

• text-align - inner text alignment (left/center/right). Type: string.

checkbox

• checked - defines the checked state.
• supplier - mark state supplier (called every frame).
• consumer - lua function-consumer of the state of the mark.

label

• valign - vertical text alignment: top/center/bottom.
• supplier - text supplier (called every frame).
• autoresize - automatic change of element size (default - false). Does not affect font size.
• multiline - allows display of multiline text.
• text-wrap - allows automatic text wrapping (works only with multiline: "true").
• markup - text markup language ("md" - Markdown).

image

• src - name of an image stored in textures folder. Extension is not specified. Type: string. Example: gui/error
• region - image region x1, y1, x2, y2 from 0.0, 0.0 (upper left corner), 1.0, 1.0 (lower right corner)

canvas

• No additional attributes

textbox

Inner text - initially entered text

• placeholder - placeholder text (used if the text field is empty)
• hint - text displayed if the text field is empty (not sent to consumer, sub-consumer and validator).
• supplier - text supplier (called every frame)
• consumer - lua function that receives the entered text. Called only when input is complete
• sub-consumer - lua function-receiver of the input text. Called during text input or deletion.
• oncontrolkey - lua function called for combinations of the form (Ctrl + ?). The codepoint of the second key is given as the first argument. The key code for comparison can be obtained via input.keycode("key_name")
• autoresize - automatic change of element size (default - false). Does not affect font size.
• multiline - allows display of multiline text.
• text-wrap - allows automatic text wrapping (works only with multiline: "true")
• editable - determines whether the text can be edited.
• line-numbers - enables line numbers display.
• keep-line-selection - keep showing selected line after defocus.
• error-color - color when entering incorrect data (the text does not pass the validator check). Type: RGBA color.
• text-color - text color. Type: RGBA color.
• validator - lua function that checks text for correctness. Takes a string as input, returns true if the text is correct.
• onup - lua function called when the up arrow is pressed.
• ondown - lua function called when the down arrow is pressed.
• syntax - syntax highlighting ("lua" - Lua).
• markup - text markup language ("md" - Markdown).

trackbar

• min - minimal value. Type: number. Default: 0
• max - maximal value. Type: number. Default: 1
• value - initial value. Type: number. Default: 0
• step - track step size. Type: number: Default: 1
• track-width track pointer width (in steps). Type: number. Default: 1
• track-color - the color of the pointer when hovering over the cursor. Type: RGBA color.
• consumer - Lua function - new value consumer
• sub-consumer - Lua function that receives intermediate values ​​(use to update text when change-on-release="true")
• supplier - Lua function - value supplier
• change-on-release - Call consumer on trackbar release only. Type: boolean. Default: false

Inline frame - iframe

Container for embedding an external document. Content is scaling to the iframe size.

• src - document id in the format pack:name (pack/layouts/name.xml)

select

Drop-down list. Options are described by option sub-elements, the value attribute of which contains the value, the inner text is the text displayed in the UI.

Example of list description:

<select selected="entity" width="200"
        onselect="function(opt) print(opt) end">
    <option value="block">Block</option>
    <option value="item">Item</option>
    <option value="entity">Entity</option>
</select>

• width - minimum content width. Default: 100.
• selected - initially selected value. Default: "".
• onselect - function to which the user-selected value is passed

Inventory elements

inventory

Element is a container. Does not have specific attributes.

Warning

Inventories position is controlled by the engine and can not be changed by attributes pos and margin

slot

Element must be in direct sub-element of inventory.

• index - inventory slot index (starting from 0). Type: integer
• item-source - content access panel behaviour (infinite source of an item). Type: boolean
• sharefunc - Lua event called on LMB + Shift. Inventory id and slot index passed as arguments.
• updatefunc - Lua event called on slot content update.Inventory id and slot index passed as arguments.
• onrightclick - Lua event called on RMB click. Inventory id and slot index passed as arguments.
• taking - the ability to take an item from a slot.
• placing - the ability to put an item in a slot.

slots-grid

• start-index - inventory slot index of the first slot. Type: integer
• rows - number of grid rows (unnecessary if cols and count specified). Type: integer
• cols - number of grid columns (unnecessary if rows and count specified). Type: integer
• count - total number of slots in grid (unnecessary if rows and cols specified). Type: integer
• interval - visual slots interval. Type: number
• padding - grid padding (not slots interval). Type: number. (deprecated)
• sharefunc - Lua event called on LMB + Shift. Inventory id and slot index passed as arguments.
• updatefunc - Lua event called on slot content update.Inventory id and slot index passed as arguments.
• onrightclick - Lua event called on RMB click. Inventory id and slot index passed as arguments.
• taking - the ability to take an item from a slot.
• placing - the ability to put an item in a slot.