Attributes commonly available to most custom UI frames created in XML.

Value type: string

Used to enable data binding of other XML attributes (where supported) by adding xmlns:bind="https://platform.wildsky.dev/xml/ui/bind" to the top level frame of a UI element. Attribute binding can be used to bind constants or state variables to XML attributes that update automatically on state change.

Attributes marked with Supports data binding indicate that the attribute can be bound to states, with some frames having unique bindings such as buttons' onClick.

<VStack xmlns:bind="https://platform.wildsky.dev/xml/ui/bind">
    <!-- Declare initial state values. -->
    <State name="red" booleanValue="false" />
    <!-- Show different background images depending on the state value and flip state value when clicked. -->
    <Button bind:backgroundImage="'btn_' .. (state.red and 'red' or 'blue')" bind:onClick="state.red = not state.red">
        <Text text="switch color" />
    </Button>
    <Text bind:text="state.red and 'red' or 'blue'" />
</VStack>

State variables can be declared using XML tag "State" and assgined an initial value (right now only boolean/number/string types are supported). To bind attributes to state variables, first add a declaration for the "bind" XML namespace to the outer most XML tag and then use "bind:xxx" attributes to bind attributes to a Lua expression. In the lua expression you can reference the current UI state variables through a Lua table named "state".

To access UI state variables in trigger, use GetXmlUiState(). E.g.:

local state = DCEI.GetXmlUiState(ui)
state.red = true

Unlike UI data binding expressions that are evaluated every frame, this new UI state binding will only re-evaluate the attributes when the state changes. It's also more convenient to use as it can be declared entirely in XML and is more expressive as it allows any valid Lua expressions.

Value type: string

The ID of the UI frame.

<Frame id="frame" height="100" width="100" backgroundImageColor="r: 1, g: 1, b: 1, a: 0.5"/>

• FindXmlUiById()

Value type: boolean

Supports data binding

The active status of the UI frame, where true is active and false is inactive. Inactive frames are not displayed.

<Frame id="frame" height="100" width="100" backgroundImageColor="r: 1, g: 1, b: 1, a: 0.5" active="false" />

• IsActive()
• SetActive()

Value type: number

Supports data binding

The width of the UI frame.

<Frame id="frame" height="100" width="100" backgroundImageColor="r: 1, g: 1, b: 1, a: 0.5"/>

• GetFrameWidth()
• SetSize()

• matchParentWidth

Value type: number

Supports data binding

The height of the UI frame.

<Frame id="frame" height="100" width="100" backgroundImageColor="r: 1, g: 1, b: 1, a: 0.5"/>

• GetFrameHeight()
• SetSize()

• matchParentHeight

Value type: number

Supports data binding

The minimum width of the UI frame.

<Frame id="frame" minHeight="100" minWidth="100" backgroundImageColor="r: 1, g: 1, b: 1, a: 0.5" />

• SetMinSize()

Value type: number

Supports data binding

The maximum width of the UI frame.

<Frame id="frame" maxHeight="100" maxWidth="100" backgroundImageColor="r: 1, g: 1, b: 1, a: 0.5">
    <Frame height="200" width="200" backgroundImageColor="r: 0, g: 0, b: 1, a: 0.5" />
</Frame>

• SetMaxSize()

Value type: number

Supports data binding

The minimum height of the UI frame.

<Frame id="frame" minHeight="100" minWidth="100" backgroundImageColor="r: 1, g: 1, b: 1, a: 0.5" />

• SetMinSize()

Value type: number

Supports data binding

The maximum height of the UI frame.

<Frame id="frame" maxHeight="100" maxWidth="100" backgroundImageColor="r: 1, g: 1, b: 1, a: 0.5">
    <Frame height="200" width="200" backgroundImageColor="r: 0, g: 0, b: 1, a: 0.5" />
</Frame>

Related Trigger Function(s):

• SetMaxSize()

Value type: string

Supports data binding

The background image of the UI frame. This background image can be tinted by backgroundImageColor.

<Frame id="frame" height="100" width="100" backgroundImage="cart" backgroundImageColor="r: 1, g: 1, b: 1, a: 0.5" />

• SetBackgroundImage()

• backgroundImageExpression
• backgroundImageColor

Value type: string

Supports data binding

The padding of the UI frame.

<VStack padding="20" backgroundImage="frame01">
    <Frame height="100" width="100" backgroundImageColor="r: 0.5, g: 1, b: 0.5, a: 1" />
    <Frame height="100" width="100" backgroundImageColor="r: 0.5, g: 0.5, b: 1, a: 1" />
</VStack>

• SetPadding()

• paddingLeft
• paddingRight
• paddingTop
• paddingBottom

Value type: boolean

Supports data binding

The left alignment status of the UI frame in its parent, where true is left-aligned and false is not.

Note that setting left/right alignment won't work for frames that have their horizontal alignment determined by another source (ex, the children frames of a hstack). This can be worked around by wrapping the frame you want to reposition inside a blank frame.

<Frame height="100" width="100" backgroundImageColor="r: 1, g: 1, b: 0.5, a: 1" leftAlignmentInParent="true" />

• SetLeftAlignmentInParent()

Value type: boolean

Supports data binding

The right alignment status of the UI frame in its parent, where true is right-aligned and false is not.

Note that setting left/right alignment won't work for frames that have their horizontal alignment determined by another source (ex, the children frames of a hstack). This can be worked around by wrapping the frame you want to reposition inside a blank frame.

<Frame height="100" width="100" backgroundImageColor="r: 1, g: 1, b: 0.5, a: 1" rightAlignmentInParent="true" />

• SetRightAlignmentInParent()

Value type: boolean

Supports data binding

The top alignment status of the UI frame in its parent, where true is top-aligned and false is not.

Note that setting top/bottom alignment won't work for frames that have their vertical alignment determined by another source (ex, the children frames of a vstack). This can be worked around by wrapping the frame you want to reposition inside a blank frame.

<Frame height="100" width="100" backgroundImageColor="r: 1, g: 1, b: 0.5, a: 1" topAlignmentInParent="true" />

• SetTopAlignmentInParent()

Value type: boolean

Supports data binding

The bottom alignment status of the UI frame in its parent, where true is bottom-aligned and false is not.

Note that setting top/bottom alignment won't work for frames that have their vertical alignment determined by another source (ex, the children frames of a vstack). This can be worked around by wrapping the frame you want to reposition inside a blank frame.

<Frame height="100" width="100" backgroundImageColor="r: 1, g: 1, b: 0.5, a: 1" bottomAlignmentInParent="true" />

• SetBottomAlignmentInParent()

Value type: boolean

Supports data binding

The center alignment status of the UI frame in its parent, where true is center-aligned and false is not. This is the default alignment for newly created frames.

<Frame height="100" width="100" backgroundImageColor="r: 1, g: 1, b: 0.5, a: 1" centerAlignmentInParent="true" />

• SetCenterAlignmentInParent()

Value type: number

Supports data binding

The horizontal offset of the UI frame in its parent.

<Frame height="100" width="100" backgroundImageColor="r: 1, g: 1, b: 0.5, a: 1" horizontalOffsetInParent="100" />

• SetHorizontalOffsetInParent

Value type: number

Supports data binding

The vertical offset of the UI frame in its parent.

<Frame height="100" width="100" backgroundImageColor="r: 1, g: 1, b: 0.5, a: 1" verticalOffsetInParent="100" />

• SetVerticalOffsetInParent

Value type: boolean

Supports data binding

The horizontal flip status of the UI frame, where true is flipped and false is not. Does not work on the root UI.

<Frame backgroundImage="cart" useImageSizeRatio="1" flipHorizontal="true" />

• FlipHorizontal()

Value type: boolean

Supports data binding

The vertical flip status of the UI frame, where true is flipped and false is not. Does not work on the root UI.

<Frame backgroundImage="cart" useImageSizeRatio="1" flipVertical="true" />

• FlipVertical()

Value type: boolean

Supports data binding

The match parent height status of the UI frame, where true is matching and false means there is a set height.

<Frame height="300" width="300">
    <Frame backgroundImage="cart" matchParentHeight="true" matchParentWidth="true" />
</Frame>

• SetMatchParent()

Value type: boolean

Supports data binding

The match parent width status of the UI frame, where true is matching and false means there is a set width.

<Frame height="300" width="300">
    <Frame backgroundImage="cart" matchParentHeight="true" matchParentWidth="true" />
</Frame>

• SetMatchParent()

Value type: number

Supports data binding

The left padding of the UI frame.

<VStack padding="10" paddingLeft="20" backgroundImage="frame01">
    <Frame height="100" width="100" backgroundImageColor="r: 0.5, g: 1, b: 0.5, a: 1" />
    <Frame height="100" width="100" backgroundImageColor="r: 0.5, g: 0.5, b: 1, a: 1" />
</VStack>

• SetPaddingLeft()

• padding

Value type: number

Supports data binding

The right padding of the UI frame.

<VStack padding="10" paddingRight="20" backgroundImage="frame01">
    <Frame height="100" width="100" backgroundImageColor="r: 0.5, g: 1, b: 0.5, a: 1" />
    <Frame height="100" width="100" backgroundImageColor="r: 0.5, g: 0.5, b: 1, a: 1" />
</VStack>

• SetPaddingRight()

• padding

Value type: number

Supports data binding

The top padding of the UI frame.

<VStack padding="10" paddingTop="20" backgroundImage="frame01">
    <Frame height="100" width="100" backgroundImageColor="r: 0.5, g: 1, b: 0.5, a: 1" />
    <Frame height="100" width="100" backgroundImageColor="r: 0.5, g: 0.5, b: 1, a: 1" />
</VStack>

• SetPaddingTop()

• padding

Value type: number

Supports data binding

The bottom padding of the UI frame.

<VStack padding="10" paddingBottom="20" backgroundImage="frame01">
    <Frame height="100" width="100" backgroundImageColor="r: 0.5, g: 1, b: 0.5, a: 1" />
    <Frame height="100" width="100" backgroundImageColor="r: 0.5, g: 0.5, b: 1, a: 1" />
</VStack>

• SetPaddingBottom()

• padding

Value type: number

Supports data binding

The spacing of the UI frame's child elements. This function affects frames that automatically position their children, such as stacks or scrolls. For scrolls, this function should be called on the content frame returned by GetScrollContent().

<VStack padding="20" spacing="20" backgroundImage="frame01">
    <Frame height="100" width="100" backgroundImageColor="r: 0.5, g: 1, b: 0.5, a: 1" />
    <Frame height="100" width="100" backgroundImageColor="r: 0.5, g: 0.5, b: 1, a: 1" />
</VStack>

• SetSpacing()

Value type: boolean

Supports data binding

The left alignment status for the UI frame's contents, where true is left-aligned and false is not.

<Frame height="200" width="200" leftAlignment="true" backgroundImageColor="r: 1, g: 0, b: 1, a: 0.4">
    <Frame backgroundImage="cart" height="100" width="100" />
</Frame>

• SetLeftAlignment()

Value type: boolean

Supports data binding

The right alignment status for the UI frame's contents, where true is right-aligned and false is not.

<Frame height="200" width="200" rightAlignment="true" backgroundImageColor="r: 1, g: 0, b: 1, a: 0.4">
    <Frame backgroundImage="cart" height="100" width="100" />
</Frame>

• SetRightAlignment()

Value type: boolean

Supports data binding

The top alignment status for the UI frame's contents, where true is top-aligned and false is not.

<Frame height="200" width="200" topAlignment="true" backgroundImageColor="r: 1, g: 0, b: 1, a: 0.4">
    <Frame backgroundImage="cart" height="100" width="100" />
</Frame>

• SetTopAlignment()

Value type: boolean

Supports data binding

The bottom alignment status for the UI frame's contents, where true is bottom-aligned and false is not.

<Frame height="200" width="200" bottomAlignment="true" backgroundImageColor="r: 1, g: 0, b: 1, a: 0.4">
    <Frame backgroundImage="cart" height="100" width="100" />
</Frame>

• SetBottomAlignment()

Value type: boolean

Supports data binding

The center alignment status for the UI frame's contents, where true is center-aligned and false is not. This is the default alignment.

<Frame height="200" width="200" centerAlignment="true" backgroundImageColor="r: 1, g: 0, b: 1, a: 0.4">
    <Frame backgroundImage="cart" height="100" width="100" />
</Frame>

• SetCenterAlignment()

Value type: number

Supports data binding

The alpha value for the UI frame. This controls the transparency of the frame, and has a compounding effect with the alpha value of the background image color. This alpha value will also be applied to any children frames, making them transparent or opaque in turn - this cannot be overwritten by calling this function on children frames.

<Frame backgroundImage="cart" useImageSizeRatio="1" alpha="0.5" />

• SetFrameAlpha()
• AnimateAlpha()

Value type: number

Supports data binding

This ratio determines the size of the frame based on the size of its background image, where 1 is the original size of the image. This size ratio will not overwrite a set size for the frame. Larger values will display a larger image.

<Frame backgroundImage="cart" useImageSizeRatio="1" />

• UseImageSizeRatio()

Value type: number

Supports data binding

The image size ratio for the UI frame. Functionally identical to useImageSizeRatio, may be deprecated.

<Frame backgroundImage="cart" frameSizeByBackgroundImageSizeAndRatio="1" />

• UseImageSizeRatio()

Value type: string

Supports data binding

The background image expression for the UI frame. Expressions use data bound by BindData().

<Frame backgroundImageExpression="data.image" useImageSizeRatio="1" />

Where "data.image" is data bound in lua:

local data = {image = "cart"}
DCEI.BindData("data", data)

• SetBackgroundImageExpression()
• BindData()

• backgroundImage

Value type: number

Supports data binding

The background image fill amount for the UI frame, from 0-1.

<Frame backgroundImage="cart" backgroundImageFillAmount="0.5" useImageSizeRatio="1" />

• SetBackgroundImageFillAmount()
• GetBackgroundImageFillAmount()

Value type: boolean

Supports data binding

The background image horizontal fill status of the UI frame in its parent, where true means the background image fill is horizontal and false means it is not. This is the default fill direction.

<Frame backgroundImage="cart" backgroundImageFillAmount="0.5" backgroundImageFillHorizontal="true" useImageSizeRatio="1" />

Horizontal fill origin left:

Horizontal fill origin right:

• SetBackgroundImageFillHorizontal()

Value type: boolean

Supports data binding

The background image vertical fill status of the UI frame in its parent, where true means the background image fill is vertical and false means it is not.

<Frame backgroundImage="cart" backgroundImageFillAmount="0.5" backgroundImageFillVertical="true" useImageSizeRatio="1" />

Vertical fill origin bottom:

Vertical fill origin top:

• SetBackgroundImageFillVertical()

Value type: boolean

Supports data binding

The background image radial fill status of the UI frame in its parent, where true means the background image fill is radial and false means it is not.

<Frame backgroundImage="cart" backgroundImageFillAmount="0.75" backgroundImageFillRadial="true" useImageSizeRatio="1" />

Radial fill origin bottom:

Radial fill origin right:

Radial fill origin top:

Radial fill origin left:

• SetBackgroundImageFillRadial()

Value type: number

Supports data binding

The background image fill origin side of the UI frame in its parent.

[0, 1] for horizontal or vertical fills ([left, right] and [bottom, top])
[0, 1, 2, 3] for radial fills ([bottom, right, top, left])

Horizontal fill origin left:

Horizontal fill origin right:

Vertical fill origin bottom:

Vertical fill origin top:

Radial fill origin bottom:

Radial fill origin right:

Radial fill origin top:

Radial fill origin left:

<Frame backgroundImage="cart" backgroundImageFillAmount="0.75" backgroundImageFillRadial="true" backgroundImageFillOrigin="3" useImageSizeRatio="1" />

• SetBackgroundImageFillOrigin()

Value type: string

Supports data binding

The background image fill amount expression for the UI frame. Expressions use data bound by BindData().

<Frame backgroundImage="cart" backgroundImageFillAmountExpression="data.fill" useImageSizeRatio="1" />

Where "data.fill" is data bound in lua:

local data = {fill = 0.5}
DCEI.BindData("data", data)

• SetBackgroundImageFillAmountExpression()
• BindData()

Value type: boolean

Supports data binding

The background image tiling status for the UI frame. By default this is true for 9 sliced images.

<Frame backgroundImage="frame01" height="300" width="300" backgroundImageTiled="false" />

• SetBackgroundImageTiled()

Value type: number

Supports data binding

The background image pixels per unit multiplier for the UI frame. For 9 sliced images, this will increase or decrease the amount of tile slices used in the background image.

<!-- standard cart background image -->
<Frame backgroundImage="cart" useImageSizeRatio="1" horizontalOffsetInParent="-300" backgroundImagePixelsPerUnitMultiplier="1" backgroundImageTiled="true" />

<!-- 9-sliced frame background image -->
<Frame backgroundImage="frame01_blue" height="250" width="250" horizontalOffsetInParent="300" backgroundImagePixelsPerUnitMultiplier="1" />

Lua code to render the frames:

    local xml = DCEI.NewUiFromXml(DCEI.GetUiRoot(), "frame")
    local cart = DCEI.NewUiFromXml(DCEI.GetUiRoot(), "cart")

The example usage above produces this output:

Both frames look normal.

When backgroundImagePixelsPerUnitMultiplier is given a value of 2:

On the left, there is now a grid of cart images, and on the right the 9-sliced image has sharper corners.

When backgroundImagePixelsPerUnitMultiplier is given a value of 0.5:

On the left, the cart image only displays the bottom right corner as that is all it has space for, and on the right the 9-sliced image is much more rounded. Both images are also noticeably more pixilated.

• SetPixelsPerUnitMultiplier()

Value type: string

Supports data binding

The width expression for the UI frame. Expressions use data bound by BindData().

<Frame backgroundImage="cart" width="data.width" height="data.height" />

Where "data.width" is data bound in lua:

local data = {width = 100, height = 100}
DCEI.BindData("data", data)

• SetWidthExpression()
• BindData()

Value type: string

Supports data binding

The height expression for the UI frame. Expressions use data bound by BindData().

<Frame backgroundImage="cart" width="data.width" height="data.height" />

Where "data.height" is data bound in lua:

local data = {width = 100, height = 100}
DCEI.BindData("data", data)

• SetHeightExpression()
• BindData()

Value type: color

The background image color or tint for the UI frame, using RGBA values (valid values are between 0 and 1). Note that frames without background images can be tinted a solid color. Alpha 1 is completely opaque, alpha 0 is completely transparent.

<Frame height="100" width="100" backgroundImageColor="r: 0.5, g: 1, b: 0.5, a: 1" />

• SetBackgroundImageColor()

• backgroundImage

Value type: string

The background image color's R value expression for the UI frame. Expressions use data bound by BindData().

<Frame backgroundImage="cart" backgroundImageColorExpressionR="data.R" backgroundImageColorExpressionG="data.G" backgroundImageColorExpressionB="data.B" backgroundImageColorExpressionA="data.A" useImageSizeRatio="1" />

Where "data.R", "data.G", "data.B", and "data.A" are data bound in lua:

local data = {R = 1, G = 1, B = 1, A = 1}
DCEI.BindData("data", data)

• SetBackgroundImageColorExpression()
• BindData()

Value type: string

The background image color's G value expression for the UI frame. Expressions use data bound by BindData().

<Frame backgroundImage="cart" backgroundImageColorExpressionR="data.R" backgroundImageColorExpressionG="data.G" backgroundImageColorExpressionB="data.B" backgroundImageColorExpressionA="data.A" useImageSizeRatio="1" />

Where "data.R", "data.G", "data.B", and "data.A" are data bound in lua:

local data = {R = 1, G = 1, B = 1, A = 1}
DCEI.BindData("data", data)

• SetBackgroundImageColorExpression()
• BindData()

Value type: string

The background image color's B value expression for the UI frame. Expressions use data bound by BindData().

<Frame backgroundImage="cart" backgroundImageColorExpressionR="data.R" backgroundImageColorExpressionG="data.G" backgroundImageColorExpressionB="data.B" backgroundImageColorExpressionA="data.A" useImageSizeRatio="1" />

Where "data.R", "data.G", "data.B", and "data.A" are data bound in lua:

local data = {R = 1, G = 1, B = 1, A = 1}
DCEI.BindData("data", data)

• SetBackgroundImageColorExpression()
• BindData()

Value type: string

The background image color's A value expression for the UI frame. Expressions use data bound by BindData().

<Frame backgroundImage="cart" backgroundImageColorExpressionR="data.R" backgroundImageColorExpressionG="data.G" backgroundImageColorExpressionB="data.B" backgroundImageColorExpressionA="data.A" useImageSizeRatio="1" />

Where "data.R", "data.G", "data.B", and "data.A" are data bound in lua:

local data = {R = 1, G = 1, B = 1, A = 1}
DCEI.BindData("data", data)

• SetBackgroundImageColorExpression()
• BindData()

Value type: boolean

Supports data binding

The background image gray scale status for the UI frame, where true means the background image is in gray scale and false means it is not.

<Frame backgroundImage="cart" useImageSizeRatio="1" backgroundImageGrayScale="true" />

• SetBackgroundImageGrayScale()

Value type: string

Supports data binding

The tooltip text for the UI frame. Child frame tooltips will show over parent frame tooltips.

<Frame backgroundImage="cart" useImageSizeRatio="1" tooltipText="Frame" />

• SetTooltipText()

Value type: boolean

Supports data binding

The input blocking status for the UI frame, where true means input is being blocked and false means it is not. Requires a background image (or color) to be set (but it can be made invisible).

<!-- Image blocking input -->
<Frame backgroundImage="cart" useImageSizeRatio="1" blockInput="true" />

<!-- Solid background color blocking input -->
<Frame backgroundImageColor="r: 0, g: 1, b: 1, a: 0.25" matchParentHeight="true" matchParentWidth="true" blockInput="true" />

• SetBlockInput()

Value type: vector3

The 3D rotation for the UI frame.

<HStack spacing="20" padding="20" backgroundImage="frame01_purple">
    <Frame backgroundImage="cart" useImageSizeRatio="1" rotation3d="x: 45, y: 0, z: 0" />
    <Frame backgroundImage="cart" useImageSizeRatio="1" rotation3d="x: 0, y: 45, z: 0" />
    <Frame backgroundImage="cart" useImageSizeRatio="1" rotation3d="x: 0, y: 0, z: 45" />
</HStack>

To help visualize the rotation axis, the above example usage creates the following UI:

• SetRotation3D()