Ui XML CommonAttributes - funovus/editor-wiki GitHub Wiki
Table of Contents
- [Ui XML Reference\CommonAttributes](#ui-xml-referencecommonattributes)
* [xmlns:bind](#xmlnsbind)
* [id](#id)
* [active](#active)
* [width](#width)
* [height](#height)
* [minWidth](#minwidth)
* [maxWidth](#maxwidth)
* [minHeight](#minheight)
* [maxHeight](#maxheight)
* [backgroundImage](#backgroundimage)
* [padding](#padding)
* [leftAlignmentInParent](#leftalignmentinparent)
* [rightAlignmentInParent](#rightalignmentinparent)
* [topAlignmentInParent](#topalignmentinparent)
* [bottomAlignmentInParent](#bottomalignmentinparent)
* [centerAlignmentInParent](#centeralignmentinparent)
* [horizontalOffsetInParent](#horizontaloffsetinparent)
* [verticalOffsetInParent](#verticaloffsetinparent)
* [flipHorizontal](#fliphorizontal)
* [flipVertical](#flipvertical)
* [matchParentHeight](#matchparentheight)
* [matchParentWidth](#matchparentwidth)
* [paddingLeft](#paddingleft)
* [paddingRight](#paddingright)
* [paddingTop](#paddingtop)
* [paddingBottom](#paddingbottom)
* [spacing](#spacing)
* [leftAlignment](#leftalignment)
* [rightAlignment](#rightalignment)
* [topAlignment](#topalignment)
* [bottomAlignment](#bottomalignment)
* [centerAlignment](#centeralignment)
* [alpha](#alpha)
* [useImageSizeRatio](#useimagesizeratio)
* [frameSizeByBackgroundImageSizeAndRatio](#framesizebybackgroundimagesizeandratio)
* [backgroundImageExpression](#backgroundimageexpression)
* [backgroundImageFillAmount](#backgroundimagefillamount)
* [backgroundImageFillHorizontal](#backgroundimagefillhorizontal)
* [backgroundImageFillVertical](#backgroundimagefillvertical)
* [backgroundImageFillRadial](#backgroundimagefillradial)
* [backgroundImageFillOrigin](#backgroundimagefillorigin)
* [backgroundImageFillAmountExpression](#backgroundimagefillamountexpression)
* [backgroundImageTiled](#backgroundimagetiled)
* [backgroundImagePixelsPerUnitMultiplier](#backgroundimagepixelsperunitmultiplier)
* [widthExpression](#widthexpression)
* [heightExpression](#heightexpression)
* [backgroundImageColor](#backgroundimagecolor)
* [backgroundImageColorExpressionR](#backgroundimagecolorexpressionr)
* [backgroundImageColorExpressionG](#backgroundimagecolorexpressiong)
* [backgroundImageColorExpressionB](#backgroundimagecolorexpressionb)
* [backgroundImageColorExpressionA](#backgroundimagecolorexpressiona)
* [backgroundImageGrayScale](#backgroundimagegrayscale)
* [tooltipText](#tooltiptext)
* [blockInput](#blockinput)
* [rotation3d](#rotation3d)
|
Ui XML Reference\CommonAttributes
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
<Frame id="frame" height="100" width="100" backgroundImageColor="r: 1, g: 1, b: 1, a: 0.5"/>
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" />
Value type: number
Supports data binding
<Frame id="frame" height="100" width="100" backgroundImageColor="r: 1, g: 1, b: 1, a: 0.5"/>
Value type: number
Supports data binding
<Frame id="frame" height="100" width="100" backgroundImageColor="r: 1, g: 1, b: 1, a: 0.5"/>
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" />
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>
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" />
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>
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" />
Value type: string
Supports data binding
<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>
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" />
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" />
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" />
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" />
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" />
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" />
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" />
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" />
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" />
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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" />
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" />
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" />
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)
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" />
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:
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:
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:
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" />
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)
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" />
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.
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)
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)
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" />
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)
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)
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)
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)
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" />
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" />
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" />
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: