Table of Contents:

Mods\UserInterface Mod

The UserInterface Mod is used to quickly create, hookup, and manage game UI. This is best used when working with UI created with XML but also supports script-created UI. It also comes with a number of handy UI templates such as red pips and big hand.

For newer projects using Presentation scripting, see GMUI, a newer generation that differentiates itself from this mod's lower case spelling of gmui.

WARNING: This mod is deprecated. See GMUI instead.

How to install:

First open the Data Window and add gmui as a registry dependency:
image
Then include in your lua file with local gmui = require("gmui")

Features

Here is a Lua snippet from the most recent demo to give you a quick rundown of how to use gmui for UI in Lua. Be sure to downlod the project for a closer look, and reference the test of this document for more documentation on the gmui mod.

Download the demo maps:

-- LIBRARIES
local core = require("core")
local gmui = require("gmui") -- Must also be added as a registry dependency under "Project Settings" in the data window
local data = require("game_data")

-- SCRIPT EXPORTS
local ui = {}

-- =======================================================================================
-- ANCHOR (1) LAYOUT BASICS
-- start here for the basics on how to use GMUI layouts, their methods, and xml states
-- =======================================================================================
-- NOTE: using recursive hookup will hook up all includes as a hierarchy of layout object references
ui.glue = gmui.Layout:New({
    name = "Glue",
    recursive_hookup = true,
})

-- GAME PAGE
-- since "Glue/Pages" was included in "Glue" with id "pages", it can now be referenced as `ui.glue.pages`
-- and since "Glue/Pages/Game" was in "Glue/Pages" with id "game", it can be referenced as `ui.glue.pages.game`
local layout = ui.glue.pages.game

-- NOTE: a layout is just a class object that represents XML defined in data
-- you can add properties to it, just like any other table
layout.button_press_count = 0

function layout:Initialize()
    -- NOTE: the root frame of a layout is automatically assigned the id "Frame" by gmui
    -- we can create a mask by adjusting the root frame's image color on init
    DCEI.SetFrameImageColor(self.Frame, { r = 0, g = 0, b = 0, a = 0.5 })

    -- set this layout as initialized
    self.is_initialized = true
end

function layout:Update()
    -- initialize this layout the first time it updates
    if not self.is_initialized then
        self:Initialize()
    end

    -- NOTE: any frame within the XML can be referenced by its id; here we're updating `ToggleCountLabel`
    -- note how "{[x]}"" in the translation text is replaced by the `x` key value
    local text = DCEI.GetTranslationText("ui/game/buttons_pressed", { x = self.button_press_count })
    DCEI.SetTextFrameText(self.ToggleCountLabel, text)
end

function layout:IncrementButtonPressCount()
    self.button_press_count = self.button_press_count + 1
    self:Update()
end

-- GAME PAGE - TOGGLE ACTIVE BUTTON
-- NOTE: XML frames (frame objects) use CamelCase id's whereas included layouts (class objects) use snake_case id's
-- this style is used so you always know what type of object you're dealing with
local layout = ui.glue.pages.game.toggle_active
DCEI.SetOnClickCallback(layout.Button, function()
    local chest_layout = ui.glue.pages.game.basic_chest

    -- NOTE: gmui layouts come with a few of useful methods, like Show/Hide() and OnShow/OnHide()
    if DCEI.IsFrameActive(chest_layout.Frame) then
        chest_layout:Hide()
    else
        chest_layout:Show()
    end

    -- increment game page button press count
    ui.glue.pages.game:IncrementButtonPressCount()
end)

Usage Instruction

Have an idea for additional features or UI templates? Let @coffee know!

Layout Methods

The following functions can be used with any layouts created with Layout:New() and can be used such as:

local gmui = require("gmui")

local layout = gmui.Layout:New({
    parent = DCEI.GetUiRootFrame(),
    name = "Standard/Layer/Mask"
})

-- initialize
layout:HideImmediate()

Note that the following are template functions and don't actually do anything until overwritten:

Layout:Show()

layout:Show()

Description

Shows the layout's root frame and runs any related functions. Specifically:

Note that Show/Hide set the root frame's active state and should not be used with DCEI.SetFrameActive().

Layout:Hide()

layout:Hide()

Description

Hides the layout's root frame and runs any related functions. Specifically:

Note that Show/Hide set the root frame's active state and should not be used with DCEI.SetFrameActive().

Layout:HideImmediate()

layout:HideImmediate()

Description

Hides the layout's root frame as in Layout:Hide() but does not play the on_hide_animation. This is useful for initializing frames that are not visible on map start.

Layout:Destroy()

layout:Destroy()

Description

Destroys the layout by running DCEI.Destroy(self.Frame).

Layout:OnShow()

layout:OnShow()

Description

An empty function that can be overwritten to execute functions when the layout is shown.

Example Usage

local layout = gmui.Layout:New({
    parent = ui.lower.Frame,
    name = "Menu/Leaderboard"
})

function layout:OnShow()
    -- shows the lower screen mask when the leaderboard is shown
    ui.lower.mask:Show()
end

Layout:OnHide()

layout:OnHide()

Description

An empty function that can be overwritten to execute functions when the layout is hidden.

Example Usage

local layout = gmui.Layout:New({
    parent = ui.lower.Frame,
    name = "Menu/Leaderboard"
})

function layout:OnHide()
    -- hides the lower screen mask when the leaderboard is hidden
    ui.lower.mask:Hide()
end

Layout:OnPress()

layout:OnPress()

Description

An empty function that exists for each layout to be overriden. This one has no explicit usage by itself, but is suggested for use if the layout is a button.

Layout:Exists()

layout:Exists()

Description

Returns true if the layout's root frame still exists.

Layout:GetChildCollection()

layout:GetChildCollection( collection_name )

Description

Returns a list of child layouts or frames with ids that match the collection_name appended with "_n" where n will be the child's collection index. Useful creating and hooking up tables of layouts with many static child items, such as inventory slots or attribute lists.

Example Usage

-- for a layout with children "item_1", "item_2", and "item_3", the collection would contain these 3 frames
layout.items = layout:GetChildCollection("item")
for index, child in ipairs(layout.items) do
    DCEI.SetTextFrameText(child.Label, index)
end

Mod Functions

Layout:New()

gmui.Layout:New(args)

Description

Returns a new layout from the given arguments. A layout is a table that represents a UI element and has some built-in functionality with the Layout Methods. Layouts can be built from UI frames defined in XML or in script.

Layouts created from XML will have each child frame with id added to the layout using the id as the frame's key. For instance, if a layout contains a child with the id TitleLabel, this child frame can be referenced as layout.TitleLabel.

Root Frame

Regardless of how the layout was constructed, the root frame can be gotten with layout.Frame such as:

local layout = gmui.Layout:New()
DCEI.SetFrameSize(layout.Frame, 100, 100)
DCEI.SetFrameImageColor(layout.Frame, {r = 1, g = 0, b = 0, a = 0.5})

Parameters

Example Usage

Using an XML frame named "Standard/Button/Button" such as:

<Frame>
    <Button id="Button" height="108" width="224">
        <Text id="Label" translationKey="ui/continue" text="Continue" fontSizeMin="22" fontSizeMax="32" maxWidth="188" maxHeight="26" />
    </Button>
</Frame>
local ui = {
    Root = DCEI.GetUiRootFrame()
}

function CreateButtonFrame()
    local layout = gmui.Layout:New({
        parent = ui.Root,
        name = "Standard/Button/Button",
        on_show_animation = gmui.Animations.BackIn
    })

    -- layout
    DCEI.SetFrameImage(layout.Button, DCEI.Texture("btn_red"))
    DCEI.SetTextFrameText(layout.Label, "Press Me!")

    -- initialize
    layout:HideImmediate()
    return layout
end

ui.button = CreateButtonFrame()
DCEI.TriggerAddTimerEventElapsed(
    function()
        ui.button:Show()
    end, 
    2
)

AnimateFrameBetweenUnits()

gmui.AnimateFrameBetweenUnits(args)

Description

Animates a frame from the position of one unit to another with the given arguments. Useful for creating world-position UI animations.

Parameters

Example Usage

local unit1 = DCEI.CreateUnitWithFacing(1, 1, DCEI.Unit("Standard MeleeUnit"), 16, 16, 1, 0)
local unit2 = DCEI.CreateUnitWithFacing(1, 1, DCEI.Unit("Standard MeleeUnit"), 13, 16, 1, 0)

local frame = DCEI.CreateFrame(DCEI.GetUiRootFrame())
DCEI.SetFrameSize(frame, 100, 100)
DCEI.SetFrameImageColor(frame, {r = 1, g = 0, b = 0, a = 0.5})

local args = {
    frame = frame,
    unit1 = unit1,
    unit2 = unit2,
    duration = 3
}
gmui.AnimateFrameBetweenUnits(args)

AnimateFrameBetweenFrames()

gmui.AnimateFrameBetweenFrames(args)

Description

Animates a frame from the position of one frame to another with the given arguments. Useful for creating world-position UI animations.

Parameters

Example Usage

local frame_1 = DCEI.CreateFrame(DCEI.GetUiRootFrame())
DCEI.SetFrameSize(frame_1, 100, 100)
DCEI.SetFrameImageColor(frame_1, {r = 1, g = 0, b = 0, a = 0.5})

local frame_2 = DCEI.CreateFrame(DCEI.GetUiRootFrame())
DCEI.SetFrameSize(frame_2 , 100, 100)
DCEI.SetFrameImageColor(frame_1, {r = 0, g = 1, b = 0, a = 0.5})
DCEI.SetFrameVerticalOffsetInParent(frame_2, 100)
DCEI.SetFrameHorizontalOffsetInParent(frame_2, 100)

local frame_3 = DCEI.CreateFrame(DCEI.GetUiRootFrame())
DCEI.SetFrameSize(frame_3 , 100, 100)
DCEI.SetFrameImageColor(frame_3, {r = 0, g = 0, b = 1, a = 0.5})
DCEI.SetFrameVerticalOffsetInParent(frame_3, -100)
DCEI.SetFrameHorizontalOffsetInParent(frame_3, -100)

local args = {
    frame = frame_1,
    start_frame = frame_2,
    end_frame = frame_3,
    duration = 3
}
gmui.AnimateFrameBetweenFrames(args)

NewBigHand()

gmui.NewBigHand(args)

big_hand

Description

Creates and returns layout for an animated "Big Hand" from the given arguments. This is commonly used for building tutorial sequences.

Dismiss

The bighand can (and should) be destroyed with layout:Dimiss() when no longer needed:

local layout = gmui.NewBigHand()
DCEI.TriggerAddTimerEventElapsed(
    function()
        layout:Dismiss()
    end,
    2
)

Parameters

Example Usage

local options = {
    frame = ui.glue_menu.post_score.Button,
    vertical_offset = -25,
    flip = true
}

ui.big_hand = gmui.NewBigHand(options)

NewBigHandBetweenUnits()

gmui.NewBigHandBetweenUnits(args)

Description

Animates a bighand from the position of one unit to another in a dragging motion.

Parameters

Example Usage

local unit1 = DCEI.CreateUnitWithFacing(1, 1, DCEI.Unit("Standard MeleeUnit"), 16, 16, 1, 0)
local unit2 = DCEI.CreateUnitWithFacing(1, 1, DCEI.Unit("Standard MeleeUnit"), 13, 16, 1, 0)

local args = {
    unit1 = unit1,
    unit2 = unit2,
    duration = 3
}
gmui.NewBigHandBetweenUnits(args)

NewPip()

gmui.NewPip(args)

red_pip

Description

Creates and returns layout for an animated "Red Pip" from the given arguments. This is commonly used for bringing player attention to specific UI elements.

ShowAnimated

The pip is initially hidden when created and can be shown with an attention grabbing animation by using layout:ShowAnimated() as such:

local layout = gmui.NewPip()
layout:ShowAnimated()

Parameters

Example Usage

local ui = {
    Root = DCEI.GetUiRootFrame()
}

function CreateButtonFrame()
    local layout = gmui.Layout:New({
        parent = ui.Root,
        name = "Standard/Button/Button",
        on_show_animation = gmui.Animations.BackIn
    })

    -- layout
    DCEI.SetFrameImage(layout.Button, DCEI.Texture("btn_red"))
    DCEI.SetTextFrameText(layout.Label, "Press Me!")

    local pip = gmui.NewPip({
        parent = layout.Frame
    })

    -- functions
    function layout:OnShow()
        pip:ShowAnimated()
    end

    -- initialize
    layout:Show()
    return layout
end

ui.button = CreateButtonFrame()

Animation Templates

This mod comes with a number of animation templates that can easily be applied to any layout using the on_show_animation/on_hide_animation parameters (ex on_hide_animation = gmui.Animations.BackOut).

UI Templates

This mod comes with a number of ready-to-use XML frame templates.

Change Log

1.1.5 (released 8/6/21)

1.1.3 (released 4/20/21)

1.1.1 (released 3/9/21)

1.0.1 (released 1/13/21)

1.0.0 (released 12/9/20)