Dropdown

A dropdown menu built on UIDropDownMenuTemplate with an optional label. It opens a scrollable pullout of selectable items and supports both single-select and multi-select ( checkbox) modes.

Create with AceGUI:Create("Dropdown"). It inherits the Common Widget API.

Widget type: Dropdown

The pullout and its individual entries (Dropdown-Pullout, Dropdown-Item-Toggle, Dropdown-Item-Execute, etc.) are internal helper widgets created automatically. You normally only interact with the Dropdown widget's own methods below.

Methods

SetList

method#

widget:SetList(list?, order?, itemType?)

Replaces the menu contents from a table. Clears any existing items (and the auto-added close button) and rebuilds the pullout.

Parameters

Parameter	Type	Default	Description
list (optional)	table		A value → text table. Passing nil empties the list.
order (optional)	table		Array of keys giving the display order. If omitted, keys are sorted automatically (numeric keys/strings numerically, everything else as strings).
itemType (optional)	string	"Dropdown-Item-Toggle"	Widget type for each entry. An invalid type raises an error.

AddItem

method#

widget:AddItem(value, text, itemType?)

Adds a single entry to the existing list (also stored in the list table).

Parameters

Parameter	Type	Default	Description
value	any		The item's value/key.
text	string		The displayed text.
itemType (optional)	string	"Dropdown-Item-Toggle"	Item widget type.

SetValue

method#

widget:SetValue(value)

Selects a value: sets the displayed text from the list entry for that value and stores it as the current value. (Single-select use.)

Parameters

Parameter	Type	Default	Description
value	any		The key to select.

GetValue

method#

widget:GetValue()

Returns the currently selected value.

Returns

Type	Description
any	The currently selected value.

SetText

method#

widget:SetText(text?)

Sets the text shown in the closed dropdown directly, without changing the selected value.

Parameters

Parameter	Type	Default	Description
text (optional)	string		The string to display, or nil for empty.

SetLabel

method#

widget:SetLabel(text?)

Sets an optional label above the dropdown. With a label the widget height becomes 40; without it, 26.

Parameters

Parameter	Type	Default	Description
text (optional)	string		The label string, or nil/"" to hide it.

SetMultiselect

method#

widget:SetMultiselect(multi)

Switches between single-select and multi-select (checkbox) mode. In multi-select mode the closed text shows the comma-joined list of checked entries and a "Close" button is appended to the pullout.

Parameters

Parameter	Type	Default	Description
multi	boolean		true for multi-select (checkbox) mode, false for single-select.

GetMultiselect

method#

widget:GetMultiselect()

Returns whether multi-select mode is enabled.

Returns

Type	Description
boolean	Whether multi-select mode is enabled.

SetItemValue

method#

widget:SetItemValue(item, value)

In multi-select mode, sets the checked state of a specific entry and refreshes the displayed multi-text. No-op when not in multi-select mode.

Parameters

Parameter	Type	Default	Description
item	any		The value/key identifying the entry.
value	boolean		The checked state to apply.

SetItemDisabled

method#

widget:SetItemDisabled(item, disabled)

Enables or disables a specific entry in the pullout.

Parameters

Parameter	Type	Default	Description
item	any		The value/key identifying the entry.
disabled	boolean		true to disable, false to enable.

SetPulloutWidth

method#

widget:SetPulloutWidth(width?)

Overrides the width of the opened pullout. When nil, the pullout matches the dropdown's own width.

Parameters

Parameter	Type	Default	Description
width (optional)	number		Pixel width, or nil to auto-match the dropdown's own width.

SetDisabled

method#

widget:SetDisabled(disabled)

Enables or disables the dropdown. A disabled dropdown greys its text/label and cannot be opened.

Parameters

Parameter	Type	Default	Description
disabled	boolean		true to disable, false to enable.

ClearFocus

method#

widget:ClearFocus()

Closes the pullout if it is open.

Defaults

On acquire the widget resets to: height 44, width 200, no label, auto pullout width, and an empty list. On release it closes and releases its pullout and clears text, value, disabled, and multiselect state.

Callbacks

OnValueChanged

callback#

OnValueChanged(value, checked?)

Fired when the user selects/toggles an entry. In single-select mode the handler receives just the newly selected value and the pullout then closes. In multi-select mode it also receives the toggled entry's checked state. Subscribe with widget:SetCallback.

Parameters

Parameter	Type	Default	Description
value	any		The selected/toggled entry's value.
checked (optional)	boolean		The entry's new checked state. Multi-select only; omitted in single-select mode.

OnOpened

callback#

OnOpened()

Fired when the pullout opens. Subscribe with widget:SetCallback.

OnClosed

callback#

OnClosed()

Fired when the pullout closes. Subscribe with widget:SetCallback.

OnEnter

callback#

OnEnter()

Fired when the mouse enters the dropdown (also locks the button highlight). Subscribe with widget:SetCallback.

OnLeave

callback#

OnLeave()

Fired when the mouse leaves the dropdown. Subscribe with widget:SetCallback.

Example

local dd = AceGUI:Create("Dropdown")
dd:SetLabel("Choose a class")
dd:SetList({
    WARRIOR = "Warrior",
    MAGE    = "Mage",
    PRIEST  = "Priest",
}, { "WARRIOR", "MAGE", "PRIEST" })
dd:SetValue(db.class)
dd:SetCallback("OnValueChanged", function(widget, event, value)
    db.class = value
end)