class sap.ui.commons.ComboBox

Control sample: sap.ui.commons.ComboBox
Visiblity: public
UX Guidelines:
Implements: sap.ui.commons.ToolbarItem
Available since: N/A
Module: sap/ui/commons/ComboBox
Application Component: CA-UI5-CTR

The control provides a field that allows end users to either enter some text, or to choose an entry out of a list of pre-defined items. The choosable items can be provided in the form of a complete ListBox, single ListItems.


Constructor

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.ui.commons.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


Properties

Name Type Default Value Description
displaySecondaryValues boolean false

Indicates whether the additionalText property that is available for sap.ui.core.ListItem shall be displayed in the list.

Visibility: public
maxPopupItems int 10

Defines the number of items that shall be displayed at once. If the overall number of items is higher than this setting, a scrollbar is provided.

Visibility: public
selectedItemId string

Id of the selected item. If the value has no corresponding item, the selectedItemId is empty.

If the selectedItemId is set to a not existing item, it will not be changed.

Visibility: public
selectedKey string

Key of the selected item.

If the value has no corresponding item the key is empty.

If duplicate keys exists the first item matching the key is used.

If the key is set to a not existing value it will not be changed.

Visibility: public

Borrowed Properties

Name Type Default Value Description
accessibleRole sap.ui.core.AccessibleRole Textbox

Accessibility role for the text field.

Visibility: public
design sap.ui.core.Design Standard

Font type. valid values are Standard and Monospace.

Visibility: public
editable boolean true

Switches edit state of the control. Read-only fields have different colors, depending on theme setting.

Visibility: public
enabled boolean true

Switches enabled state of the control. Disabled fields have different colors, and can not be focused.

Visibility: public
helpId string empty string

Unique identifier used for help service.

Visibility: public
imeMode sap.ui.core.ImeMode Auto

State of the Input Method Editor (IME).

Visibility: public
maxLength int 0

Maximum number of characters. Value '0' means the feature is switched off.

Visibility: public
name string

The name property to be used in the HTML code (e.g. for HTML forms that send data to the server via 'submit').

Visibility: public
placeholder string

Placeholder for the text field.

Since: 1.14.0.

Visibility: public
required boolean false

Depending on theme the TextField is shown as required. If a Label is assigned to the TextField it will visualize the requires state too.

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

Sets the horizontal alignment of the text.

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

Direction of the text. Possible values: "rtl", "ltr".

Visibility: public
value string empty string

Text inside the TextField

Visibility: public
valueState sap.ui.core.ValueState None

Visualizes warnings or errors related to the text field. Possible values: Warning, Error, Success.

Visibility: public
width sap.ui.core.CSSSize

Width of text field. When it is set (CSS-size such as % or px), this is the exact size. When left blank, the text field length defines the width.

Visibility: public

Aggregations

Default Aggregation: items

Name Cardinality Type Description
items (default) 0..n sap.ui.core.ListItem

ListItems (see sap.ui.core.ListBox) that shall be displayed in the list.

myListBox 0..1 sap.ui.commons.ListBox

The hidden ListBox which is only used when no shared ListBox is set via association listBox


Associations

Name Cardinality Type Description
listBox 0..1 sap.ui.commons.ListBox

Using this method, you provide a ListBox control. This allows reuse of item lists in different controls. Either a control id can be used as new target, or a control instance.

Note: The ListBox must not be rendered somewhere in the UI. But if you want to bind the ListBox items to a model it must be in the control tree. So we suggest to add it as dependent somewhere (e.g. to the view or the first used ComboBox). If it is not set as child or dependant to an other control it will be automatically set as dependent to the first ComboBox where it is assigned.


Events Overview

Event Description
change

Event is fired when the text in the field has changed AND the focus leaves the ComboBox or the Enter key is pressed.

change

Event is fired when the text in the field has changed AND the focus leaves the ComboBox or the Enter key is pressed.

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

The new / changed value of the ComboBox.

selectedItem sap.ui.core.ListItem

The new / changed item of the ComboBox.


Methods Overview

Method Description
_checkChange

Compares the previous value with the current value and fires the "Change" event if the ComboBox is editable and the value has changed or whether the value has been changed e.g. via up/down or auto-complete feature

addItem

Adds some item to the aggregation items.

bindItems

Binds aggregation items to model data.

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

destroyItems

Destroys all the items in the aggregation items.

sap.ui.commons.ComboBox.extend

Creates a new subclass of class sap.ui.commons.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.ui.commons.TextField.extend.

fireChange

Fire event change to attached listeners.

Expects following event parameters:

  • 'newValue' of type string The new / changed value of the textfield.
  • 'selectedItem' of type sap.ui.core.ListItem selected item

getAccessibilityInfo

References:

  • sap.ui.core.Control#getAccessibilityInfo

getDisplaySecondaryValues

Gets current value of property displaySecondaryValues.

Indicates whether the additionalText property that is available for sap.ui.core.ListItem shall be displayed in the list.

Default value is false.

getF4ButtonDomRef

Returns the DomRef which represents the icon for value help. Could be overwritten in child-classes

getItems

Gets content of aggregation items.

ListItems (see sap.ui.core.ListBox) that shall be displayed in the list.

getListBox

ID of the element which is the current target of the association listBox, or null.

getMaxPopupItems

Gets current value of property maxPopupItems.

Defines the number of items that shall be displayed at once. If the overall number of items is higher than this setting, a scrollbar is provided.

Default value is 10.

sap.ui.commons.ComboBox.getMetadata

Returns a metadata object for class sap.ui.commons.ComboBox.

getSelectedItemId

Gets current value of property selectedItemId.

Id of the selected item. If the value has no corresponding item, the selectedItemId is empty.

If the selectedItemId is set to a not existing item, it will not be changed.

getSelectedKey

Gets current value of property selectedKey.

Key of the selected item.

If the value has no corresponding item the key is empty.

If duplicate keys exists the first item matching the key is used.

If the key is set to a not existing value it will not be changed.

indexOfItem

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

insertItem

Inserts a item into the aggregation items.

onsapenter

Handle sapenter pseudo events on the control

onsapescape

Handle sapescape pseudo events on the control

onsaphide

Handle saphide pseudo events on the control

onsapnextmodifiers

Handle sapnextmodifiers pseudo events on the control if in toolbar prevent item navigation if popup is opened.

onsapshow

Handle sapshow pseudo events on the control

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.

setDisplaySecondaryValues

Sets a new value for property displaySecondaryValues.

Indicates whether the additionalText property that is available for sap.ui.core.ListItem shall be displayed in the list.

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

Default value is false.

setListBox

Sets the associated listBox.

setMaxPopupItems

Sets a new value for property maxPopupItems.

Defines the number of items that shall be displayed at once. If the overall number of items is higher than this setting, a scrollbar is provided.

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

Default value is 10.

setSelectedItemId

Sets a new value for property selectedItemId.

Id of the selected item. If the value has no corresponding item, the selectedItemId is empty.

If the selectedItemId is set to a not existing item, it will not be changed.

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

setSelectedKey

Sets a new value for property selectedKey.

Key of the selected item.

If the value has no corresponding item the key is empty.

If duplicate keys exists the first item matching the key is used.

If the key is set to a not existing value it will not be changed.

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

unbindItems

Unbinds aggregation items from model data.

_checkChange

Compares the previous value with the current value and fires the "Change" event if the ComboBox is editable and the value has changed or whether the value has been changed e.g. via up/down or auto-complete feature

Param Type DefaultValue Description
oEvent jQuery.Event

The event object.

bImmediate boolean

indicate whether the check should happen immediately or delayed (e.g. to avoid focusout / click double event processing)

addItem

Adds some item to the aggregation items.

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

The item to add; if empty, nothing is inserted

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

destroyItems

Destroys all the items in the aggregation items.

sap.ui.commons.ComboBox.extend

Creates a new subclass of class sap.ui.commons.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.ui.commons.TextField.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

fireChange

Fire event change to attached listeners.

Expects following event parameters:

Param Type DefaultValue Description
mArguments object

the arguments to pass along with the event.

getAccessibilityInfo

References:

getDisplaySecondaryValues

Gets current value of property displaySecondaryValues.

Indicates whether the additionalText property that is available for sap.ui.core.ListItem shall be displayed in the list.

Default value is false.

getF4ButtonDomRef

Returns the DomRef which represents the icon for value help. Could be overwritten in child-classes

getItems

Gets content of aggregation items.

ListItems (see sap.ui.core.ListBox) that shall be displayed in the list.

getListBox

ID of the element which is the current target of the association listBox, or null.

getMaxPopupItems

Gets current value of property maxPopupItems.

Defines the number of items that shall be displayed at once. If the overall number of items is higher than this setting, a scrollbar is provided.

Default value is 10.

sap.ui.commons.ComboBox.getMetadata

Returns a metadata object for class sap.ui.commons.ComboBox.

getSelectedItemId

Gets current value of property selectedItemId.

Id of the selected item. If the value has no corresponding item, the selectedItemId is empty.

If the selectedItemId is set to a not existing item, it will not be changed.

getSelectedKey

Gets current value of property selectedKey.

Key of the selected item.

If the value has no corresponding item the key is empty.

If duplicate keys exists the first item matching the key is used.

If the key is set to a not existing value it will not be changed.

indexOfItem

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

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

The item whose index is looked for

insertItem

Inserts a item into the aggregation items.

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

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

onsapenter

Handle sapenter pseudo events on the control

Param Type DefaultValue Description
oEvent jQuery.Event

The event object.

onsapescape

Handle sapescape pseudo events on the control

Param Type DefaultValue Description
oEvent jQuery.Event

The event object.

onsaphide

Handle saphide pseudo events on the control

Param Type DefaultValue Description
oEvent jQuery.Event

The event object.

onsapnextmodifiers

Handle sapnextmodifiers pseudo events on the control if in toolbar prevent item navigation if popup is opened.

Param Type DefaultValue Description
oEvent jQuery.Event

The event object.

onsapshow

Handle sapshow pseudo events on the control

Param Type DefaultValue Description
oEvent jQuery.Event

The event object.

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

The item to remove or its index or id

setDisplaySecondaryValues

Sets a new value for property displaySecondaryValues.

Indicates whether the additionalText property that is available for sap.ui.core.ListItem shall be displayed in the list.

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

New value for property displaySecondaryValues

setListBox

Sets the associated listBox.

Param Type DefaultValue Description
oListBox sap.ui.core.ID sap.ui.commons.ListBox

ID of an element which becomes the new target of this listBox association; alternatively, an element instance may be given

setMaxPopupItems

Sets a new value for property maxPopupItems.

Defines the number of items that shall be displayed at once. If the overall number of items is higher than this setting, a scrollbar is provided.

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

Default value is 10.

Param Type DefaultValue Description
iMaxPopupItems int 10

New value for property maxPopupItems

setSelectedItemId

Sets a new value for property selectedItemId.

Id of the selected item. If the value has no corresponding item, the selectedItemId is empty.

If the selectedItemId is set to a not existing item, it will not be changed.

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

Param Type DefaultValue Description
sSelectedItemId string

New value for property selectedItemId

setSelectedKey

Sets a new value for property selectedKey.

Key of the selected item.

If the value has no corresponding item the key is empty.

If duplicate keys exists the first item matching the key is used.

If the key is set to a not existing value it will not be changed.

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

Param Type DefaultValue Description
sSelectedKey string

New value for property selectedKey

unbindItems

Unbinds aggregation items from model data.