Class: MenuSelectWidget

.ui.MenuSelectWidget(configopt)

MenuSelectWidget is a select widget that contains options and is used together with OO.ui.MenuOptionWidget. It is designed be used as part of another widget. See DropdownWidget, ComboBoxInputWidget, and LookupElement for examples of widgets that contain menus. MenuSelectWidgets themselves are not instantiated directly, rather subclassed and customized to be opened, closed, and displayed as needed. By default, menus are clipped to the visible viewport and are not visible when a user presses the mouse outside the menu. Menus also have support for keyboard interaction: - Enter/Return key: choose and select a menu option - Up-arrow key: highlight the previous menu option - Down-arrow key: highlight the next menu option - Esc key: hide the menu Unlike most widgets, MenuSelectWidget is initially hidden and must be shown by calling #toggle. Please see the [OOUI documentation on MediaWiki][1] for more information. [1]: https://www.mediawiki.org/wiki/OOUI/Widgets/Selects_and_Options
Parameters:
Name Type Attributes Description
config Object <optional>
Configuration options
Properties
Name Type Attributes Default Description
input OO.ui.TextInputWidget <optional>
Text input used to implement option highlighting for menu items that match the text the user types. This config is used by ComboBoxInputWidget and LookupElement
$input jQuery <optional>
Text input used to implement option highlighting for menu items that match the text the user types. This config is used by CapsuleMultiselectWidget
widget OO.ui.Widget <optional>
Widget associated with the menu's active state. If the user clicks the mouse anywhere on the page outside of this widget, the menu is hidden. For example, if there is a button that toggles the menu's visibility on click, the menu will be hidden then re-shown when the user clicks that button, unless the button (or its parent widget) is passed in here.
autoHide boolean <optional>
true Hide the menu when the mouse is pressed outside the menu.
$autoCloseIgnore jQuery <optional>
If these elements are clicked, don't auto-hide the menu.
hideOnChoose boolean <optional>
true Hide the menu when the user chooses an option.
filterFromInput boolean <optional>
false Filter the displayed options from the input
highlightOnFilter boolean <optional>
Highlight the first result when filtering
width number <optional>
Width of the menu
Mixes In:
Source:

Extends

Methods

addItems(items, indexopt)

Add an array of options to the select. Optionally, an index number can be used to specify an insertion point.
Parameters:
Name Type Attributes Description
items Array.<OO.ui.OptionWidget> Items to add
index number <optional>
Index to insert items after
Overrides:
Source:
Fires:

(protected) bindKeyDownListener()

Bind key down listener.
Overrides:
Source:

(protected) bindKeyPressListener()

Bind key press listener.
Overrides:
Source:

chooseItem(item)

Choose an item. When a user chooses an item, the menu is closed, unless the hideOnChoose config option is set to false. Note that ‘choose’ should never be modified programmatically. A user can choose an option with the keyboard or mouse and it becomes selected. To select an item programmatically, use the #selectItem method.
Parameters:
Name Type Description
item OO.ui.OptionWidget Item to choose
Overrides:
Source:

clearItems()

Clear all options from the select. Options will be detached from the DOM, not removed, so that they can be reused later. To remove a subset of options from the select, use the #removeItems method.
Overrides:
Source:
Fires:

(protected) clearKeyPressBuffer()

Clear the key-press buffer
Inherited From:
Source:

findFirstSelectableItem() → {OO.ui.OptionWidget|null}

Find the next selectable item or `null` if there are no selectable items. Disabled options and menu-section markers and breaks are not selectable.
Inherited From:
Source:
Returns:
Item, `null` if there aren't any selectable items
Type
OO.ui.OptionWidget | null

findHighlightedItem() → {OO.ui.OptionWidget|null}

Find highlighted item.
Inherited From:
Source:
Returns:
Highlighted item, `null` if no item is highlighted
Type
OO.ui.OptionWidget | null

findRelativeSelectableItem(item, direction, filteropt) → {OO.ui.OptionWidget|null}

Find an option by its position relative to the specified item (or to the start of the option array, if item is `null`). The direction in which to search through the option array is specified with a number: -1 for reverse (the default) or 1 for forward. The method will return an option, or `null` if there are no options in the array.
Parameters:
Name Type Attributes Description
item OO.ui.OptionWidget | null Item to describe the start position, or `null` to start at the beginning of the array.
direction number Direction to move in: -1 to move backward, 1 to move forward
filter function <optional>
Only consider items for which this function returns true. Function takes an OO.ui.OptionWidget and returns a boolean.
Inherited From:
Source:
Returns:
Item at position, `null` if there are no items in the select
Type
OO.ui.OptionWidget | null

findSelectedItem() → {OO.ui.OptionWidget|null}

Find selected item.
Inherited From:
Source:
Returns:
Selected item, `null` if no item is selected
Type
OO.ui.OptionWidget | null

getClosestScrollableElementContainer() → {HTMLElement}

Get closest scrollable container.
Inherited From:
Source:
Returns:
Closest scrollable container
Type
HTMLElement

getData() → {Mixed}

Get element data.
Inherited From:
Source:
Returns:
Element data
Type
Mixed

getElementDocument() → {HTMLDocument}

Get the DOM document.
Inherited From:
Source:
Returns:
Document object
Type
HTMLDocument

getElementGroup() → {OO.ui.mixin.GroupElement|null}

Get group element is in.
Inherited From:
Source:
Returns:
Group element, null if none
Type
OO.ui.mixin.GroupElement | null

getElementId() → {string}

Ensure that the element has an 'id' attribute, setting it to an unique value if it's missing, and return its value.
Inherited From:
Source:
Returns:
Type
string

getElementWindow() → {Window}

Get the DOM window.
Inherited From:
Source:
Returns:
Window object
Type
Window

getInputId() → {string|null}

Get an ID of a labelable node which is part of this widget, if any, to be used for `
Inherited From:
Source:
Returns:
The ID of the labelable element
Type
string | null

getItemFromLabel(label, prefixopt) → {OO.ui.Element|null}

Fetch an item by its label.
Parameters:
Name Type Attributes Default Description
label string Label of the item to select.
prefix boolean <optional>
false Allow a prefix match, if only a single item matches
Inherited From:
Source:
Returns:
Item with equivalent label, `null` if none exists
Type
OO.ui.Element | null

(protected) getItemMatcher(s, exactopt) → {function}

Get a matcher for the specific string
Parameters:
Name Type Attributes Default Description
s string String to match against items
exact boolean <optional>
false Only accept exact matches
Inherited From:
Source:
Returns:
function ( OO.ui.OptionWidget ) => boolean
Type
function

getSelectedItem() → {OO.ui.OptionWidget|null}

Get selected item.
Inherited From:
Deprecated:
  • Since v0.25.0; use #findSelectedItem instead.
Source:
Returns:
Selected item, `null` if no item is selected
Type
OO.ui.OptionWidget | null

getTagName() → {string}

Get the HTML tag name. Override this method to base the result on instance information.
Inherited From:
Source:
Returns:
HTML tag name
Type
string

highlightItem(itemopt)

Highlight an option. If the `item` param is omitted, no options will be highlighted and any existing highlight will be removed. The highlight is mutually exclusive.
Parameters:
Name Type Attributes Description
item OO.ui.OptionWidget <optional>
Item to highlight, omit for no highlight
Inherited From:
Source:
Fires:
  • event:highlight

isDisabled() → {boolean}

Check if the widget is disabled.
Inherited From:
Source:
Returns:
Widget is disabled
Type
boolean

isElementAttached() → {boolean}

Check if the element is attached to the DOM
Inherited From:
Source:
Returns:
The element is attached to the DOM
Type
boolean

isVisible() → {boolean}

Check if element is visible.
Inherited From:
Source:
Returns:
element is visible
Type
boolean

(protected) onDocumentMouseDown(e)

Handles document mouse down events.
Parameters:
Name Type Description
e MouseEvent Mouse down event
Source:

(protected) onKeyDown(e)

Handle key down events.
Parameters:
Name Type Description
e KeyboardEvent Key down event
Overrides:
Source:

(protected) onKeyPress(e)

Handle key press events.
Parameters:
Name Type Description
e KeyboardEvent Key press event
Inherited From:
Source:

(protected) onToggle(visible)

Visibility change handler
Parameters:
Name Type Description
visible boolean
Inherited From:
Source:

pressItem(itemopt)

Press an item. Press is a state that occurs when a user mouses down on an item, but has not yet let go of the mouse. The item may appear selected, but it will not be selected until the user releases the mouse.
Parameters:
Name Type Attributes Description
item OO.ui.OptionWidget <optional>
Item to press, omit to depress all
Inherited From:
Source:
Fires:
  • event:press

removeItems(items)

Remove the specified array of options from the select. Options will be detached from the DOM, not removed, so they can be reused later. To remove all options from the select, you may wish to use the #clearItems method instead.
Parameters:
Name Type Description
items Array.<OO.ui.OptionWidget> Items to remove
Overrides:
Source:
Fires:

(protected) restorePreInfuseState(state)

Restore the pre-infusion dynamic state for this widget. This method is called after #$element has been inserted into DOM. The parameter is the return value of #gatherPreInfuseState.
Parameters:
Name Type Description
state Object
Inherited From:
Source:

scrollElementIntoView(configopt) → {jQuery.Promise}

Scroll element into view.
Parameters:
Name Type Attributes Description
config Object <optional>
Configuration options
Inherited From:
Source:
Returns:
Promise which resolves when the scroll is complete
Type
jQuery.Promise

scrollItemIntoView(item)

Scroll item into view, preventing spurious mouse highlight actions from happening.
Parameters:
Name Type Description
item OO.ui.OptionWidget Item to scroll into view
Inherited From:
Source:

selectItem(itemopt)

Programmatically select an option by its reference. If the `item` parameter is omitted, all options will be deselected.
Parameters:
Name Type Attributes Description
item OO.ui.OptionWidget <optional>
Item to select, omit to deselect all
Inherited From:
Source:
Fires:
  • event:select

selectItemByData(dataopt)

Programmatically select an option by its data. If the `data` parameter is omitted, or if the item does not exist, all options will be deselected.
Parameters:
Name Type Attributes Description
data Object | string <optional>
Value of the item to select, omit to deselect all
Inherited From:
Source:
Fires:
  • event:select

selectItemByLabel(labelopt, prefixopt)

Programmatically select an option by its label. If the item does not exist, all options will be deselected.
Parameters:
Name Type Attributes Default Description
label string <optional>
Label of the item to select.
prefix boolean <optional>
false Allow a prefix match, if only a single item matches
Inherited From:
Source:
Fires:
  • event:select

setData(data)

Set element data.
Parameters:
Name Type Description
data Mixed Element data
Inherited From:
Source:

setDisabled(disabled)

Set the 'disabled' state of the widget. When a widget is disabled, it cannot be used and its appearance is updated to reflect this state.
Parameters:
Name Type Description
disabled boolean Disable widget
Inherited From:
Source:

setElementGroup(group)

Set group element is in.
Parameters:
Name Type Description
group OO.ui.mixin.GroupElement | null Group element, null if none
Inherited From:
Source:

setElementId(id)

Set the element has an 'id' attribute.
Parameters:
Name Type Description
id string
Inherited From:
Source:

(protected) setFocusOwner($focusOwner)

Set the DOM element which has focus while the user is interacting with this SelectWidget. Currently this is just used to set `aria-activedescendant` on it.
Parameters:
Name Type Description
$focusOwner jQuery
Inherited From:
Source:

simulateLabelClick()

Simulate the behavior of clicking on a label (a HTML `
Inherited From:
Source:

supports(methods) → {boolean}

Check if element supports one or more methods.
Parameters:
Name Type Description
methods string | Array.<string> Method or list of methods to check
Inherited From:
Source:
Returns:
All methods are supported
Type
boolean

toggle(showopt)

Toggle visibility of an element.
Parameters:
Name Type Attributes Description
show boolean <optional>
Make element visible, omit to toggle visibility
Overrides:
Source:
Fires:
  • event:visible

togglePressed(pressed)

Toggle pressed state. Press is a state that occurs when a user mouses down on an item, but has not yet let go of the mouse. The item may appear selected, but it will not be selected until the user releases the mouse.
Parameters:
Name Type Description
pressed boolean An option is being pressed
Inherited From:
Source:

(protected) unbindKeyDownListener()

Unbind key down listener.
Overrides:
Source:

(protected) unbindKeyPressListener()

Unbind key down listener. If you override this, be sure to call this.clearKeyPressBuffer() from your implementation.
Overrides:
Source:

updateDisabled()

Update the disabled state, in case of changes in parent widget.
Inherited From:
Source:

(protected) updateItemVisibility()

Update menu item visibility and clipping after input changes (if filterFromInput is enabled) or after items were added/removed (always).
Source:

updateThemeClasses()

Update the theme-provided classes.
Inherited From:
Source:

Events

add

An `add` event is emitted when options are added to the select with the #addItems method.
Parameters:
Name Type Description
items Array.<OO.ui.OptionWidget> Added items
index number Index of insertion point
Inherited From:
Source:

choose

A `choose` event is emitted when an item is chosen with the #chooseItem method.
Parameters:
Name Type Description
item OO.ui.OptionWidget Chosen item
Inherited From:
Source:

highlight

A `highlight` event is emitted when the highlight is changed with the #highlightItem method.
Parameters:
Name Type Description
item OO.ui.OptionWidget | null Highlighted item
Inherited From:
Source:

press

A `press` event is emitted when the #pressItem method is used to programmatically modify the pressed state of an option.
Parameters:
Name Type Description
item OO.ui.OptionWidget | null Pressed item
Inherited From:
Source:

remove

A `remove` event is emitted when options are removed from the select with the #clearItems or #removeItems methods.
Parameters:
Name Type Description
items Array.<OO.ui.OptionWidget> Removed items
Inherited From:
Source:

select

A `select` event is emitted when the selection is modified programmatically with the #selectItem method.
Parameters:
Name Type Description
item OO.ui.OptionWidget | null Selected item
Inherited From:
Source: