Dropdown

Component stability: Beta

Dropdown

StdUi:Dropdown(parent, width, height, options, value, multi, assoc)

Description

Note: Depends on Button, Scroll Widgets

Dropdown component is similar to HTML select element. It is nowhere near as complex as Blizzard UIDropDownMenu mostly because in usual cases you need something simple. UIDropDownMenu has meaning in context menus but does pretty poor job as simple select.

Main body of select is a Button and list of option is FauxScrollFrame. Unlike HTML select, option list will always match select width.

Arguments

Argument	Type	Optional	Description
parent	Frame	-	Object that should be a parent
width	number	-	Width of the panel
height	number	-	Height of the panel
options	table	Y	List of elements
value	any	Y	Initial value of Dropdown
multi	bool	Default: false	If you set this to true, dropdown will behave like multiselect
assoc	bool	Default: false	If you use multiselect, this will turn dropdown to work with associative array mode instead of normal array

Associative array mode

Normally dropdown sets value to something like this:

{ 1, 2, 6 }

However if you set assoc param to true it will modify value table like this:

{ [1] = true, [2] = true, [3] = false, [4] = false, [5] = false, [6] = true }

Returns

• Button

Options format

Options should be array of tables. Each option should have text and value. Each option may contain additional elements. value may be of any type however number or string is recommended.

WARNING: Widget will throw errors if you use complex values with associative mode.

Note: values should be of the same type across all options

local items = {
   {text = 'Test 1', value = 1}, -- First option
   {text = 'Test 2', value = 2, anyElement = 'Something'}, -- Second option
};

Value

If dropdown is in single select mode. Value will be exactly what you put in options. For multiselects, value is array of toggled values ex:

local val = {1, 2, 3, 6};

For associative array mode:

local val = { [1] = true, [2] = true, [3] = true, [4] = false, [5] = false, [6] = true }

Methods

Function	Returns	Arguments	Description
ShowOptions()	-	-	Shows the option frame
HideOptions()	-	-	Hides the option frame
ToggleOptions()	-	-	Toggles the option frame
SetPlaceholder(placeholderText)	-	string	Sets the placeholder text, a text that should be show when there is nothing selected
ToggleValue(value, state)	-	any, boolean	Toggles the value of multiselect, only works if multi was set to true. state a boolean value indicates if value is selected or not
SetOptions(options)	-	table	Sets the options table
SetValue(value, text)	-	any, string	Sets the value of Dropdown, text is optional to text to display.
GetValue()	any		Gets the current value of Dropdown
FindValueText(value)	string		Finds the text of any value withing options table. If placeholder was set and value does not match anything from options, placeholder text will be returned.

Named children

Child	Type	Description
dropdown.multi	bool	Read only, indicates if dropdown is in multiselect mode
dropdown.assoc	bool	Indicates if dropdown is in associative mode, does nothing if dropdown is not multiselet
dropdown.text	FontString	FontString that is used as dropdown text
dropdown.dropTex	Texture	Arrow Texture on the right of dropdown
dropdown.options	table	Table of options
dropdown.optsFrame	Texture	Options FauxScrollFrame object
dropdown.optsFrame.scrollChild	Frame	Scroll Child frame (it holds all option buttons)
dropdown.optsFrame.scrollChild.items	table	Table of all option buttons

Because optsFrame is a FauxScrollFrame widget, please refer: Here for a detailed information.

Demo

local StdUi = LibStub('StdUi');

local window = StdUi:Window(UIParent, 300, 200, 'Title');
window:SetPoint('CENTER');

local items = {
	{text = 'test 1', value = 1},
	{text = 'test 2', value = 2},
	{text = 'test 3', value = 3},
	{text = 'test 4', value = 4},
	{text = 'test 5', value = 5},
	{text = 'test 6', value = 6},
	{text = 'test 7', value = 7},
};

local dd = StdUi:Dropdown(window, 200, 20, items, 2);
dd:SetPoint('CENTER');

local items2 = {
	{text = 'test 4', value = 'one'},
	{text = 'test 2', value = 'two'},
	{text = 'test 3', value = 'three'},
	{text = 'test 4', value = 'four'},
};

local dd2 = StdUi:Dropdown(window, 200, 20, items2);
dd2:SetPlaceholder('-- Please Select --');
StdUi:GlueBelow(dd2, dd, 0, -20);

local items3 = {
	{text = 'test 4', value = 'one'},
	{text = 'test 2', value = 'two'},
	{text = 'test 3', value = 'three'},
	{text = 'test 4', value = 'four'},
	{text = 'test 5', value = 5},
	{text = 'test 6', value = 6},
	{text = 'test 7', value = 7},
};

-- multi select dropdown
local ddm = StdUi:Dropdown(window, 200, 20, items3, nil, true);
ddm:SetPlaceholder('-- This is a multiselect --');
StdUi:GlueBelow(ddm, dd2, 0, -20);
ddm.OnValueChanged = function(self, value)
	print('Dropdown Values: ', unpack(value));
	print('Dropdown Text: ', self:GetText());
end;

local b = StdUi:Button(window, 60, 20, 'Random');
StdUi:GlueTop(b, window, 0, -40);
b:SetScript('OnClick', function()
	local x = math.random(2, 20);
	local opts = {};
	for i = 1, x do
		tinsert(opts, {text = 'test '.. i, value = i});
	end
	dd2:SetOptions(opts)
end);