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

extends Control

Overview

A SelectDialog is a dialog containing a list, search functionality to filter it and a confirmation/cancel button. The list used in the dialog is a growing list and can be filled with any kind of list item.

Structure

Dialog structure

The select dialog has the following components:

  • Header - title of the dialog
  • Search field - input field to enter search terms
  • Info toolbar (only in multi-select) - displays the number of currently selected items
  • Content - standard list items, display list items or feed list items
  • Button toolbar - for confirmation/cancellation buttons

List structure & selection

  • The search field triggers the events search and liveChange where a filter function can be applied to the list binding.
  • 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.
  • In the multi-select mode of the select dialog, checkboxes are provided for choosing multiple entries.
  • You can set rememberSelections to true to store the current selection and load this state when the dialog is opened again.
  • When cancelling the selection, the event change will be fired and the selection is restored to the state when the dialog was opened.

Usage

When to use:

  • You need to select one or more entries from a comprehensive list that contains multiple attributes or values.

When not to use:

  • You need to pick one item from a predefined set of options. Use select or combobox instead.
  • You need to select a range of item. Use value help dialog instead.
  • You need to be able to add your own values to an existing list. Use a {@link sap.m.Dialog dialog instead.

Responsive Behavior

  • On phones, the select dialog takes up the whole screen.
  • On desktop and tablet devices, the select dialog appears as a popover.
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
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(mParameters?)Fires event cancel to attached listeners.
fireConfirm(mParameters?)Fires event confirm to attached listeners.
fireLiveChange(mParameters?)Fires event liveChange to attached listeners.
fireSearch(mParameters?)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
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:
stringsId?ID for the new control, generated automatically if no ID is given
objectmSettings?Initial settings for the new control A dialog that enables users to select one or more items from a comprehensive list.
Event Detail
cancel(oControlEvent)
This event will be fired when the cancel button is clicked
Parameters:
sap.ui.base.EventoControlEvent
sap.ui.base.EventProvideroControlEvent.getSource
objectoControlEvent.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.EventoControlEvent
sap.ui.base.EventProvideroControlEvent.getSource
objectoControlEvent.getParameters
sap.m.StandardListItemoControlEvent.getParameters.selectedItemReturns 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.selectedItemsReturns an array containing the visible selected list items. If no items are selected, an empty array is returned.
stringoControlEvent.getParameters.selectedContextsReturns 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.EventoControlEvent
sap.ui.base.EventProvideroControlEvent.getSource
objectoControlEvent.getParameters
stringoControlEvent.getParameters.valueThe value to search for, which can change at any keypress
anyoControlEvent.getParameters.itemsBindingThe 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.EventoControlEvent
sap.ui.base.EventProvideroControlEvent.getSource
objectoControlEvent.getParameters
stringoControlEvent.getParameters.valueThe value entered in the search
anyoControlEvent.getParameters.itemsBindingThe 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:
stringsClassNameName of the class being created
objectoClassInfo?Object literal with information about the class
functionFNMetaImpl?Constructor function for the metadata object; if not given, it defaults to sap.ui.core.ElementMetadata
Returns:
functionCreated class / constructor function
sap.m.SelectDialog.getMetadata(): sap.ui.base.Metadata
Returns a metadata object for class sap.m.SelectDialog.
Returns:
sap.ui.base.MetadataMetadata object describing this class
addItem(oItem): sap.m.SelectDialog
Adds some item to the aggregation items.
Parameters:
sap.m.ListItemBaseoItemthe item to add; if empty, nothing is inserted
Returns:
sap.m.SelectDialogReference 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:
objectoData?An application-specific payload object that will be passed to the event handler along with the event object when firing the event
functionfnFunctionThe function to be called when the event occurs
objectoListener?Context object to call the event handler with. Defaults to this sap.m.SelectDialog itself
Returns:
sap.m.SelectDialogReference 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:
objectoData?An application-specific payload object that will be passed to the event handler along with the event object when firing the event
functionfnFunctionThe function to be called when the event occurs
objectoListener?Context object to call the event handler with. Defaults to this sap.m.SelectDialog itself
Returns:
sap.m.SelectDialogReference 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:
objectoData?An application-specific payload object that will be passed to the event handler along with the event object when firing the event
functionfnFunctionThe function to be called when the event occurs
objectoListener?Context object to call the event handler with. Defaults to this sap.m.SelectDialog itself
Returns:
sap.m.SelectDialogReference 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:
objectoData?An application-specific payload object that will be passed to the event handler along with the event object when firing the event
functionfnFunctionThe function to be called when the event occurs
objectoListener?Context object to call the event handler with. Defaults to this sap.m.SelectDialog itself
Returns:
sap.m.SelectDialogReference to this in order to allow method chaining
destroyItems(): sap.m.SelectDialog
Destroys all the items in the aggregation items.
Returns:
sap.m.SelectDialogReference 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:
functionfnFunctionThe function to be called, when the event occurs
objectoListenerContext object on which the given function had to be called
Returns:
sap.m.SelectDialogReference 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:
functionfnFunctionThe function to be called, when the event occurs
objectoListenerContext object on which the given function had to be called
Returns:
sap.m.SelectDialogReference 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:
functionfnFunctionThe function to be called, when the event occurs
objectoListenerContext object on which the given function had to be called
Returns:
sap.m.SelectDialogReference 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:
functionfnFunctionThe function to be called, when the event occurs
objectoListenerContext object on which the given function had to be called
Returns:
sap.m.SelectDialogReference to this in order to allow method chaining
fireCancel(mParameters?): sap.m.SelectDialog
Fires event cancel to attached listeners.
Parameters:
objectmParameters?Parameters to pass along with the event
Returns:
sap.m.SelectDialogReference to this in order to allow method chaining
fireConfirm(mParameters?): sap.m.SelectDialog
Fires event confirm to attached listeners.
Parameters:
objectmParameters?Parameters to pass along with the event
sap.m.StandardListItemmParameters.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[]mParameters.selectedItems?Returns an array containing the visible selected list items. If no items are selected, an empty array is returned.
stringmParameters.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.
Returns:
sap.m.SelectDialogReference to this in order to allow method chaining
fireLiveChange(mParameters?): sap.m.SelectDialog
Fires event liveChange to attached listeners.
Parameters:
objectmParameters?Parameters to pass along with the event
stringmParameters.value?The value to search for, which can change at any keypress
anymParameters.itemsBinding?The Items binding of the Select Dialog. It will only be available if the items aggregation is bound to a model.
Returns:
sap.m.SelectDialogReference to this in order to allow method chaining
fireSearch(mParameters?): sap.m.SelectDialog
Fires event search to attached listeners.
Parameters:
objectmParameters?Parameters to pass along with the event
stringmParameters.value?The value entered in the search
anymParameters.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.
Returns:
sap.m.SelectDialogReference 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.CSSSizesHeight 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.CSSSizesWidth 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:
intValue 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:
booleanValue of property multiSelect
getNoDataText(): string
Get the internal List's no data text property
Returns:
stringthe 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.

Returns:
booleanValue of property rememberSelections
Since:
1.18
getTitle(): string

Gets current value of property title.

Determines the title text that appears in the dialog header

Returns:
stringValue 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.ListItemBaseoItemThe item whose index is looked for
Returns:
intThe 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.ListItemBaseoItemthe item to insert; if empty, nothing is inserted
intiIndexthe 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.SelectDialogReference to this in order to allow method chaining
open(sSearchValue): sap.m.SelectDialog
Opens the internal dialog with a searchfield and a list.
Parameters:
stringsSearchValueA 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.ListItemBasevItemThe item to remove or its index or id
Returns:
sap.m.ListItemBaseThe removed item or null
setContentHeight(sHeight): sap.m.SelectDialog
Set the internal Dialog's contentHeight property sap.m.Dialog
Parameters:
sap.ui.core.CSSSizesHeightThe new content width value for the dialog
Returns:
sap.m.SelectDialogthis pointer for chaining
setContentWidth(sWidth): sap.m.SelectDialog
Set the internal Dialog's contentWidth property sap.m.Dialog
Parameters:
sap.ui.core.CSSSizesWidthThe new content width value for the dialog
Returns:
sap.m.SelectDialogthis pointer for chaining
setGrowingThreshold(iValue): sap.m.SelectDialog
Sets the growing threshold to the internal list
Parameters:
intiValueValue for the list's growing threshold.
Returns:
sap.m.SelectDialogthis pointer for chaining
setMultiSelect(bMulti): sap.m.SelectDialog
Enable/Disable multi selection mode.
Parameters:
booleanbMultiFlag for multi selection mode
Returns:
sap.m.SelectDialogthis pointer for chaining
setNoDataText(sNoDataText): sap.m.SelectDialog
Set the internal List's no data text property
Parameters:
stringsNoDataTextThe no data text for the list
Returns:
sap.m.SelectDialogthis 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:
booleanbRememberSelectionsNew value for property rememberSelections
Returns:
sap.m.SelectDialogReference to this in order to allow method chaining
Since:
1.18
setTitle(sTitle): sap.m.SelectDialog
Set the title of the internal dialog
Parameters:
stringsTitleThe title text for the dialog
Returns:
sap.m.SelectDialogthis pointer for chaining