Custom UI Overview - BLKTower/TestWiki GitHub Wiki

This page will cover the basics of creating custom UI. This page assumes a basic understanding of lua and contemporary UI frameworks. This tutorial focuses on the basics of UI and creating UI frames using script. For information on how to create custom UI with XML, refer to this guide.

References

• Download the example map here.
• Custom UI Trigger APIs.

Basics

You can create new UI elements with the NewFrame() function. If you look at the API, you'll see that all new frames require a parent frame (the new frame is created inside the parent frame). On a blank map, the only existing frame is the UI Root, which can be referenced with GetUiRoot(). The following script is how to create a basic frame:

local root = DCEI.GetUiRoot()

local square = DCEI.NewFrame(root)
DCEI.SetBackgroundImage(square, "btn_grey")
DCEI.SetMinSize(square, 120, 120)

This creates a blank square in the middle of the screen. Exquisite.

By default, new frames are centered inside their parent frame (in this case the UI root) and have no dimensions unless set by SetMinSize() or by having child frames with dimensions. Parent frames will attempt to expand to fit all children frames.

You can find a list of available textures that can used in SetBackgroundImage() in the Asset Previewer (Window > Asset Preview Window) under "Sprites.

We can add the following script to create two text labels in either corner of our square:

local label_one = DCEI.NewText(square)
DCEI.SetTopAlignmentInParent(label_one)
DCEI.SetLeftAlignmentInParent(label_one)
DCEI.SetText(label_one, "1")

local label_two = DCEI.NewText(square)
DCEI.SetBottomAlignmentInParent(label_two)
DCEI.SetRightAlignmentInParent(label_two)
DCEI.SetText(label_two, "2")

Our new text frames are pressed directly against the edges of our square, which doesn't look quite right. Let's fix this.

One approach is to add offsets to our text frames. Note that positive values move frames right/up and negative values move frames left/down.

local label_one = DCEI.NewText(square)
DCEI.SetTopAlignmentInParent(label_one)
DCEI.SetLeftAlignmentInParent(label_one)
DCEI.SetHorizontalOffsetInParent(label_one, 10)
DCEI.SetVerticalOffsetInParent(label_one, -10)
DCEI.SetText(label_one, "1")

local label_two = DCEI.NewText(square)
DCEI.SetBottomAlignmentInParent(label_two)
DCEI.SetRightAlignmentInParent(label_two)
DCEI.SetHorizontalOffsetInParent(label_two, -10)
DCEI.SetVerticalOffsetInParent(label_two, 10)
DCEI.SetText(label_two, "2")

Another approach is to simply apply some padding to our square.

DCEI.SetPadding(square, 10)

Either method creates space between the edge of the frame and our text labels (note that using both will create double spacing).

Lastly you can destroy a UI frame with Destroy(). Destroying a frame will destroy all of its children frames. Variables that hold references to UI frames are not set to nil when the referenced frame is destroyed, so you will want to manage this yourself if needed.

Frame Types

• NewFrame() is the basic frame type and is commonly used for containers and images.

• NewVStack() creates a vertical stack that evenly spaces children frames vertically.

  • SetSpacing() to set the spacing between stack elements.

• NewHStack() creates a horizontal stack that evenly spaces children frames horizontally.

  • Use SetSpacing() to set the spacing between stack elements.

• NewButton() creates a clickable button.

  • Use SetOnClickCallback() to add a callback function to execute when the button is pressed.
  • Use EnableButton() to enable/disable buttons.

• NewText() creates a text label.

  • Use SetText() to set the content of the text label.

Discussion

Visualizing how the badge_container vstack (black) expands to hold badge_row hstacks (blue) by adding background images to the respective frames. Note that the stacks only expand left-to-right and top-to-bottom due to how their alignment has been set.