A drop-down list for selecting and filtering values.
The control represents a drop-down menu with a list of the available options and a text input field to narrow down the options.
The combo-box consists of the following elements:
items
aggregation.showSecondaryValues
property, the combo box can display an additional value for each option (if there is one). Note: The typeahead feature is not available on Android devices due to a OS specific issue.
The control has the following behavior regarding the selectedKey
and value
properties:
selectedKey
set which corresponds to a matching item, and a set value
, the value
will be updated to the matching item's text. selectedKey
is set and the user types an input which corresponds to an item's text, the selectedKey
will be updated with the matching item's key. selectedKey
is set and the user types an input which does not correspond to any item's text, the selectedKey
will be set to an empty string ("") selectedKey
is set and the user selects an item, the selectedKey
will be updated to match the selected item's key. selectedKey
is bound and the user types before the data is loaded, the user's input will be overwritten by the binding update.
sap.m.ComboBox
control allows free text, as well as has selectedKey
/ selectedItem
properties, here is brief explanation of how they are updated during model change:selectedKey
and selectedItem
set, the model changes and the item key is no longer amongst the newly added items, the value of the ComboBox will remain the same and the selectedKey
and selectedItem
properties will not be changed.selectedKey
and selectedItem
set, the model changes and the item key corresponds to newly added item, with different text, the value of the ComboBox will be updated with the text of the newly corresponding item.selectedKey
and selectedItem
set, the model changes, the value will remain the same and the selectedKey
and selectedItem
properties will not be changed.Constructor for a new ComboBox.
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.ComboBox(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 |
---|---|---|---|
filterSecondaryValues | boolean | false | Indicates whether the filter should check in both the |
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 |
Name | Type | Default Value | Description |
---|---|---|---|
open | boolean | false | Indicates whether the picker is opened. Visibility: public |
showSecondaryValues | boolean | false | Indicates whether the text values of the |
maxWidth | sap.ui.core.CSSSize | 100% | Sets the maximum width of the text field. Visibility: public |
showButton | boolean | true | Indicates whether the dropdown downward-facing arrow button is shown. |
editable | boolean | true | Defines whether the control can be modified by the user or not. Note: A user can tab to non-editable control, highlight it, and copy the text from it. |
enabled | boolean | true | Indicates whether the user can interact with the control or not. Note: Disabled controls cannot be focused and they are out of the tab-chain. Visibility: public |
name | string | The name to be used in the HTML code (for example, for HTML forms that send data to the server via submission). Visibility: public |
|
placeholder | string | Defines a short hint intended to aid the user with data entry when the control has no value. Visibility: public |
|
required | boolean | false | Indicates that user input is required. This property is only needed for accessibility purposes when a single relationship between the field and a label (see aggregation |
showValueStateMessage | boolean | true | Indicates whether the value state message should be shown or not. |
textAlign | sap.ui.core.TextAlign | Initial | Defines the horizontal alignment of the text that is shown inside the input field. |
textDirection | sap.ui.core.TextDirection | Inherit | Defines the text directionality of the input field, e.g. |
value | string | Defines the value of the control. Visibility: public |
|
valueState | sap.ui.core.ValueState | None | Visualizes the validation state of the control, e.g. |
valueStateText | string | Defines the text that appears in the value state message pop-up. If this is not specified, a default text is shown from the resource bundle. |
|
width | sap.ui.core.CSSSize | Defines the width of the control. Note: If the provided width is too small, the control gets stretched to its min width, which is needed in order for the control to be usable and well aligned. Visibility: public |
Name | Cardinality | Type | Description |
---|---|---|---|
items | 0..n | sap.ui.core.Item |
Defines the items contained within this control. Note: Disabled items are not visualized in the list with the available options, however they can still be accessed through the aggregation. |
formattedValueStateText | 0..1 | sap.m.FormattedText |
Defines the formatted text that appears in the value state message pop-up. It can include links. If both |
Name | Cardinality | Type | Description |
---|---|---|---|
selectedItem | 0..1 | sap.ui.core.Item |
Sets or retrieves the selected item from the aggregation named items. |
Event | Description |
---|---|
change |
This event is fired when the value in the text input field is changed in combination with one of the following actions:
|
selectionChange |
This event is fired when the user types something that matches with an item in the list; it is also fired when the user presses on a list item, or when navigating via keyboard. |
This event is fired when the value in the text input field is changed in combination with one of the following actions:
Param | Type | Description |
---|---|---|
oControlEvent | sap.ui.base.Event | |
getSource | sap.ui.base.EventProvider | |
getParameters | object | |
value | string |
The new |
itemPressed | boolean |
Indicates whether the change event was caused by selecting an item in the list |
This event is fired when the user types something that matches with an item in the list; it is also fired when the user presses on a list item, or when navigating via keyboard.
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 |
---|---|
_configureList |
Configures the SuggestionsPopover's list. |
_decoratePopupInput |
Modifies the suggestions dialog input |
applyShowItemsFilters |
Applies Combobox specific filtering over the list items. Called within showItems method. |
attachChange |
Attaches event handler When called, the context of the event handler (its This event is fired when the value in the text input field is changed in combination with one of the following actions:
|
attachSelectionChange |
Attaches event handler When called, the context of the event handler (its This event is fired when the user types something that matches with an item in the list; it is also fired when the user presses on a list item, or when navigating via keyboard. |
clearSelection |
Clears the selection. |
clone |
Clones the |
configPicker |
|
detachChange |
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. |
exit |
This method will be called when the ComboBox is being destroyed. |
sap.m.ComboBox.extend |
Creates a new subclass of class sap.m.ComboBox with name
|
fireChange |
Fires event change to attached listeners. |
fireSelectionChange |
Fires event selectionChange to attached listeners. |
getDefaultSelectedItem |
Gets the default selected item from the aggregation named |
getFilterSecondaryValues |
Gets current value of property filterSecondaryValues. Indicates whether the filter should check in both the Default value is |
sap.m.ComboBox.getMetadata |
Returns a metadata object for class sap.m.ComboBox. |
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 |
init |
This method will be called when the ComboBox is initially created. |
onAfterRenderingList |
This event handler will be called after the ComboBox Picker's List is rendered. |
onAfterRenderingPicker |
This event handler will be called after the ComboBox's Picker is rendered. |
onBeforeOpen |
This event handler is called before the picker popup is opened. |
onBeforeRendering |
This event handler will be called before the ComboBox is rendered. |
onBeforeRenderingDropdown |
This event handler will be called before the ComboBox' Picker of type |
onBeforeRenderingList |
This event handler will be called before the ComboBox Picker's List is rendered. |
onBeforeRenderingPicker |
This event handler will be called before the ComboBox's Picker is rendered. |
ontap |
Called when the |
open |
Opens the control's picker popup. |
selectText |
Sets the start and end positions of the current text selection. |
setFilterSecondaryValues |
Sets a new value for property filterSecondaryValues. Indicates whether the filter should check in both the When called with a value of Default value is |
setSelectedItem |
Sets the Default value is |
setSelectedItemId |
Sets the Default value is an empty string |
setSelectedKey |
Sets the Default value is an empty string |
synchronizeSelection |
Synchronizes the |
syncPickerContent |
Creates picker if doesn't exist yet and sync with Control items |
Configures the SuggestionsPopover's list.
Param | Type | DefaultValue | Description |
---|---|---|---|
oList | sap.m.List |
The list instance to be configured |
Modifies the suggestions dialog input
Param | Type | DefaultValue | Description |
---|---|---|---|
oInput | sap.m.Input |
The input |
Applies Combobox specific filtering over the list items. Called within showItems method.
Attaches event handler fnFunction
to the change event of this sap.m.ComboBox
.
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.ComboBox
itself.
This event is fired when the value in the text input field is changed in combination with one of the following actions:
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.ComboBox
.
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.ComboBox
itself.
This event is fired when the user types something that matches with an item in the list; it is also fired when the user presses on a list item, or when navigating via keyboard.
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 |
Clones the sap.m.ComboBox
control.
Param | Type | DefaultValue | Description |
---|---|---|---|
sIdSuffix | string |
Suffix to be added to the IDs of the new control and its internal objects. |
ComboBox
picker configuration
Param | Type | DefaultValue | Description |
---|---|---|---|
oPicker | sap.m.Popover sap.m.Dialog |
Picker instance |
Detaches event handler fnFunction
from the change event of this sap.m.ComboBox
.
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.ComboBox
.
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.ComboBox with name sClassName
and enriches it with the information contained in oClassInfo
.
oClassInfo
might contain the same kind of information as described in sap.m.ComboBoxBase.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 change to attached listeners.
Param | Type | DefaultValue | Description |
---|---|---|---|
mParameters | object |
Parameters to pass along with the event |
|
value | string |
The new |
|
itemPressed | boolean |
Indicates whether the change event was caused by selecting an item in the list |
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. |
Gets current value of property filterSecondaryValues.
Indicates whether the filter should check in both the text
and the additionalText
property of the sap.ui.core.ListItem for the suggestion.
Default value is false
.
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
.
This event handler will be called after the ComboBox Picker's List is rendered.
This event handler will be called before the ComboBox' Picker of type sap.m.Popover
is rendered.
This event handler will be called before the ComboBox Picker's List is rendered.
Called when the ComboBox
is clicked or tapped.
Param | Type | DefaultValue | Description |
---|---|---|---|
oEvent | jQuery.Event |
The event object. |
Sets the start and end positions of the current text selection.
Param | Type | DefaultValue | Description |
---|---|---|---|
iSelectionStart | int |
The index of the first selected character. |
|
iSelectionEnd | int |
The index of the character after the last selected character. |
Sets a new value for property filterSecondaryValues.
Indicates whether the filter should check in both the text
and the additionalText
property of the sap.ui.core.ListItem for the suggestion.
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 |
---|---|---|---|
bFilterSecondaryValues | boolean | false |
New value for property |
Sets the selectedItem
association.
Default value is null
.
Param | Type | DefaultValue | Description |
---|---|---|---|
vItem | string sap.ui.core.Item null |
New value for the |
Sets the selectedItemId
property.
Default value is an empty string ""
or undefined
.
Param | Type | DefaultValue | Description |
---|---|---|---|
vItem | string undefined |
New value for property |
Sets the selectedKey
property.
Default value is an empty string ""
or undefined
.
Param | Type | DefaultValue | Description |
---|---|---|---|
sKey | string |
New value for property |