class sap.m.Tree

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

The Tree control provides a tree structure for displaying data in a hierarchy. Note: Growing feature is not supported by Tree.


Constructor

Constructor for a new Tree.

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.Tree(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

Borrowed 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

Borrowed Aggregations

Name Cardinality Type Description
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 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.

Events Overview

Event Description
toggleOpenState

Fired when an item has been expanded or collapsed by user interaction.

Since: 1.50.

toggleOpenState

Fired when an item has been expanded or collapsed by user interaction.

Since: 1.50.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
itemIndex int

Index of the expanded/collapsed item

itemContext object

Binding context of the item

expanded boolean

Flag that indicates whether the item has been expanded or collapsed


Methods Overview

Method Description
attachToggleOpenState

Attaches event handler fnFunction to the toggleOpenState event of this sap.m.Tree.

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

Fired when an item has been expanded or collapsed by user interaction.

collapse

Collapses one or multiple items.

collapseAll

Collapses all nodes.

detachToggleOpenState

Detaches event handler fnFunction from the toggleOpenState event of this sap.m.Tree.

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

expand

Expands one or multiple items. Note that items that are hidden at the time of calling this API can't be expanded.

expandToLevel

Defines the level to which the tree is expanded. The function can be used to define the initial expanding state. An alternative way to define the initial expanding state is to set the parameter numberOfExpandedLevels of the binding.

Example:

  oTree.bindItems({
     path: "...",
     parameters: {
        numberOfExpandedLevels: 1
     }
  });

sap.m.Tree.extend

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

fireToggleOpenState

Fires event toggleOpenState to attached listeners.

sap.m.Tree.getMetadata

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

setGrowing

The growing property is not supported for control Tree.

setGrowingDirection

The growingDirection property is not supported for control Tree.

setGrowingScrollToLoad

The growingScrollToLoad property is not supported for control Tree.

setGrowingThreshold

The growingThreshold property is not supported for control Tree.

setGrowingTriggerText

The growingTriggerText property is not supported for control Tree.

attachToggleOpenState

Attaches event handler fnFunction to the toggleOpenState event of this sap.m.Tree.

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

Fired when an item has been expanded or collapsed by user interaction.

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

collapse

Collapses one or multiple items.

Param Type DefaultValue Description
vParam int int[]

The index or indices of the tree items to be collapsed

collapseAll

Collapses all nodes.

detachToggleOpenState

Detaches event handler fnFunction from the toggleOpenState event of this sap.m.Tree.

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

expand

Expands one or multiple items. Note that items that are hidden at the time of calling this API can't be expanded.

Param Type DefaultValue Description
vParam int int[]

The index or indices of the item to be expanded

expandToLevel

Defines the level to which the tree is expanded. The function can be used to define the initial expanding state. An alternative way to define the initial expanding state is to set the parameter numberOfExpandedLevels of the binding.

Example:

  oTree.bindItems({
     path: "...",
     parameters: {
        numberOfExpandedLevels: 1
     }
  });

Param Type DefaultValue Description
iLevel int

The level to which the data is expanded

sap.m.Tree.extend

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

fireToggleOpenState

Fires event toggleOpenState to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

itemIndex int

Index of the expanded/collapsed item

itemContext object

Binding context of the item

expanded boolean

Flag that indicates whether the item has been expanded or collapsed

sap.m.Tree.getMetadata

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

setGrowing

The growing property is not supported for control Tree.

Param Type DefaultValue Description
bValue boolean

New value for the growing property, ignored.

setGrowingDirection

The growingDirection property is not supported for control Tree.

Param Type DefaultValue Description
sValue sap.m.ListGrowingDirection

New value for the growingDirection property, ignored.

setGrowingScrollToLoad

The growingScrollToLoad property is not supported for control Tree.

Param Type DefaultValue Description
bValue boolean

New value for the growingScrollToLoad property, ignored.

setGrowingThreshold

The growingThreshold property is not supported for control Tree.

Param Type DefaultValue Description
iValue int

New value for the growingThreshold property, ignored.

setGrowingTriggerText

The growingTriggerText property is not supported for control Tree.

Param Type DefaultValue Description
sValue string

New value for the growingTriggerText property, ignored.