Class sap.m.SelectDialogModule: sap/m/SelectDialog

extends Control

A SelectDialog is a dialog containing a list, search functionality to filter it and a confirmation/cancel button. The control can be used when the user should select one or multiple items out of many.

The list used in the SelectDialog is a growing list and can be filled with a any kind of list item. The search field triggers the events "search" and "liveChange" where a filter function can be applied to the list binding.

After selecting an item in single selection mode or after confirming in multi selection mode, the dialog will be closed and the event "confirm" is fired with the items that have been selected. By default, the selection will also be reset to allow for a new selection when opening the dialog again.

When cancelling the selection, the event "change" will be fired and the selection is restored to the state when the dialog was opened.

NOTE: The growing functionality of the list does not support two-way Binding, so if you use this control with a JSON model make sure the binding mode is set to "OneWay" and that you update the selection model manually with the items passed in the "confirm" event.

Constructor Summary
new sap.m.SelectDialog(sId?, mSettings?)Constructor for a new SelectDialog.
Event Summary
cancel(oControlEvent)This event will be fired when the cancel button is clicked
confirm(oControlEvent)This event will be fired when the dialog is confirmed by selecting an item in single selection mode or by pressing the confirmation button in multi selection mode .
liveChange(oControlEvent)This event will be fired when the value of the search field is changed by a user - e.g.
search(oControlEvent)This event will be fired when the search button has been clicked on the searchfield on the visual control
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.m.SelectDialog.extend(sClassName, oClassInfo?, FNMetaImpl?)Creates a new subclass of class sap.m.SelectDialog with name sClassName and enriches it with the information contained in oClassInfo.
sap.m.SelectDialog.getMetadata()Returns a metadata object for class sap.m.SelectDialog.
addItem(oItem)Adds some item to the aggregation items.
attachCancel(oData?, fnFunction, oListener?)Attaches event handler fnFunction to the cancel event of this sap.m.SelectDialog.
attachConfirm(oData?, fnFunction, oListener?)Attaches event handler fnFunction to the confirm event of this sap.m.SelectDialog.
attachLiveChange(oData?, fnFunction, oListener?)Attaches event handler fnFunction to the liveChange event of this sap.m.SelectDialog.
attachSearch(oData?, fnFunction, oListener?)Attaches event handler fnFunction to the search event of this sap.m.SelectDialog.
destroyItems()Destroys all the items in the aggregation items.
detachCancel(fnFunction, oListener)Detaches event handler fnFunction from the cancel event of this sap.m.SelectDialog.
detachConfirm(fnFunction, oListener)Detaches event handler fnFunction from the confirm event of this sap.m.SelectDialog.
detachLiveChange(fnFunction, oListener)Detaches event handler fnFunction from the liveChange event of this sap.m.SelectDialog.
detachSearch(fnFunction, oListener)Detaches event handler fnFunction from the search event of this sap.m.SelectDialog.
fireCancel(mArguments?)Fires event cancel to attached listeners.
fireConfirm(mArguments?)Fires event confirm to attached listeners.
fireLiveChange(mArguments?)Fires event liveChange to attached listeners.
fireSearch(mArguments?)Fires event search to attached listeners.
getContentHeight()Get the internal Dialog's contentHeight property sap.m.Dialog
getContentWidth()Get the internal Dialog's contentWidth property sap.m.Dialog
getGrowingThreshold()Gets current value of property growingThreshold.
getItems()Gets content of aggregation items.
getMultiSelect()Gets current value of property multiSelect.
getNoDataText()Get the internal List's no data text property
getRememberSelections()Gets current value of property rememberSelections.
getTitle()Gets current value of property title.
indexOfItem(oItem)Checks for the provided sap.m.ListItemBase in the aggregation items.
insertItem(oItem, iIndex)Inserts a item into the aggregation items.
open(sSearchValue)Opens the internal dialog with a searchfield and a list.
removeAllItems()Removes all the controls from the aggregation items.
removeItem(vItem)Removes a item from the aggregation items.
setContentHeight(sHeight)Set the internal Dialog's contentHeight property sap.m.Dialog
setContentWidth(sWidth)Set the internal Dialog's contentWidth property sap.m.Dialog
setGrowingThreshold(iValue)Sets the growing threshold to the internal list
setMultiSelect(bMulti)Enable/Disable multi selection mode.
setNoDataText(sNoDataText)Set the internal List's no data text property
setRememberSelections(bRememberSelections)Sets a new value for property rememberSelections.
setTitle(sTitle)Set the title of the internal dialog
Methods borrowed from class sap.ui.core.Control
addStyleClass, allowTextSelection, attachBrowserEvent, attachValidateFieldGroup, checkFieldGroupIds, clone, detachBrowserEvent, detachValidateFieldGroup, fireValidateFieldGroup, getAccessibilityInfo, 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, getFocusInfo, 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.m.SelectDialog(sId?, mSettings?)
Constructor for a new SelectDialog.

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:

  • Properties
  • Aggregations
    • items : sap.m.ListItemBase[] (default)
  • Events
    • confirm : fnListenerFunction or [fnListenerFunction, oListenerObject] or [oData, fnListenerFunction, oListenerObject]
    • search : fnListenerFunction or [fnListenerFunction, oListenerObject] or [oData, fnListenerFunction, oListenerObject]
    • liveChange : fnListenerFunction or [fnListenerFunction, oListenerObject] or [oData, fnListenerFunction, oListenerObject]
    • cancel : fnListenerFunction or [fnListenerFunction, oListenerObject] or [oData, fnListenerFunction, oListenerObject]

In addition, all settings applicable to the base type sap.ui.core.Control 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
Event Detail
cancel(oControlEvent)
This event will be fired when the cancel button is clicked
Parameters:
{sap.ui.base.Event}oControlEvent
{sap.ui.base.EventProvider}oControlEvent.getSource
{object}oControlEvent.getParameters
confirm(oControlEvent)
This event will be fired when the dialog is confirmed by selecting an item in single selection mode or by pressing the confirmation button in multi selection mode . The items being selected are returned as event parameters.
Parameters:
{sap.ui.base.Event}oControlEvent
{sap.ui.base.EventProvider}oControlEvent.getSource
{object}oControlEvent.getParameters
{sap.m.StandardListItem}oControlEvent.getParameters.selectedItem Returns the selected list item. When no item is selected, "null" is returned. When multi-selection is enabled and multiple items are selected, only the first selected item is returned.
{sap.m.StandardListItem[]}oControlEvent.getParameters.selectedItems Returns an array containing the visible selected list items. If no items are selected, an empty array is returned.
{string}oControlEvent.getParameters.selectedContexts Returns the binding contexts of the selected items including the non-visible items. NOTE: In contrast to the parameter "selectedItems", this parameter will also include the selected but NOT visible items (e.g. due to list filtering). An empty array will be set for this parameter if no data binding is used. NOTE: When the list binding is pre-filtered and there are items in the selection that are not visible upon opening the dialog, these contexts are not loaded. Therefore, these items will not be included in the selectedContexts array unless they are displayed at least once.
liveChange(oControlEvent)
This event will be fired when the value of the search field is changed by a user - e.g. at each key press
Parameters:
{sap.ui.base.Event}oControlEvent
{sap.ui.base.EventProvider}oControlEvent.getSource
{object}oControlEvent.getParameters
{string}oControlEvent.getParameters.value The value to search for, which can change at any keypress
{any}oControlEvent.getParameters.itemsBinding The Items binding of the Select Dialog. It will only be available if the items aggregation is bound to a model.
search(oControlEvent)
This event will be fired when the search button has been clicked on the searchfield on the visual control
Parameters:
{sap.ui.base.Event}oControlEvent
{sap.ui.base.EventProvider}oControlEvent.getSource
{object}oControlEvent.getParameters
{string}oControlEvent.getParameters.value The value entered in the search
{any}oControlEvent.getParameters.itemsBinding The Items binding of the Select Dialog for search purposes. It will only be available if the items aggregation is bound to a model.
Method Detail
sap.m.SelectDialog.extend(sClassName, oClassInfo?, FNMetaImpl?): function
Creates a new subclass of class sap.m.SelectDialog 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.core.Control.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.m.SelectDialog.getMetadata(): sap.ui.base.Metadata
Returns a metadata object for class sap.m.SelectDialog.
Returns:
{sap.ui.base.Metadata} Metadata object describing this class
addItem(oItem): sap.m.SelectDialog
Adds some item to the aggregation items.
Parameters:
{sap.m.ListItemBase}oItem the item to add; if empty, nothing is inserted
Returns:
{sap.m.SelectDialog} Reference to this in order to allow method chaining
attachCancel(oData?, fnFunction, oListener?): sap.m.SelectDialog
Attaches event handler fnFunction to the cancel event of this sap.m.SelectDialog.

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

This event will be fired when the cancel button is clicked

Parameters:
{object}oData? An application-specific payload object that will be passed to the event handler along with the event object when firing the event
{function}fnFunction The function to be called when the event occurs
{object}oListener? Context object to call the event handler with. Defaults to this sap.m.SelectDialog itself
Returns:
{sap.m.SelectDialog} Reference to this in order to allow method chaining
attachConfirm(oData?, fnFunction, oListener?): sap.m.SelectDialog
Attaches event handler fnFunction to the confirm event of this sap.m.SelectDialog.

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

This event will be fired when the dialog is confirmed by selecting an item in single selection mode or by pressing the confirmation button in multi selection mode . The items being selected are returned as event parameters.

Parameters:
{object}oData? An application-specific payload object that will be passed to the event handler along with the event object when firing the event
{function}fnFunction The function to be called when the event occurs
{object}oListener? Context object to call the event handler with. Defaults to this sap.m.SelectDialog itself
Returns:
{sap.m.SelectDialog} Reference to this in order to allow method chaining
attachLiveChange(oData?, fnFunction, oListener?): sap.m.SelectDialog
Attaches event handler fnFunction to the liveChange event of this sap.m.SelectDialog.

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

This event will be fired when the value of the search field is changed by a user - e.g. at each key press

Parameters:
{object}oData? An application-specific payload object that will be passed to the event handler along with the event object when firing the event
{function}fnFunction The function to be called when the event occurs
{object}oListener? Context object to call the event handler with. Defaults to this sap.m.SelectDialog itself
Returns:
{sap.m.SelectDialog} Reference to this in order to allow method chaining
attachSearch(oData?, fnFunction, oListener?): sap.m.SelectDialog
Attaches event handler fnFunction to the search event of this sap.m.SelectDialog.

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

This event will be fired when the search button has been clicked on the searchfield on the visual control

Parameters:
{object}oData? An application-specific payload object that will be passed to the event handler along with the event object when firing the event
{function}fnFunction The function to be called when the event occurs
{object}oListener? Context object to call the event handler with. Defaults to this sap.m.SelectDialog itself
Returns:
{sap.m.SelectDialog} Reference to this in order to allow method chaining
destroyItems(): sap.m.SelectDialog
Destroys all the items in the aggregation items.
Returns:
{sap.m.SelectDialog} Reference to this in order to allow method chaining
detachCancel(fnFunction, oListener): sap.m.SelectDialog
Detaches event handler fnFunction from the cancel event of this sap.m.SelectDialog.

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

Parameters:
{function}fnFunction The function to be called, when the event occurs
{object}oListener Context object on which the given function had to be called
Returns:
{sap.m.SelectDialog} Reference to this in order to allow method chaining
detachConfirm(fnFunction, oListener): sap.m.SelectDialog
Detaches event handler fnFunction from the confirm event of this sap.m.SelectDialog.

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

Parameters:
{function}fnFunction The function to be called, when the event occurs
{object}oListener Context object on which the given function had to be called
Returns:
{sap.m.SelectDialog} Reference to this in order to allow method chaining
detachLiveChange(fnFunction, oListener): sap.m.SelectDialog
Detaches event handler fnFunction from the liveChange event of this sap.m.SelectDialog.

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

Parameters:
{function}fnFunction The function to be called, when the event occurs
{object}oListener Context object on which the given function had to be called
Returns:
{sap.m.SelectDialog} Reference to this in order to allow method chaining
detachSearch(fnFunction, oListener): sap.m.SelectDialog
Detaches event handler fnFunction from the search event of this sap.m.SelectDialog.

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

Parameters:
{function}fnFunction The function to be called, when the event occurs
{object}oListener Context object on which the given function had to be called
Returns:
{sap.m.SelectDialog} Reference to this in order to allow method chaining
fireCancel(mArguments?): sap.m.SelectDialog
Fires event cancel to attached listeners.
Parameters:
{Map}mArguments? The arguments to pass along with the event
Returns:
{sap.m.SelectDialog} Reference to this in order to allow method chaining
fireConfirm(mArguments?): sap.m.SelectDialog
Fires event confirm to attached listeners.

Expects the following event parameters:

  • selectedItem of type sap.m.StandardListItemReturns the selected list item. When no item is selected, "null" is returned. When multi-selection is enabled and multiple items are selected, only the first selected item is returned.
  • selectedItems of type sap.m.StandardListItem[]Returns an array containing the visible selected list items. If no items are selected, an empty array is returned.
  • selectedContexts of type stringReturns the binding contexts of the selected items including the non-visible items. NOTE: In contrast to the parameter "selectedItems", this parameter will also include the selected but NOT visible items (e.g. due to list filtering). An empty array will be set for this parameter if no data binding is used. NOTE: When the list binding is pre-filtered and there are items in the selection that are not visible upon opening the dialog, these contexts are not loaded. Therefore, these items will not be included in the selectedContexts array unless they are displayed at least once.
Parameters:
{Map}mArguments? The arguments to pass along with the event
Returns:
{sap.m.SelectDialog} Reference to this in order to allow method chaining
fireLiveChange(mArguments?): sap.m.SelectDialog
Fires event liveChange to attached listeners.

Expects the following event parameters:

  • value of type stringThe value to search for, which can change at any keypress
  • itemsBinding of type anyThe Items binding of the Select Dialog. It will only be available if the items aggregation is bound to a model.
Parameters:
{Map}mArguments? The arguments to pass along with the event
Returns:
{sap.m.SelectDialog} Reference to this in order to allow method chaining
fireSearch(mArguments?): sap.m.SelectDialog
Fires event search to attached listeners.

Expects the following event parameters:

  • value of type stringThe value entered in the search
  • itemsBinding of type anyThe Items binding of the Select Dialog for search purposes. It will only be available if the items aggregation is bound to a model.
Parameters:
{Map}mArguments? The arguments to pass along with the event
Returns:
{sap.m.SelectDialog} Reference to this in order to allow method chaining
getContentHeight(): sap.ui.core.CSSSize
Get the internal Dialog's contentHeight property sap.m.Dialog
Returns:
{sap.ui.core.CSSSize} sHeight The content width of the internal dialog
getContentWidth(): sap.ui.core.CSSSize
Get the internal Dialog's contentWidth property sap.m.Dialog
Returns:
{sap.ui.core.CSSSize} sWidth The content width of the internal dialog
getGrowingThreshold(): int
Gets current value of property growingThreshold.

Determines the number of items initially displayed in the list. Also defines the number of items to be requested from the model for each grow.

Returns:
{int} Value of property growingThreshold
getItems(): sap.m.ListItemBase[]
Gets content of aggregation items.

The items of the list shown in the search dialog. It is recommended to use a StandardListItem for the dialog but other combinations are also possible.

Returns:
{sap.m.ListItemBase[]}
getMultiSelect(): boolean
Gets current value of property multiSelect.

Determines if the user can select several options from the list

Default value is false.

Returns:
{boolean} Value of property multiSelect
getNoDataText(): string
Get the internal List's no data text property
Returns:
{string} the current no data text
getRememberSelections(): boolean
Gets current value of property rememberSelections.

This flag controls whether the dialog clears the selection after the confirm event has been fired. If the dialog needs to be opened multiple times in the same context to allow for corrections of previous user inputs, set this flag to "true".

Default value is false.

Since:
1.18
Returns:
{boolean} Value of property rememberSelections
getTitle(): string
Gets current value of property title.

Determines the title text that appears in the dialog header

Returns:
{string} Value of property title
indexOfItem(oItem): int
Checks for the provided sap.m.ListItemBase in the aggregation items. and returns its index if found or -1 otherwise.
Parameters:
{sap.m.ListItemBase}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.m.SelectDialog
Inserts a item into the aggregation items.
Parameters:
{sap.m.ListItemBase}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.m.SelectDialog} Reference to this in order to allow method chaining
open(sSearchValue): sap.m.SelectDialog
Opens the internal dialog with a searchfield and a list.
Parameters:
{string}sSearchValue A value for the search can be passed to match with the filter applied to the list binding.
Returns:
{sap.m.SelectDialog}
removeAllItems(): sap.m.ListItemBase[]
Removes all the controls from the aggregation items.

Additionally, it unregisters them from the hosting UIArea.

Returns:
{sap.m.ListItemBase[]} An array of the removed elements (might be empty)
removeItem(vItem): sap.m.ListItemBase
Removes a item from the aggregation items.
Parameters:
{int|string|sap.m.ListItemBase}vItem The itemto remove or its index or id
Returns:
{sap.m.ListItemBase} The removed item or null
setContentHeight(sHeight): sap.m.SelectDialog
Set the internal Dialog's contentHeight property sap.m.Dialog
Parameters:
{sap.ui.core.CSSSize}sHeight The new content width value for the dialog
Returns:
{sap.m.SelectDialog} this pointer for chaining
setContentWidth(sWidth): sap.m.SelectDialog
Set the internal Dialog's contentWidth property sap.m.Dialog
Parameters:
{sap.ui.core.CSSSize}sWidth The new content width value for the dialog
Returns:
{sap.m.SelectDialog} this pointer for chaining
setGrowingThreshold(iValue): sap.m.SelectDialog
Sets the growing threshold to the internal list
Parameters:
{int}iValue Value for the list's growing threshold.
Returns:
{sap.m.SelectDialog} this pointer for chaining
setMultiSelect(bMulti): sap.m.SelectDialog
Enable/Disable multi selection mode.
Parameters:
{boolean}bMulti Flag for multi selection mode
Returns:
{sap.m.SelectDialog} this pointer for chaining
setNoDataText(sNoDataText): sap.m.SelectDialog
Set the internal List's no data text property
Parameters:
{string}sNoDataText The no data text for the list
Returns:
{sap.m.SelectDialog} this pointer for chaining
setRememberSelections(bRememberSelections): sap.m.SelectDialog
Sets a new value for property rememberSelections.

This flag controls whether the dialog clears the selection after the confirm event has been fired. If the dialog needs to be opened multiple times in the same context to allow for corrections of previous user inputs, set this flag to "true".

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

Default value is false.

Parameters:
{boolean}bRememberSelections New value for property rememberSelections
Since:
1.18
Returns:
{sap.m.SelectDialog} Reference to this in order to allow method chaining
setTitle(sTitle): sap.m.SelectDialog
Set the title of the internal dialog
Parameters:
{string}sTitle The title text for the dialog
Returns:
{sap.m.SelectDialog} this pointer for chaining