The sap.m.SelectList
displays a list of items that allows the user to select an item.
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. |
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 |
|
_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. |
keyboardNavigationMode | sap.m.SelectListKeyboardNavigationMode | Delimited | Defines the keyboard navigation mode. Note: The |
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 |
width | sap.ui.core.CSSSize | auto | Sets the width of the control. Visibility: public |
Default Aggregation: items
Name | Cardinality | Type | Description |
---|---|---|---|
items (default) | 0..n | sap.ui.core.Item |
Defines the items contained within this control. |
Name | Cardinality | Type | Description |
---|---|---|---|
ariaLabelledBy | 0..n | sap.ui.core.Control |
Association to controls / IDs which label this control (see WAI-ARIA attribute |
selectedItem | 0..1 | sap.ui.core.Item |
Sets or retrieves the selected item from the aggregation named items. |
Event | Description |
---|---|
itemPress |
This event is fired when an item is pressed. |
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. |
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. |
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. |
Method | Description |
---|---|
addAriaLabelledBy |
Adds some ariaLabelledBy into the association ariaLabelledBy. |
addItem |
Adds some item to the aggregation items. |
attachItemPress |
Attaches event handler When called, the context of the event handler (its This event is fired when an item is pressed. |
attachSelectionChange |
Attaches event handler When called, the context of the event handler (its 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 |
clearSelection |
Clear the selection. |
destroyItems |
Destroys all the items in the aggregation named |
detachItemPress |
Detaches event handler The passed function and listener object must match the ones used for event registration. |
detachSelectionChange |
Detaches event handler 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
|
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 |
getEnabled |
Gets current value of property enabled. Indicates whether the user can change the selection. Default value is |
getEnabledItems |
Gets the enabled items from the aggregation named |
getFirstItem |
Gets the first item from the aggregation named |
getHideDisabledItems |
Gets current value of property hideDisabledItems. Determines whether the disabled items are hidden from the DOM structure. Default value is |
getItemAt |
Gets the item from the aggregation named |
getItemByKey |
Gets the item with the given key from the aggregation named 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 Default value is |
getLastItem |
Gets the enabled items from the aggregation named |
getMaxWidth |
Gets current value of property maxWidth. Sets the maximum width of the control. Default value is |
sap.m.SelectList.getMetadata |
Returns a metadata object for class sap.m.SelectList. |
getSelectedItem |
Gets the selected item object from the aggregation named |
getSelectedItemId |
Gets current value of property selectedItemId. ID of the selected item. Default value is |
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 |
getShowSecondaryValues |
Gets current value of property showSecondaryValues. Indicates whether the text values of the Default value is |
getWidth |
Gets current value of property width. Sets the width of the control. Default value is |
indexOfItem |
Checks for the provided |
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 |
removeAriaLabelledBy |
Removes an ariaLabelledBy from the association named ariaLabelledBy. |
removeItem |
Removes an item from the aggregation named |
setEnabled |
Sets a new value for property enabled. Indicates whether the user can change the selection. When called with a value of Default value is |
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 Default value is |
setKeyboardNavigationMode |
Sets a new value for property keyboardNavigationMode. Defines the keyboard navigation mode. Note: The When called with a value of Default value is |
setMaxWidth |
Sets a new value for property maxWidth. Sets the maximum width of the control. When called with a value of Default value is |
setSelectedItem |
Sets the |
setSelectedItemId |
Sets property Default value is an empty string |
setSelectedKey |
Sets property Default value is an empty string |
setSelection |
Updates and synchronizes |
setShowSecondaryValues |
Sets a new value for property showSecondaryValues. Indicates whether the text values of the When called with a value of Default value is |
setWidth |
Sets a new value for property width. Sets the width of the control. When called with a value of Default value is |
unbindItems |
Unbinds aggregation items from model data. |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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. |
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. |
Returns array of IDs of the elements which are the current targets of the association ariaLabelledBy.
Retrieves the default selected item from the aggregation named items
.
Param | Type | DefaultValue | Description |
---|---|---|---|
aItems | sap.ui.core.Item[] |
Gets current value of property enabled.
Indicates whether the user can change the selection.
Default value is true
.
Gets the enabled items from the aggregation named items
.
Param | Type | DefaultValue | Description |
---|---|---|---|
aItems | sap.ui.core.Item[] | getItems() |
items to filter |
Gets current value of property hideDisabledItems.
Determines whether the disabled items are hidden from the DOM structure.
Default value is false
.
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. |
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. |
Gets current value of property maxWidth.
Sets the maximum width of the control.
Default value is "100%"
.
Gets current value of property selectedItemId.
ID of the selected item.
Default value is empty string
.
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
.
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
.
Gets current value of property width.
Sets the width of the control.
Default value is "auto"
.
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 |
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 |
Removes all the items in the aggregation named items
. Additionally unregisters them from the hosting UIArea.
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 |
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. |
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 |
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 |
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 |
Sets the selectedItem
association.
Param | Type | DefaultValue | Description |
---|---|---|---|
vItem | string sap.ui.core.Item null |
New value for the |
Sets property selectedItemId
.
Default value is an empty string ""
or undefined
.
Param | Type | DefaultValue | Description |
---|---|---|---|
vItem | string undefined |
New value for property |
Sets property selectedKey
.
Default value is an empty string ""
or undefined
.
Param | Type | DefaultValue | Description |
---|---|---|---|
sKey | string |
New value for property |
Updates and synchronizes selectedItem
association, selectedItemId
and selectedKey
properties.
Param | Type | DefaultValue | Description |
---|---|---|---|
vItem | string sap.ui.core.Item null |
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 |
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 |