UI Object UIDropDownMenu

This guide will demonstrate how to create dynamic drop down menu frames and point out common traps that you may fall into when modifying these frames during run time.

Essential Class Methods

Creates a drop down menu frame on the core UI parent window

Frame Creation

MyDropDownMenu = CreateFrame("Frame", "MyDropDownMenu", UIParent, "UIDropDownMenuTemplate");

MyDropDownMenu:SetPoint("CENTER",UIParent); --This is the only frame inherited method along with Frame:Show() and Frame:Hide()

Basic Drop Down Menu Frame Modifiers

Futher modifications are made using functions that are bound to a "virtual" drop down menu. You need to supply the actual frame object as an argument to modify a particular drop down menu object as shown below:

UIDropDownMenu_SetWidth(80, MyDropDownMenu) --Sets the width of MyDropDownMenu to 80 pixels. When MyDropDownMenu is orignally created, it has a default width. If the default width is not appropriate, then this function is the one for you.

UIDropDownMenu_SetButtonWidth(20, MyDropDownMenu) --Changes the drop down menu button with from it's default width to 20 pixels

Drop Down Menu Item Initialiser

Drop down menues require an initialisation function in order to create menu items. It is important to note that every time the drop down menu button is clicked that the initialise function is executed. When creating drop down menues that have dynamic menu items, this is an important point to consider.

UIDropDownMenu_Initialize(MyDropDownMenu, MyDropDownMenu_Initialise); --The virtual drop down menu will now call the function MyDropDownMenu_Initialize to setup the menu items for MyDropDownMenu

Typical Drop Down Menu Initialisation Function

function MyDropDownMenu_Initialise()
 level = level or 1 --drop down menus can have sub menus. The value of "level" determines the drop down sub menu tier.
 
 local info = UIDropDownMenu_CreateInfo();
 

 info.text = "First Menu Item"; --the text of the menu item
 info.value = 0; -- the value of the menu item. This can be a string also.
 info.func = function() MyDropDownMenuItem_OnClick() end; --sets the function to execute when this item is clicked
 info.owner = this:GetParent(); --binds the drop down menu as the parent of the menu item. This is very important for dynamic drop down menues.
 info.checked = nil; --initially set the menu item to being unchecked with a yellow tick
 info.icon = nil; --we can use this to set an icon for the drop down menu item to accompany the text
 UIDropDownMenu_AddButton(info, level); --Adds the new button to the drop down menu specified in the UIDropDownMenu_Initialise function. In this case, it's MyDropDownMenu


 info.text = "Second Menu Item";
 info.value = 1;
 info.func = function() MyDropDownMenuItem_OnClick() end;
 info.owner = this:GetParent();
 info.checked = nil;
 info.icon = nil;
 UIDropDownMenu_AddButton(info, level);
end

The info structure is used to determine the attributes of a single menu item. Setting the value of info.value is important as I'll demonstrate next. For now, our MyDropDownMenu is ready to use with two menu items.

See "List of button attributes" in the FrameXML file UIDropDownMenu.lua for the full list of available table elements.

Drop Down Menu Item Clicking

I will now show how to handle an item clicking event. As you can see from the initialisation function defined in info.func, the specified function will be called when that menu item is clicked. You are not restricted to specifying one function for all menu items. It's handy having one function for all items though as you reduce the amount of code in your mod and it is essential for dynamic drop down menues which have changing menu items.

When this function is called from clicking the drop down menu item, the scope of the governing object is the individual menu item. You can therefore get information on the specific menu item click (i.e. this.value, this.owner, this.icon etc).

function MyDropDownMenuItem_OnClick()
  UIDropDownMenu_SetSelectedValue(this.owner, this.value); --this is where the <b>info.value</b> comes in handy. The SetSelectedValue function updates the drop down menu's currently selected item. The function prefers the <b>info.value</b> value instead of the <b>info.text</b> value for setting the selected value. Furthermore, when depending on a selected value of a drop down menu for other sections in your mod, the GetSelectedValue method is more useful than the GetText method.


  if (this.value == 0) then
    --We clicked the first menu item. Enter code here to affect the rest of your mod.
  elseif (this.value == 1) then
    --We clicked the second menu item. Enter code here to affect the rest of your mod.
  end
end

We are now all setup for using the drop down menu with our mod. Below are some useful functions for getting information from your new drop down menu.

Drop Down Menu Functions

UIDropDownMenu_GetSelectedValue(MyDropDownMenu) - Gets the info.value value of the currently selected item in MyDropDownMenu.

UIDropDownMenu_GetText(MyDropDownMenu) - Gets the info.text value of the currently selected item in MyDropDownMenu.

UIDropDownMenu_ClearAll(MyDropDownMenu) - Resets MyDropDownMenu so it's no longer selecting anything.

See Also

• HOWTO: Use UIDropDownMenu
• API EasyMenu