The MultiComboBox control provides a list box with items and a text field allowing the user to either type a value directly into the control or choose from the list of existing items.
A drop-down list for selecting and filtering values.
The MultiComboBox control is commonly used to enable users to select one or more options from a predefined list. The control provides an editable input field to filter the list, and a dropdown arrow of available options. The select options in the list have checkboxes that permit multi-selection. Entered values are displayed as tokens.
When an invalid character is typed into the text field of the MultiComboBox control, the value state is changed to sap.ui.core.ValueState.Error
only for a second, as the invalid value is immediately deleted from the input field.
The MultiComboBox consists of the following elements:
items
aggregation.
If there are many tokens, the control shows only the last selected tokens that fit and for the others a label N-more is provided. In case the length of the last selected token is exceeding the width of the control, only a label N-Items is shown. In both cases, pressing on the label will show the tokens in a popup. On Phones:
Constructor for a new MultiComboBox.
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.MultiComboBox(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 |
---|---|---|---|
hasSelection | boolean | false | Defines if there are selected items or not. Visibility: hidden |
selectedKeys | string[] | Keys of the selected items. If the key has no corresponding item, no changes will apply. If duplicate keys exists the first item matching the key is used. Visibility: public |
|
showSelectAll | boolean | false | Determines if the select all checkbox is visible on top of suggestions. 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 |
Default Aggregation:
Name | Cardinality | Type | Description |
---|---|---|---|
tokenizer | 0..1 | sap.m.Tokenizer |
The tokenizer which displays the tokens |
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 |
---|---|---|---|
selectedItems | 0..n | sap.ui.core.Item |
Provides getter and setter for the selected items from the aggregation named items. |
Event | Description |
---|---|
selectionChange |
Event is fired when selection of an item is changed. Note: please do not use the "change" event inherited from sap.m.InputBase |
selectionFinish |
Event is fired when user has finished a selection of items in a list box and list box has been closed. |
Event is fired when selection of an item is changed. Note: please do not use the "change" event inherited from sap.m.InputBase
Param | Type | Description |
---|---|---|
oControlEvent | sap.ui.base.Event | |
getSource | sap.ui.base.EventProvider | |
getParameters | object | |
changedItem | sap.ui.core.Item |
Item which selection is changed |
changedItems | sap.ui.core.Item[] |
Array of items whose selection has changed. |
selected | boolean |
Selection state: true if item is selected, false if item is not selected |
selectAll | boolean |
Indicates whether the select all action is triggered or not. |
Event is fired when user has finished a selection of items in a list box and list box has been closed.
Param | Type | Description |
---|---|---|
oControlEvent | sap.ui.base.Event | |
getSource | sap.ui.base.EventProvider | |
getParameters | object | |
selectedItems | sap.ui.core.Item[] |
The selected items which are selected after list box has been closed. |
Method | Description |
---|---|
_decoratePopupInput |
Modifies the suggestions dialog input |
addSelectedItem |
Adds some item |
addSelectedKeys |
Adds selected items. Only items with valid keys are added as selected. |
applyShowItemsFilters |
Applies |
attachSelectionChange |
Attaches event handler When called, the context of the event handler (its Event is fired when selection of an item is changed. Note: please do not use the "change" event inherited from sap.m.InputBase |
attachSelectionFinish |
Attaches event handler When called, the context of the event handler (its Event is fired when user has finished a selection of items in a list box and list box has been closed. |
clone |
Clones the |
configPicker |
|
destroyItems |
Destroys all the items in the aggregation named |
detachSelectionChange |
Detaches event handler The passed function and listener object must match the ones used for event registration. |
detachSelectionFinish |
Detaches event handler The passed function and listener object must match the ones used for event registration. |
sap.m.MultiComboBox.extend |
Creates a new subclass of class sap.m.MultiComboBox with name
|
fireSelectionChange |
Fires event selectionChange to attached listeners. |
fireSelectionFinish |
Fires event selectionFinish to attached listeners. |
getAccessibilityInfo |
Gets the accessibility info for the control
|
sap.m.MultiComboBox.getMetadata |
Returns a metadata object for class sap.m.MultiComboBox. |
getSelectedItems |
Retrieves the selected item objects from the association named |
getSelectedKeys |
Gets current value of property selectedKeys. Keys of the selected items. If the key has no corresponding item, no changes will apply. If duplicate keys exists the first item matching the key is used. Default value is |
getShowSelectAll |
Gets current value of property showSelectAll. Determines if the select all checkbox is visible on top of suggestions. Default value is |
isItemSelected |
Checks whether an item is selected. |
onAfterRenderingPicker |
This hook method is called after the MultiComboBox's Pop-up is rendered. |
onBeforeRendering |
This hook method is called before the MultiComboBox is rendered. |
onBeforeRenderingPicker |
This hook method is called before the MultiComboBox's Pop-up is rendered. |
onclick |
Handles control click event. |
open |
Opens the control's picker popup. |
removeAllSelectedItems |
Removes all the controls in the association named selectedItems. |
removeSelectedItem |
Removes an selectedItem from the association named |
removeSelectedKeys |
Removes selected items. Only items with valid keys are removed. |
setSelectedItems |
Setter for association |
setSelectedKeys |
Sets a new value for property |
setShowSelectAll |
Sets a new value for property showSelectAll. Determines if the select all checkbox is visible on top of suggestions. When called with a value of Default value is |
syncPickerContent |
Creates picker if doesn't exist yet and sync with Control items |
Modifies the suggestions dialog input
Param | Type | DefaultValue | Description |
---|---|---|---|
oInput | sap.m.Input |
The input |
Adds some item oItem
to the association named selectedItems
.
Param | Type | DefaultValue | Description |
---|---|---|---|
oItem | sap.ui.core.Item |
The selected item to add; if empty, nothing is added. |
Adds selected items. Only items with valid keys are added as selected.
Param | Type | DefaultValue | Description |
---|---|---|---|
aKeys | string[] |
An array of item keys that identifies the items to be added as selected |
Applies MultiComboBox
specific filtering over the list items. Called within showItems method.
Attaches event handler fnFunction
to the selectionChange event of this sap.m.MultiComboBox
.
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.MultiComboBox
itself.
Event is fired when selection of an item is changed. Note: please do not use the "change" event inherited from sap.m.InputBase
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 selectionFinish event of this sap.m.MultiComboBox
.
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.MultiComboBox
itself.
Event is fired when user has finished a selection of items in a list box and list box has been closed.
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.MultiComboBox
control.
Param | Type | DefaultValue | Description |
---|---|---|---|
sIdSuffix | string |
Suffix to be added to the ids of the new control and its internal objects. |
MultiComboBox
picker configuration
Param | Type | DefaultValue | Description |
---|---|---|---|
oPicker | sap.m.Popover sap.m.Dialog |
Picker instance |
Detaches event handler fnFunction
from the selectionChange event of this sap.m.MultiComboBox
.
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 selectionFinish event of this sap.m.MultiComboBox
.
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.MultiComboBox 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 selectionChange to attached listeners.
Param | Type | DefaultValue | Description |
---|---|---|---|
mParameters | object |
Parameters to pass along with the event |
|
changedItem | sap.ui.core.Item |
Item which selection is changed |
|
changedItems | sap.ui.core.Item[] |
Array of items whose selection has changed. |
|
selected | boolean |
Selection state: true if item is selected, false if item is not selected |
|
selectAll | boolean |
Indicates whether the select all action is triggered or not. |
Fires event selectionFinish to attached listeners.
Param | Type | DefaultValue | Description |
---|---|---|---|
mParameters | object |
Parameters to pass along with the event |
|
selectedItems | sap.ui.core.Item[] |
The selected items which are selected after list box has been closed. |
Gets the accessibility info for the control
References:
Gets current value of property selectedKeys.
Keys of the selected items. If the key has no corresponding item, no changes will apply. If duplicate keys exists the first item matching the key is used.
Default value is []
.
Gets current value of property showSelectAll.
Determines if the select all checkbox is visible on top of suggestions.
Default value is false
.
Checks whether an item is selected.
Param | Type | DefaultValue | Description |
---|---|---|---|
oItem | sap.ui.core.Item |
The item to check. |
Removes an selectedItem from the association named selectedItems
.
Param | Type | DefaultValue | Description |
---|---|---|---|
oItem | sap.ui.core.Item sap.ui.core.ID string |
The item to be removed |
Removes selected items. Only items with valid keys are removed.
Param | Type | DefaultValue | Description |
---|---|---|---|
aKeys | string[] |
An array of item keys that identifies the items to be removed |
Setter for association selectedItems
.
Param | Type | DefaultValue | Description |
---|---|---|---|
aItems | string[] sap.ui.core.Item[] null |
new values for association |
Sets a new value for property selectedKeys
. Keys of the selected items. If the key has no corresponding item, no changes will apply. If duplicate keys exists the first item matching the key is used. When called with a value of null or undefined, the default value of the property will be restored. Default value is [].
Param | Type | DefaultValue | Description |
---|---|---|---|
aKeys | string[] |
Keys of items to be set as selected |
Sets a new value for property showSelectAll.
Determines if the select all checkbox is visible on top of suggestions.
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 |
---|---|---|---|
bShowSelectAll | boolean | false |
New value for property |