Class sap.ui.commons.ComboBoxModule: sap/ui/commons/ComboBox

extends TextField
implements ToolbarItem
known direct subclasses: AutoComplete, DropdownBox

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.

Deprecated API:Since version 1.38. Instead, use the sap.m.ComboBox control.

Constructor Summary
new sap.ui.commons.ComboBox(sId?, mSettings?)Constructor for a new ComboBox.
Event Summary
change(oControlEvent)Event is fired when the text in the field has changed AND the focus leaves the ComboBox or the Enter key is pressed.
Events borrowed from class sap.ui.commons.TextField
liveChange
Events borrowed from class sap.ui.core.Control
validateFieldGroup
Events borrowed from class sap.ui.base.ManagedObject
formatError, modelContextChange, parseError, validationError, validationSuccess
Method Summary
sap.ui.commons.ComboBox.extend(sClassName, oClassInfo?, FNMetaImpl?)Creates a new subclass of class sap.ui.commons.ComboBox with name sClassName and enriches it with the information contained in oClassInfo.
sap.ui.commons.ComboBox.getMetadata()Returns a metadata object for class sap.ui.commons.ComboBox.
_checkChange(oEvent, bImmediate?)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.
addItem(oItem)Adds some item to the aggregation items.
bindItems(oBindingInfo)Binds aggregation items to model data.
destroyItems()Destroys all the items in the aggregation items.
fireChange(mArguments?)Fire event change to attached listeners.
getAccessibilityInfo()
getDisplaySecondaryValues()Gets current value of property displaySecondaryValues.
getF4ButtonDomRef()Returns the DomRef which represents the icon for value help.
getItems()Gets content of aggregation items.
getListBox()ID of the element which is the current target of the association listBox, or null.
getMaxPopupItems()Gets current value of property maxPopupItems.
getSelectedItemId()Gets current value of property selectedItemId.
getSelectedKey()Gets current value of property selectedKey.
indexOfItem(oItem)Checks for the provided sap.ui.core.ListItem in the aggregation items.
insertItem(oItem, iIndex)Inserts a item into the aggregation items.
onsapenter(oEvent)Handle sapenter pseudo events on the control
onsapescape(oEvent)Handle sapescape pseudo events on the control
onsaphide(oEvent)Handle saphide pseudo events on the control
onsapnextmodifiers(oEvent)Handle sapnextmodifiers pseudo events on the control if in toolbar prevent item navigation if popup is opened.
onsapshow(oEvent)Handle sapshow pseudo events on the control
removeAllItems()Removes all the controls from the aggregation items.
removeItem(vItem)Removes a item from the aggregation items.
setDisplaySecondaryValues(bDisplaySecondaryValues)Sets a new value for property displaySecondaryValues.
setListBox(oListBox)Sets the associated listBox.
setMaxPopupItems(iMaxPopupItems)Sets a new value for property maxPopupItems.
setSelectedItemId(sSelectedItemId)Sets a new value for property selectedItemId.
setSelectedKey(sSelectedKey)Sets a new value for property selectedKey.
unbindItems()Unbinds aggregation items from model data.
Methods borrowed from class sap.ui.commons.TextField
addAriaDescribedBy, addAriaLabelledBy, attachChange, attachLiveChange, bindValue, detachChange, detachLiveChange, fireLiveChange, getAccessibleRole, getAriaDescribedBy, getAriaLabelledBy, getDesign, getEditable, getEnabled, getFocusInfo, getHelpId, getImeMode, getInputDomRef, getLiveValue, getMaxLength, getName, getPlaceholder, getRequired, getTextAlign, getTextDirection, getValue, getValueState, getWidth, onfocusin, onkeyup, onsapfocusleave, onselectstart, removeAllAriaDescribedBy, removeAllAriaLabelledBy, removeAriaDescribedBy, removeAriaLabelledBy, setAccessibleRole, setDesign, setEditable, setEnabled, setHelpId, setImeMode, setMaxLength, setName, setPlaceholder, setRequired, setTextAlign, setTextDirection, setValue, setValueState, setWidth, unbindValue
Methods borrowed from class sap.ui.core.Control
addStyleClass, allowTextSelection, attachBrowserEvent, attachValidateFieldGroup, checkFieldGroupIds, clone, detachBrowserEvent, detachValidateFieldGroup, fireValidateFieldGroup, getBusy, getBusyIndicatorDelay, getControlsByFieldGroupId, getFieldGroupIds, getIdForLabel, getRenderer, getVisible, hasStyleClass, invalidate, isBusy, onAfterRendering, onBeforeRendering, placeAt, removeStyleClass, rerender, setBusy, setBusyIndicatorDelay, setFieldGroupIds, setVisible, toggleStyleClass, triggerValidateFieldGroup
Methods borrowed from class sap.ui.core.Element
$, addCustomData, addDependent, addEventDelegate, applyFocusInfo, bindElement, data, destroy, destroyCustomData, destroyDependents, destroyLayoutData, destroyTooltip, enhanceAccessibilityState, findElements, fireEvent, focus, getCustomData, getDependents, getDomRef, getElementBinding, getFocusDomRef, getInterface, getLayoutData, getMetadata, getTooltip, getTooltip_AsString, getTooltip_Text, indexOfCustomData, indexOfDependent, insertCustomData, insertDependent, prop, removeAllCustomData, removeAllDependents, removeCustomData, removeDependent, removeEventDelegate, setLayoutData, setTooltip, toString, unbindElement
Methods borrowed from class sap.ui.base.ManagedObject
addAggregation, addAssociation, applySettings, attachFormatError, attachModelContextChange, attachParseError, attachValidationError, attachValidationSuccess, bindAggregation, bindContext, bindObject, bindProperty, destroyAggregation, detachFormatError, detachModelContextChange, detachParseError, detachValidationError, detachValidationSuccess, findAggregatedObjects, fireFormatError, fireModelContextChange, fireParseError, fireValidationError, fireValidationSuccess, getAggregation, getAssociation, getBinding, getBindingContext, getBindingInfo, getBindingPath, getEventingParent, getId, getModel, getObjectBinding, getOriginInfo, getParent, getProperty, hasModel, indexOfAggregation, insertAggregation, isBound, isInvalidateSuppressed, isTreeBinding, propagateMessages, removeAggregation, removeAllAggregation, removeAllAssociation, removeAssociation, setAggregation, setAssociation, setBindingContext, setModel, setProperty, unbindAggregation, unbindContext, unbindObject, unbindProperty, validateAggregation, validateProperty
Methods borrowed from class sap.ui.base.EventProvider
attachEvent, attachEventOnce, detachEvent, hasListeners
Constructor Detail
new sap.ui.commons.ComboBox(sId?, mSettings?)
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 for a general description of the syntax of the settings object.

The supported settings are:

In addition, all settings applicable to the base type sap.ui.commons.TextField can be used as well.

Parameters:
{string}sId? Id for the new control, generated automatically if no id is given
{object}mSettings? Initial settings for the new control
Deprecated:
Since version 1.38. Instead, use the sap.m.ComboBox control.
Event Detail
change(oControlEvent)
Event is fired when the text in the field has changed AND the focus leaves the ComboBox or the Enter key is pressed.
Parameters:
{sap.ui.base.Event}oControlEvent
{sap.ui.base.EventProvider}oControlEvent.getSource
{object}oControlEvent.getParameters
{string}oControlEvent.getParameters.newValue The new / changed value of the ComboBox.
{sap.ui.core.ListItem}oControlEvent.getParameters.selectedItem The new / changed item of the ComboBox.
Method Detail
sap.ui.commons.ComboBox.extend(sClassName, oClassInfo?, FNMetaImpl?): function
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.

Parameters:
{string}sClassName Name of the class being created
{object}oClassInfo? Object literal with information about the class
{function}FNMetaImpl? Constructor function for the metadata object; if not given, it defaults to sap.ui.core.ElementMetadata
Returns:
{function} Created class / constructor function
sap.ui.commons.ComboBox.getMetadata(): sap.ui.base.Metadata
Returns a metadata object for class sap.ui.commons.ComboBox.
Returns:
{sap.ui.base.Metadata} Metadata object describing this class
_checkChange(oEvent, bImmediate?)
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
Parameters:
{jQuery.Event}oEvent The event object.
{boolean}bImmediate? indicate whether the check should happen immediately or delayed (e.g. to avoid focusout / click double event processing)
addItem(oItem): sap.ui.commons.ComboBox
Adds some item to the aggregation items.
Parameters:
{sap.ui.core.ListItem}oItem the item to add; if empty, nothing is inserted
Returns:
{sap.ui.commons.ComboBox} Reference to this in order to allow method chaining
bindItems(oBindingInfo): sap.ui.commons.ComboBox
Binds aggregation items to model data.

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

Parameters:
{object}oBindingInfo The binding information
Returns:
{sap.ui.commons.ComboBox} Reference to this in order to allow method chaining
destroyItems(): sap.ui.commons.ComboBox
Destroys all the items in the aggregation items.
Returns:
{sap.ui.commons.ComboBox} Reference to this in order to allow method chaining
fireChange(mArguments?): sap.ui.commons.ComboBox
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
Parameters:
{Map}mArguments? the arguments to pass along with the event.
Returns:
{sap.ui.commons.ComboBox}this to allow method chaining
getAccessibilityInfo()
See:
{sap.ui.core.Control#getAccessibilityInfo}
getDisplaySecondaryValues(): boolean
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.

Returns:
{boolean} Value of property displaySecondaryValues
getF4ButtonDomRef(): Element
Returns the DomRef which represents the icon for value help. Could be overwritten in child-classes
Returns:
{Element} The F4-element's DOM reference or null
getItems(): sap.ui.core.ListItem[]
Gets content of aggregation items.

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

Returns:
{sap.ui.core.ListItem[]}
getListBox(): sap.ui.commons.ListBox
ID of the element which is the current target of the association listBox, or null.
Returns:
{sap.ui.commons.ListBox}
getMaxPopupItems(): int
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.

Returns:
{int} Value of property maxPopupItems
getSelectedItemId(): string
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 an not existing item, it will not be changed.

Returns:
{string} Value of property selectedItemId
getSelectedKey(): string
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.

Returns:
{string} Value of property selectedKey
indexOfItem(oItem): int
Checks for the provided sap.ui.core.ListItem in the aggregation items. and returns its index if found or -1 otherwise.
Parameters:
{sap.ui.core.ListItem}oItem The item whose index is looked for
Returns:
{int} The index of the provided control in the aggregation if found, or -1 otherwise
insertItem(oItem, iIndex): sap.ui.commons.ComboBox
Inserts a item into the aggregation items.
Parameters:
{sap.ui.core.ListItem}oItem the item to insert; if empty, nothing is inserted
{int}iIndex 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
Returns:
{sap.ui.commons.ComboBox} Reference to this in order to allow method chaining
onsapenter(oEvent)
Handle sapenter pseudo events on the control
Parameters:
{jQuery.Event}oEvent The event object.
onsapescape(oEvent)
Handle sapescape pseudo events on the control
Parameters:
{jQuery.Event}oEvent The event object.
onsaphide(oEvent)
Handle saphide pseudo events on the control
Parameters:
{jQuery.Event}oEvent The event object.
onsapnextmodifiers(oEvent)
Handle sapnextmodifiers pseudo events on the control if in toolbar prevent item navigation if popup is opened.
Parameters:
{jQuery.Event}oEvent The event object.
onsapshow(oEvent)
Handle sapshow pseudo events on the control
Parameters:
{jQuery.Event}oEvent The event object.
removeAllItems(): sap.ui.core.ListItem[]
Removes all the controls from the aggregation items.

Additionally, it unregisters them from the hosting UIArea.

Returns:
{sap.ui.core.ListItem[]} An array of the removed elements (might be empty)
removeItem(vItem): sap.ui.core.ListItem
Removes a item from the aggregation items.
Parameters:
{int|string|sap.ui.core.ListItem}vItem The itemto remove or its index or id
Returns:
{sap.ui.core.ListItem} The removed item or null
setDisplaySecondaryValues(bDisplaySecondaryValues): sap.ui.commons.ComboBox
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.

Parameters:
{boolean}bDisplaySecondaryValues New value for property displaySecondaryValues
Returns:
{sap.ui.commons.ComboBox} Reference to this in order to allow method chaining
setListBox(oListBox): sap.ui.commons.ComboBox
Sets the associated listBox.
Parameters:
{sap.ui.commons.ListBox}oListBox Id of an element which becomes the new target of this listBox association; alternatively, an element instance may be given
Returns:
{sap.ui.commons.ComboBox} Reference to this in order to allow method chaining
setMaxPopupItems(iMaxPopupItems): sap.ui.commons.ComboBox
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.

Parameters:
{int}iMaxPopupItems New value for property maxPopupItems
Returns:
{sap.ui.commons.ComboBox} Reference to this in order to allow method chaining
setSelectedItemId(sSelectedItemId): sap.ui.commons.ComboBox
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 an 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.

Parameters:
{string}sSelectedItemId New value for property selectedItemId
Returns:
{sap.ui.commons.ComboBox} Reference to this in order to allow method chaining
setSelectedKey(sSelectedKey): sap.ui.commons.ComboBox
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.

Parameters:
{string}sSelectedKey New value for property selectedKey
Returns:
{sap.ui.commons.ComboBox} Reference to this in order to allow method chaining
unbindItems(): sap.ui.commons.ComboBox
Unbinds aggregation items from model data.
Returns:
{sap.ui.commons.ComboBox} Reference to this in order to allow method chaining