OO.ui.RadioSelectWidget

Extends

Constructor

new OO.ui.RadioSelectWidget(config) #

RadioSelectWidget is a select widget that contains radio options and is used together with OO.ui.RadioOptionWidget. The RadioSelectWidget provides an interface for adding, removing and selecting options. Please see the OOUI documentation on MediaWiki for more information.

If you want to use this within an HTML form, such as a OO.ui.FormLayout, use OO.ui.RadioSelectInputWidget instead.

Example

// A RadioSelectWidget with RadioOptions.
    const option1 = new OO.ui.RadioOptionWidget( {
            data: 'a',
            label: 'Selected radio option'
        } ),
        option2 = new OO.ui.RadioOptionWidget( {
            data: 'b',
            label: 'Unselected radio option'
        } );
        radioSelect = new OO.ui.RadioSelectWidget( {
            items: [ option1, option2 ]
        } );

    // Select 'option 1' using the RadioSelectWidget's selectItem() method.
    radioSelect.selectItem( option1 );

    $( document.body ).append( radioSelect.$element );

Parameters:

Name Type Attributes Description
config Object optional

Configuration options
Mixes in:
Source:

RadioSelectWidget is a select widget that contains radio options and is used together with OO.ui.RadioOptionWidget.

Methods

addItems(items, index) → {OO.ui.Widget} #

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:

Fires:

Returns:

The widget, for chaining

Type
OO.ui.Widget
Add an array of options to the select.

bindDocumentKeyDownListener()protected #

Bind document key down listener.

Inherited from:
Source:
Bind document key down listener.

bindDocumentKeyPressListener()protected #

Bind document key press listener.

Inherited from:
Source:
Bind document key press listener.

chooseItem(item) → {OO.ui.Widget} #

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:

Fires:

Returns:

The widget, for chaining

Type
OO.ui.Widget
Select an item or toggle an item's selection when multiselect is enabled.

clearItems() → {OO.ui.Widget} #

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:

Fires:

Returns:

The widget, for chaining

Type
OO.ui.Widget
Clear all options from the select.

clearKeyPressBuffer()protected #

Clear the key-press buffer

Inherited from:
Source:

Clear the key-press buffer

.

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
Find the next selectable item or null if there are no selectable items.

findFirstSelectedItem() → {OO.ui.OptionWidget|null} #

Inherited from:
Source:

Returns:

The first (of possibly many) selected item, if any

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
Find highlighted item.

findRelativeSelectableItem(item, offset, filter, wrap) → {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 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 null to start at the beginning of the array.
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} #

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
Find selected item.

findSelectedItems() → {Array.<OO.ui.OptionWidget>|OO.ui.OptionWidget|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
Find all selected items, if there are any.

getClosestScrollableElementContainer() → {HTMLElement} #

Get closest scrollable container.

Inherited from:
Source:

Returns:

Closest scrollable container

Type
HTMLElement
Get closest scrollable container.

getData() → {Mixed} #

Get element data.

Inherited from:
Source:

Returns:

Element data

Type
Mixed
Get element data.

getElementDocument() → {HTMLDocument} #

Get the DOM document.

Inherited from:
Source:

Returns:

Document object

Type
HTMLDocument
Get the DOM document.

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
Get group element is in.

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} #

Get the DOM window.

Inherited from:
Source:

Returns:

Window object

Type
Window
Get the DOM 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

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} #

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
Fetch an item by its label.

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

Get a matcher for the specific string

.

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
Get the HTML tag name.

highlightItem(item) → {OO.ui.Widget} #

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:

Returns:

The widget, for chaining

Type
OO.ui.Widget
Highlight an option.

isDisabled() → {boolean} #

Check if the widget is disabled.

Inherited from:
Source:

Returns:

Widget is disabled

Type
boolean
Check if the widget is disabled.

isElementAttached() → {boolean} #

Check if the element is attached to the DOM

Inherited from:
Source:

Returns:

The element is attached to the DOM

Type
boolean

Check if the element is attached to the DOM

.

isVisible() → {boolean} #

Check if element is visible.

Inherited from:
Source:

Returns:

element is visible

Type
boolean
Check if element is visible.

onDocumentKeyDown(e)protected #

Handle document key down events.

Parameters:

Name Type Description
e KeyboardEvent

Key down event
Inherited from:
Source:
Handle document key down events.

onDocumentKeyPress(e) → {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
Handle key press events.

onToggle(visible)protected #

Visibility change handler

Parameters:

Name Type Description
visible boolean
Inherited from:
Source:

Visibility change handler

.

pressItem(item) → {OO.ui.Widget} #

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:

Returns:

The widget, for chaining

Type
OO.ui.Widget
Press an item.

removeItems(items) → {OO.ui.Widget} #

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:

Fires:

Returns:

The widget, for chaining

Type
OO.ui.Widget
Remove the specified array of options from the select.

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:
Restore the pre-infusion dynamic state for this widget.

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
Scroll element into view.

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:
Scroll item into view, preventing spurious mouse highlight actions from happening.

selectItem(item) → {OO.ui.Widget} #

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:

Returns:

The widget, for chaining

Type
OO.ui.Widget
Programmatically select an option by its reference.

selectItemByData(data) → {OO.ui.Widget} #

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:

Returns:

The widget, for chaining

Type
OO.ui.Widget
Programmatically select an option by its data.

selectItemByLabel(label, prefix) → {OO.ui.Widget} #

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:

Returns:

The widget, for chaining

Type
OO.ui.Widget
Programmatically select an option by its label.

setData(data) → {OO.ui.Element} #

Set element data.

Parameters:

Name Type Description
data Mixed

Element data
Inherited from:
Source:

Returns:

The element, for chaining

Type
OO.ui.Element
Set element data.

setDisabled(disabled) → {OO.ui.Widget} #

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
Set the 'disabled' state of the widget.

setElementGroup(group) → {OO.ui.Element} #

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
Set group element is in.

setElementId(id) → {OO.ui.Element} #

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
Set the element has an 'id' attribute.

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:
Set the DOM element which has focus while the user is interacting with this SelectWidget.

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:
Set the element with the given ID as a label for this widget.

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:
Simulate the behavior of clicking on a label (a HTML <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
Check if element supports one or more methods.

toggle(show) → {OO.ui.Element} #

Toggle visibility of an element.

Parameters:

Name Type Attributes Description
show boolean optional

Make element visible, omit to toggle visibility
Inherited from:
Source:

Fires:

Returns:

The element, for chaining

Type
OO.ui.Element
Toggle visibility of an element.

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:
Toggle pressed state.

unbindDocumentKeyDownListener()protected #

Unbind document key down listener.

Inherited from:
Source:
Unbind document key down listener.

unbindDocumentKeyPressListener()protected #

Unbind document key down listener.

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

Inherited from:
Source:
Unbind document key down listener.

unselectItem(unselectedItem) → {OO.ui.Widget} #

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:

Fires:

Returns:

The widget, for chaining

Type
OO.ui.Widget
Programmatically unselect an option by its reference.

updateDisabled() → {OO.ui.Widget} #

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

Inherited from:
Source:

Returns:

The widget, for chaining

Type
OO.ui.Widget
Update the disabled state, in case of changes in parent 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:
Update the theme-provided classes.

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:
An 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:
A 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:
A 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:
A 'toggle' event is emitted when the visibility of the widget changes.