UI

UI, a static global class AND an Object class. It is the method to interact with custom UI elements. It allows you to read/write attributes of elements defined in the XML of the UI. It also allows you to receive information from various inputs (like buttons) on-screen and on objects.

Attention

This class allows for the manipulation of UI at runtime. It does NOT modify or fetch the original XML in the editor, but rather what is displayed as it continues to run during a game. Just like with Lua, you can only get/set dynamic values during runtime. You can use onSave and onLoad to record any data you want to persist through save/load/undo.

For more information on how to build UI elements within XML, view the UI API.

Global and Object¶

UI can either be placed on the screen by using the Global UI or placed on an Object using Object UI. Depending on which you are using, these commands are used differently.

Example of calling a function targeted at the Global UI:
    UI.getAttributes(id)
Example of calling a function targeted at an Object UI:
    object.UI.getAttributes(id)

Inputs¶

Input Elements are able to trigger a function. By default, Global UI will trigger a function in Global and Object UI will trigger a function in the Object's script. To change the target script for an input, view more details here.

When creating the input element in XML, you will select the name of the function it activates. Regardless of its name, it always will pass parameters

functionName(player, value, id)

player: A direct Player reference to the person that triggered the input.
value: The value sent by the input. A numeric value or a string, generally.
- This is not used by buttons!
id:
- This is only passed if the element was given an Id attribute in the XML.

function onButtonClick(player, value, id)
    print(player.steam_name)
    print(id)
end

Member Variable Summary¶

Variable	Description	Type
loading	Indicates whether (the server) has finished loading all UI custom assets.

Function Summary¶

Function Name	Description	Return
getAttribute( id, attribute)	Obtains the value of a specified attribute of a UI element.
getAttributes( id)	Returns the attributes and their values of a UI element.
getCustomAssets()	Returns a table/array of custom assets.
getValue( id)	Obtains the value between elements tags, like: `<Text>ValueToGet</Text>`
getXml() getXml()	Returns the contents of the current UI formatted as XML.
getXmlTable()	Returns the contents of the current UI formatted as a table.
hide( id)	Hides the given UI element. Unlike the "active" attribute, hide triggers animations.
setAttribute( id, attribute, value)	Sets the value of a specified attribute of a UI element.
setAttributes( id, data)	Updates the value of the supplied attributes of a UI element.
setClass( id, names)	Replaces all classes on a UI element.
setCustomAssets( assets)	Sets/replaces the custom assets which your UI may make use of.
setValue( id, value)	Updates the value between elements tags, like: `<Text>ValueChanged</Text>`
setXml( xml, assets)	Sets/replaces the UI with the contents of the provided XML.
setXmlTable( data, assets)	Sets/replaces the UI with the contents of the provided UI table.
show( id)	Displays the given UI element. Unlike the "active" attribute, show triggers animations.

Function Details¶

getAttribute(...)¶

Obtains the value of a specified attribute of a UI element. What it returns will typically be a string or a number.

getAttribute(id, attribute)

id: The Id that was assigned, as an attribute, to the desired XML UI element.
attribute: The name of the attribute you wish to get the value of.

self.UI.getAttribute("testElement", "fontSize")

getAttributes(...)¶

Returns the attributes and their values of a UI element. It only returns the attributes (and values) for elements that have had those attributes set by the user.

getAttributes(id)

id: The Id that was assigned, as an attribute, to the desired XML UI element.

Return table

parameters: A Table with the attributes as keys and their XML value as the key's value.
- texture: The name of the image element
- color: The hex used for the color element's value.

IMPORTANT: This return table is an example of one you may get back from using it on a RawImage element type. The attribute keys you get back and their values will depend on the element you use the function on as well as the attributes you, the user, have assigned to it.

getCustomAssets()¶

Returns a table/array of custom assets.

Example

Log the UI's current custom assets.

log(UI.getCustomAssets())

getValue(...)¶

Obtains the value between elements tags, like: <Text>ValueObtained</Text>

getValue(id)

id: The Id that was assigned, as an attribute, to the desired XML UI element.

string = UI.getValue("testElement")
print(string)

getXmlTable()¶

Returns the contents of the current UI formatted as a table.

Example Returned Table:

{
    {
        tag="HorizontalLayout",
        attributes={
            height=200,
            width=1000,
            color="rgba(0,0,0,0.7)",
        },
        children={
            {
                tag="Text",
                attributes={
                    fontSize=100,
                    color="red",
                },
                value="Example",
            },
            {
                tag="Text",
                attributes={
                    text="Message",
                    fontSize=100,
                    color="blue",
                },
            },
        }
    }
}

What the XML would look like which returns that table:

<HorizontalLayout height="200" width="1000" color="rgba(0,0,0,0.7)">
    <Text fontSize="100" color="red">Example</Text>
    <Text text="Message" fontSize="100" color="blue" />
</HorizontalLayout>

hide(...)¶

Hides the given UI element. Unlike the "active" attribute, hide triggers animations.

hide(id)

id: The Id that was assigned, as an attribute, to the desired XML UI element.

self.UI.hide("testElement")

setAttribute(...)¶

Sets the value of a specified attribute of a UI element.

Important

This will override the run-time value from the XML UI for all players, forcing them to see the same value.

setAttribute(id, attribute, value)

id: The Id that was assigned, as an attribute, to the desired XML UI element.
attribute: The name of the attribute you want to set the value of.
value: The value to set for the attribute.

self.UI.setAttribute("testElement", "fontSize", 200)

setAttributes(...)¶

Updates the value of the supplied attributes of a UI element. You do not need to set every attribute with the data table, an element will continue using any previous values you do not overwrite.

Important

This will override the run-time value from the XML UI for all players, forcing them to see the same value.

setAttributes(id, data)

id: The Id that was assigned, as an attribute, to the desired XML UI element.
data: A Table with key/value pairs representing attributes and their values.

Example data table

data: A Table with parameters which guide the function.
- data.fontSize: Attribute's desired value value
- data.color: Attribute's desired value

IMPORTANT: This table is an example of one you may use when setting a text UI element. The attribute keys you use and their values will depend on the element you use the function on.

attributeTable = {
    fontSize = 300,
    color = "#000000"
}
self.UI.setAttributes("exampleText", attributeTable)

setClass(...)¶

Replaces all classes on a UI element.

setClass(id, names)

id: The ID of the UI element that should have its classes replaced.
names: Space separated class names.

Example

Replace all classes on the element with ID someElementId with two classes "important" and "large".

UI.setClass("someElementId", "important large")

setCustomAssets(...)¶

Sets/replaces the custom assets which your UI may make use of. Providing an empty table will remove all existing UI Assets.

Warning

This function will overwrite/replace any currently existing assets in Custom UI Assets, not add to them.

setCustomAssets(assets)

assets: A table/array containing sub-tables which each represent a custom asset.

Custom Assets¶

Custom assets are represented as a table with the following properties:

Name	Type	Default	Description
name		Mandatory	The name you'll use to refer to this asset in your XML UI.
url		Mandatory	The URL this asset will be loaded from.

Currently, only images are supported as custom assets.

Example

Add two images which can be used within your XML UI.

UI.setCustomAssets({
    {
        name = "Image1",
        url = "http://placehold.it/120x120&text=image1"
    },
    {
        name = "Image2",
        url = "http://placehold.it/120x120&text=image2"
    },
})

setValue(...)¶

Updates the value between elements tags, like: <Text>ValueChanged</Text>

setValue(id, value)

id: The Id that was assigned, as an attribute, to the desired XML UI element.
value: The value to put between the element tags.

UI.setValue("testElement", "New Text To Display")

setXml(...)¶

Sets/replaces the UI with the contents of the provided XML.

setXml(xml, assets)

xml: A string containing XML representing the desired UI.
assets: A table/array containing sub-tables which each represent a custom asset.
- Optional. When omitted existing custom assets will not be modified.

Warning

UI changes do not take effect immediately. Any attempt to query the contents of the XML will return stale results until loading returns to false.

Example

Display a single text label with the contents "Test".

UI.setXml("<Text>Test</Text>")

setXmlTable(...)¶

Sets/replaces the UI with the contents of the provided UI table.

setXmlTable(data, assets)

data: A table containing sub-tables. One sub-table for each element being created.
- tag: The element type.
- attributes: A table containing attribute names for keys. Available attribute types depend on tag's element type.
  - Optional, defaults to not being used.
  - Example key/value pairs: text="Test", color="black"
- value: Text that appears <Text>Here</Text>, between the <> and ``.
  - Optional, defaults to an empty string.
- children: A table containing more sub-tables, formatted as above. This does mean the sub-tables can contain their own children as well, containing sub-sub tables, etc.
  - Optional, defaults to not being used.
assets: A table/array containing sub-tables which each represent a custom asset.
- Optional. When omitted existing custom assets will not be modified.

Warning

UI changes do not take effect immediately. Any attempt to query the contents of the XML will return stale results until loading returns to false.

Example

Display two text labels within a horizontal layout.

UI.setXmlTable({
    {
        tag="HorizontalLayout",
        attributes={
            height=200,
            width=1000,
            color="rgba(0,0,0,0.7)",
        },
        children={
            {
                tag="Text",
                attributes={
                    fontSize=100,
                    color="red",
                },
                value="Example",
            },
            {
                tag="Text",
                attributes={
                    text="Message",
                    fontSize=100,
                    color="blue",
                },
            },
        }
    }
})

show(...)¶

Shows the given UI element. Unlike the "active" attribute, show triggers animations.

show(id)

id: The Id that was assigned, as an attribute, to the desired XML UI element.

self.UI.show("testElement")

UI

Global and Object¶

Inputs¶

Member Variable Summary¶

Function Summary¶

getXml()

Function Details¶

getAttribute(...)¶

getAttributes(...)¶

getCustomAssets()¶

getValue(...)¶

getXmlTable()¶

hide(...)¶

setAttribute(...)¶

setAttributes(...)¶

setClass(...)¶

setCustomAssets(...)¶

Custom Assets¶

setValue(...)¶

setXml(...)¶

setXmlTable(...)¶

show(...)¶