Wikia

WoWWiki

UI Object UIDropDownMenu

Talk5
101,545pages on
this wiki
Revision as of 23:55, September 8, 2010 by Bdrummer (Talk | contribs)

(diff) ←Older revision | Latest revision (diff) | Newer revision → (diff)
UIDropDownMenu-NoMenu

A dropdown box created using UIDropDownMenu.

UIDropDownMenu is a FrameXML Frame template that can be used to create contextual menus and dropdown boxes in World of Warcraft. The relevant API is highlighted on this page.

The menu architecture Edit

UIDropDownMenu-Menu

The "MENU" style for context menus.

FrameXML provides a Frame template -- UIDropDownMenuTemplate -- that all menu or dropdown boxes should inherit from. Once a frame inheriting from UIDropDownMenuTemplate has been created, call UIDropDownMenu_Initialize to bind a menu function to it; the menu function will be responsible for creating the menu entries when the menu is open. The frame is used to store limited menu-related data, as well as a container for the dropdown list box if that menu style is used. Note that most of the usual frame-related methods may not work as expected on the dropdown menus, so additional API is provided to perform functions such as setting the selected entries, text, or adjusting dropdown box appearance.

The menus themselves are displayed using FrameXML-owned frames. Because of this, menu representations generally do not exist in memory unless the menu is open, and only one menu may be open at a time. The function provided to UIDropDownMenu_Initialize is used to create the required menu's entries when that menu is opened.

To implement a dropdown menu or list, one typically needs to create a frame inheriting from UIDropDownMenuTemplate, implement an initialization function to populate the menu when needed, and bind the initialization function to the frame using UIDropDownMenu_Initialize.

General API Edit

UIDropDownMenu_Initialize(frame, initFunction, displayMode, level, menuList) 
Initializes a dropdown menu attached to a specific frame.
frame 
Required - Frame handle the menu will be bound to.
initFunction 
Required - Function called when the menu is opened, responsible for adding menu buttons. Signature: (frame, level, menuList); additional global variables are used to communicate menu state.
displayMode 
Optional - "MENU" to use context-menu style, any other value to create a dropdown list box.
level 
Optional - 2nd argument to the initialization function when called for the first time.
menuList 
Optional - 3rd argument to the initialization function; used by EasyMenu.
UIDropDownMenu_AddButton(info, level) 
Add a button to the currently open menu.
info 
Table describing the button: key/value pairs listed below.
level 
Number specifying nesting level; can typically reuse the level argument to initFunction.
ToggleDropDownMenu(level, value, dropDownFrame, anchorName, ofsX, ofsY, menuList, button) 
Opens or closes a menu; arguments marked as internal are used from within the UIDropDownMenu implementation to open sub-menus etc.
level 
Internal - level of the opened menu; nil for external calls.
value 
Internal - parent node value for the sub menu; nil for external calls.
dropDownFrame 
Both - dropdown menu frame reference (menu handle).
anchorName, ofsX, ofsY 
Both - Positioning information (anchor and x,y offsets) for context menus.
menuList 
Internal - EasyMenu wrapper argument, passed as the third argument to the initialization function.
button 
Internal - Dropdown menu "open" button.
UIDropDownMenu_EnableDropDown(dropDownFrame) 
Enables a dropdown menu that has been disabled.
dropDownFrame 
Both - dropdown menu frame reference (menu handle).
UIDropDownMenu_DisableDropDown(dropDownFrame) 
Disables a dropdown menu that is currently enabled.
dropDownFrame 
Both - dropdown menu frame reference (menu handle).

Initialization functions Edit

The initFunction supplied to UIDropDownMenu_Initialize is called when the menu (as well as any nested menu levels) should be constructed, as well as as part of the UIDropDownMenu_Initialize call (this allows you to use the selection API to specify a selection immediately after binding the function to a menu frame should you so desire). The function is given three arguments:

frame 
Frame handle to the menu frame.
level 
Number specifying nesting level.
menuList 
An EasyMenu helper argument that can safely be ignored.

Additionally, some global variables may be useful to determine which entry's nested menu the initializer function is asked to supply.

It is expected that the initialization function will create any required menu entries using UIDropDownMenu_AddButton when called.

The info table Edit

Bolded keys are required.

Key Value type Description
text String Button text for this option.
icon String A texture path. The icon is scaled down and displayed to the right of the text.
value Any A value tag for this option.
func Function Function called when this button is clicked. The signature is (self, arg1, arg2, checked)
arg1, arg2 Any Arguments to the custom function assigned in func.
isTitle Boolean True if this is a title (cannot be clicked, special formatting).
disabled Boolean If true, this button is disabled (cannot be clicked, special formatting)
checked Boolean If true, this button is checked (tick icon displayed next to it)
hasArrow Boolean If true, this button has an arrow and opens a nested menu.
hasColorSwatch Boolean If true, this button has an attached color selector.
r, g, b Numbers [0.0, 1.0] Initial color value for the color selector.
colorCode String "|cffrrggbb" sequence that is prepended to info.text only if the button is enabled.
swatchFunc Function Function called when the color is changed.
hasOpacity Boolean If true, opacity can be customized in addition to color.
opacity Number [0.0, 1.0] Initial opacity value (0 = transparent).
opacityFunc Function Function called when opacity is changed.
cancelFunc Function Function called when color/opacity alteration is cancelled.
notClickable Boolean If true, this button cannot be clicked.
notCheckable String If true, this button cannot be checked (selected) - this also moves the button to the left, since there's no space stored for the tick-icon
keepShownOnClick Boolean If true, the menu isn't hidden when this button is clicked.
tooltipTitle String Tooltip title text. The tooltip appears when the player hovers over the button.
tooltipText String Tooltip content text.
justifyH String Horizontal text justification: "LEFT", "CENTER", "RIGHT".
fontObject Font Font object used to render the button's text.
menuList Table Table used to store nested menu descriptions for the EasyMenu functionality.

Selection functions Edit

To use the _SetSelected* functions, your dropdown menu must be the currently open / currently being initialized. Otherwise, the functions will not have the desired effect.

UIDropDownMenu_SetSelectedName(frame, name, useValue) 
Sets selection based on info.text values.
UIDropDownMenu_SetSelectedValue(frame, value, useValue) 
Sets selection based on info.value values.
UIDropDownMenu_SetSelectedID(frame, id, useValue) 
Sets selection based on button appearance order.
UIDropDownMenu_GetSelectedName(frame) 
Returns selected button's text field.
UIDropDownMenu_GetSelectedID(frame) 
Return selected button's ID.
UIDropDownMenu_GetSelectedValue(frame) 
Returns selected button's value field.

Layout functions Edit

UIDropDownMenu_SetWidth(frame, width, padding) 
Adjusts dropdown menu width.
UIDropDownMenu_SetButtonWidth(frame, width) 
Adjust the dropdown box button width.
UIDropDownMenu_SetText(frame, text) 
Alters text displayed on the dropdown box.
UIDropDownMenu_GetText(frame) 
Return text displayed on the dropdown box.
UIDropDownMenu_JustifyText(frame, justification) 
Adjusts text justification on the dropdown box.

Global variables Edit

UIDROPDOWNMENU_OPEN_MENU 
Frame handle of the currently open menu.
UIDROPDOWNMENU_INIT_MENU 
Frame handle of the menu currently initializing.
UIDROPDOWNMENU_MENU_LEVEL 
Current menu nesting level.
UIDROPDOWNMENU_MENU_VALUE 
Value of the parent node.
UIDROPDOWNMENU_SHOW_TIME 
Number of seconds to keep the menu visible after the cursor leaves it.

See Also Edit

Around Wikia's network

Random Wiki