class sap.m.MultiComboBox

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

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.

Overview

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.

Structure

The MultiComboBox consists of the following elements:

Usage

When to use:

When not to use:

Responsive Behavior

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:

On Tablets: On Desktop:

This control can be a drop target.

Constructor

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


Properties

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

Borrowed Properties

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 additionalText property of a sap.ui.core.ListItem are shown.

Since: 1.60.

Visibility: public
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.

Since: 1.38.

Visibility: public
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.

Since: 1.12.0.

Visibility: public
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 labelFor of sap.m.Label) cannot be established (e.g. one label should label multiple fields).

Since: 1.38.4.

Visibility: public
showValueStateMessage boolean true

Indicates whether the value state message should be shown or not.

Since: 1.26.0.

Visibility: public
textAlign sap.ui.core.TextAlign Initial

Defines the horizontal alignment of the text that is shown inside the input field.

Since: 1.26.0.

Visibility: public
textDirection sap.ui.core.TextDirection Inherit

Defines the text directionality of the input field, e.g. RTL, LTR

Since: 1.28.0.

Visibility: public
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. Error, Warning, Success.

Visibility: public
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.

Since: 1.26.0.

Visibility: public
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

Aggregations

Default Aggregation:

Name Cardinality Type Description
tokenizer 0..1 sap.m.Tokenizer

The tokenizer which displays the tokens

Borrowed Aggregations

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 valueStateText and formattedValueStateText are set - the latter is shown.

Since: 1.78.


Associations

Name Cardinality Type Description
selectedItems 0..n sap.ui.core.Item

Provides getter and setter for the selected items from the aggregation named items.


Events Overview

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.

selectionChange

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.

selectionFinish

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.


Methods Overview

Method Description
_decoratePopupInput

Modifies the suggestions dialog input

addSelectedItem

Adds some item oItem to the association named selectedItems.

addSelectedKeys

Adds selected items. Only items with valid keys are added as selected.

applyShowItemsFilters

Applies MultiComboBox specific filtering over the list items. Called within showItems method.

attachSelectionChange

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

attachSelectionFinish

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.

clone

Clones the sap.m.MultiComboBox control.

configPicker

MultiComboBox picker configuration

destroyItems

Destroys all the items in the aggregation named items.

detachSelectionChange

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.

detachSelectionFinish

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.

sap.m.MultiComboBox.extend

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.

fireSelectionChange

Fires event selectionChange to attached listeners.

fireSelectionFinish

Fires event selectionFinish to attached listeners.

getAccessibilityInfo

Gets the accessibility info for the control

References:

  • sap.ui.core.Control#getAccessibilityInfo

sap.m.MultiComboBox.getMetadata

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

getSelectedItems

Retrieves the selected item objects from the association named selectedItems.

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 false.

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 selectedItems.

removeSelectedKeys

Removes selected items. Only items with valid keys are removed.

setSelectedItems

Setter for association selectedItems.

setSelectedKeys

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 [].

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 null or undefined, the default value of the property will be restored.

Default value is false.

syncPickerContent

Creates picker if doesn't exist yet and sync with Control items

_decoratePopupInput

Modifies the suggestions dialog input

Param Type DefaultValue Description
oInput sap.m.Input

The input

addSelectedItem

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.

addSelectedKeys

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

applyShowItemsFilters

Applies MultiComboBox specific filtering over the list items. Called within showItems method.

attachSelectionChange

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 sap.m.MultiComboBox itself

attachSelectionFinish

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 sap.m.MultiComboBox itself

clone

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.

configPicker

MultiComboBox picker configuration

Param Type DefaultValue Description
oPicker sap.m.Popover sap.m.Dialog

Picker instance

destroyItems

Destroys all the items in the aggregation named items.

detachSelectionChange

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

detachSelectionFinish

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

sap.m.MultiComboBox.extend

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

fireSelectionChange

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.

fireSelectionFinish

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.

getAccessibilityInfo

Gets the accessibility info for the control

References:

sap.m.MultiComboBox.getMetadata

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

getSelectedItems

Retrieves the selected item objects from the association named selectedItems.

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 false.

isItemSelected

Checks whether an item is selected.

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

The item to check.

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.

Param Type DefaultValue Description
oEvent undefined

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 selectedItems.

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

The item to be removed

removeSelectedKeys

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

setSelectedItems

Setter for association selectedItems.

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

new values for association selectedItems. Array of sap.ui.core.Item Id which becomes the new target of this selectedItems association. Alternatively, an array of sap.ui.core.Item instance may be given or null.

setSelectedKeys

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

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 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 showSelectAll

syncPickerContent

Creates picker if doesn't exist yet and sync with Control items

Param Type DefaultValue Description
bForceListSync boolean

Force MultiComboBox to SuggestionPopover sync