class sap.m.SelectList

Control sample: sap.m.SelectList
Visiblity: public
UX Guidelines:
Implements:
Available since: N/A
Module: sap/m/SelectList
Application Component: CA-UI5-CTR

The sap.m.SelectList displays a list of items that allows the user to select an item.


Constructor

Constructor for a new sap.m.SelectList.

Accepts an object literal mSettings that defines initial property values, aggregated and associated objects as well as event handlers. See sap.ui.base.ManagedObject#constructor for a general description of the syntax of the settings object.

new sap.m.SelectList(sId?, mSettings?)
Param Type Default Value Description
sId? string

ID for the new control, generated automatically if no ID is given.

mSettings? object

Initial settings for the new control.


Properties

Name Type Default Value Description
_columnRatio sap.m.SelectColumnRatio

Determines the ratio between the first and the second column when secondary values are displayed.

Note: This property takes effect only when the showSecondaryValues property is set to true and only in the context of sap.m.Select.

Visibility: hidden
_tabIndex string empty string

Determines the tabindex value of the [role="listbox"] element.

Visibility: hidden
enabled boolean true

Indicates whether the user can change the selection.

Visibility: public
hideDisabledItems boolean false

Determines whether the disabled items are hidden from the DOM structure.

Since: 1.91.

Visibility: public
keyboardNavigationMode sap.m.SelectListKeyboardNavigationMode Delimited

Defines the keyboard navigation mode.

Note: The sap.m.SelectListKeyboardNavigationMode.None enumeration value, is only intended for use in some composite controls that handles keyboard navigation by themselves.

Since: 1.38.

Visibility: public
maxWidth sap.ui.core.CSSSize 100%

Sets the maximum width of the control.

Visibility: public
selectedItemId string empty string

ID of the selected item.

Visibility: public
selectedKey string empty string

Key of the selected item.

Note: If duplicate keys exist, the first item matching the key is used.

Visibility: public
showSecondaryValues boolean false

Indicates whether the text values of the additionalText property of a sap.ui.core.ListItem are shown.

Since: 1.32.3.

Visibility: public
width sap.ui.core.CSSSize auto

Sets the width of the control.

Visibility: public

Aggregations

Default Aggregation: items

Name Cardinality Type Description
items (default) 0..n sap.ui.core.Item

Defines the items contained within this control.


Associations

Name Cardinality Type Description
ariaLabelledBy 0..n sap.ui.core.Control

Association to controls / IDs which label this control (see WAI-ARIA attribute aria-labelledby).

Since: 1.27.0.

selectedItem 0..1 sap.ui.core.Item

Sets or retrieves the selected item from the aggregation named items.


Events Overview

Event Description
itemPress

This event is fired when an item is pressed.

Since: 1.32.4.

selectionChange

This event is fired when the selection has changed.

Note: The selection can be changed by pressing a non-selected item or via keyboard and after the enter or space key is pressed.

itemPress

This event is fired when an item is pressed.

Since: 1.32.4.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
item sap.ui.core.Item

The pressed item.

selectionChange

This event is fired when the selection has changed.

Note: The selection can be changed by pressing a non-selected item or via keyboard and after the enter or space key is pressed.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
selectedItem sap.ui.core.Item

The selected item.


Methods Overview

Method Description
addAriaLabelledBy

Adds some ariaLabelledBy into the association ariaLabelledBy.

addItem

Adds some item to the aggregation items.

attachItemPress

Attaches event handler fnFunction to the itemPress event of this sap.m.SelectList.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.SelectList itself.

This event is fired when an item is pressed.

attachSelectionChange

Attaches event handler fnFunction to the selectionChange event of this sap.m.SelectList.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.SelectList itself.

This event is fired when the selection has changed.

Note: The selection can be changed by pressing a non-selected item or via keyboard and after the enter or space key is pressed.

bindItems

Binds aggregation items to model data.

See ManagedObject.bindAggregation for a detailed description of the possible properties of oBindingInfo.

clearSelection

Clear the selection.

destroyItems

Destroys all the items in the aggregation named items.

detachItemPress

Detaches event handler fnFunction from the itemPress event of this sap.m.SelectList.

The passed function and listener object must match the ones used for event registration.

detachSelectionChange

Detaches event handler fnFunction from the selectionChange event of this sap.m.SelectList.

The passed function and listener object must match the ones used for event registration.

sap.m.SelectList.extend

Creates a new subclass of class sap.m.SelectList with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.ui.core.Control.extend.

fireItemPress

Fires event itemPress to attached listeners.

fireSelectionChange

Fires event selectionChange to attached listeners.

getAriaLabelledBy

Returns array of IDs of the elements which are the current targets of the association ariaLabelledBy.

getDefaultSelectedItem

Retrieves the default selected item from the aggregation named items.

getEnabled

Gets current value of property enabled.

Indicates whether the user can change the selection.

Default value is true.

getEnabledItems

Gets the enabled items from the aggregation named items.

getFirstItem

Gets the first item from the aggregation named items.

getHideDisabledItems

Gets current value of property hideDisabledItems.

Determines whether the disabled items are hidden from the DOM structure.

Default value is false.

getItemAt

Gets the item from the aggregation named items at the given 0-based index.

getItemByKey

Gets the item with the given key from the aggregation named items.

Note: If duplicate keys exists, the first item matching the key is returned.

getItems

Gets content of aggregation items.

Defines the items contained within this control.

getKeyboardNavigationMode

Gets current value of property keyboardNavigationMode.

Defines the keyboard navigation mode.

Note: The sap.m.SelectListKeyboardNavigationMode.None enumeration value, is only intended for use in some composite controls that handles keyboard navigation by themselves.

Default value is Delimited.

getLastItem

Gets the enabled items from the aggregation named items.

getMaxWidth

Gets current value of property maxWidth.

Sets the maximum width of the control.

Default value is "100%".

sap.m.SelectList.getMetadata

Returns a metadata object for class sap.m.SelectList.

getSelectedItem

Gets the selected item object from the aggregation named items.

getSelectedItemId

Gets current value of property selectedItemId.

ID of the selected item.

Default value is empty string.

getSelectedKey

Gets current value of property selectedKey.

Key of the selected item.

Note: If duplicate keys exist, the first item matching the key is used.

Default value is empty string.

getShowSecondaryValues

Gets current value of property showSecondaryValues.

Indicates whether the text values of the additionalText property of a sap.ui.core.ListItem are shown.

Default value is false.

getWidth

Gets current value of property width.

Sets the width of the control.

Default value is "auto".

indexOfItem

Checks for the provided sap.ui.core.Item in the aggregation items. and returns its index if found or -1 otherwise.

insertItem

Inserts a item into the aggregation items.

removeAllAriaLabelledBy

Removes all the controls in the association named ariaLabelledBy.

removeAllItems

Removes all the items in the aggregation named items. Additionally unregisters them from the hosting UIArea.

removeAriaLabelledBy

Removes an ariaLabelledBy from the association named ariaLabelledBy.

removeItem

Removes an item from the aggregation named items.

setEnabled

Sets a new value for property enabled.

Indicates whether the user can change the selection.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

setHideDisabledItems

Sets a new value for property hideDisabledItems.

Determines whether the disabled items are hidden from the DOM structure.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

setKeyboardNavigationMode

Sets a new value for property keyboardNavigationMode.

Defines the keyboard navigation mode.

Note: The sap.m.SelectListKeyboardNavigationMode.None enumeration value, is only intended for use in some composite controls that handles keyboard navigation by themselves.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is Delimited.

setMaxWidth

Sets a new value for property maxWidth.

Sets the maximum width of the control.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is "100%".

setSelectedItem

Sets the selectedItem association.

setSelectedItemId

Sets property selectedItemId.

Default value is an empty string "" or undefined.

setSelectedKey

Sets property selectedKey.

Default value is an empty string "" or undefined.

setSelection

Updates and synchronizes selectedItem association, selectedItemId and selectedKey properties.

setShowSecondaryValues

Sets a new value for property showSecondaryValues.

Indicates whether the text values of the additionalText property of a sap.ui.core.ListItem are shown.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

setWidth

Sets a new value for property width.

Sets the width of the control.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is "auto".

unbindItems

Unbinds aggregation items from model data.

addAriaLabelledBy

Adds some ariaLabelledBy into the association ariaLabelledBy.

Param Type DefaultValue Description
vAriaLabelledBy sap.ui.core.ID sap.ui.core.Control

The ariaLabelledBy to add; if empty, nothing is inserted

addItem

Adds some item to the aggregation items.

Param Type DefaultValue Description
oItem sap.ui.core.Item

The item to add; if empty, nothing is inserted

attachItemPress

Attaches event handler fnFunction to the itemPress event of this sap.m.SelectList.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.SelectList itself.

This event is fired when an item is pressed.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function(sap.ui.base.Event) : void

The function to be called when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.m.SelectList itself

attachSelectionChange

Attaches event handler fnFunction to the selectionChange event of this sap.m.SelectList.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.SelectList itself.

This event is fired when the selection has changed.

Note: The selection can be changed by pressing a non-selected item or via keyboard and after the enter or space key is pressed.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function(sap.ui.base.Event) : void

The function to be called when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.m.SelectList itself

bindItems

Binds aggregation items to model data.

See ManagedObject.bindAggregation for a detailed description of the possible properties of oBindingInfo.

Param Type DefaultValue Description
oBindingInfo sap.ui.base.ManagedObject.AggregationBindingInfo

The binding information

clearSelection

Clear the selection.

destroyItems

Destroys all the items in the aggregation named items.

detachItemPress

Detaches event handler fnFunction from the itemPress event of this sap.m.SelectList.

The passed function and listener object must match the ones used for event registration.

Param Type DefaultValue Description
fnFunction function(sap.ui.base.Event) : void

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

detachSelectionChange

Detaches event handler fnFunction from the selectionChange event of this sap.m.SelectList.

The passed function and listener object must match the ones used for event registration.

Param Type DefaultValue Description
fnFunction function(sap.ui.base.Event) : void

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

sap.m.SelectList.extend

Creates a new subclass of class sap.m.SelectList with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.ui.core.Control.extend.

Param Type DefaultValue Description
sClassName string

Name of the class being created

oClassInfo object

Object literal with information about the class

FNMetaImpl function

Constructor function for the metadata object; if not given, it defaults to the metadata implementation used by this class

fireItemPress

Fires event itemPress to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

item sap.ui.core.Item

The pressed item.

fireSelectionChange

Fires event selectionChange to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

selectedItem sap.ui.core.Item

The selected item.

getAriaLabelledBy

Returns array of IDs of the elements which are the current targets of the association ariaLabelledBy.

getDefaultSelectedItem

Retrieves the default selected item from the aggregation named items.

Param Type DefaultValue Description
aItems sap.ui.core.Item[]

getEnabled

Gets current value of property enabled.

Indicates whether the user can change the selection.

Default value is true.

getEnabledItems

Gets the enabled items from the aggregation named items.

Param Type DefaultValue Description
aItems sap.ui.core.Item[] getItems()

items to filter

getFirstItem

Gets the first item from the aggregation named items.

getHideDisabledItems

Gets current value of property hideDisabledItems.

Determines whether the disabled items are hidden from the DOM structure.

Default value is false.

getItemAt

Gets the item from the aggregation named items at the given 0-based index.

Param Type DefaultValue Description
iIndex int

Index of the item to return.

getItemByKey

Gets the item with the given key from the aggregation named items.

Note: If duplicate keys exists, the first item matching the key is returned.

Param Type DefaultValue Description
sKey string

An item key that specifies the item to retrieve.

getItems

Gets content of aggregation items.

Defines the items contained within this control.

getKeyboardNavigationMode

Gets current value of property keyboardNavigationMode.

Defines the keyboard navigation mode.

Note: The sap.m.SelectListKeyboardNavigationMode.None enumeration value, is only intended for use in some composite controls that handles keyboard navigation by themselves.

Default value is Delimited.

getLastItem

Gets the enabled items from the aggregation named items.

getMaxWidth

Gets current value of property maxWidth.

Sets the maximum width of the control.

Default value is "100%".

sap.m.SelectList.getMetadata

Returns a metadata object for class sap.m.SelectList.

getSelectedItem

Gets the selected item object from the aggregation named items.

getSelectedItemId

Gets current value of property selectedItemId.

ID of the selected item.

Default value is empty string.

getSelectedKey

Gets current value of property selectedKey.

Key of the selected item.

Note: If duplicate keys exist, the first item matching the key is used.

Default value is empty string.

getShowSecondaryValues

Gets current value of property showSecondaryValues.

Indicates whether the text values of the additionalText property of a sap.ui.core.ListItem are shown.

Default value is false.

getWidth

Gets current value of property width.

Sets the width of the control.

Default value is "auto".

indexOfItem

Checks for the provided sap.ui.core.Item in the aggregation items. and returns its index if found or -1 otherwise.

Param Type DefaultValue Description
oItem sap.ui.core.Item

The item whose index is looked for

insertItem

Inserts a item into the aggregation items.

Param Type DefaultValue Description
oItem sap.ui.core.Item

The item to insert; if empty, nothing is inserted

iIndex int

The 0-based index the item should be inserted at; for a negative value of iIndex, the item is inserted at position 0; for a value greater than the current size of the aggregation, the item is inserted at the last position

removeAllAriaLabelledBy

Removes all the controls in the association named ariaLabelledBy.

removeAllItems

Removes all the items in the aggregation named items. Additionally unregisters them from the hosting UIArea.

removeAriaLabelledBy

Removes an ariaLabelledBy from the association named ariaLabelledBy.

Param Type DefaultValue Description
vAriaLabelledBy int sap.ui.core.ID sap.ui.core.Control

The ariaLabelledBy to be removed or its index or ID

removeItem

Removes an item from the aggregation named items.

Param Type DefaultValue Description
vItem int string sap.ui.core.Item

The item to remove or its index or id.

setEnabled

Sets a new value for property enabled.

Indicates whether the user can change the selection.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

Param Type DefaultValue Description
bEnabled boolean true

New value for property enabled

setHideDisabledItems

Sets a new value for property hideDisabledItems.

Determines whether the disabled items are hidden from the DOM structure.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

Param Type DefaultValue Description
bHideDisabledItems boolean false

New value for property hideDisabledItems

setKeyboardNavigationMode

Sets a new value for property keyboardNavigationMode.

Defines the keyboard navigation mode.

Note: The sap.m.SelectListKeyboardNavigationMode.None enumeration value, is only intended for use in some composite controls that handles keyboard navigation by themselves.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is Delimited.

Param Type DefaultValue Description
sKeyboardNavigationMode sap.m.SelectListKeyboardNavigationMode Delimited

New value for property keyboardNavigationMode

setMaxWidth

Sets a new value for property maxWidth.

Sets the maximum width of the control.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is "100%".

Param Type DefaultValue Description
sMaxWidth sap.ui.core.CSSSize "100%"

New value for property maxWidth

setSelectedItem

Sets the selectedItem association.

Param Type DefaultValue Description
vItem string sap.ui.core.Item null

New value for the selectedItem association. If an ID of a sap.ui.core.Item is given, the item with this ID becomes the selectedItem association. Alternatively, a sap.ui.core.Item instance may be given or null to clear the selection.

setSelectedItemId

Sets property selectedItemId.

Default value is an empty string "" or undefined.

Param Type DefaultValue Description
vItem string undefined

New value for property selectedItemId.

setSelectedKey

Sets property selectedKey.

Default value is an empty string "" or undefined.

Param Type DefaultValue Description
sKey string

New value for property selectedKey.

setSelection

Updates and synchronizes selectedItem association, selectedItemId and selectedKey properties.

Param Type DefaultValue Description
vItem string sap.ui.core.Item null

setShowSecondaryValues

Sets a new value for property showSecondaryValues.

Indicates whether the text values of the additionalText property of a sap.ui.core.ListItem are shown.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

Param Type DefaultValue Description
bShowSecondaryValues boolean false

New value for property showSecondaryValues

setWidth

Sets a new value for property width.

Sets the width of the control.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is "auto".

Param Type DefaultValue Description
sWidth sap.ui.core.CSSSize "auto"

New value for property width

unbindItems

Unbinds aggregation items from model data.