This documentation is for MSA-DropDownMenu version 1.0.5 and higher. And was created based on UIDropDownMenu documentation located at wow.gamepedia.com.

MSA-DropDownMenu vs UIDropDownMenu

MSA-DropDownMenu usage is almost the same as the default Blizzard UIDropDownMenu.

- Constants and functions are prefixed "MSA_" and was removed original prefix "UI", if it contained.
- Templates have been completely removed and replaced with functions.
- EasyMenu is not implemented.

For example:
- Constant ... UIDROPDOWNMENU_MENU_LEVEL --> MSA_DROPDOWNMENU_MENU_LEVEL
- Function ... UIDropDownMenu_Initialize --> MSA_DropDownMenu_Initialize
- Template ... UIDropDownMenuTemplate --> MSA_DropDownMenu_Create (replaced by a function)

General API

MSA_DropDownMenu_Create(name, parent)
Creates a dropdown menu or dropdown boxes base frame.

      name
      Required - Name of the newly created frame or existing frame handle. If it is nil, no frame name is assigned.

      parent
      Optional - The frame object that will be used as the created Frame's parent (cannot be a string!). No value use nil for created frame.

MSA_DropDownMenu_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 (see below) 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.

MSA_DropDownMenu_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.

MSA_ToggleDropDownMenu(level, value, dropDownFrame, anchorName, ofsX, ofsY, menuList, button)
Opens or closes a menu; arguments marked as internal are used from within the MSA_DropDownMenu 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.

MSA_DropDownMenu_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.

MSA_DropDownMenu_EnableDropDown(dropDownFrame)
Enables a dropdown menu that has been disabled.

      dropDownFrame
      Both - dropdown menu frame reference (menu handle).

MSA_DropDownMenu_DisableDropDown(dropDownFrame)
Disables a dropdown menu that is currently enabled.

      dropDownFrame
      Both - dropdown menu frame reference (menu handle).

Initialization functions

The initFunction supplied to MSA_DropDownMenu_Initialize is called when the menu (as well as any nested menu levels) should be constructed, as well as as part of the MSA_DropDownMenu_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 (see below) 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 MSA_DropDownMenu_AddButton when called.

The info table

Key	Value type	Description
text	String	Required - 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.
tCoord<side>	Number	SetTexCoord(tCoordLeft, tCoordRight, tCoordTop, tCoordBottom) for the icon. ALL four must be defined for this to work.
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.
notClickable	Boolean	If true, this button cannot be clicked.
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.
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.
menuList	Table	Table used to store nested menu descriptions for the EasyMenu functionality.

 

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.

MSA_DropDownMenu_SetSelectedName(frame, name, useValue)
Sets selection based on info.text values.

MSA_DropDownMenu_SetSelectedValue(frame, value, useValue)
Sets selection based on info.value values.

MSA_DropDownMenu_SetSelectedID(frame, id, useValue)
Sets selection based on button appearance order.

MSA_DropDownMenu_GetSelectedName(frame)
Returns selected button's text field.

MSA_DropDownMenu_GetSelectedID(frame)
Return selected button's ID.

MSA_DropDownMenu_GetSelectedValue(frame)
Returns selected button's value field.

Layout functions

MSA_DropDownMenu_SetWidth(frame, width, padding)
Adjusts dropdown menu width.

MSA_DropDownMenu_SetButtonWidth(frame, width)
Adjust the dropdown box button width.

MSA_DropDownMenu_SetText(frame, text)
Alters text displayed on the dropdown box.

MSA_DropDownMenu_GetText(frame)
Return text displayed on the dropdown box.

MSA_DropDownMenu_JustifyText(frame, justification)
Adjusts text justification on the dropdown box.

Global variables

MSA_DROPDOWNMENU_OPEN_MENU
Frame handle of the currently open menu.

MSA_DROPDOWNMENU_INIT_MENU
Frame handle of the menu currently initializing.

MSA_DROPDOWNMENU_MENU_LEVEL
Current menu nesting level.

MSA_DROPDOWNMENU_MENU_VALUE
Value of the parent node.

MSA_DROPDOWNMENU_SHOW_TIME
Number of seconds to keep the menu visible after the cursor leaves it.