Extends
Constructor
new OO.ui.ButtonSelectWidget([config])
#
ButtonSelectWidget is a select widget
that contains
button options and is used together with
OO.ui.ButtonOptionWidget. The ButtonSelectWidget provides an interface for
highlighting, choosing, and selecting mutually exclusive options. Please see
the OOUI documentation on MediaWiki for more information.
Example
// A ButtonSelectWidget that contains three ButtonOptionWidgets.
const option1 = new OO.ui.ButtonOptionWidget( {
data: 1,
label: 'Option 1',
title: 'Button option 1'
} ),
option2 = new OO.ui.ButtonOptionWidget( {
data: 2,
label: 'Option 2',
title: 'Button option 2'
} ),
option3 = new OO.ui.ButtonOptionWidget( {
data: 3,
label: 'Option 3',
title: 'Button option 3'
} ),
buttonSelect = new OO.ui.ButtonSelectWidget( {
items: [ option1, option2, option3 ]
} );
$( document.body ).append( buttonSelect.$element );
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
config |
Object |
optional |
Configuration options |
- Mixes in:
- Source:
ButtonSelectWidget is a select widget
that contains
button options and is used together with
OO.ui.ButtonOptionWidget.
Methods
addItems([items], [index]) → {OO.ui.Widget}chainable
#
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> |
optional |
Options to add |
index |
number |
optional |
Index to insert items after |
- Inherited from:
- Source:
Returns:
The widget, for chaining
- Type
- OO.ui.Widget
Fires:
bindDocumentKeyDownListener()protected
#
Bind document key down listener.
- Inherited from:
- Source:
bindDocumentKeyPressListener()protected
#
Bind document key press listener.
- Inherited from:
- Source:
chooseItem(item) → {OO.ui.Widget}chainable
#
Select an item or toggle an item's selection when multiselect is enabled.
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 not identical to #selectItem and may vary further 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 |
- Inherited from:
- Source:
Returns:
The widget, for chaining
- Type
- OO.ui.Widget
Fires:
clearItems() → {OO.ui.Widget}chainable
#
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.
- Inherited from:
- Source:
Returns:
The widget, for chaining
- Type
- OO.ui.Widget
Fires:
clearKeyPressBuffer()protected
#
Clear the key-press buffer
- Inherited from:
- Source:
findFirstSelectableItem() → {OO.ui.OptionWidget|null
}
#
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
null
if there are no selectable items.
findFirstSelectedItem() → {OO.ui.OptionWidget|null
}
#
null
}
#
- Inherited from:
- Source:
Returns:
The first (of possibly many) selected item, if any
- Type
-
OO.ui.OptionWidget
|
null
findHighlightedItem() → {OO.ui.OptionWidget|null
}
#
null
}
#
Find highlighted item.
- Inherited from:
- Source:
Returns:
Highlighted item, null
if no item is highlighted
- Type
-
OO.ui.OptionWidget
|
null
findRelativeSelectableItem(item, offset, [filter], [wrap]) → {OO.ui.OptionWidget|null
}
#
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 and distance in which to search through the option array
is specified with a number: e.g. -1 for the previous item (the default) or 1 for the next item,
or 15 for the 15th next item, etc. The method will return an option, or null
if there are no
options in the array.
Parameters:
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
item |
OO.ui.OptionWidget
|
null
|
Item to describe the start position, or |
||
offset |
number | Relative position: negative to move backward, positive 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. |
|
wrap |
boolean |
optional |
false | Do not wrap around after reaching the last or first item |
- Inherited from:
- Source:
Returns:
Item at position, null
if there are no items in the select
- Type
-
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
).
findSelectedItem() → {Array.<OO.ui.OptionWidget>|OO.ui.OptionWidget|null
}
#
null
}
#
Find selected item.
- Inherited from:
- Source:
Returns:
If the widget is multiselect
then return an array of selected items (or empty array),
if the widget is not multiselect, return a single selected item, or null
if no item is selected
- Type
-
Array.<OO.ui.OptionWidget>
|
OO.ui.OptionWidget
|
null
findSelectedItems() → {Array.<OO.ui.OptionWidget>|OO.ui.OptionWidget|null
}
#
null
}
#
Find all selected items, if there are any. If the widget allows for multiselect it will return an array of selected options. If the widget doesn't allow for multiselect, it will return the selected option or null if no item is selected.
- Inherited from:
- Source:
Returns:
If the widget is multiselect
then return an array of selected items (or empty array),
if the widget is not multiselect, return a single selected item, or null
if no item is selected
- Type
-
Array.<OO.ui.OptionWidget>
|
OO.ui.OptionWidget
|
null
getClosestScrollableElementContainer() → {HTMLElement}
#
Get closest scrollable container.
- Inherited from:
- Source:
Returns:
Closest scrollable container
- Type
- HTMLElement
getData() → {any}
#
Get element data.
- Inherited from:
- Source:
Returns:
Element data
- Type
- any
getElementDocument() → {HTMLDocument}
#
getElementGroup() → {OO.ui.mixin.GroupElement|null
}
#
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
Ensure that the element has an 'id' attribute, setting it to an unique value if it's missing, and return its value.
getElementWindow() → {Window}
#
getInputId() → {string|null
}
#
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
Get an ID of a labelable node which is part of this widget, if any, to be used for <label for>
value.
getItemFromLabel(label, [prefix]) → {OO.ui.Element|null
}
#
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
getItemMatcher(query, [mode]) → {function}protected
#
Get a matcher for the specific string
Parameters:
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
query |
string | String to match against items |
||
mode |
string |
optional |
'prefix' | Matching mode: 'substring', 'prefix', or 'exact' |
- Inherited from:
- Source:
Returns:
function ( OO.ui.OptionWidget ) => boolean
- Type
- function
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([item]) → {OO.ui.Widget}chainable
#
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:
Returns:
The widget, for chaining
- Type
- OO.ui.Widget
Fires:
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
onDocumentKeyDown(e)protected
#
Handle document key down events.
Parameters:
Name | Type | Description |
---|---|---|
e |
KeyboardEvent | Key down event |
- Inherited from:
- Source:
onDocumentKeyPress(e) → {undefined
|boolean}protected
#
undefined
|boolean}protected
#
Handle key press events.
Parameters:
Name | Type | Description |
---|---|---|
e |
KeyboardEvent | Key press event |
- Inherited from:
- Source:
Returns:
False to prevent default if event is handled
- Type
-
undefined
| boolean
onToggle(visible)protected
#
Visibility change handler
Parameters:
Name | Type | Description |
---|---|---|
visible |
boolean |
- Inherited from:
- Source:
pressItem([item]) → {OO.ui.Widget}chainable
#
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:
Returns:
The widget, for chaining
- Type
- OO.ui.Widget
Fires:
removeItems(items) → {OO.ui.Widget}chainable
#
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 |
- Inherited from:
- Source:
Returns:
The widget, for chaining
- Type
- OO.ui.Widget
Fires:
restorePreInfuseState(state)protected
#
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([config]) → {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([item]) → {OO.ui.Widget}chainable
#
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:
Returns:
The widget, for chaining
- Type
- OO.ui.Widget
Fires:
selectItemByData([data]) → {OO.ui.Widget}chainable
#
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:
Returns:
The widget, for chaining
- Type
- OO.ui.Widget
Fires:
selectItemByLabel([label], [prefix]) → {OO.ui.Widget}chainable
#
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:
Returns:
The widget, for chaining
- Type
- OO.ui.Widget
Fires:
setData(data) → {OO.ui.Element}chainable
#
Set element data.
Parameters:
Name | Type | Description |
---|---|---|
data |
any | Element data |
- Inherited from:
- Source:
Returns:
The element, for chaining
- Type
- OO.ui.Element
setDisabled([disabled]) → {OO.ui.Widget}chainable
#
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 | Attributes | Default | Description |
---|---|---|---|---|
disabled |
boolean |
optional |
false | Disable widget |
- Inherited from:
- Source:
Returns:
The widget, for chaining
- Type
- OO.ui.Widget
setElementGroup(group) → {OO.ui.Element}chainable
#
Set group element is in.
Parameters:
Name | Type | Description |
---|---|---|
group |
OO.ui.mixin.GroupElement
|
null
|
Group element, null if none |
- Inherited from:
- Source:
Returns:
The element, for chaining
- Type
- OO.ui.Element
setElementId(id) → {OO.ui.Element}chainable
#
Set the element has an 'id' attribute.
Parameters:
Name | Type | Description |
---|---|---|
id |
string |
- Inherited from:
- Source:
Returns:
The element, for chaining
- Type
- OO.ui.Element
setFocusOwner($focusOwner)protected
#
Set the DOM element which has focus while the user is interacting with this SelectWidget.
This is used to set aria-activedescendant
and aria-expanded
on it.
Parameters:
Name | Type | Description |
---|---|---|
$focusOwner |
jQuery |
- Inherited from:
- Source:
setLabelledBy(id)
#
Set the element with the given ID as a label for this widget.
Parameters:
Name | Type | Description |
---|---|---|
id |
string
|
null
|
- Inherited from:
- 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:
<label>
element) bound to this input.
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([show]) → {OO.ui.Element}chainable
#
Toggle visibility of an element.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
show |
boolean |
optional |
Make element visible, omit to toggle visibility |
- Inherited from:
- Source:
Returns:
The element, for chaining
- Type
- OO.ui.Element
Fires:
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 | Attributes | Description |
---|---|---|---|
pressed |
boolean |
optional |
An option is being pressed, omit to toggle |
- Inherited from:
- Source:
unbindDocumentKeyDownListener()protected
#
Unbind document key down listener.
- Inherited from:
- Source:
unbindDocumentKeyPressListener()protected
#
Unbind document key down listener.
If you override this, be sure to call this.clearKeyPressBuffer() from your implementation.
- Inherited from:
- Source:
unselectItem([unselectedItem]) → {OO.ui.Widget}chainable
#
Programmatically unselect an option by its reference. If the widget allows for multiple selections, there may be other items still selected; otherwise, no items will be selected. If no item is given, all selected items will be unselected.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
unselectedItem |
OO.ui.OptionWidget |
optional |
Item to unselect, or nothing to unselect all |
- Inherited from:
- Source:
Returns:
The widget, for chaining
- Type
- OO.ui.Widget
Fires:
updateDisabled() → {OO.ui.Widget}chainable
#
Update the disabled state, in case of changes in parent widget.
- Inherited from:
- Source:
Returns:
The widget, for chaining
- Type
- OO.ui.Widget
updateThemeClasses()
#
Update the theme-provided classes.
This is called in element mixins and widget classes any time state changes. Updating is debounced, minimizing overhead of changing multiple attributes and guaranteeing that theme updates do not occur within an element's constructor
- Inherited from:
- Source:
Events
add(items, index)
#
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:
add
event is emitted when options are added to the select with the #addItems method.
choose(item, selected)
#
A choose
event is emitted when an item is chosen with the #chooseItem method.
Parameters:
Name | Type | Description |
---|---|---|
item |
OO.ui.OptionWidget | Chosen item |
selected |
boolean | Item is selected |
- Inherited from:
- Source:
choose
event is emitted when an item is chosen with the #chooseItem method.
disable(disabled)
#
A 'disable' event is emitted when the disabled state of the widget changes (i.e. on disable and enable).
Parameters:
Name | Type | Description |
---|---|---|
disabled |
boolean | Widget is disabled |
- Inherited from:
- Source:
A 'disable' event is emitted when the disabled state of the widget changes (i.e.
highlight(item)
#
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:
highlight
event is emitted when the highlight is changed with the #highlightItem method.
press(item)
#
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:
A press
event is emitted when the #pressItem method is used to programmatically modify the
pressed state of an option.
remove(items)
#
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:
A remove
event is emitted when options are removed from the select with the #clearItems
or #removeItems methods.
select(items)
#
A select
event is emitted when the selection is modified programmatically with the #selectItem
method.
Parameters:
Name | Type | Description |
---|---|---|
items |
Array.<OO.ui.OptionWidget>
|
OO.ui.OptionWidget
|
null
|
Currently selected items |
- Inherited from:
- Source:
A select
event is emitted when the selection is modified programmatically with the #selectItem
method.
toggle(visible)
#
A 'toggle' event is emitted when the visibility of the widget changes.
Parameters:
Name | Type | Description |
---|---|---|
visible |
boolean | Widget is visible |
- Inherited from:
- Source: