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.
The select dialog has the following components:
search
and liveChange
where a filter function can be applied to the list binding. OneWay
and that you update the selection model manually with the items passed in the confirm
event. rememberSelections
to true
to store the current selection and load this state when the dialog is opened again. change
will be fired and the selection is restored to the state when the dialog was opened. resizable
and draggable
properties. Both properties are available only in desktop mode.
The property growing
determines the progressive loading. If it's set to true
(the default value), the selected count (if present) and search, will work for currently loaded items only. To make sure that all items in the list are loaded at once and the above features works properly, we recommend setting the growing
property to false
.
sap.m.SelectDialog
in SAP Quartz themes, the breakpoints and layout paddings could be determined by the dialog's width. To enable this concept and add responsive paddings to an element of the control, you have to add the following classes depending on your use case: sapUiResponsivePadding--header
, sapUiResponsivePadding--subHeader
, sapUiResponsivePadding--content
, sapUiResponsivePadding--footer
.
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#constructor for a general description of the syntax of the settings object.
new sap.m.SelectDialog(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 A dialog that enables users to select one or more items from a comprehensive list. |
Name | Type | Default Value | Description |
---|---|---|---|
confirmButtonText | string | Overwrites the default text for the confirmation button. |
|
contentHeight | sap.ui.core.CSSSize | Determines the content height of the inner dialog. For more information, see the dialog documentation. Visibility: public |
|
contentWidth | sap.ui.core.CSSSize | Determines the content width of the inner dialog. For more information, see the dialog documentation. |
|
draggable | boolean | false | When set to |
growing | boolean | true | If set to |
growingThreshold | int | 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. Note: This property could take affect only be used if the property |
|
multiSelect | boolean | false | Determines if the user can select several options from the list Visibility: public |
noDataText | string | Determines the text shown when the list has no data Visibility: public |
|
rememberSelections | boolean | false | 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 Note: The sap.m.SelectDialog uses this property of the ListBase and therefore its limitations also apply here. |
resizable | boolean | false | When set to |
showClearButton | boolean | false | This flag controls whether the Clear button is shown. When set to |
title | string | Determines the title text that appears in the dialog header Visibility: public |
|
titleAlignment | sap.m.TitleAlignment | Auto | Specifies the Title alignment (theme specific). If set to |
Default Aggregation: items
Name | Cardinality | Type | Description |
---|---|---|---|
_dialog | 0..1 | sap.ui.core.Control |
The internal dialog that will be shown when method open is called |
items (default) | 0..n | sap.m.ListItemBase |
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. |
Event | Description |
---|---|
cancel |
This event will be fired when the cancel button is clicked or ESC key is pressed |
confirm |
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. |
liveChange |
This event will be fired when the value of the search field is changed by a user - e.g. at each key press |
search |
This event will be fired when the search button has been clicked on the searchfield on the visual control |
This event will be fired when the cancel button is clicked or ESC key is pressed
Param | Type | Description |
---|---|---|
oControlEvent | sap.ui.base.Event | |
getSource | sap.ui.base.EventProvider | |
getParameters | object |
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.
Param | Type | Description |
---|---|---|
oControlEvent | sap.ui.base.Event | |
getSource | sap.ui.base.EventProvider | |
getParameters | object | |
selectedItem | sap.m.StandardListItem |
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. |
selectedItems | sap.m.StandardListItem[] |
Returns an array containing the visible selected list items. If no items are selected, an empty array is returned. |
selectedContexts | object[] |
Returns the binding contexts of the selected items including the non-visible items, but excluding the not loaded items. See getSelectedContexts of |
This event will be fired when the value of the search field is changed by a user - e.g. at each key press
Param | Type | Description |
---|---|---|
oControlEvent | sap.ui.base.Event | |
getSource | sap.ui.base.EventProvider | |
getParameters | object | |
value | string |
The value to search for, which can change at any keypress |
itemsBinding | any |
The Items binding of the Select Dialog. It will only be available if the items aggregation is bound to a model. |
This event will be fired when the search button has been clicked on the searchfield on the visual control
Param | Type | Description |
---|---|---|
oControlEvent | sap.ui.base.Event | |
getSource | sap.ui.base.EventProvider | |
getParameters | object | |
value | string |
The value entered in the search |
itemsBinding | any |
The Items binding of the Select Dialog for search purposes. It will only be available if the items aggregation is bound to a model. |
clearButtonPressed | boolean |
Returns if the Clear button is pressed. |
Method | Description |
---|---|
addItem |
Adds some item to the aggregation items. |
addStyleClass |
Forward method to the inner dialog: addStyleClass |
attachCancel |
Attaches event handler When called, the context of the event handler (its This event will be fired when the cancel button is clicked or ESC key is pressed |
attachConfirm |
Attaches event handler When called, the context of the event handler (its 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. |
attachLiveChange |
Attaches event handler When called, the context of the event handler (its This event will be fired when the value of the search field is changed by a user - e.g. at each key press |
attachSearch |
Attaches event handler When called, the context of the event handler (its This event will be fired when the search button has been clicked on the searchfield on the visual control |
clearSelection |
Clears the selections in the Use this method whenever the application logic expects changes in the model providing data for the SelectDialog that will modify the position of the items, or will change the set with completely new items. |
destroyItems |
Destroys all the items in the aggregation items. |
detachCancel |
Detaches event handler The passed function and listener object must match the ones used for event registration. |
detachConfirm |
Detaches event handler The passed function and listener object must match the ones used for event registration. |
detachLiveChange |
Detaches event handler The passed function and listener object must match the ones used for event registration. |
detachSearch |
Detaches event handler The passed function and listener object must match the ones used for event registration. |
sap.m.SelectDialog.extend |
Creates a new subclass of class sap.m.SelectDialog with name
|
fireCancel |
Fires event cancel to attached listeners. |
fireConfirm |
Fires event confirm to attached listeners. |
fireLiveChange |
Fires event liveChange to attached listeners. |
fireSearch |
Fires event search to attached listeners. |
getConfirmButtonText |
Gets current value of property confirmButtonText. Overwrites the default text for the confirmation button. |
getContentHeight |
Get the internal Dialog's contentHeight property sap.m.Dialog |
getContentWidth |
Get the internal Dialog's contentWidth property sap.m.Dialog |
getDomRef |
Forward method to the inner dialog: getDomRef |
getDraggable |
Gets current value of property draggable. When set to Default value is |
getGrowing |
Gets current value of property growing. If set to Default value is |
getGrowingThreshold |
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. Note: This property could take affect only be used if the property |
getItems |
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. |
sap.m.SelectDialog.getMetadata |
Returns a metadata object for class sap.m.SelectDialog. |
getMultiSelect |
Gets current value of property multiSelect. Determines if the user can select several options from the list Default value is |
getNoDataText |
Get the internal List's no data text property |
getRememberSelections |
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 Note: The sap.m.SelectDialog uses this property of the ListBase and therefore its limitations also apply here. Default value is |
getResizable |
Gets current value of property resizable. When set to Default value is |
getShowClearButton |
Gets current value of property showClearButton. This flag controls whether the Clear button is shown. When set to Default value is |
getTitle |
Gets current value of property title. Determines the title text that appears in the dialog header |
getTitleAlignment |
Gets current value of property titleAlignment. Specifies the Title alignment (theme specific). If set to Default value is |
hasStyleClass |
Forward method to the inner dialog: hasStyleClass |
indexOfItem |
Checks for the provided |
insertItem |
Inserts a item into the aggregation items. |
invalidate |
Invalidates the dialog instead of this control (we don't have a renderer) |
onAfterRendering |
Is called after renderer is finished to show the busy state |
open |
Opens the internal dialog with a searchfield and a list. |
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. |
removeStyleClass |
Forward method to the inner dialog: removeStyleClass |
setBindingContext |
Set the binding context for the internal list AND the current control so that both controls can be used with the context |
setBusyIndicatorDelay |
Sets the busyIndicatorDelay value to the internal list |
setConfirmButtonText |
Sets the text of the confirmation button. |
setContentHeight |
Set the internal Dialog's contentHeight property sap.m.Dialog |
setContentWidth |
Set the internal Dialog's contentWidth property sap.m.Dialog |
setDraggable |
Sets the draggable property. |
setGrowing |
Sets the growing to the internal list |
setGrowingThreshold |
Sets the growing threshold to the internal list |
setModel |
Set the model for the internal list AND the current control so that both controls can be used with data binding |
setMultiSelect |
Enable/Disable multi selection mode. |
setNoDataText |
Set the internal List's no data text property |
setRememberSelections |
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 Note: The sap.m.SelectDialog uses this property of the ListBase and therefore its limitations also apply here. When called with a value of Default value is |
setResizable |
Sets the resizable property. |
setShowClearButton |
Sets the Clear button visible state |
setTitle |
Set the title of the internal dialog |
setTitleAlignment |
Sets a new value for property titleAlignment. Specifies the Title alignment (theme specific). If set to When called with a value of Default value is |
toggleStyleClass |
Forward method to the inner dialog: toggleStyleClass. |
Adds some item to the aggregation items.
Param | Type | DefaultValue | Description |
---|---|---|---|
oItem | sap.m.ListItemBase |
The item to add; if empty, nothing is inserted |
Forward method to the inner dialog: addStyleClass
Param | Type | DefaultValue | Description |
---|---|---|---|
sStyleClass | string |
CSS class name to add |
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 or ESC key is pressed
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 |
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.
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 |
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
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 |
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
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 |
Clears the selections in the sap.m.SelectDialog
and its internally used sap.m.List
control.
Use this method whenever the application logic expects changes in the model providing data for the SelectDialog that will modify the position of the items, or will change the set with completely new items.
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.
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 |
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.
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 |
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.
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 |
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.
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.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.m.SelectDialogBase.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 cancel to attached listeners.
Param | Type | DefaultValue | Description |
---|---|---|---|
mParameters | object |
Parameters to pass along with the event |
Fires event confirm to attached listeners.
Param | Type | DefaultValue | Description |
---|---|---|---|
mParameters | object |
Parameters to pass along with the event |
|
selectedItem | sap.m.StandardListItem |
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. |
|
selectedItems | sap.m.StandardListItem[] |
Returns an array containing the visible selected list items. If no items are selected, an empty array is returned. |
|
selectedContexts | object[] |
Returns the binding contexts of the selected items including the non-visible items, but excluding the not loaded items. See getSelectedContexts of |
Fires event liveChange to attached listeners.
Param | Type | DefaultValue | Description |
---|---|---|---|
mParameters | object |
Parameters to pass along with the event |
|
value | string |
The value to search for, which can change at any keypress |
|
itemsBinding | any |
The Items binding of the Select Dialog. It will only be available if the items aggregation is bound to a model. |
Fires event search to attached listeners.
Param | Type | DefaultValue | Description |
---|---|---|---|
mParameters | object |
Parameters to pass along with the event |
|
value | string |
The value entered in the search |
|
itemsBinding | any |
The Items binding of the Select Dialog for search purposes. It will only be available if the items aggregation is bound to a model. |
|
clearButtonPressed | boolean |
Returns if the Clear button is pressed. |
Gets current value of property confirmButtonText.
Overwrites the default text for the confirmation button.
Gets current value of property draggable.
When set to true
, the SelectDialog is draggable by its header. The default value is false
. Note: The SelectDialog can be draggable only in desktop mode.
Default value is false
.
Gets current value of property growing.
If set to true
, enables the growing feature of the control to load more items by requesting from the bound model (progressive loading). Note: This feature only works when an items
aggregation is bound. Note: Growing property, must not be used together with two-way binding. Note: If the property is set to true
, selected count (if present) and search, will work for currently loaded items only. To make sure that all items in the table are loaded at once and the above features work properly, we recommend setting the growing
property to false.
Default value is true
.
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. Note: This property could take affect only be used if the property growing
is set to true
.
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.
Gets current value of property multiSelect.
Determines if the user can select several options from the list
Default value is false
.
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
.
Note: The sap.m.SelectDialog uses this property of the ListBase and therefore its limitations also apply here.
Default value is false
.
Gets current value of property resizable.
When set to true
, the SelectDialog will have a resize handler in its bottom right corner. The default value is false
. Note: The SelectDialog can be resizable only in desktop mode.
Default value is false
.
Gets current value of property showClearButton.
This flag controls whether the Clear button is shown. When set to true
, it provides a way to clear selection mode in Select Dialog. We recommended enabling of the Clear button in the following cases, where a mechanism to clear the value is needed: In case of single selection mode(default mode) for Select Dialog and rememberSelections
is set to true
. Clear button needs to be enabled in order to allow users to clear the selection. In case of using sap.m.Input
with valueHelpOnly
set to true
, the Clear button could be used for clearing selection. In case the application stores a value and uses only Select Dialog to edit/maintain it. Note:When used with oData, only the loaded selections will be cleared.
Default value is false
.
Gets current value of property title.
Determines the title text that appears in the dialog header
Gets current value of property titleAlignment.
Specifies the Title alignment (theme specific). If set to TitleAlignment.Auto
, the Title will be aligned as it is set in the theme (if not set, the default value is center
); Other possible values are TitleAlignment.Start
(left or right depending on LTR/RTL), and TitleAlignment.Center
(centered)
Default value is Auto
.
Checks for the provided sap.m.ListItemBase
in the aggregation items. and returns its index if found or -1 otherwise.
Param | Type | DefaultValue | Description |
---|---|---|---|
oItem | sap.m.ListItemBase |
The item whose index is looked for |
Inserts a item into the aggregation items.
Param | Type | DefaultValue | Description |
---|---|---|---|
oItem | sap.m.ListItemBase |
The item to insert; if empty, nothing is inserted |
|
iIndex | int |
The |
Opens the internal dialog with a searchfield and a list.
Param | Type | DefaultValue | Description |
---|---|---|---|
sSearchValue | string |
A value for the search can be passed to match with the filter applied to the list binding. |
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.m.ListItemBase |
The item to remove or its index or id |
Forward method to the inner dialog: removeStyleClass
Param | Type | DefaultValue | Description |
---|---|---|---|
sStyleClass | string |
CSS class name to remove |
Set the binding context for the internal list AND the current control so that both controls can be used with the context
Param | Type | DefaultValue | Description |
---|---|---|---|
oContext | sap.ui.model.Context |
The new context |
|
sModelName | string |
The optional model name |
Sets the busyIndicatorDelay value to the internal list
Param | Type | DefaultValue | Description |
---|---|---|---|
iValue | int |
Value for the busyIndicatorDelay. |
Sets the text of the confirmation button.
Param | Type | DefaultValue | Description |
---|---|---|---|
sText | string |
The text for the confirm button |
Set the internal Dialog's contentHeight property sap.m.Dialog
Param | Type | DefaultValue | Description |
---|---|---|---|
sHeight | sap.ui.core.CSSSize |
The new content width value for the dialog |
Set the internal Dialog's contentWidth property sap.m.Dialog
Param | Type | DefaultValue | Description |
---|---|---|---|
sWidth | sap.ui.core.CSSSize |
The new content width value for the dialog |
Sets the draggable property.
Param | Type | DefaultValue | Description |
---|---|---|---|
bValue | boolean |
Value for the draggable property |
Sets the growing to the internal list
Param | Type | DefaultValue | Description |
---|---|---|---|
bValue | boolean |
Value for the list's growing. |
Sets the growing threshold to the internal list
Param | Type | DefaultValue | Description |
---|---|---|---|
iValue | int |
Value for the list's growing threshold. |
Set the model for the internal list AND the current control so that both controls can be used with data binding
Param | Type | DefaultValue | Description |
---|---|---|---|
oModel | sap.ui.model.Model |
the model that holds the data for the list |
|
sModelName | string |
the optional model name |
Enable/Disable multi selection mode.
Param | Type | DefaultValue | Description |
---|---|---|---|
bMulti | boolean |
Flag for multi selection mode |
Set the internal List's no data text property
Param | Type | DefaultValue | Description |
---|---|---|---|
sNoDataText | string |
The no data text for the list |
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
.
Note: The sap.m.SelectDialog uses this property of the ListBase and therefore its limitations also apply here.
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 |
---|---|---|---|
bRememberSelections | boolean | false |
New value for property |
Sets the resizable property.
Param | Type | DefaultValue | Description |
---|---|---|---|
bValue | boolean |
Value for the resizable property |
Sets the Clear button visible state
Param | Type | DefaultValue | Description |
---|---|---|---|
bVisible | boolean |
Value for the Clear button visible state. |
Set the title of the internal dialog
Param | Type | DefaultValue | Description |
---|---|---|---|
sTitle | string |
The title text for the dialog |
Sets a new value for property titleAlignment.
Specifies the Title alignment (theme specific). If set to TitleAlignment.Auto
, the Title will be aligned as it is set in the theme (if not set, the default value is center
); Other possible values are TitleAlignment.Start
(left or right depending on LTR/RTL), and TitleAlignment.Center
(centered)
When called with a value of null
or undefined
, the default value of the property will be restored.
Default value is Auto
.
Param | Type | DefaultValue | Description |
---|---|---|---|
sTitleAlignment | sap.m.TitleAlignment | Auto |
New value for property |
Forward method to the inner dialog: toggleStyleClass.
Param | Type | DefaultValue | Description |
---|---|---|---|
sStyleClass | string |
CSS class name to add or remove |
|
bAdd | boolean |
Whether style class should be added (or removed); when this parameter is not given, the given style class will be toggled (removed, if present, and added if not present) |