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