Class sap.m.SelectModule: sap/m/Select

extends Control
implements IFormContent
known direct subclasses: ActionSelect, HierarchicalSelect

The sap.m.Select control provides a list of items that allows users to select an item.
Constructor Summary
new sap.m.Select(sId?, mSettings?)Constructor for a new sap.m.Select.
Event Summary
change(oControlEvent)

This event is fired when the value in the selection field is changed in combination with one of the following actions:

  • The focus leaves the selection field
  • The Enter key is pressed
  • The item is pressed
Events borrowed from class sap.ui.core.Control
Method Summary
sap.m.Select.extend(sClassName, oClassInfo?, FNMetaImpl?)Creates a new subclass of class sap.m.Select with name sClassName and enriches it with the information contained in oClassInfo.
sap.m.Select.getMetadata()Returns a metadata object for class sap.m.Select.
addAriaLabelledBy(vAriaLabelledBy)Adds some ariaLabelledBy into the association ariaLabelledBy.
addItem(oItem)Adds an item to the aggregation named items.
attachChange(oData?, fnFunction, oListener?)Attaches event handler fnFunction to the change event of this sap.m.Select.
bindItems(oBindingInfo)Binds aggregation items to model data.
close()Closes the control's picker popup.
createPicker(sPickerType)Creates a picker popup container where the selection should take place.
destroyItems()Destroys all the items in the aggregation named items.
detachChange(fnFunction, oListener)Detaches event handler fnFunction from the change event of this sap.m.Select.
fireChange(mParameters?)Fires event change to attached listeners.
getAriaLabelledBy()Returns array of IDs of the elements which are the current targets of the association ariaLabelledBy.
getAutoAdjustWidth()Gets current value of property autoAdjustWidth.
getEnabled()Gets current value of property enabled.
getEnabledItems(aItems?)Gets the enabled items from the aggregation named items.
getFirstItem()Gets the first item from the aggregation named items.
getForceSelection()Gets current value of property forceSelection.
getIcon()Gets current value of property icon.
getItemAt(iIndex)Gets the item from the aggregation named items at the given 0-based index.
getItemByKey(sKey)Gets the item with the given key from the aggregation named items.
getItems()Gets aggregation items.
getLastItem()Gets the last item from the aggregation named items.
getMaxWidth()Gets current value of property maxWidth.
getName()Gets current value of property name.
getSelectedItem()Gets the selected item object from the aggregation named items.
getSelectedItemId()Gets current value of property selectedItemId.
getSelectedKey()Gets current value of property selectedKey.
getShowSecondaryValues()Gets current value of property showSecondaryValues.
getTextAlign()Gets current value of property textAlign.
getTextDirection()Gets current value of property textDirection.
getType()Gets current value of property type.
getValueState()Gets current value of property valueState.
getValueStateText()Gets current value of property valueStateText.
getWidth()Gets current value of property width.
indexOfItem(oItem)Checks for the provided sap.ui.core.Item in the aggregation items.
insertItem(oItem, iIndex)Inserts an item into the aggregation named items.
isOpen()Indicates whether the control's picker popup is opened.
open()Open the control's picker popup.
removeAllAriaLabelledBy()Removes all the controls in the association named ariaLabelledBy.
removeAllItems()Removes all the items in the aggregation named items.
removeAriaLabelledBy(vAriaLabelledBy)Removes an ariaLabelledBy from the association named ariaLabelledBy.
removeItem(vItem)Removes an item from the aggregation named items.
setAutoAdjustWidth(bAutoAdjustWidth)Sets a new value for property autoAdjustWidth.
setEnabled(bEnabled)Sets a new value for property enabled.
setForceSelection(bForceSelection)Sets a new value for property forceSelection.
setIcon(sIcon)Sets a new value for property icon.
setMaxWidth(sMaxWidth)Sets a new value for property maxWidth.
setName(sName)Sets a new value for property name.
setSelectedItem(vItem)Sets the selectedItem association.
setSelectedItemId(vItem)Sets the selectedItemId property.
setSelectedKey(sKey)Sets property selectedKey.
setShowSecondaryValues(bShowSecondaryValues)Sets a new value for property showSecondaryValues.
setTextAlign(sTextAlign)Sets a new value for property textAlign.
setTextDirection(sTextDirection)Sets a new value for property textDirection.
setType(sType)Sets a new value for property type.
setValueState(sValueState)Sets a new value for property valueState.
setValueStateText(sValueStateText)Sets a new value for property valueStateText.
setWidth(sWidth)Sets a new value for property width.
unbindItems()Unbinds aggregation items from model data.
Constructor Detail
new sap.m.Select(sId?, mSettings?)

Constructor for a new sap.m.Select.

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

The supported settings are:

In addition, all settings applicable to the base type sap.ui.core.Control can be used as well.

Parameters:
stringsId?ID for the new control, generated automatically if no ID is given.
objectmSettings?Initial settings for the new control.
Event Detail
change(oControlEvent)

This event is fired when the value in the selection field is changed in combination with one of the following actions:

  • The focus leaves the selection field
  • The Enter key is pressed
  • The item is pressed
Parameters:
sap.ui.base.EventoControlEvent
sap.ui.base.EventProvideroControlEvent.getSource
objectoControlEvent.getParameters
sap.ui.core.ItemoControlEvent.getParameters.selectedItemThe selected item.
Method Detail
sap.m.Select.extend(sClassName, oClassInfo?, FNMetaImpl?): function

Creates a new subclass of class sap.m.Select 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.

Parameters:
stringsClassNameName of the class being created
objectoClassInfo?Object literal with information about the class
functionFNMetaImpl?Constructor function for the metadata object; if not given, it defaults to sap.ui.core.ElementMetadata
Returns:
functionCreated class / constructor function
sap.m.Select.getMetadata(): sap.ui.base.Metadata
Returns a metadata object for class sap.m.Select.
Returns:
sap.ui.base.MetadataMetadata object describing this class
addAriaLabelledBy(vAriaLabelledBy): sap.m.Select
Adds some ariaLabelledBy into the association ariaLabelledBy.
Parameters:
sap.ui.core.ID|sap.ui.core.ControlvAriaLabelledBythe ariaLabelledBy to add; if empty, nothing is inserted
Returns:
sap.m.SelectReference to this in order to allow method chaining
Since:
1.27.0
addItem(oItem): sap.m.Select
Adds an item to the aggregation named items.
Parameters:
sap.ui.core.ItemoItemThe item to be added; if empty, nothing is added.
Returns:
sap.m.Selectthis to allow method chaining.
attachChange(oData?, fnFunction, oListener?): sap.m.Select

Attaches event handler fnFunction to the change event of this sap.m.Select.

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.Select itself.

This event is fired when the value in the selection field is changed in combination with one of the following actions:

  • The focus leaves the selection field
  • The Enter key is pressed
  • The item is pressed
Parameters:
objectoData?An application-specific payload object that will be passed to the event handler along with the event object when firing the event
functionfnFunctionThe function to be called when the event occurs
objectoListener?Context object to call the event handler with. Defaults to this sap.m.Select itself
Returns:
sap.m.SelectReference to this in order to allow method chaining
bindItems(oBindingInfo): sap.m.Select

Binds aggregation items to model data.

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

Parameters:
objectoBindingInfoThe binding information
Returns:
sap.m.SelectReference to this in order to allow method chaining
close(): sap.m.Select
Closes the control's picker popup.
Returns:
sap.m.Selectthis to allow method chaining.
Since:
1.16
createPicker(sPickerType): sap.m.Popover|sap.m.Dialog
Creates a picker popup container where the selection should take place.
Parameters:
stringsPickerType
Returns:
sap.m.Popover|sap.m.Dialog
destroyItems(): sap.m.Select
Destroys all the items in the aggregation named items.
Returns:
sap.m.Selectthis to allow method chaining.
detachChange(fnFunction, oListener): sap.m.Select

Detaches event handler fnFunction from the change event of this sap.m.Select.

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

Parameters:
functionfnFunctionThe function to be called, when the event occurs
objectoListenerContext object on which the given function had to be called
Returns:
sap.m.SelectReference to this in order to allow method chaining
fireChange(mParameters?): sap.m.Select
Fires event change to attached listeners.
Parameters:
objectmParameters?Parameters to pass along with the event
sap.ui.core.ItemmParameters.selectedItem?The selected item.
Returns:
sap.m.SelectReference to this in order to allow method chaining
getAccessibilityInfo()
See:
sap.ui.core.Control#getAccessibilityInfo
getAriaLabelledBy(): sap.ui.core.ID[]
Returns array of IDs of the elements which are the current targets of the association ariaLabelledBy.
Returns:
sap.ui.core.ID[]
Since:
1.27.0
getAutoAdjustWidth(): boolean

Gets current value of property autoAdjustWidth.

Indicates whether the width of the input field is determined by the selected item's content.

Default value is false.

Returns:
booleanValue of property autoAdjustWidth
Since:
1.16
getEnabled(): boolean

Gets current value of property enabled.

Indicates whether the user can change the selection.

Default value is true.

Returns:
booleanValue of property enabled
getEnabledItems(aItems?): sap.ui.core.Item[]
Gets the enabled items from the aggregation named items.
Parameters:
sap.ui.core.Item[]aItems?, Default: getItems()Items to filter.
Returns:
sap.ui.core.Item[]An array containing the enabled items.
Since:
1.22.0
getFirstItem(): sap.ui.core.Item|null
Gets the first item from the aggregation named items.
Returns:
sap.ui.core.Item|nullThe first item, or null if there are no items.
Since:
1.16
getForceSelection(): boolean

Gets current value of property forceSelection.

Indicates whether the selection is restricted to one of the items in the list. Note: We strongly recommend that you always set this property to false and bind the selectedKey property to the desired value for better interoperability with data binding.

Default value is true.

Returns:
booleanValue of property forceSelection
Since:
1.34
getIcon(): sap.ui.core.URI

Gets current value of property icon.

The URI to the icon that will be displayed only when using the IconOnly type.

Default value is .

Returns:
sap.ui.core.URIValue of property icon
Since:
1.16
getItemAt(iIndex): sap.ui.core.Item|null
Gets the item from the aggregation named items at the given 0-based index.
Parameters:
intiIndexIndex of the item to return.
Returns:
sap.ui.core.Item|nullItem at the given index, or null if none.
Since:
1.16
getItemByKey(sKey): sap.ui.core.Item|null

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

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

Parameters:
stringsKeyAn item key that specifies the item to be retrieved.
Returns:
sap.ui.core.Item|null
Since:
1.16
getItems(): sap.ui.core.Item[]

Gets aggregation items.

Note: This is the default aggregation.

Returns:
sap.ui.core.Item[]
getLastItem(): sap.ui.core.Item|null
Gets the last item from the aggregation named items.
Returns:
sap.ui.core.Item|nullThe last item, or null if there are no items.
Since:
1.16
getMaxWidth(): sap.ui.core.CSSSize

Gets current value of property maxWidth.

Sets the maximum width of the control.

Note: This property is ignored if the autoAdjustWidth property is set to true.

Default value is 100%.

Returns:
sap.ui.core.CSSSizeValue of property maxWidth
getName(): string

Gets current value of property name.

The name to be used in the HTML code (for example, for HTML forms that send data to the server via submit).

Default value is .

Returns:
stringValue of property name
getSelectedItem(): sap.ui.core.Item|null
Gets the selected item object from the aggregation named items.
Returns:
sap.ui.core.Item|nullThe current target of the selectedItem association, or null.
getSelectedItemId(): string

Gets current value of property selectedItemId.

ID of the selected item.

Default value is .

Returns:
stringValue of property selectedItemId
Since:
1.12
getSelectedKey(): 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 .

Returns:
stringValue of property selectedKey
Since:
1.11
getShowSecondaryValues(): boolean

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.

Returns:
booleanValue of property showSecondaryValues
Since:
1.40
getTextAlign(): sap.ui.core.TextAlign

Gets current value of property textAlign.

Sets the horizontal alignment of the text within the input field.

Default value is Initial.

Returns:
sap.ui.core.TextAlignValue of property textAlign
Since:
1.28
getTextDirection(): sap.ui.core.TextDirection

Gets current value of property textDirection.

Specifies the direction of the text within the input field with enumerated options. By default, the control inherits text direction from the DOM.

Default value is Inherit.

Returns:
sap.ui.core.TextDirectionValue of property textDirection
Since:
1.28
getType(): sap.m.SelectType

Gets current value of property type.

Type of a select. Possible values Default, IconOnly.

Default value is Default.

Returns:
sap.m.SelectTypeValue of property type
Since:
1.16
getValueState(): sap.ui.core.ValueState

Gets current value of property valueState.

Visualizes the validation state of the control, e.g. Error, Warning, Success.

Default value is None.

Returns:
sap.ui.core.ValueStateValue of property valueState
Since:
1.40.2
getValueStateText(): string

Gets current value of property valueStateText.

Defines the text of the value state message popup. If this is not specified, a default text is shown from the resource bundle.

Default value is .

Returns:
stringValue of property valueStateText
Since:
1.40.5
getWidth(): sap.ui.core.CSSSize

Gets current value of property width.

Sets the width of the field. By default, the field width is automatically adjusted to the size of its content and the default width of the field is calculated based on the widest list item in the dropdown list. If the width defined is smaller than its content, only the field width is changed whereas the dropdown list keeps the width of its content. If the dropdown list is wider than the visual viewport, it is truncated and an ellipsis is displayed for each item. For phones, the width of the dropdown list is always the same as the viewport.

Note: This property is ignored if the autoAdjustWidth property is set to true.

Default value is auto.

Returns:
sap.ui.core.CSSSizeValue of property width
indexOfItem(oItem): int
Checks for the provided sap.ui.core.Item in the aggregation items. and returns its index if found or -1 otherwise.
Parameters:
sap.ui.core.ItemoItemThe item whose index is looked for
Returns:
intThe index of the provided control in the aggregation if found, or -1 otherwise
insertItem(oItem, iIndex): sap.m.Select
Inserts an item into the aggregation named items.
Parameters:
sap.ui.core.ItemoItemThe item to be inserted; if empty, nothing is inserted.
intiIndexThe 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.
Returns:
sap.m.Selectthis to allow method chaining.
isOpen(): boolean
Indicates whether the control's picker popup is opened.
Returns:
booleanIndicates whether the picker popup is currently open (this includes opening and closing animations).
Since:
1.16
open(): sap.m.Select
Open the control's picker popup.
Returns:
sap.m.Selectthis to allow method chaining.
Since:
1.16
removeAllAriaLabelledBy(): sap.ui.core.ID[]
Removes all the controls in the association named ariaLabelledBy.
Returns:
sap.ui.core.ID[]An array of the removed elements (might be empty)
Since:
1.27.0
removeAllItems(): sap.ui.core.Item[]
Removes all the items in the aggregation named items. Additionally unregisters them from the hosting UIArea.
Returns:
sap.ui.core.Item[]An array of the removed items (might be empty).
removeAriaLabelledBy(vAriaLabelledBy): sap.ui.core.ID
Removes an ariaLabelledBy from the association named ariaLabelledBy.
Parameters:
int|sap.ui.core.ID|sap.ui.core.ControlvAriaLabelledByThe ariaLabelledBy to be removed or its index or ID
Returns:
sap.ui.core.IDThe removed ariaLabelledBy or null
Since:
1.27.0
removeItem(vItem): sap.ui.core.Item
Removes an item from the aggregation named items.
Parameters:
int|string|sap.ui.core.ItemvItemThe item to be removed or its index or ID.
Returns:
sap.ui.core.ItemThe removed item or null.
setAutoAdjustWidth(bAutoAdjustWidth): sap.m.Select

Sets a new value for property autoAdjustWidth.

Indicates whether the width of the input field is determined by the selected item's content.

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

Default value is false.

Parameters:
booleanbAutoAdjustWidthNew value for property autoAdjustWidth
Returns:
sap.m.SelectReference to this in order to allow method chaining
Since:
1.16
setEnabled(bEnabled): sap.m.Select

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.

Parameters:
booleanbEnabledNew value for property enabled
Returns:
sap.m.SelectReference to this in order to allow method chaining
setForceSelection(bForceSelection): sap.m.Select

Sets a new value for property forceSelection.

Indicates whether the selection is restricted to one of the items in the list. Note: We strongly recommend that you always set this property to false and bind the selectedKey property to the desired value for better interoperability with data binding.

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

Default value is true.

Parameters:
booleanbForceSelectionNew value for property forceSelection
Returns:
sap.m.SelectReference to this in order to allow method chaining
Since:
1.34
setIcon(sIcon): sap.m.Select

Sets a new value for property icon.

The URI to the icon that will be displayed only when using the IconOnly type.

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

Default value is .

Parameters:
sap.ui.core.URIsIconNew value for property icon
Returns:
sap.m.SelectReference to this in order to allow method chaining
Since:
1.16
setMaxWidth(sMaxWidth): sap.m.Select

Sets a new value for property maxWidth.

Sets the maximum width of the control.

Note: This property is ignored if the autoAdjustWidth property is set to true.

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

Default value is 100%.

Parameters:
sap.ui.core.CSSSizesMaxWidthNew value for property maxWidth
Returns:
sap.m.SelectReference to this in order to allow method chaining
setName(sName): sap.m.Select

Sets a new value for property name.

The name to be used in the HTML code (for example, for HTML forms that send data to the server via submit).

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

Default value is .

Parameters:
stringsNameNew value for property name
Returns:
sap.m.SelectReference to this in order to allow method chaining
setSelectedItem(vItem): sap.m.Select

Sets the selectedItem association.

Default value is null.

Parameters:
string|sap.ui.core.Item|nullvItemNew 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. If the value of null is provided, the first enabled item will be selected (if any items exist).
Returns:
sap.m.Selectthis to allow method chaining.
setSelectedItemId(vItem): sap.m.Select

Sets the selectedItemId property.

Default value is an empty string "" or undefined.

Parameters:
string|undefinedvItemNew value for property selectedItemId. If the provided vItem has a default value, the first enabled item will be selected (if any items exist).
Returns:
sap.m.Selectthis to allow method chaining.
Since:
1.12
setSelectedKey(sKey): sap.m.Select

Sets property selectedKey.

Default value is an empty string "" or undefined.

Parameters:
stringsKey

New value for property selectedKey. If the forceSelection property is set to true and the provided sKey is an empty string "" or undefined, the value of sKey is changed to match the key of the first enabled item and the first enabled item is selected (if any items exist).

In the case that an item has the default key value, it is selected instead. If duplicate keys exist, the first item matching the key is selected.

Returns:
sap.m.Selectthis to allow method chaining.
Since:
1.11
setShowSecondaryValues(bShowSecondaryValues): sap.m.Select

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.

Parameters:
booleanbShowSecondaryValuesNew value for property showSecondaryValues
Returns:
sap.m.SelectReference to this in order to allow method chaining
Since:
1.40
setTextAlign(sTextAlign): sap.m.Select

Sets a new value for property textAlign.

Sets the horizontal alignment of the text within the input field.

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

Default value is Initial.

Parameters:
sap.ui.core.TextAlignsTextAlignNew value for property textAlign
Returns:
sap.m.SelectReference to this in order to allow method chaining
Since:
1.28
setTextDirection(sTextDirection): sap.m.Select

Sets a new value for property textDirection.

Specifies the direction of the text within the input field with enumerated options. By default, the control inherits text direction from the DOM.

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

Default value is Inherit.

Parameters:
sap.ui.core.TextDirectionsTextDirectionNew value for property textDirection
Returns:
sap.m.SelectReference to this in order to allow method chaining
Since:
1.28
setType(sType): sap.m.Select

Sets a new value for property type.

Type of a select. Possible values Default, IconOnly.

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

Default value is Default.

Parameters:
sap.m.SelectTypesTypeNew value for property type
Returns:
sap.m.SelectReference to this in order to allow method chaining
Since:
1.16
setValueState(sValueState): sap.m.Select

Sets a new value for property valueState.

Visualizes the validation state of the control, e.g. Error, Warning, Success.

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

Default value is None.

Parameters:
sap.ui.core.ValueStatesValueStateNew value for property valueState
Returns:
sap.m.SelectReference to this in order to allow method chaining
Since:
1.40.2
setValueStateText(sValueStateText): sap.m.Select

Sets a new value for property valueStateText.

Defines the text of the value state message popup. If this is not specified, a default text is shown from the resource bundle.

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

Default value is .

Parameters:
stringsValueStateTextNew value for property valueStateText
Returns:
sap.m.SelectReference to this in order to allow method chaining
Since:
1.40.5
setWidth(sWidth): sap.m.Select

Sets a new value for property width.

Sets the width of the field. By default, the field width is automatically adjusted to the size of its content and the default width of the field is calculated based on the widest list item in the dropdown list. If the width defined is smaller than its content, only the field width is changed whereas the dropdown list keeps the width of its content. If the dropdown list is wider than the visual viewport, it is truncated and an ellipsis is displayed for each item. For phones, the width of the dropdown list is always the same as the viewport.

Note: This property is ignored if the autoAdjustWidth property is set to true.

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

Default value is auto.

Parameters:
sap.ui.core.CSSSizesWidthNew value for property width
Returns:
sap.m.SelectReference to this in order to allow method chaining
unbindItems(): sap.m.Select
Unbinds aggregation items from model data.
Returns:
sap.m.SelectReference to this in order to allow method chaining