abstract class sap.m.ComboBoxBase

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

An abstract class for combo boxes.

This control can be a drop target.

Constructor

Constructor for a new sap.m.ComboBoxBase.

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.ComboBoxBase(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
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

Borrowed Properties

Name Type Default Value Description
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: items

Name Cardinality Type Description
items (default) 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.

picker 0..1 sap.ui.core.PopupInterface

Internal aggregation to hold the inner picker popup.

Borrowed Aggregations

Name Cardinality Type Description
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.


Events Overview

Event Description
loadItems

This event is fired when the end user clicks the combo box button to open the dropdown list and the data used to display items is not already loaded. Alternatively, it is fired after the user moves the cursor to the combo box text field and perform an action that requires data to be loaded. For example, pressing F4 to open the dropdown list or typing something in the text field fires the event.

Note: Use this feature in performance critical scenarios only. Loading the data lazily (on demand) to defer initialization has several implications for the end user experience. For example, the busy indicator has to be shown while the items are being loaded and assistive technology software also has to announce the state changes (which may be confusing for some screen reader users).

Note: Currently the sap.m.MultiComboBox does not support this event.

Since: 1.38.

loadItems

This event is fired when the end user clicks the combo box button to open the dropdown list and the data used to display items is not already loaded. Alternatively, it is fired after the user moves the cursor to the combo box text field and perform an action that requires data to be loaded. For example, pressing F4 to open the dropdown list or typing something in the text field fires the event.

Note: Use this feature in performance critical scenarios only. Loading the data lazily (on demand) to defer initialization has several implications for the end user experience. For example, the busy indicator has to be shown while the items are being loaded and assistive technology software also has to announce the state changes (which may be confusing for some screen reader users).

Note: Currently the sap.m.MultiComboBox does not support this event.

Since: 1.38.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object

Methods Overview

Method Description
_decoratePopupInput

Decorates the Input

_getGroupHeaderInvisibleText

Gets the ID of the hidden label for the group header items

addItem

Adds some item to the aggregation items.

applyShowItemsFilters

Should be overwritten in children classes to apply control specific filtering over the items.

attachLoadItems

Attaches event handler fnFunction to the loadItems event of this sap.m.ComboBoxBase.

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

This event is fired when the end user clicks the combo box button to open the dropdown list and the data used to display items is not already loaded. Alternatively, it is fired after the user moves the cursor to the combo box text field and perform an action that requires data to be loaded. For example, pressing F4 to open the dropdown list or typing something in the text field fires the event.

Note: Use this feature in performance critical scenarios only. Loading the data lazily (on demand) to defer initialization has several implications for the end user experience. For example, the busy indicator has to be shown while the items are being loaded and assistive technology software also has to announce the state changes (which may be confusing for some screen reader users).

Note: Currently the sap.m.MultiComboBox does not support this event.

bindItems

Binds aggregation items to model data.

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

clearSelection

Clears the selection. To be overwritten by subclasses.

close

Closes the control's picker popup.

configPicker

Base method for picker configuration

createPicker

Creates a picker popup container where the selection should take place. To be overwritten by subclasses.

destroyItems

Destroys all the items in the aggregation items.

detachLoadItems

Detaches event handler fnFunction from the loadItems event of this sap.m.ComboBoxBase.

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

sap.m.ComboBoxBase.extend

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

fireLoadItems

Fires event loadItems to attached listeners.

getEnabledItems

Gets the enabled items from the aggregation named items.

Since 1.86 The enabled items should be managed by the application.
getFirstItem

Gets the first item from the aggregation named items.

getInputForwardableProperties

Gets the input properties, which should be forwarded from the combobox text field to the picker text field

getItemAt

Gets the item from the aggregation named items at the given 0-based index.

getItemByKey

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.

getItems

Gets content of aggregation items.

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.

getLastItem

Gets the last item from the aggregation named items.

getList

Gets the list.

Since 1.62 The list structure should not be used as per SAP note: 2746748.
sap.m.ComboBoxBase.getMetadata

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

getOpen

Gets current value of property open.

Indicates whether the picker is opened.

Default value is false.

getPicker

Gets the control's picker popup.

getPickerInvisibleTextId

Gets the ID of the hidden label

getPickerTextField

Gets the control's input from the picker.

getPickerType

Gets the property _sPickerType

getRecreateItems

Gets the flag indicating whether the list items should be recreated

getShowSecondaryValues

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.

handleItemInsertion

Fires when an object gets inserted in the items aggregation

handleItemRemoval

Fires when an object gets removed from the items aggregation

hasContent

Determines whether the control has content or not.

highlightList

Handles highlighting of items after filtering.

indexOfItem

Checks for the provided sap.ui.core.Item in the aggregation items. and returns its index if found or -1 otherwise.

insertItem

Inserts a item into the aggregation items.

intersectItems

Finds the common items of two arrays

isOpen

Indicates whether the control's picker popup is open.

oncompositionend

Called when the composition of a passage of text has been completed or cancelled.

onItemChange

Handles properties' changes of items in the aggregation named items.

open

Opens the control's picker popup.

removeAllItems

Removes all the controls from the aggregation items.

Additionally, it unregisters them from the hosting UIArea.

removeItem

Removes a item from the aggregation items.

setFilterFunction

Sets a custom filter function for items. The function accepts two parameters: - currenly typed value in the input field - item to be matched The function should return a Boolean value (true or false) which represents whether an item will be shown in the dropdown or not.

setOpen

Sets a new value for property open.

Indicates whether the picker is opened.

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

Default value is false.

setPickerType

Sets the property _sPickerType.

setRecreateItems

Sets whether the list items should be recreated

setSelectable

Sets the selectable property of sap.ui.core.Item

setShowSecondaryValues

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.

setTextFieldHandler

Sets the TextField handler

showItems

Opens the SuggestionsPopover with the available items.

syncPickerContent

Creates picker if doesn't exist yet and sync with Control items To be overwritten by subclasses.

unbindItems

Unbinds aggregation items from model data.

_decoratePopupInput

Decorates the Input

Param Type DefaultValue Description
oInput sap.m.InputBase

_getGroupHeaderInvisibleText

Gets the ID of the hidden label for the group header items

addItem

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

applyShowItemsFilters

Should be overwritten in children classes to apply control specific filtering over the items.

attachLoadItems

Attaches event handler fnFunction to the loadItems event of this sap.m.ComboBoxBase.

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

This event is fired when the end user clicks the combo box button to open the dropdown list and the data used to display items is not already loaded. Alternatively, it is fired after the user moves the cursor to the combo box text field and perform an action that requires data to be loaded. For example, pressing F4 to open the dropdown list or typing something in the text field fires the event.

Note: Use this feature in performance critical scenarios only. Loading the data lazily (on demand) to defer initialization has several implications for the end user experience. For example, the busy indicator has to be shown while the items are being loaded and assistive technology software also has to announce the state changes (which may be confusing for some screen reader users).

Note: Currently the sap.m.MultiComboBox does not support this event.

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

bindItems

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

clearSelection

Clears the selection. To be overwritten by subclasses.

close

Closes the control's picker popup.

configPicker

Base method for picker configuration

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

Picker instance

createPicker

Creates a picker popup container where the selection should take place. To be overwritten by subclasses.

Param Type DefaultValue Description
sPickerType string

The picker type

destroyItems

Destroys all the items in the aggregation items.

detachLoadItems

Detaches event handler fnFunction from the loadItems event of this sap.m.ComboBoxBase.

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.ComboBoxBase.extend

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

fireLoadItems

Fires event loadItems to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

getEnabledItems

Gets the enabled items from the aggregation named items.

Since 1.86 The enabled items should be managed by the application.
Param Type DefaultValue Description
aItems sap.ui.core.Item[] getItems()

Items to filter.

getFirstItem

Gets the first item from the aggregation named items.

getInputForwardableProperties

Gets the input properties, which should be forwarded from the combobox text field to the picker text field

getItemAt

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.

getItemByKey

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.

Param Type DefaultValue Description
sKey string

An item key that specifies the item to retrieve.

getItems

Gets content of aggregation items.

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.

getLastItem

Gets the last item from the aggregation named items.

getList

Gets the list.

Since 1.62 The list structure should not be used as per SAP note: 2746748.

sap.m.ComboBoxBase.getMetadata

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

getOpen

Gets current value of property open.

Indicates whether the picker is opened.

Default value is false.

getPicker

Gets the control's picker popup.

getPickerInvisibleTextId

Gets the ID of the hidden label

getPickerTextField

Gets the control's input from the picker.

getPickerType

Gets the property _sPickerType

getRecreateItems

Gets the flag indicating whether the list items should be recreated

getShowSecondaryValues

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.

handleItemInsertion

Fires when an object gets inserted in the items aggregation

handleItemRemoval

Fires when an object gets removed from the items aggregation

hasContent

Determines whether the control has content or not.

highlightList

Handles highlighting of items after filtering.

Param Type DefaultValue Description
sValue string

The value of the item

indexOfItem

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

insertItem

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

intersectItems

Finds the common items of two arrays

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

Array of Items

aOtherItems sap.ui.core.Item[]

Second array of items

isOpen

Indicates whether the control's picker popup is open.

oncompositionend

Called when the composition of a passage of text has been completed or cancelled.

Param Type DefaultValue Description
oEvent jQuery.Event

The event object.

onItemChange

Handles properties' changes of items in the aggregation named items.

Param Type DefaultValue Description
oControlEvent sap.ui.base.Event

The change event

bShowSecondaryValues boolean

Indicates whether second values should be shown

open

Opens the control's picker popup.

removeAllItems

Removes all the controls from the aggregation items.

Additionally, it unregisters them from the hosting UIArea.

removeItem

Removes a item from the aggregation items.

Param Type DefaultValue Description
vItem int string sap.ui.core.Item

The item to remove or its index or id

setFilterFunction

Sets a custom filter function for items. The function accepts two parameters: - currenly typed value in the input field - item to be matched The function should return a Boolean value (true or false) which represents whether an item will be shown in the dropdown or not.

Param Type DefaultValue Description
fnFilter function

A callback function called when typing in a ComboBoxBase control or ancestor.

setOpen

Sets a new value for property open.

Indicates whether the picker is opened.

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
bOpen boolean false

New value for property open

setPickerType

Sets the property _sPickerType.

Param Type DefaultValue Description
sPickerType string

The picker type

setRecreateItems

Sets whether the list items should be recreated

setSelectable

Sets the selectable property of sap.ui.core.Item

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

The item to set the property

bSelectable boolean

The selectable value

setShowSecondaryValues

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 showSecondaryValues

setTextFieldHandler

Sets the TextField handler

Param Type DefaultValue Description
oTextField sap.m.ComboBoxTextField sap.m.Input

Text field instance

showItems

Opens the SuggestionsPopover with the available items.

Param Type DefaultValue Description
fnFilter function

Function to filter the items shown in the SuggestionsPopover

syncPickerContent

Creates picker if doesn't exist yet and sync with Control items To be overwritten by subclasses.

unbindItems

Unbinds aggregation items from model data.