class sap.m.ListBase

Control sample: sap.m.ListBase
Visiblity: public
UX Guidelines:
Implements:
Available since: N/A
Module: sap/m/ListBase
Application Component: CA-UI5-TBL

The sap.m.ListBase control provides a base functionality of the sap.m.List and sap.m.Table controls. Selection, deletion, unread states and inset style are also maintained in sap.m.ListBase.

See section "List, List Item, and Table" in the documentation for an introduction to subclasses of sap.m.ListBase control.

Note: The ListBase including all contained items may be completely re-rendered when the data of a bound model is changed. Due to the limited hardware resources of mobile devices this can lead to longer delays for lists that contain many items. As such the usage of a list is not recommended for these use cases.

This control can be a drag source.
This control can be a drop target.

Constructor

Constructor for a new ListBase.

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.ListBase(sId?, mSettings?)
Param Type Default Value Description
sId? string

Id for the new control, generated automatically if no id is given

mSettings? object

Initial settings for the new control


Properties

Name Type Default Value Description
enableBusyIndicator boolean true

When this property is set to true, the control will automatically display a busy indicator when it detects that data is being loaded. This busy indicator blocks the interaction with the items until data loading is finished. By default, the busy indicator will be shown after one second. This behavior can be customized by setting the busyIndicatorDelay property.

Since: 1.20.2.

Visibility: public
footerText string

Defines the footer text that appears in the control.

Visibility: public
growing boolean false

If set to true, enables the growing feature of the control to load more items by requesting from the model. Note:: This feature only works when an items aggregation is bound. Growing must not be used together with two-way binding.

Since: 1.16.0.

Visibility: public
growingDirection sap.m.ListGrowingDirection Downwards

Defines the direction of the growing feature. If set to Downwards the user has to scroll down to load more items or the growing button is displayed at the bottom. If set to Upwards the user has to scroll up to load more items or the growing button is displayed at the top.

Since: 1.40.0.

Visibility: public
growingScrollToLoad boolean false

If set to true, the user can scroll down/up to load more items. Otherwise a growing button is displayed at the bottom/top of the control. Note: This property can only be used if the growing property is set to true and only if there is one instance of sap.m.List or sap.m.Table inside the scrollable scroll container (e.g sap.m.Page).

Since: 1.16.0.

Visibility: public
growingThreshold int 20

Defines the number of items to be requested from the model for each grow. This property can only be used if the growing property is set to true.

Since: 1.16.0.

Visibility: public
growingTriggerText string

Defines the text displayed on the growing button. The default is a translated text ("More") coming from the message bundle. This property can only be used if the growing property is set to true.

Since: 1.16.0.

Visibility: public
headerDesign sap.m.ListHeaderDesign Standard

Defines the header style of the control. Possible values are Standard and Plain.

Since: 1.14.

Visibility: public
headerText string

Defines the header text that appears in the control. Note: If headerToolbar aggregation is set, then this property is ignored.

Visibility: public
includeItemInSelection boolean false

Defines whether the items are selectable by clicking on the item itself (true) rather than having to set the selection control first. Note: The SingleSelectMaster mode also provides this functionality by default.

Visibility: public
inset boolean false

Defines the indentation of the container. Setting it to true indents the list.

Visibility: public
keyboardMode sap.m.ListKeyboardMode Navigation

Defines keyboard handling behavior of the control.

Since: 1.38.0.

Visibility: public
mode sap.m.ListMode None

Defines the mode of the control (e.g. None, SingleSelect, MultiSelect, Delete).

Visibility: public
modeAnimationOn boolean true

Defines if animations will be shown while switching between modes.

Visibility: public
multiSelectMode sap.m.MultiSelectMode Default

Defines the multi-selection mode for the control. If this property is set to the Default value, the sap.m.Table control renders the Select All checkbox in the column header, otherwise the Deselect All icon is rendered. The Select All checkbox allows the user to select all the items in the control, and the Deselect All icon deselects the items. If the property is set to ClearAll, then selecting items via the selectAll method is not possible. See selectAll for more details.

Note: This property must be used with the MultiSelect mode. If this property is set to ClearAll, then a selection of multiple items is still possible via the range selection feature except CTRL + A. Additionally, the CTRL + SHIFT + A key combination can be used for deselecting all the items. For details on the range selection, please see Keyboard Handling for Item Selection.

Since: 1.93.

Visibility: public
noDataText string

This text is displayed when the control contains no items.

Visibility: public
rememberSelections boolean true

If set to true, this control remembers and retains the selection of the items after a binding update has been performed (e.g. sorting, filtering). Note: This feature works only if two-way data binding for the selected property of the item is not used. It also needs to be turned off if the binding context of the item does not always point to the same entry in the model, for example, if the order of the data in the JSONModel is changed.

Since: 1.16.6.

Visibility: public
showNoData boolean true

Defines whether or not the text specified in the noDataText property is displayed.

Visibility: public
showSeparators sap.m.ListSeparators All

Defines which item separator style will be used.

Visibility: public
showUnread boolean false

Activates the unread indicator for all items, if set to true.

Visibility: public
sticky sap.m.Sticky[]

Defines the section of the control that remains fixed at the top of the page during vertical scrolling as long as the control is in the viewport.

Note: Enabling sticky column headers in List controls will not have any effect.

There are some known restrictions. A few are given below:

  • If the control is placed in layout containers that have the overflow: hidden or overflow: auto style definition, this can prevent the sticky elements of the control from becoming fixed at the top of the viewport.
  • If sticky column headers are enabled in the sap.m.Table control, setting focus on the column headers will let the table scroll to the top.
  • A transparent toolbar design is not supported for sticky bars. The toolbar will automatically get an intransparent background color.
  • This feature supports only the default height of the toolbar control.


Since: 1.58.

Visibility: public
swipeDirection sap.m.SwipeDirection Both

Defines the direction of the swipe movement (e.g LeftToRight, RightToLeft, Both) to display the control defined in the swipeContent aggregation.

Visibility: public
width sap.ui.core.CSSSize 100%

Sets the width of the control.

Visibility: public

Aggregations

Default Aggregation: items

Name Cardinality Type Description
_messageStrip 0..1 sap.m.MessageStrip

Defines the message strip to display binding-related messages.

Since: 1.73.

contextMenu 0..1 sap.ui.core.IContextMenu

Defines the context menu of the items.

Since: 1.54.

headerToolbar 0..1 sap.m.Toolbar

The header area can be used as a toolbar to add extra controls for user interactions. Note: When set, this overwrites the headerText property.

Since: 1.16.

infoToolbar 0..1 sap.m.Toolbar

A toolbar that is placed below the header to show extra information to the user.

Since: 1.16.

items (default) 0..n sap.m.ListItemBase

Defines the items contained within this control.

swipeContent 0..1 sap.ui.core.Control

User can swipe to bring in this control on the right hand side of an item. Note:

  • For non-touch screen devices, this functionality is ignored.
  • There is no accessible alternative provided by the control for swiping. Applications that use this functionality must provide an accessible alternative UI to perform the same action.

Associations

Name Cardinality Type Description
ariaLabelledBy 0..n sap.ui.core.Control

Association to controls / ids which label this control (see WAI-ARIA attribute aria-labelledby).

Since: 1.28.0.


Events Overview

Event Description
beforeOpenContextMenu

Fired when the context menu is opened. When the context menu is opened, the binding context of the item is set to the given contextMenu.

Listeners may prevent the default action of this event by calling the preventDefault method on the event object.

Since: 1.54.

delete

Fires when delete icon is pressed by user.

growingFinished

Fires after the new growing chunk has been fetched from the model and processed by the control.

Since: 1.16.

growingStarted

Fires before the new growing chunk is requested from the model.

Since: 1.16.

itemPress

Fires when an item is pressed unless the item's type property is Inactive.

Since: 1.20.

select

Fires when selection is changed via user interaction. In MultiSelect mode, this event is also fired on deselection.

selectionChange

Fires when selection is changed via user interaction inside the control.

Since: 1.16.

swipe

Fires after user's swipe action and before the swipeContent is shown. On the swipe event handler, swipeContent can be changed according to the swiped item. Calling the preventDefault method of the event cancels the swipe action.

Note: There is no accessible alternative provided by the control for swiping. Applications that use this functionality must provide an accessible alternative UI to perform the same action.

Listeners may prevent the default action of this event by calling the preventDefault method on the event object.

updateFinished

Fires after items binding is updated and processed by the control.

Since: 1.16.3.

updateStarted

Fires before items binding is updated (e.g. sorting, filtering)

Note: Event handler should not invalidate the control.

Since: 1.16.3.

beforeOpenContextMenu

Fired when the context menu is opened. When the context menu is opened, the binding context of the item is set to the given contextMenu.

Listeners may prevent the default action of this event by calling the preventDefault method on the event object.

Since: 1.54.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
listItem sap.m.ListItemBase

Item in which the context menu was opened.

delete

Fires when delete icon is pressed by user.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
listItem sap.m.ListItemBase

The item which fired the delete event.

growingFinished

Fires after the new growing chunk has been fetched from the model and processed by the control.

Since: 1.16.

Instead, use "updateFinished" event.
Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
actual int

Actual number of items.

total int

Total number of items.

growingStarted

Fires before the new growing chunk is requested from the model.

Since: 1.16.

Instead, use <code>updateStarted</code> event with listening <code>changeReason</code>.
Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
actual int

Actual number of items.

total int

Total number of items.

itemPress

Fires when an item is pressed unless the item's type property is Inactive.

Since: 1.20.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
listItem sap.m.ListItemBase

The item which fired the pressed event.

srcControl sap.ui.core.Control

The control which caused the press event within the container.

select

Fires when selection is changed via user interaction. In MultiSelect mode, this event is also fired on deselection.

Use the <code>selectionChange</code> event instead.
Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
listItem sap.m.ListItemBase

The item which fired the select event.

selectionChange

Fires when selection is changed via user interaction inside the control.

Since: 1.16.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
listItem sap.m.ListItemBase

The item whose selection has changed. In MultiSelect mode, only the up-most selected item is returned. This parameter can be used for single-selection modes.

listItems sap.m.ListItemBase[]

Array of items whose selection has changed. This parameter can be used for MultiSelect mode.

selected boolean

Indicates whether the listItem parameter is selected or not.

selectAll boolean

Indicates whether the select all action is triggered or not.

swipe

Fires after user's swipe action and before the swipeContent is shown. On the swipe event handler, swipeContent can be changed according to the swiped item. Calling the preventDefault method of the event cancels the swipe action.

Note: There is no accessible alternative provided by the control for swiping. Applications that use this functionality must provide an accessible alternative UI to perform the same action.

Listeners may prevent the default action of this event by calling the preventDefault method on the event object.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
listItem sap.m.ListItemBase

The item which fired the swipe.

swipeContent sap.ui.core.Control

Aggregated swipeContent control that is shown on the right hand side of the item.

srcControl sap.ui.core.Control

Holds which control caused the swipe event within the item.

swipeDirection sap.m.SwipeDirection

Shows in which direction the user swipes and can have the value BeginToEnd (left to right in LTR languages and right to left in RTL languages) or EndToBegin (right to left in LTR languages and left to right in RTL languages)

updateFinished

Fires after items binding is updated and processed by the control.

Since: 1.16.3.

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

The reason of the update, e.g. Binding, Filter, Sort, Growing, Change, Refresh, Context.

actual int

Actual number of items.

total int

The total count of bound items. This can be used if the growing property is set to true.

updateStarted

Fires before items binding is updated (e.g. sorting, filtering)

Note: Event handler should not invalidate the control.

Since: 1.16.3.

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

The reason of the update, e.g. Binding, Filter, Sort, Growing, Change, Refresh, Context.

actual int

Actual number of items.

total int

The total count of bound items. This can be used if the growing property is set to true.


Methods Overview

Method Description
addAriaLabelledBy

Adds some ariaLabelledBy into the association ariaLabelledBy.

addItem

Adds some item to the aggregation items.

attachBeforeOpenContextMenu

Attaches event handler fnFunction to the beforeOpenContextMenu event of this sap.m.ListBase.

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

Fired when the context menu is opened. When the context menu is opened, the binding context of the item is set to the given contextMenu.

attachDelete

Attaches event handler fnFunction to the delete event of this sap.m.ListBase.

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

Fires when delete icon is pressed by user.

attachGrowingFinished

Attaches event handler fnFunction to the growingFinished event of this sap.m.ListBase.

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

Fires after the new growing chunk has been fetched from the model and processed by the control.

Since 1.16.3 Instead, use "updateFinished" event.
attachGrowingStarted

Attaches event handler fnFunction to the growingStarted event of this sap.m.ListBase.

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

Fires before the new growing chunk is requested from the model.

Since 1.16.3 Instead, use <code>updateStarted</code> event with listening <code>changeReason</code>.
attachItemPress

Attaches event handler fnFunction to the itemPress event of this sap.m.ListBase.

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

Fires when an item is pressed unless the item's type property is Inactive.

attachSelect

Attaches event handler fnFunction to the select event of this sap.m.ListBase.

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

Fires when selection is changed via user interaction. In MultiSelect mode, this event is also fired on deselection.

Since 1.16 Use the <code>selectionChange</code> event instead.
attachSelectionChange

Attaches event handler fnFunction to the selectionChange event of this sap.m.ListBase.

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

Fires when selection is changed via user interaction inside the control.

attachSwipe

Attaches event handler fnFunction to the swipe event of this sap.m.ListBase.

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

Fires after user's swipe action and before the swipeContent is shown. On the swipe event handler, swipeContent can be changed according to the swiped item. Calling the preventDefault method of the event cancels the swipe action.

Note: There is no accessible alternative provided by the control for swiping. Applications that use this functionality must provide an accessible alternative UI to perform the same action.

attachUpdateFinished

Attaches event handler fnFunction to the updateFinished event of this sap.m.ListBase.

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

Fires after items binding is updated and processed by the control.

attachUpdateStarted

Attaches event handler fnFunction to the updateStarted event of this sap.m.ListBase.

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

Fires before items binding is updated (e.g. sorting, filtering)

Note: Event handler should not invalidate the control.

bindItems

Binds aggregation items to model data.

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

destroyContextMenu

Destroys the contextMenu in the aggregation contextMenu.

destroyHeaderToolbar

Destroys the headerToolbar in the aggregation headerToolbar.

destroyInfoToolbar

Destroys the infoToolbar in the aggregation infoToolbar.

destroyItems

Destroys all the items in the aggregation items.

destroySwipeContent

Destroys the swipeContent in the aggregation swipeContent.

detachBeforeOpenContextMenu

Detaches event handler fnFunction from the beforeOpenContextMenu event of this sap.m.ListBase.

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

detachDelete

Detaches event handler fnFunction from the delete event of this sap.m.ListBase.

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

detachGrowingFinished

Detaches event handler fnFunction from the growingFinished event of this sap.m.ListBase.

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

Since 1.16.3 Instead, use "updateFinished" event.
detachGrowingStarted

Detaches event handler fnFunction from the growingStarted event of this sap.m.ListBase.

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

Since 1.16.3 Instead, use <code>updateStarted</code> event with listening <code>changeReason</code>.
detachItemPress

Detaches event handler fnFunction from the itemPress event of this sap.m.ListBase.

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

detachSelect

Detaches event handler fnFunction from the select event of this sap.m.ListBase.

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

Since 1.16 Use the <code>selectionChange</code> event instead.
detachSelectionChange

Detaches event handler fnFunction from the selectionChange event of this sap.m.ListBase.

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

detachSwipe

Detaches event handler fnFunction from the swipe event of this sap.m.ListBase.

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

detachUpdateFinished

Detaches event handler fnFunction from the updateFinished event of this sap.m.ListBase.

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

detachUpdateStarted

Detaches event handler fnFunction from the updateStarted event of this sap.m.ListBase.

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

sap.m.ListBase.extend

Creates a new subclass of class sap.m.ListBase 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.

fireBeforeOpenContextMenu

Fires event beforeOpenContextMenu to attached listeners.

Listeners may prevent the default action of this event by calling the preventDefault method on the event object. The return value of this method indicates whether the default action should be executed.

fireDelete

Fires event delete to attached listeners.

fireGrowingFinished

Fires event growingFinished to attached listeners.

Since 1.16.3 Instead, use "updateFinished" event.
fireGrowingStarted

Fires event growingStarted to attached listeners.

Since 1.16.3 Instead, use <code>updateStarted</code> event with listening <code>changeReason</code>.
fireItemPress

Fires event itemPress to attached listeners.

fireSelect

Fires event select to attached listeners.

Since 1.16 Use the <code>selectionChange</code> event instead.
fireSelectionChange

Fires event selectionChange to attached listeners.

fireSwipe

Fires event swipe to attached listeners.

Listeners may prevent the default action of this event by calling the preventDefault method on the event object. The return value of this method indicates whether the default action should be executed.

fireUpdateFinished

Fires event updateFinished to attached listeners.

fireUpdateStarted

Fires event updateStarted to attached listeners.

getAriaLabelledBy

Returns array of IDs of the elements which are the current targets of the association ariaLabelledBy.

getContextMenu

Gets content of aggregation contextMenu.

Defines the context menu of the items.

getEnableBusyIndicator

Gets current value of property enableBusyIndicator.

When this property is set to true, the control will automatically display a busy indicator when it detects that data is being loaded. This busy indicator blocks the interaction with the items until data loading is finished. By default, the busy indicator will be shown after one second. This behavior can be customized by setting the busyIndicatorDelay property.

Default value is true.

getFooterText

Gets current value of property footerText.

Defines the footer text that appears in the control.

getGrowing

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 model. Note:: This feature only works when an items aggregation is bound. Growing must not be used together with two-way binding.

Default value is false.

getGrowingDirection

Gets current value of property growingDirection.

Defines the direction of the growing feature. If set to Downwards the user has to scroll down to load more items or the growing button is displayed at the bottom. If set to Upwards the user has to scroll up to load more items or the growing button is displayed at the top.

Default value is Downwards.

getGrowingInfo

Returns growing information as object with "actual" and "total" keys. Note: This function returns "null" if "growing" feature is disabled.

getGrowingScrollToLoad

Gets current value of property growingScrollToLoad.

If set to true, the user can scroll down/up to load more items. Otherwise a growing button is displayed at the bottom/top of the control. Note: This property can only be used if the growing property is set to true and only if there is one instance of sap.m.List or sap.m.Table inside the scrollable scroll container (e.g sap.m.Page).

Default value is false.

getGrowingThreshold

Gets current value of property growingThreshold.

Defines the number of items to be requested from the model for each grow. This property can only be used if the growing property is set to true.

Default value is 20.

getGrowingTriggerText

Gets current value of property growingTriggerText.

Defines the text displayed on the growing button. The default is a translated text ("More") coming from the message bundle. This property can only be used if the growing property is set to true.

getHeaderDesign

Gets current value of property headerDesign.

Defines the header style of the control. Possible values are Standard and Plain.

Default value is Standard.

Since 1.16 No longer has any functionality.
getHeaderText

Gets current value of property headerText.

Defines the header text that appears in the control. Note: If headerToolbar aggregation is set, then this property is ignored.

getHeaderToolbar

Gets content of aggregation headerToolbar.

The header area can be used as a toolbar to add extra controls for user interactions. Note: When set, this overwrites the headerText property.

getIncludeItemInSelection

Gets current value of property includeItemInSelection.

Defines whether the items are selectable by clicking on the item itself (true) rather than having to set the selection control first. Note: The SingleSelectMaster mode also provides this functionality by default.

Default value is false.

getInfoToolbar

Gets content of aggregation infoToolbar.

A toolbar that is placed below the header to show extra information to the user.

getInset

Gets current value of property inset.

Defines the indentation of the container. Setting it to true indents the list.

Default value is false.

getItemNavigation

Returns the ItemNavigation delegate of the list

getItems

Gets content of aggregation items.

Defines the items contained within this control.

getKeyboardMode

Gets current value of property keyboardMode.

Defines keyboard handling behavior of the control.

Default value is Navigation.

getLastMode

Returns the last list mode, the mode that is rendered This can be used to detect mode changes during rendering

sap.m.ListBase.getMetadata

Returns a metadata object for class sap.m.ListBase.

getMode

Gets current value of property mode.

Defines the mode of the control (e.g. None, SingleSelect, MultiSelect, Delete).

Default value is None.

getModeAnimationOn

Gets current value of property modeAnimationOn.

Defines if animations will be shown while switching between modes.

Default value is true.

getMultiSelectMode

Gets current value of property multiSelectMode.

Defines the multi-selection mode for the control. If this property is set to the Default value, the sap.m.Table control renders the Select All checkbox in the column header, otherwise the Deselect All icon is rendered. The Select All checkbox allows the user to select all the items in the control, and the Deselect All icon deselects the items. If the property is set to ClearAll, then selecting items via the selectAll method is not possible. See selectAll for more details.

Note: This property must be used with the MultiSelect mode. If this property is set to ClearAll, then a selection of multiple items is still possible via the range selection feature except CTRL + A. Additionally, the CTRL + SHIFT + A key combination can be used for deselecting all the items. For details on the range selection, please see Keyboard Handling for Item Selection.

Default value is Default.

getNoDataText

Gets current value of property noDataText.

This text is displayed when the control contains no items.

getRememberSelections

Gets current value of property rememberSelections.

If set to true, this control remembers and retains the selection of the items after a binding update has been performed (e.g. sorting, filtering). Note: This feature works only if two-way data binding for the selected property of the item is not used. It also needs to be turned off if the binding context of the item does not always point to the same entry in the model, for example, if the order of the data in the JSONModel is changed.

Default value is true.

getSelectedContexts

Returns the binding contexts of the selected items. Note: This method returns an empty array if no databinding is used.

getSelectedItem

Returns selected list item. When no item is selected, "null" is returned. When "multi-selection" is enabled and multiple items are selected, only the up-most selected item is returned.

getSelectedItems

Returns an array containing the selected list items. If no items are selected, an empty array is returned.

getShowNoData

Gets current value of property showNoData.

Defines whether or not the text specified in the noDataText property is displayed.

Default value is true.

getShowSeparators

Gets current value of property showSeparators.

Defines which item separator style will be used.

Default value is All.

getShowUnread

Gets current value of property showUnread.

Activates the unread indicator for all items, if set to true.

Default value is false.

getSticky

Gets current value of property sticky.

Defines the section of the control that remains fixed at the top of the page during vertical scrolling as long as the control is in the viewport.

Note: Enabling sticky column headers in List controls will not have any effect.

There are some known restrictions. A few are given below:

  • If the control is placed in layout containers that have the overflow: hidden or overflow: auto style definition, this can prevent the sticky elements of the control from becoming fixed at the top of the viewport.
  • If sticky column headers are enabled in the sap.m.Table control, setting focus on the column headers will let the table scroll to the top.
  • A transparent toolbar design is not supported for sticky bars. The toolbar will automatically get an intransparent background color.
  • This feature supports only the default height of the toolbar control.

getSwipeContent

Gets content of aggregation swipeContent.

User can swipe to bring in this control on the right hand side of an item. Note:

  • For non-touch screen devices, this functionality is ignored.
  • There is no accessible alternative provided by the control for swiping. Applications that use this functionality must provide an accessible alternative UI to perform the same action.
getSwipeDirection

Gets current value of property swipeDirection.

Defines the direction of the swipe movement (e.g LeftToRight, RightToLeft, Both) to display the control defined in the swipeContent aggregation.

Default value is Both.

getSwipedItem

Returns swiped list item. When no item is swiped, "null" is returned.

getWidth

Gets current value of property width.

Sets the width of the control.

Default value is "100%".

indexOfItem

Checks for the provided sap.m.ListItemBase in the aggregation items. and returns its index if found or -1 otherwise.

insertItem

Inserts a item into the aggregation items.

removeAllAriaLabelledBy

Removes all the controls in the association named ariaLabelledBy.

removeAllItems

Removes all the controls from the aggregation items.

Additionally, it unregisters them from the hosting UIArea.

removeAriaLabelledBy

Removes an ariaLabelledBy from the association named ariaLabelledBy.

removeItem

Removes a item from the aggregation items.

removeSelections

Removes visible selections of the current selection mode.

requestItems

Requests a specified number of items from the back end to load more data in the list. If the number of items are not specified, the growingThreshold value is used to request more data.

Note: To use this method, the growing feature must be enabled.

See growing and growingThreshold for more information.

scrollToIndex

Scrolls the list so that the item with the given index is in the viewport. If the index is -1, it scrolls to the bottom of the list. If the growing feature is enabled, the list is scrolled to the last available item.

Growing in combination with growingScrollToLoad=true can result in loading of new items when scrolling to the bottom of the list.

selectAll

Selects all items in the MultiSelection mode.

Note: If growing is enabled, only the visible items in the list are selected. Since version 1.93, the items are not selected if getMultiSelectMode=ClearAll.

setContextMenu

Sets the aggregated contextMenu.

setEnableBusyIndicator

Sets a new value for property enableBusyIndicator.

When this property is set to true, the control will automatically display a busy indicator when it detects that data is being loaded. This busy indicator blocks the interaction with the items until data loading is finished. By default, the busy indicator will be shown after one second. This behavior can be customized by setting the busyIndicatorDelay property.

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

Default value is true.

setFooterText

Sets a new value for property footerText.

Defines the footer text that appears in the control.

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

setGrowing

Sets a new value for property growing.

If set to true, enables the growing feature of the control to load more items by requesting from the model. Note:: This feature only works when an items aggregation is bound. Growing must not be used together with two-way binding.

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

Default value is false.

setGrowingDirection

Sets a new value for property growingDirection.

Defines the direction of the growing feature. If set to Downwards the user has to scroll down to load more items or the growing button is displayed at the bottom. If set to Upwards the user has to scroll up to load more items or the growing button is displayed at the top.

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

Default value is Downwards.

setGrowingScrollToLoad

Sets a new value for property growingScrollToLoad.

If set to true, the user can scroll down/up to load more items. Otherwise a growing button is displayed at the bottom/top of the control. Note: This property can only be used if the growing property is set to true and only if there is one instance of sap.m.List or sap.m.Table inside the scrollable scroll container (e.g sap.m.Page).

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

Default value is false.

setGrowingThreshold

Sets a new value for property growingThreshold.

Defines the number of items to be requested from the model for each grow. This property can only be used if the growing property is set to true.

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

Default value is 20.

setGrowingTriggerText

Sets a new value for property growingTriggerText.

Defines the text displayed on the growing button. The default is a translated text ("More") coming from the message bundle. This property can only be used if the growing property is set to true.

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

setHeaderDesign

Sets a new value for property headerDesign.

Defines the header style of the control. Possible values are Standard and Plain.

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

Default value is Standard.

Since 1.16 No longer has any functionality.
setHeaderText

Sets a new value for property headerText.

Defines the header text that appears in the control. Note: If headerToolbar aggregation is set, then this property is ignored.

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

setHeaderToolbar

Sets the aggregated headerToolbar.

setIncludeItemInSelection

Sets a new value for property includeItemInSelection.

Defines whether the items are selectable by clicking on the item itself (true) rather than having to set the selection control first. Note: The SingleSelectMaster mode also provides this functionality by default.

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

Default value is false.

setInfoToolbar

Sets the aggregated infoToolbar.

setInset

Sets a new value for property inset.

Defines the indentation of the container. Setting it to true indents the list.

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

Default value is false.

setKeyboardMode

Sets a new value for property keyboardMode.

Defines keyboard handling behavior of the control.

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

Default value is Navigation.

setMode

Sets a new value for property mode.

Defines the mode of the control (e.g. None, SingleSelect, MultiSelect, Delete).

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

Default value is None.

setModeAnimationOn

Sets a new value for property modeAnimationOn.

Defines if animations will be shown while switching between modes.

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

Default value is true.

setMultiSelectMode

Sets a new value for property multiSelectMode.

Defines the multi-selection mode for the control. If this property is set to the Default value, the sap.m.Table control renders the Select All checkbox in the column header, otherwise the Deselect All icon is rendered. The Select All checkbox allows the user to select all the items in the control, and the Deselect All icon deselects the items. If the property is set to ClearAll, then selecting items via the selectAll method is not possible. See selectAll for more details.

Note: This property must be used with the MultiSelect mode. If this property is set to ClearAll, then a selection of multiple items is still possible via the range selection feature except CTRL + A. Additionally, the CTRL + SHIFT + A key combination can be used for deselecting all the items. For details on the range selection, please see Keyboard Handling for Item Selection.

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

Default value is Default.

setNoDataText

Sets a new value for property noDataText.

This text is displayed when the control contains no items.

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

setRememberSelections

Sets a new value for property rememberSelections.

If set to true, this control remembers and retains the selection of the items after a binding update has been performed (e.g. sorting, filtering). Note: This feature works only if two-way data binding for the selected property of the item is not used. It also needs to be turned off if the binding context of the item does not always point to the same entry in the model, for example, if the order of the data in the JSONModel is changed.

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

Default value is true.

setSelectedItem

Selects or deselects the given list item.

setSelectedItemById

Sets a list item to be selected by id. In single mode the method removes the previous selection.

setShowNoData

Sets a new value for property showNoData.

Defines whether or not the text specified in the noDataText property is displayed.

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

Default value is true.

setShowSeparators

Sets a new value for property showSeparators.

Defines which item separator style will be used.

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

Default value is All.

setShowUnread

Sets a new value for property showUnread.

Activates the unread indicator for all items, if set to true.

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

Default value is false.

setSticky

Sets a new value for property sticky.

Defines the section of the control that remains fixed at the top of the page during vertical scrolling as long as the control is in the viewport.

Note: Enabling sticky column headers in List controls will not have any effect.

There are some known restrictions. A few are given below:

  • If the control is placed in layout containers that have the overflow: hidden or overflow: auto style definition, this can prevent the sticky elements of the control from becoming fixed at the top of the viewport.
  • If sticky column headers are enabled in the sap.m.Table control, setting focus on the column headers will let the table scroll to the top.
  • A transparent toolbar design is not supported for sticky bars. The toolbar will automatically get an intransparent background color.
  • This feature supports only the default height of the toolbar control.

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

setSwipeContent

Sets the aggregated swipeContent.

setSwipeDirection

Sets a new value for property swipeDirection.

Defines the direction of the swipe movement (e.g LeftToRight, RightToLeft, Both) to display the control defined in the swipeContent aggregation.

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

Default value is Both.

setWidth

Sets a new value for property width.

Sets the width of the control.

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

Default value is "100%".

swipeOut

After swipeContent is shown, user can interact with this control(e.g Tap). After interaction is done, you can/should use this method to hide swipeContent from screen. Note: If users try to tap inside of the list but outside of the swipeContent then control hides automatically.

unbindItems

Unbinds aggregation items from model data.

addAriaLabelledBy

Adds some ariaLabelledBy into the association ariaLabelledBy.

Param Type DefaultValue Description
vAriaLabelledBy sap.ui.core.ID sap.ui.core.Control

The ariaLabelledBy to add; if empty, nothing is inserted

addItem

Adds some item to the aggregation items.

Param Type DefaultValue Description
oItem sap.m.ListItemBase

The item to add; if empty, nothing is inserted

attachBeforeOpenContextMenu

Attaches event handler fnFunction to the beforeOpenContextMenu event of this sap.m.ListBase.

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

Fired when the context menu is opened. When the context menu is opened, the binding context of the item is set to the given contextMenu.

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 sap.m.ListBase itself

attachDelete

Attaches event handler fnFunction to the delete event of this sap.m.ListBase.

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

Fires when delete icon is pressed by user.

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 sap.m.ListBase itself

attachGrowingFinished

Attaches event handler fnFunction to the growingFinished event of this sap.m.ListBase.

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

Fires after the new growing chunk has been fetched from the model and processed by the control.

Since 1.16.3 Instead, use "updateFinished" event.
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 sap.m.ListBase itself

attachGrowingStarted

Attaches event handler fnFunction to the growingStarted event of this sap.m.ListBase.

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

Fires before the new growing chunk is requested from the model.

Since 1.16.3 Instead, use <code>updateStarted</code> event with listening <code>changeReason</code>.
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 sap.m.ListBase itself

attachItemPress

Attaches event handler fnFunction to the itemPress event of this sap.m.ListBase.

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

Fires when an item is pressed unless the item's type property is Inactive.

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 sap.m.ListBase itself

attachSelect

Attaches event handler fnFunction to the select event of this sap.m.ListBase.

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

Fires when selection is changed via user interaction. In MultiSelect mode, this event is also fired on deselection.

Since 1.16 Use the <code>selectionChange</code> event instead.
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 sap.m.ListBase itself

attachSelectionChange

Attaches event handler fnFunction to the selectionChange event of this sap.m.ListBase.

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

Fires when selection is changed via user interaction inside the 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 sap.m.ListBase itself

attachSwipe

Attaches event handler fnFunction to the swipe event of this sap.m.ListBase.

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

Fires after user's swipe action and before the swipeContent is shown. On the swipe event handler, swipeContent can be changed according to the swiped item. Calling the preventDefault method of the event cancels the swipe action.

Note: There is no accessible alternative provided by the control for swiping. Applications that use this functionality must provide an accessible alternative UI to perform the same action.

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 sap.m.ListBase itself

attachUpdateFinished

Attaches event handler fnFunction to the updateFinished event of this sap.m.ListBase.

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

Fires after items binding is updated and processed by the 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 sap.m.ListBase itself

attachUpdateStarted

Attaches event handler fnFunction to the updateStarted event of this sap.m.ListBase.

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

Fires before items binding is updated (e.g. sorting, filtering)

Note: Event handler should not invalidate the 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 sap.m.ListBase itself

bindItems

Binds aggregation items to model data.

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

Param Type DefaultValue Description
oBindingInfo sap.ui.base.ManagedObject.AggregationBindingInfo

The binding information

destroyContextMenu

Destroys the contextMenu in the aggregation contextMenu.

destroyHeaderToolbar

Destroys the headerToolbar in the aggregation headerToolbar.

destroyInfoToolbar

Destroys the infoToolbar in the aggregation infoToolbar.

destroyItems

Destroys all the items in the aggregation items.

destroySwipeContent

Destroys the swipeContent in the aggregation swipeContent.

detachBeforeOpenContextMenu

Detaches event handler fnFunction from the beforeOpenContextMenu event of this sap.m.ListBase.

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

detachDelete

Detaches event handler fnFunction from the delete event of this sap.m.ListBase.

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

detachGrowingFinished

Detaches event handler fnFunction from the growingFinished event of this sap.m.ListBase.

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

Since 1.16.3 Instead, use "updateFinished" event.
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

detachGrowingStarted

Detaches event handler fnFunction from the growingStarted event of this sap.m.ListBase.

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

Since 1.16.3 Instead, use <code>updateStarted</code> event with listening <code>changeReason</code>.
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

detachItemPress

Detaches event handler fnFunction from the itemPress event of this sap.m.ListBase.

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

detachSelect

Detaches event handler fnFunction from the select event of this sap.m.ListBase.

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

Since 1.16 Use the <code>selectionChange</code> event instead.
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

detachSelectionChange

Detaches event handler fnFunction from the selectionChange event of this sap.m.ListBase.

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

detachSwipe

Detaches event handler fnFunction from the swipe event of this sap.m.ListBase.

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

detachUpdateFinished

Detaches event handler fnFunction from the updateFinished event of this sap.m.ListBase.

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

detachUpdateStarted

Detaches event handler fnFunction from the updateStarted event of this sap.m.ListBase.

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

sap.m.ListBase.extend

Creates a new subclass of class sap.m.ListBase 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.

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

fireBeforeOpenContextMenu

Fires event beforeOpenContextMenu to attached listeners.

Listeners may prevent the default action of this event by calling the preventDefault method on the event object. The return value of this method indicates whether the default action should be executed.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

listItem sap.m.ListItemBase

Item in which the context menu was opened.

fireDelete

Fires event delete to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

listItem sap.m.ListItemBase

The item which fired the delete event.

fireGrowingFinished

Fires event growingFinished to attached listeners.

Since 1.16.3 Instead, use "updateFinished" event.
Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

actual int

Actual number of items.

total int

Total number of items.

fireGrowingStarted

Fires event growingStarted to attached listeners.

Since 1.16.3 Instead, use <code>updateStarted</code> event with listening <code>changeReason</code>.
Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

actual int

Actual number of items.

total int

Total number of items.

fireItemPress

Fires event itemPress to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

listItem sap.m.ListItemBase

The item which fired the pressed event.

srcControl sap.ui.core.Control

The control which caused the press event within the container.

fireSelect

Fires event select to attached listeners.

Since 1.16 Use the <code>selectionChange</code> event instead.
Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

listItem sap.m.ListItemBase

The item which fired the select event.

fireSelectionChange

Fires event selectionChange to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

listItem sap.m.ListItemBase

The item whose selection has changed. In MultiSelect mode, only the up-most selected item is returned. This parameter can be used for single-selection modes.

listItems sap.m.ListItemBase[]

Array of items whose selection has changed. This parameter can be used for MultiSelect mode.

selected boolean

Indicates whether the listItem parameter is selected or not.

selectAll boolean

Indicates whether the select all action is triggered or not.

fireSwipe

Fires event swipe to attached listeners.

Listeners may prevent the default action of this event by calling the preventDefault method on the event object. The return value of this method indicates whether the default action should be executed.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

listItem sap.m.ListItemBase

The item which fired the swipe.

swipeContent sap.ui.core.Control

Aggregated swipeContent control that is shown on the right hand side of the item.

srcControl sap.ui.core.Control

Holds which control caused the swipe event within the item.

swipeDirection sap.m.SwipeDirection

Shows in which direction the user swipes and can have the value BeginToEnd (left to right in LTR languages and right to left in RTL languages) or EndToBegin (right to left in LTR languages and left to right in RTL languages)

fireUpdateFinished

Fires event updateFinished to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

reason string

The reason of the update, e.g. Binding, Filter, Sort, Growing, Change, Refresh, Context.

actual int

Actual number of items.

total int

The total count of bound items. This can be used if the growing property is set to true.

fireUpdateStarted

Fires event updateStarted to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

reason string

The reason of the update, e.g. Binding, Filter, Sort, Growing, Change, Refresh, Context.

actual int

Actual number of items.

total int

The total count of bound items. This can be used if the growing property is set to true.

getAriaLabelledBy

Returns array of IDs of the elements which are the current targets of the association ariaLabelledBy.

getContextMenu

Gets content of aggregation contextMenu.

Defines the context menu of the items.

getEnableBusyIndicator

Gets current value of property enableBusyIndicator.

When this property is set to true, the control will automatically display a busy indicator when it detects that data is being loaded. This busy indicator blocks the interaction with the items until data loading is finished. By default, the busy indicator will be shown after one second. This behavior can be customized by setting the busyIndicatorDelay property.

Default value is true.

getFooterText

Gets current value of property footerText.

Defines the footer text that appears in the control.

getGrowing

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 model. Note:: This feature only works when an items aggregation is bound. Growing must not be used together with two-way binding.

Default value is false.

getGrowingDirection

Gets current value of property growingDirection.

Defines the direction of the growing feature. If set to Downwards the user has to scroll down to load more items or the growing button is displayed at the bottom. If set to Upwards the user has to scroll up to load more items or the growing button is displayed at the top.

Default value is Downwards.

getGrowingInfo

Returns growing information as object with "actual" and "total" keys. Note: This function returns "null" if "growing" feature is disabled.

getGrowingScrollToLoad

Gets current value of property growingScrollToLoad.

If set to true, the user can scroll down/up to load more items. Otherwise a growing button is displayed at the bottom/top of the control. Note: This property can only be used if the growing property is set to true and only if there is one instance of sap.m.List or sap.m.Table inside the scrollable scroll container (e.g sap.m.Page).

Default value is false.

getGrowingThreshold

Gets current value of property growingThreshold.

Defines the number of items to be requested from the model for each grow. This property can only be used if the growing property is set to true.

Default value is 20.

getGrowingTriggerText

Gets current value of property growingTriggerText.

Defines the text displayed on the growing button. The default is a translated text ("More") coming from the message bundle. This property can only be used if the growing property is set to true.

getHeaderDesign

Gets current value of property headerDesign.

Defines the header style of the control. Possible values are Standard and Plain.

Default value is Standard.

Since 1.16 No longer has any functionality.

getHeaderText

Gets current value of property headerText.

Defines the header text that appears in the control. Note: If headerToolbar aggregation is set, then this property is ignored.

getHeaderToolbar

Gets content of aggregation headerToolbar.

The header area can be used as a toolbar to add extra controls for user interactions. Note: When set, this overwrites the headerText property.

getIncludeItemInSelection

Gets current value of property includeItemInSelection.

Defines whether the items are selectable by clicking on the item itself (true) rather than having to set the selection control first. Note: The SingleSelectMaster mode also provides this functionality by default.

Default value is false.

getInfoToolbar

Gets content of aggregation infoToolbar.

A toolbar that is placed below the header to show extra information to the user.

getInset

Gets current value of property inset.

Defines the indentation of the container. Setting it to true indents the list.

Default value is false.

getItemNavigation

Returns the ItemNavigation delegate of the list

getItems

Gets content of aggregation items.

Defines the items contained within this control.

getKeyboardMode

Gets current value of property keyboardMode.

Defines keyboard handling behavior of the control.

Default value is Navigation.

getLastMode

Returns the last list mode, the mode that is rendered This can be used to detect mode changes during rendering

sap.m.ListBase.getMetadata

Returns a metadata object for class sap.m.ListBase.

getMode

Gets current value of property mode.

Defines the mode of the control (e.g. None, SingleSelect, MultiSelect, Delete).

Default value is None.

getModeAnimationOn

Gets current value of property modeAnimationOn.

Defines if animations will be shown while switching between modes.

Default value is true.

getMultiSelectMode

Gets current value of property multiSelectMode.

Defines the multi-selection mode for the control. If this property is set to the Default value, the sap.m.Table control renders the Select All checkbox in the column header, otherwise the Deselect All icon is rendered. The Select All checkbox allows the user to select all the items in the control, and the Deselect All icon deselects the items. If the property is set to ClearAll, then selecting items via the selectAll method is not possible. See selectAll for more details.

Note: This property must be used with the MultiSelect mode. If this property is set to ClearAll, then a selection of multiple items is still possible via the range selection feature except CTRL + A. Additionally, the CTRL + SHIFT + A key combination can be used for deselecting all the items. For details on the range selection, please see Keyboard Handling for Item Selection.

Default value is Default.

getNoDataText

Gets current value of property noDataText.

This text is displayed when the control contains no items.

getRememberSelections

Gets current value of property rememberSelections.

If set to true, this control remembers and retains the selection of the items after a binding update has been performed (e.g. sorting, filtering). Note: This feature works only if two-way data binding for the selected property of the item is not used. It also needs to be turned off if the binding context of the item does not always point to the same entry in the model, for example, if the order of the data in the JSONModel is changed.

Default value is true.

getSelectedContexts

Returns the binding contexts of the selected items. Note: This method returns an empty array if no databinding is used.

Param Type DefaultValue Description
bAll boolean false

Set true to include even invisible selected items(e.g. the selections from the previous filters). Note: In single selection modes, only the last selected item's binding context is returned in array.

getSelectedItem

Returns selected list item. When no item is selected, "null" is returned. When "multi-selection" is enabled and multiple items are selected, only the up-most selected item is returned.

getSelectedItems

Returns an array containing the selected list items. If no items are selected, an empty array is returned.

getShowNoData

Gets current value of property showNoData.

Defines whether or not the text specified in the noDataText property is displayed.

Default value is true.

getShowSeparators

Gets current value of property showSeparators.

Defines which item separator style will be used.

Default value is All.

getShowUnread

Gets current value of property showUnread.

Activates the unread indicator for all items, if set to true.

Default value is false.

getSticky

Gets current value of property sticky.

Defines the section of the control that remains fixed at the top of the page during vertical scrolling as long as the control is in the viewport.

Note: Enabling sticky column headers in List controls will not have any effect.

There are some known restrictions. A few are given below:

getSwipeContent

Gets content of aggregation swipeContent.

User can swipe to bring in this control on the right hand side of an item. Note:

getSwipeDirection

Gets current value of property swipeDirection.

Defines the direction of the swipe movement (e.g LeftToRight, RightToLeft, Both) to display the control defined in the swipeContent aggregation.

Default value is Both.

getSwipedItem

Returns swiped list item. When no item is swiped, "null" is returned.

getWidth

Gets current value of property width.

Sets the width of the control.

Default value is "100%".

indexOfItem

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

insertItem

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

removeAllAriaLabelledBy

Removes all the controls in the association named ariaLabelledBy.

removeAllItems

Removes all the controls from the aggregation items.

Additionally, it unregisters them from the hosting UIArea.

removeAriaLabelledBy

Removes an ariaLabelledBy from the association named ariaLabelledBy.

Param Type DefaultValue Description
vAriaLabelledBy int sap.ui.core.ID sap.ui.core.Control

The ariaLabelledBy to be removed or its index or ID

removeItem

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

removeSelections

Removes visible selections of the current selection mode.

Param Type DefaultValue Description
bAll boolean

Since version 1.16.3. This control keeps old selections after filter or sorting. Set this parameter "true" to remove all selections.

requestItems

Requests a specified number of items from the back end to load more data in the list. If the number of items are not specified, the growingThreshold value is used to request more data.

Note: To use this method, the growing feature must be enabled.

See growing and growingThreshold for more information.

Param Type DefaultValue Description
iItems int

A positive number of items to be requested

scrollToIndex

Scrolls the list so that the item with the given index is in the viewport. If the index is -1, it scrolls to the bottom of the list. If the growing feature is enabled, the list is scrolled to the last available item.

Growing in combination with growingScrollToLoad=true can result in loading of new items when scrolling to the bottom of the list.

Param Type DefaultValue Description
iIndex number

The list item index that must be scrolled into the viewport

selectAll

Selects all items in the MultiSelection mode.

Note: If growing is enabled, only the visible items in the list are selected. Since version 1.93, the items are not selected if getMultiSelectMode=ClearAll.

setContextMenu

Sets the aggregated contextMenu.

Param Type DefaultValue Description
oContextMenu sap.ui.core.IContextMenu

The contextMenu to set

setEnableBusyIndicator

Sets a new value for property enableBusyIndicator.

When this property is set to true, the control will automatically display a busy indicator when it detects that data is being loaded. This busy indicator blocks the interaction with the items until data loading is finished. By default, the busy indicator will be shown after one second. This behavior can be customized by setting the busyIndicatorDelay property.

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

Default value is true.

Param Type DefaultValue Description
bEnableBusyIndicator boolean true

New value for property enableBusyIndicator

setFooterText

Sets a new value for property footerText.

Defines the footer text that appears in the control.

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

Param Type DefaultValue Description
sFooterText string

New value for property footerText

setGrowing

Sets a new value for property growing.

If set to true, enables the growing feature of the control to load more items by requesting from the model. Note:: This feature only works when an items aggregation is bound. Growing must not be used together with two-way binding.

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

New value for property growing

setGrowingDirection

Sets a new value for property growingDirection.

Defines the direction of the growing feature. If set to Downwards the user has to scroll down to load more items or the growing button is displayed at the bottom. If set to Upwards the user has to scroll up to load more items or the growing button is displayed at the top.

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

Default value is Downwards.

Param Type DefaultValue Description
sGrowingDirection sap.m.ListGrowingDirection Downwards

New value for property growingDirection

setGrowingScrollToLoad

Sets a new value for property growingScrollToLoad.

If set to true, the user can scroll down/up to load more items. Otherwise a growing button is displayed at the bottom/top of the control. Note: This property can only be used if the growing property is set to true and only if there is one instance of sap.m.List or sap.m.Table inside the scrollable scroll container (e.g sap.m.Page).

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

New value for property growingScrollToLoad

setGrowingThreshold

Sets a new value for property growingThreshold.

Defines the number of items to be requested from the model for each grow. This property can only be used if the growing property is set to true.

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

Default value is 20.

Param Type DefaultValue Description
iGrowingThreshold int 20

New value for property growingThreshold

setGrowingTriggerText

Sets a new value for property growingTriggerText.

Defines the text displayed on the growing button. The default is a translated text ("More") coming from the message bundle. This property can only be used if the growing property is set to true.

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

Param Type DefaultValue Description
sGrowingTriggerText string

New value for property growingTriggerText

setHeaderDesign

Sets a new value for property headerDesign.

Defines the header style of the control. Possible values are Standard and Plain.

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

Default value is Standard.

Since 1.16 No longer has any functionality.
Param Type DefaultValue Description
sHeaderDesign sap.m.ListHeaderDesign Standard

New value for property headerDesign

setHeaderText

Sets a new value for property headerText.

Defines the header text that appears in the control. Note: If headerToolbar aggregation is set, then this property is ignored.

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

Param Type DefaultValue Description
sHeaderText string

New value for property headerText

setHeaderToolbar

Sets the aggregated headerToolbar.

Param Type DefaultValue Description
oHeaderToolbar sap.m.Toolbar

The headerToolbar to set

setIncludeItemInSelection

Sets a new value for property includeItemInSelection.

Defines whether the items are selectable by clicking on the item itself (true) rather than having to set the selection control first. Note: The SingleSelectMaster mode also provides this functionality by default.

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

New value for property includeItemInSelection

setInfoToolbar

Sets the aggregated infoToolbar.

Param Type DefaultValue Description
oInfoToolbar sap.m.Toolbar

The infoToolbar to set

setInset

Sets a new value for property inset.

Defines the indentation of the container. Setting it to true indents the list.

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

Default value is false.

Param Type DefaultValue Description
bInset boolean false

New value for property inset

setKeyboardMode

Sets a new value for property keyboardMode.

Defines keyboard handling behavior of the control.

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

Default value is Navigation.

Param Type DefaultValue Description
sKeyboardMode sap.m.ListKeyboardMode Navigation

New value for property keyboardMode

setMode

Sets a new value for property mode.

Defines the mode of the control (e.g. None, SingleSelect, MultiSelect, Delete).

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

Default value is None.

Param Type DefaultValue Description
sMode sap.m.ListMode None

New value for property mode

setModeAnimationOn

Sets a new value for property modeAnimationOn.

Defines if animations will be shown while switching between modes.

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

Default value is true.

Param Type DefaultValue Description
bModeAnimationOn boolean true

New value for property modeAnimationOn

setMultiSelectMode

Sets a new value for property multiSelectMode.

Defines the multi-selection mode for the control. If this property is set to the Default value, the sap.m.Table control renders the Select All checkbox in the column header, otherwise the Deselect All icon is rendered. The Select All checkbox allows the user to select all the items in the control, and the Deselect All icon deselects the items. If the property is set to ClearAll, then selecting items via the selectAll method is not possible. See selectAll for more details.

Note: This property must be used with the MultiSelect mode. If this property is set to ClearAll, then a selection of multiple items is still possible via the range selection feature except CTRL + A. Additionally, the CTRL + SHIFT + A key combination can be used for deselecting all the items. For details on the range selection, please see Keyboard Handling for Item Selection.

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

Default value is Default.

Param Type DefaultValue Description
sMultiSelectMode sap.m.MultiSelectMode Default

New value for property multiSelectMode

setNoDataText

Sets a new value for property noDataText.

This text is displayed when the control contains no items.

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

Param Type DefaultValue Description
sNoDataText string

New value for property noDataText

setRememberSelections

Sets a new value for property rememberSelections.

If set to true, this control remembers and retains the selection of the items after a binding update has been performed (e.g. sorting, filtering). Note: This feature works only if two-way data binding for the selected property of the item is not used. It also needs to be turned off if the binding context of the item does not always point to the same entry in the model, for example, if the order of the data in the JSONModel is changed.

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

Default value is true.

Param Type DefaultValue Description
bRememberSelections boolean true

New value for property rememberSelections

setSelectedItem

Selects or deselects the given list item.

Param Type DefaultValue Description
oListItem sap.m.ListItemBase

The list item whose selection to be changed. This parameter is mandatory.

bSelect boolean true

Sets selected status of the list item

setSelectedItemById

Sets a list item to be selected by id. In single mode the method removes the previous selection.

Param Type DefaultValue Description
sId string

The id of the list item whose selection to be changed.

bSelect boolean true

Sets selected status of the list item

setShowNoData

Sets a new value for property showNoData.

Defines whether or not the text specified in the noDataText property is displayed.

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

Default value is true.

Param Type DefaultValue Description
bShowNoData boolean true

New value for property showNoData

setShowSeparators

Sets a new value for property showSeparators.

Defines which item separator style will be used.

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

Default value is All.

Param Type DefaultValue Description
sShowSeparators sap.m.ListSeparators All

New value for property showSeparators

setShowUnread

Sets a new value for property showUnread.

Activates the unread indicator for all items, if set to true.

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

New value for property showUnread

setSticky

Sets a new value for property sticky.

Defines the section of the control that remains fixed at the top of the page during vertical scrolling as long as the control is in the viewport.

Note: Enabling sticky column headers in List controls will not have any effect.

There are some known restrictions. A few are given below:

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

Param Type DefaultValue Description
sSticky sap.m.Sticky[]

New value for property sticky

setSwipeContent

Sets the aggregated swipeContent.

Param Type DefaultValue Description
oSwipeContent sap.ui.core.Control

The swipeContent to set

setSwipeDirection

Sets a new value for property swipeDirection.

Defines the direction of the swipe movement (e.g LeftToRight, RightToLeft, Both) to display the control defined in the swipeContent aggregation.

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

Default value is Both.

Param Type DefaultValue Description
sSwipeDirection sap.m.SwipeDirection Both

New value for property swipeDirection

setWidth

Sets a new value for property width.

Sets the width of the control.

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

Default value is "100%".

Param Type DefaultValue Description
sWidth sap.ui.core.CSSSize "100%"

New value for property width

swipeOut

After swipeContent is shown, user can interact with this control(e.g Tap). After interaction is done, you can/should use this method to hide swipeContent from screen. Note: If users try to tap inside of the list but outside of the swipeContent then control hides automatically.

Param Type DefaultValue Description
oCallback any

This callback function is called with two parameters(swipedListItem and swipedContent) after swipe-out animation is finished.

unbindItems

Unbinds aggregation items from model data.