(abstract) new SelectWidget(configopt)
A SelectWidget is of a generic selection of options. The OOUI 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 [OOUI documentation on MediaWiki][1].
Parameters:
Name | Type | Attributes | Description | ||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
config |
Object |
<optional> |
Configuration options
Properties
|
- 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/OOUI/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 `
- 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 `
- 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: