Class: SelectWidget

(abstract) .ui.SelectWidget(configopt)

(abstract) new SelectWidget(configopt)

A SelectWidget is of a generic selection of options. The OOjs UI library contains several types of select widgets, including button selects, radio selects, and menu selects.

This class should be used together with OO.ui.OptionWidget or OO.ui.DecoratedOptionWidget. For more information, please see the [OOjs UI documentation on MediaWiki][1].

Parameters:
Name Type Attributes Description
config Object <optional>

Configuration options

Properties
Name Type Attributes Description
items Array.<OO.ui.OptionWidget> <optional>

An array of options to add to the select. Options are created with OptionWidget classes. See the OOjs UI documentation on MediaWiki for examples.

Mixes In:
Source:
Example
// Example of a select widget with three options
    var select = new OO.ui.SelectWidget( {
        items: [
            new OO.ui.OptionWidget( {
                data: 'a',
                label: 'Option One',
            } ),
            new OO.ui.OptionWidget( {
                data: 'b',
                label: 'Option Two',
            } ),
            new OO.ui.OptionWidget( {
                data: 'c',
                label: 'Option Three',
            } )
        ]
    } );
    $( 'body' ).append( select.$element );

[1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options

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

Source:
Fires:

(protected) bindKeyDownListener()

Bind key down listener.

Source:

(protected) bindKeyPressListener()

Bind key press listener.

Source:

chooseItem(item)

Choose an item.

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.

This method is identical to #selectItem, but may vary in subclasses that take additional action when users choose an item with the keyboard or mouse.

Parameters:
Name Type Description
item OO.ui.OptionWidget

Item to choose

Source:
Fires:
  • event:choose

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.

Source:
Fires:

(protected) clearKeyPressBuffer()

Clear the key-press buffer

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.

Source:
Returns:

Item, null if there aren't any selectable items

Type
OO.ui.OptionWidget | null

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

Find highlighted item.

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.

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.

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 <label for> value.

If this function returns null, the widget should have a meaningful #simulateLabelClick method instead.

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

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

Source:
Returns:

function ( OO.ui.OptionWidget ) => boolean

Type
function

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

Get selected item.

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

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) onKeyDown(e)

Handle key down events.

Parameters:
Name Type Description
e KeyboardEvent

Key down event

Source:

(protected) onKeyPress(e)

Handle key press events.

Parameters:
Name Type Description
e KeyboardEvent

Key press event

Source:

(protected) onToggle(visible)

Visibility change handler

Parameters:
Name Type Description
visible boolean
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

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

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

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

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

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

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
Source:

simulateLabelClick()

Simulate the behavior of clicking on a label (a HTML <label> element) bound to this input. HTML only allows <label> to act on specific "labelable" elements; complex widgets might need to override this method to provide intuitive, accessible behavior.

By default, this does nothing. OO.ui.mixin.TabIndexedElement overrides it for focusable widgets. Individual widgets may override it too.

This method is called by OO.ui.LabelWidget and OO.ui.FieldLayout. It should not be called directly.

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

Inherited From:
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

Source:

(protected) unbindKeyDownListener()

Unbind key down listener.

Source:

(protected) unbindKeyPressListener()

Unbind key down listener.

If you override this, be sure to call this.clearKeyPressBuffer() from your implementation.

Source:

updateDisabled()

Update the disabled state, in case of changes in parent widget.

Inherited From:
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

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

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

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

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

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

Source: