Input Elements

All input elements allow for the XML UI to interact with the Lua scripts in the game instance.

Tip

Be sure to check out the UI section of the Lua Scripting API for how to receive the input from these element types. With Lua scripting, you can even modify the UI elements!

Targeting Triggers

When using an attribute that triggers scripting, like onValueChanged or onClick, the UI will target a default location. Global UI targets Global script, Object UI targets the Object's script. This behavior can be overwritten. For example:

<Button onClick="uiClickFunc">Click Me</Button>

If this was in the Global UI, this would trigger a function in the Global Lua script function uiClickFunc(). But if you want to target a function on an Object's script? Place the GUID for the object before the function name, like so:

<Button onClick="aaa111/uiClickFunc">Click Me</Button>

Now when the button is clicked, it will still try to activate function uiClickFunc() but it will try to do so on the Object Lua script of the Object with the GUID of "aaa111".

<Button onClick="Global/uiClickFunc">Click Me</Button>

And if this was in an Object's UI, it would direct the function activation to Global instead of that Object.

Remember you can also use the Id attribute to identify which UI element triggered the function.

---

Element Summary

Element Name	Description
<InputField></InputField>	A text input for single or multiple lines. Is able to send the text (during edit and when finished).
<Button></Button>	A button. Is able to send a trigger event.
<Toggle></Toggle>	A simple on/off toggle. Is able to send on/off status.
<ToggleButton></ToggleButton>	A toggle, but styled as a button.
<ToggleGroup></ToggleGroup>	Allows a group of toggles to act as a radio button, where only 1 of them can be "checked" at once.
<Slider></Slider>	A value slider. Is able to send Value.
<Dropdown></Dropdown>	A dropdown menu. Is able to send the contents of the selection made in it.

---

Element Details

InputField

A text input for single or multiple lines. Is able to send the text (during edit and when finished).

Attribute Name	Description	Type / Options	Default Value
onValueChanged	Each time the text is changed, a Lua function with this name will be triggered.	string	(none)
onEndEdit	When the input box is deselected, a Lua function with this name will be triggered.	string	(none)
text	The string in the text box, if any. Is the value sent to onValueChanged's or onEndEdit's function.	string	(none)
placeholder	A string that is semi-visible when there is no text in the input.	string	(none)
interactable			true
colors			#FFFFFF|#FFFFFF|#C8C8C8|rgba(0.78,0.78,0.78,0.5)
lineType		SingleLine MultiLineSubmit MultiLineNewLine	SingleLine
characterValidation		None Integer Decimal Alphanumeric Name EmailAddress	None
caretBlinkRate		float	0.85
caretWidth		float	1
caretColor			#323232
selectionColor			rgba(0.65,0.8,1,0.75)
readOnly			false
textColor			#323232
characterLimit		int	0 (no limit)

Note

The text typed into an XML input field can't be obtained outside of the automatically passed arguments to onValueChanged / onEndEdit.

Example

<InputField onEndEdit="onEndEdit" >Default Text</InputField>

function onEndEdit(player, value, id)
    print(player.steam_name .. " entered: " .. value)

    -- store the value in a global variable for later access
    enteredValue = value
end

---

Button

A button. Is able to send a trigger event.

Attribute Name	Description	Type / Options	Default Value
onClick	When clicked, a Lua function with this name will be triggered.	string	(none)
interactable			true
colors			#FFFFFF|#FFFFFF|#C8C8C8|rgba(0.78,0.78,0.78,0.5)
textShadow			(none)
textOutline			(none)
textAlignment		UpperLeft UpperCenter UpperRight MiddleLeft MiddleCenter MiddleRight LowerLeft LowerCenter LowerRight	UpperLeft
icon		string	(none)
iconWidth		float
iconColor
iconAlignment		Left Right	Left
padding		float float float float	0 0 0 0
transition		None ColorTint SpriteSwap Animation	ColorTint
highlightedSprite		string
pressedSprite		string
disabledSprite		string

Example

<!-- Standard Button -->
<Button>Button Text</Button>
<!-- Button with Icon -->
<Button icon="SomeName" />
<!-- Button with Icon and Text -->
<Button icon="SomeName">Button With Icon</Button>

Tip

onClick passes nil for the value by default. However, you can assign a string that will be passed in onClick.

<Button onClick="clickFunction(stringName)" />

The above example passes a string with the name of "stringName" to the Lua function for the value property.

---

Toggle

A simple on/off toggle. Is able to send on/off status.

Attribute Name	Description	Type / Options	Default Value
onValueChanged	When toggled, a Lua function with this name will be triggered.	string	(none)
interactable			true
textColor			#000000
colors			#FFFFFF|#FFFFFF|#C8C8C8|rgba(0.78,0.78,0.78,0.5)
isOn	If the toggle is "on" or not. Is the value sent to onValueChanged's function.		false
toggleWidth	Sets the width in pixels of the internal check box	float	20
toggleHeight	Sets the width in pixels of the internal check box	float	20

Example

<Toggle>Toggle Text</Toggle>
<!-- Toggle which is selected by default -->
<Toggle isOn="true">Toggle Text</Toggle>

---

ToggleButton

A toggle, but styled as a button.

Attribute Name	Description	Type / Options	Default Value
onValueChanged	When toggled, a Lua function with this name will be triggered.	string	(none)
interactable			true
textColor			#000000
colors			#FFFFFF|#FFFFFF|#C8C8C8|rgba(0.78,0.78,0.78,0.5)
isOn	If the toggle is "on" or not. Is the value sent to onValueChanged's function.		false
textShadow			(none)
textOutline			(none)
textAlignment		UpperLeft UpperCenter UpperRight MiddleLeft MiddleCenter MiddleRight LowerLeft LowerCenter LowerRight	UpperLeft
icon		string	(none)
iconWidth		float
iconColor
iconAlignment		Left Right	Left
padding		float float float float	0 0 0 0

Example

<ToggleButton>Toggle Button Text</Toggle>

---

ToggleGroup

Allows a group of toggles to act as a radio button, where only 1 of them can be "checked" at once (works with Toggle or ToggleButton).

Attribute Name	Description	Type / Options	Default Value
allowSwitchOff	If this is set to true, then the user may clear their selection from within the ToggleGroup by clicking on the selected Toggle.		false
toggleBackgroundImage	Sets the default background image to use for nested Toggle elements.	string
toggleBackgroundColor			#FFFFFF
toggleSelectedImage	Sets the default image to use for selected (checked) nested Toggle elements.	string
toggleSelectedColor			#FFFFFF

Example

<ToggleGroup>
    <VerticalLayout>
        <Toggle>Toggle A</Toggle>
        <Toggle>Toggle B</Toggle>
        <Toggle>Toggle C</Toggle>
    </VerticalLayout>
</ToggleGroup>

<ToggleGroup>
    <HorizontalLayout>
        <ToggleButton>ToggleButton A</ToggleButton>
        <ToggleButton>ToggleButton B</ToggleButton>
        <ToggleButton>ToggleButton C</ToggleButton>
    </HorizontalLayout>
</ToggleGroup>

---

Slider

A value slider. Is able to send Value.

Attribute Name	Description	Type / Options	Default Value
onValueChanged	When the slider is moved, a Lua function with this name will be triggered. (rapidly)	string	(none)
interactable			true
colors			#FFFFFF|#FFFFFF|#C8C8C8|rgba(0.78,0.78,0.78,0.5)
minValue		float	0
maxValue		float	1
value	The value currently selected. Is the value sent to onValueChanged's function.	float	0
wholeNumbers			false
direction		LeftToRight RightToLeft TopToBottom BottomToTop	LeftToRight
backgroundColor			(none)
fillColor			(none)
fillImage		string
handleColor			(none)
handleImage		string

Example

<Slider minValue="0" maxValue="1" value="0.5" />

---

Dropdown

A dropdown menu. Is able to send the contents (or the index of the item in the list) of the selection made in it.

Attribute Name	Description	Type / Options	Default Value
onValueChanged	When an option is selected, a Lua function with this name will be triggered.	string	(none)
interactable			true
textColor			#000000
itemBackgroundColors			#FFFFFF
itemTextColor			#000000
checkColor	Color of the checkmark next to the selected item.		#000000
checkImage		string
arrowColor			#000000
arrowImage		string
dropdownBackgroundColor			#000000
dropdownBackgroundImage		string
dropdownHeight	Height of the dropdown list.	float
scrollbarColors
scrollbarImage		string
itemHeight	Height of the items in the dropdown list.	float

Tip

It's likely that you will need to adjust the scrollSensitivity for large dropdown menus.

Example

<Dropdown id="Selection" onValueChanged="optionSelected">
    <Option selected="true">Option 1</Option>
    <Option>Option 2</Option>
    <Option>Option 3</Option>
    <Option>Option 4</Option>
</Dropdown>

function optionSelected(player, selectedValue, id)
    print(player.steam_name .. " selected: " .. selectedValue)
end

Tip

Append (selectedIndex) to the function name to pass the index (0-indexed) of the selected option as second parameter. Note that this is passed as string, so you might want to turn it into a number for indexing a list.

To make sure that the dropdown selection is consistent across clients and edits with scripting, set the value attribute to the index (see the following example).

Example

<Dropdown id="Selection" onValueChanged="optionSelected(selectedIndex)">
    <Option selected="true">Option 1</Option>
    <Option>Option 2</Option>
    <Option>Option 3</Option>
    <Option>Option 4</Option>
</Dropdown>

function optionSelected(player, selectedIndex, id)
    -- convert string to number
    selectedIndex = tonumber(selectedIndex)

    -- set dropdown value to item index
    UI.setAttribute(id, "value", selectedIndex)

    -- example print
    print(player.steam_name .. " selected option with index: " .. selectedIndex)
end

---