An abstract class for combo boxes.
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. |
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 |
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. |
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: 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. |
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 |
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 |
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 |
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 When called, the context of the event handler (its 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 |
bindItems |
Binds aggregation items to model data. See ManagedObject.bindAggregation for a detailed description of the possible properties of |
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 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
|
fireLoadItems |
Fires event loadItems to attached listeners. |
getEnabledItems |
Gets the enabled items from the aggregation named
Since 1.86 The enabled items should be managed by the application.
|
getFirstItem |
Gets the first item from the aggregation named |
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 |
getItemByKey |
Gets the item with the given key from the aggregation named |
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 |
getList |
Gets the
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 |
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 |
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 Default value is |
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 |
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 |
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 Default value is |
setPickerType |
Sets the property |
setRecreateItems |
Sets whether the list items should be recreated |
setSelectable |
Sets the selectable property of |
setShowSecondaryValues |
Sets a new value for property showSecondaryValues. Indicates whether the text values of the When called with a value of Default value is |
setTextFieldHandler |
Sets the TextField handler |
showItems |
Opens the |
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. |
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 |
Should be overwritten in children classes to apply control specific filtering over the items.
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 |
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 |
Base method for picker configuration
Param | Type | DefaultValue | Description |
---|---|---|---|
oPicker | sap.m.Popover sap.m.Dialog |
Picker instance |
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 |
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 |
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 |
Fires event loadItems to attached listeners.
Param | Type | DefaultValue | Description |
---|---|---|---|
mParameters | object |
Parameters to pass along with the event |
Gets the enabled items from the aggregation named items
.
Param | Type | DefaultValue | Description |
---|---|---|---|
aItems | sap.ui.core.Item[] | getItems() |
Items to filter. |
Gets the input properties, which should be forwarded from the combobox text field to the picker text field
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. |
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. |
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.
Gets current value of property open.
Indicates whether the picker is opened.
Default value is false
.
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
.
Handles highlighting of items after filtering.
Param | Type | DefaultValue | Description |
---|---|---|---|
sValue | string |
The value of the item |
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 |
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 |
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 |
Called when the composition of a passage of text has been completed or cancelled.
Param | Type | DefaultValue | Description |
---|---|---|---|
oEvent | jQuery.Event |
The event object. |
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 |
Removes all the controls from the aggregation items.
Additionally, it unregisters them from the hosting UIArea.
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 |
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. |
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 |
Sets the property _sPickerType
.
Param | Type | DefaultValue | Description |
---|---|---|---|
sPickerType | string |
The picker type |
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 |
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 |
Sets the TextField handler
Param | Type | DefaultValue | Description |
---|---|---|---|
oTextField | sap.m.ComboBoxTextField sap.m.Input |
Text field instance |
Opens the SuggestionsPopover
with the available items.
Param | Type | DefaultValue | Description |
---|---|---|---|
fnFilter | function |
Function to filter the items shown in the SuggestionsPopover |