TreeGroup

A container that switches between groups of widgets using a tree control.

Create with AceGUI:Create("TreeGroup"). This is a container; it inherits the Common Widget API and container methods.

Widget type: TreeGroup

Methods

SetTree

method#

container:SetTree(tree, filter?)

Set the tree to display and refresh it. See Tree node format for the structure of tree.

Parameters

Parameter	Type	Default	Description
tree	table		Array of node tables (may contain nested children). Asserted to be a table when non-nil. See Tree node format.
filter (optional)	boolean		When truthy, branches and leaves whose visible is false are hidden, and branches are only shown if they contain at least one visible descendant.

SelectByPath

method#

container:SelectByPath(...)

Select a node by its path of values from the root down, expanding every ancestor group along the way and scrolling the selection into view. Fires OnGroupSelected.

Parameters

Parameter	Type	Default	Description
...	string		The sequence of node values from the top level to the target node (e.g. "parentValue", "childValue").

SelectByValue

method#

container:SelectByValue(uniquevalue)

Select a node by its full unique value (the path components joined by \001). Splits on \001 to derive the path, expands ancestors, scrolls into view, and fires OnGroupSelected.

Parameters

Parameter	Type	Default	Description
uniquevalue	string		The unique value string, e.g. "parentValue\001childValue".

Select

method#

container:Select(uniquevalue, ...)

Lower-level selection method used by SelectByPath/SelectByValue. Disables filtering, expands every group along the path, sets the selection, refreshes (scrolling to the selection), and fires OnGroupSelected.

Parameters

Parameter	Type	Default	Description
uniquevalue	string		The unique value to mark as selected.
...	string		The path components used to expand ancestor groups.

SetSelected

method#

container:SetSelected(value)

Set the selected node to value (the node's unique value). Only fires OnGroupSelected if the selection actually changed. Does not expand ancestors or scroll.

Parameters

Parameter	Type	Default	Description
value	string		The unique value of the node to select.

SetStatusTable

method#

container:SetStatusTable(status)

Supply an external table for persisting tree state. The container stores/reads groups (expanded-state map keyed by unique value), scrollvalue, treewidth, treesizable, and selected. Missing keys are initialized. After setting, applies the stored tree width and refreshes.

Parameters

Parameter	Type	Default	Description
status	table		A table you own and keep alive (asserted to be of type table).

SetTreeWidth

method#

container:SetTreeWidth(treewidth?, resizable?)

Set the width of the tree pane and whether the user may drag-resize it. treewidth may be omitted or boolean: if a boolean is passed as the first argument, it is treated as resizable and the width defaults to 175. Stores the values in the status table.

Parameters

Parameter	Type	Default	Description
treewidth (optional)	number | boolean		Width in pixels (default 175), or a boolean to set only resizable.
resizable (optional)	boolean		When true, the drag handle is enabled.

GetTreeWidth

method#

container:GetTreeWidth()

Returns the current tree-pane width (defaults to 175 if unset).

Returns

Type	Description
number	The current tree-pane width (defaults to 175 if unset).

EnableButtonTooltips

method#

container:EnableButtonTooltips(enable)

Enable or disable the built-in tooltip shown when hovering over a tree button (the tooltip text is the button label). Enabled by default on acquire.

Parameters

Parameter	Type	Default	Description
enable	boolean		Whether the built-in hover tooltip is shown.

RefreshTree

method#

container:RefreshTree(scrollToSelection?, fromOnUpdate?)

Rebuild the visible button list from the current tree and status tables. Called automatically after most mutations; call directly if you mutate the tree table in place.

Parameters

Parameter	Type	Default	Description
scrollToSelection (optional)	boolean		Pass true to scroll the selected node into view.
fromOnUpdate (optional)	boolean		Internal flag set when called from the first-frame OnUpdate handler.

The container also defines CreateButton, BuildLevel, and ShowScroll as internal helpers, plus OnWidthSet/ OnHeightSet/LayoutFinished for layout.

Callbacks

OnGroupSelected

callback#

OnGroupSelected(uniquevalue)

Fired when the selected node changes (via SetSelected, Select, SelectByPath, SelectByValue, or clicking a button). Release and rebuild the content here.

Parameters

Parameter	Type	Default	Description
uniquevalue	string		The selected node's unique value (path components joined by \001).

OnClick

callback#

OnClick(uniquevalue, selected)

Fired when a tree button is clicked, before selection is applied.

Parameters

Parameter	Type	Default	Description
uniquevalue	string		The clicked node's unique value.
selected	boolean		The button's selected state at click time.

OnButtonEnter

callback#

OnButtonEnter(uniquevalue, buttonFrame)

Fired when the mouse enters a tree button.

Parameters

Parameter	Type	Default	Description
uniquevalue	string		The node's unique value.
buttonFrame	Button		The underlying tree button.

OnButtonLeave

callback#

OnButtonLeave(uniquevalue, buttonFrame)

Fired when the mouse leaves a tree button.

Parameters

Parameter	Type	Default	Description
uniquevalue	string		The node's unique value.
buttonFrame	Button		The underlying tree button.

OnTreeResize

callback#

OnTreeResize(width)

Fired after the user finishes drag-resizing the tree pane.

Parameters

Parameter	Type	Default	Description
width	number		The new tree width in pixels.

Tree node format

SetTree takes an array of node tables. Each node recognizes the following fields (read from the source addLine/UpdateButton):

• value: the node's identifier within its level. The full path of values (joined by \001) forms the node's * unique value*, which is what OnGroupSelected/OnClick report and what SelectByValue expects. Sibling node values must be unique within their parent.
• text: the label shown for the node.
• icon: optional texture (path or file ID) drawn left of the text.
• iconCoords: optional table of texture coordinates {left, right, top, bottom} (passed to SetTexCoord).
• disabled: if truthy, the node is greyed out and not mouse-interactive.
• children: optional array of child node tables. A node with children is a collapsible branch whose expanded state is tracked per unique value in the status table.
• visible: optional boolean. When the tree is set with a filter, nodes with visible = false are hidden (and empty branches are pruned).

Example

local AceGUI = LibStub("AceGUI-3.0")

local tree = AceGUI:Create("TreeGroup")
tree:SetFullWidth(true)
tree:SetFullHeight(true)
tree:SetLayout("Flow")

tree:SetTree({
    {
        value = "combat",
        text  = "Combat",
        children = {
            { value = "melee",  text = "Melee"  },
            { value = "ranged", text = "Ranged" },
        },
    },
    {
        value = "ui",
        text  = "Interface",
        icon  = "Interface\\Icons\\INV_Misc_Gear_01",
        children = {
            { value = "frames", text = "Frames" },
            { value = "fonts",  text = "Fonts", disabled = true },
        },
    },
})

tree:SetCallback("OnGroupSelected", function(container, event, uniquevalue)
    container:ReleaseChildren()
    -- uniquevalue is e.g. "combat\001melee"
    local lbl = AceGUI:Create("Label")
    lbl:SetText("Selected: " .. uniquevalue)
    container:AddChild(lbl)
end)

-- expand "combat" and select its "melee" child
tree:SelectByPath("combat", "melee")