UI Object UIDropDownMenu
UIDropDownMenuTemplate 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.
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
- 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_SetAnchor(dropDownFrame, xOffset, yOffset, point, relativeTo, relativePoint)
- Sets the anchor of the dropdown menu.
- dropDownFrame
- Both - dropdown menu frame reference (menu handle).
- xOffset
- Number - x-offset (negative values will move obj left, positive values will move obj right), defaults to 0 if not specified.
- yOffset
- Number - y-offset (negative values will move obj down, positive values will move obj up), defaults to 0 if not specified.
- point
- String - Point of the object to adjust based on the anchor.
- relativeTo
- String/Widget - Name or reference to a frame to attach the menu to. If nil, it typically defaults to the object's parent. However, if relativePoint is also not defined, relativeFrame will default to UIParent.
- relativePoint
- String - point of the relativeFrame to attach point of obj to. If not specified, defaults to the value of point.
- 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
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
Bolded keys are required.
| Key | Value type | Description |
|---|---|---|
| text | String | Button text for this option. |
| value | Any | A value tag for this option. Inherits text key if this is undefined. |
| checked | Boolean, Function | If true, this button is checked (tick icon displayed next to it) |
| func | Function | Function called when this button is clicked. The signature is (self, arg1, arg2, checked) |
| 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) |
| arg1, arg2 | Any | Arguments to the custom function assigned in func. |
| hasArrow | Boolean | If true, this button has an arrow and opens a nested menu. |
| icon | String | A texture path. The icon is scaled down and displayed to the right of the text. |
| iconOnly | Boolean | If true, only the icon is shown. |
| iconXOffset | Number | Number of pixels to shift the button's icon to the left or right (positive numbers shift right, negative numbers shift left). |
| iconTooltipTitle | String | Title of the tooltip shown on icon mouseover |
| iconTooltipText | String | Text of the tooltip shown on icon mouseover |
| iconTooltipBackdropStyle | Table | Optional Backdrop style of the tooltip shown on icon mouseover |
| mouseOverIcon | Texture | An override icon when a button is moused over |
| tCoord<side> | Number | SetTexCoord(tCoordLeft, tCoordRight, tCoordTop, tCoordBottom) for the icon. ALL four must be defined for this to work. |
| tSizeX / tSizeY | Number | Sets the icon width / height. SetWidth(tSizeX), SetHeight(tSizeY) |
| iconInfo.tFitDropDownSizeX | Boolean | Adjusts the dropdowns automatic width by minus 5 (internally used for UIDropDownMenu_AddSeparator to fix the icon adding too much width) |
| isNotRadio | Boolean | If true, use a check mark for the tick icon instead of a circular dot. |
| 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. |
| registerForRightClick | Boolean | Register dropdown buttons for right clicks |
| notClickable | Boolean | If true, this button cannot be clicked, but changes the Disabled Font to match the standard white font (GameFontHighlightSmallLeft) - Does not respect fontObject. |
| noClickSound | Boolean | Set to 1 to suppress the sound when clicking the button. The sound only plays if .func is set. |
| notCheckable | Boolean | 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. |
| tooltipOnButton | Boolean | Show the tooltip attached to the button instead of as a Newbie tooltip. |
| tooltipWhileDisabled | Boolean | Show the tooltip, even when the button is disabled. |
| tooltipWarning | String | Warning-style text of the tooltip shown on mouseover |
| tooltipInstruction | String | Instruction-style text of the tooltip shown on mouseover |
| tooltipBackdropStyle | Table | Optional Backdrop style of the tooltip shown on mouseover |
| justifyH | String | Horizontal text justification: "CENTER" for "CENTER", any other value or nil for "LEFT". |
| fontObject | Font | Font object used to render the button's text. |
| owner | Frame | Dropdown frame that "owns" the current dropdown list. |
| padding | Number | Number of pixels to pad the text on the right side. |
| topPadding | Number | Extra spacing between buttons |
| leftPadding | Number | Number of pixels to pad the button on the left side |
| midWidth | Number | Minimum width for this option's line |
| menuList | Table | Table used to store nested menu descriptions for the EasyMenu functionality. |
| customCheckIconAtlas | Boolean | Needs explanation. |
| classicChecks | Boolean | Classic WoW only - needs explanation. |
| customFrame | Frame | Allows this button to be a completely custom frame. Custom frame should inherit from UIDropDownCustomMenuEntryTemplate and override appropriate methods |
Selection functions
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
- 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
- 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
- Using UIDropDownMenu -- a tutorial.
- API EasyMenu -- table-based UIDropDownMenu interface.
