namespace sap.ui.vtm.TreeItemUtilities

Visiblity: public
Available since: N/A
Module: sap/ui/vtm/TreeItemUtilities
Application Component:

A set of utility functions for working with tree items for sap.ui.vtm.Tree controls.


Nodes Overview

Node Description

Methods Overview

Method Description
sap.ui.vtm.TreeItemUtilities.addChild

Adds a child tree item to the end of the the includedChildren or excludedChildren collection of its parent tree item.

sap.ui.vtm.TreeItemUtilities.addExcludedChild

Adds a child tree item to the end of the the excludedChildren collection of its parent tree item.

sap.ui.vtm.TreeItemUtilities.addIncludedChild

Adds a child tree item to the end of the the includedChildren collection of its parent tree item.

sap.ui.vtm.TreeItemUtilities.addRoot

Adds a root item to the tree.

sap.ui.vtm.TreeItemUtilities.calculateAbsoluteMatrix

Calculates the absolute matrix that should be applied to a tree item given its relative matrix and the absolute matrix of its parent.

sap.ui.vtm.TreeItemUtilities.calculateRelativeMatrix

Calculates the relative matrix that should be applied to a tree item given its absolute matrix and the absolute matrix of its parent.

sap.ui.vtm.TreeItemUtilities.cloneAppData

Returns a cloned copy of the appData on the passed tree item.

sap.ui.vtm.TreeItemUtilities.cloneIdentifiers

Returns a cloned copy of the identifiers on the passed tree item.

sap.ui.vtm.TreeItemUtilities.cloneMetadata

Returns a cloned copy of the metadata on the passed tree item.

sap.ui.vtm.TreeItemUtilities.excludeAllChildren

Moves all items from the includedChildren collection of a tree item (or set of tree items) to the excludedChildren collection.

sap.ui.vtm.TreeItemUtilities.getAppDataDescriptors

Gets the application data field descriptors for a given tree item.

sap.ui.vtm.TreeItemUtilities.getAppDataValues

Gets the application data values associated with a particular descriptor for a tree item.

sap.ui.vtm.TreeItemUtilities.getChildren

Gets the children of a tree item from the includedChildren and/or excludedChildren collections.

sap.ui.vtm.TreeItemUtilities.getExcludedChildren

Gets the excluded children of a tree item.

sap.ui.vtm.TreeItemUtilities.getIdentifierDescriptors

Gets the identifier descriptors for a given tree item.

sap.ui.vtm.TreeItemUtilities.getIdentifierValues

Gets the identifier values associated with a particular descriptor for a tree item.

sap.ui.vtm.TreeItemUtilities.getIncludedChildren

Gets the included children of a tree item.

sap.ui.vtm.TreeItemUtilities.getMessages

Gets the messages stored on a tree item.

sap.ui.vtm.TreeItemUtilities.getMetadataDescriptors

Gets the metadata field descriptors for a given tree item.

sap.ui.vtm.TreeItemUtilities.getMetadataValues

Gets the metadata values associated with a particular descriptor for a tree item.

sap.ui.vtm.TreeItemUtilities.getSceneNodeIds

Gets the IDs of the scene nodes associated with a tree item as an array of strings.

sap.ui.vtm.TreeItemUtilities.hasChildren

Gets whether a tree item has items in the includedChildren and/or excludedChildren collections.

sap.ui.vtm.TreeItemUtilities.hasExcludedChildren

Gets whether a tree item has excluded children.

sap.ui.vtm.TreeItemUtilities.hasIncludedChildren

Gets whether a tree item has included children.

sap.ui.vtm.TreeItemUtilities.hasVisibility

Returns whether the tree item has a visibility value.

sap.ui.vtm.TreeItemUtilities.includeAllChildren

Moves all items from the excludedChildren collection of a tree item (or set of tree items) to the includedChildren collection.

sap.ui.vtm.TreeItemUtilities.mapBranch

Applies a mapping function to each tree item in a branch of a tree to create a new tree branch.

sap.ui.vtm.TreeItemUtilities.mapTree

Applies a mapping function to each tree item in a tree to create a new tree.

sap.ui.vtm.TreeItemUtilities.removeChild

Removes a child tree item from the includedChildren and/or excludedChildren collection of its parent tree item.

sap.ui.vtm.TreeItemUtilities.removeExcludedChild

Removes a child tree item from the excludedChildren collection of its parent tree item.

sap.ui.vtm.TreeItemUtilities.removeIncludedChild

Removes a child tree item from the includedChildren collection of its parent tree item.

sap.ui.vtm.TreeItemUtilities.removeRoot

Removes a root item from the tree.

sap.ui.vtm.TreeItemUtilities.setAppDataValues

Set the application data values associated with a particular descriptor for a tree item (replacing any existing values).

sap.ui.vtm.TreeItemUtilities.setChildren

Sets either the includedChildren or excludedChildren collection of a tree item.

sap.ui.vtm.TreeItemUtilities.setExcludedChildren

Sets the excludedChildren collection of a tree item.

sap.ui.vtm.TreeItemUtilities.setIdentifierValues

Set the identifier values associated with a particular descriptor for a tree item (replacing any existing values).

sap.ui.vtm.TreeItemUtilities.setIncludedChildren

Sets the includedChildren collection of a tree item.

sap.ui.vtm.TreeItemUtilities.setMessages

Sets the messages stored on a tree item.

sap.ui.vtm.TreeItemUtilities.setMetadataValues

Set the metadata values associated with a particular descriptor for a tree item (replacing any existing values).

sap.ui.vtm.TreeItemUtilities.setSceneNodeIds

Sets the IDs of the scene nodes to associate with a tree item in a memory efficient manner.

sap.ui.vtm.TreeItemUtilities.traverseBranch

Recursively traverses a tree branch calling a function on each item (including the tree item that is the root of the branch).

sap.ui.vtm.TreeItemUtilities.traverseTree

Recursively traverses a tree calling a function on each item.

sap.ui.vtm.TreeItemUtilities.validateTree

Validates a tree and returns a set of error messages.

sap.ui.vtm.TreeItemUtilities.validateTreeItem

Validates a tree item and returns a set of error messages.

sap.ui.vtm.TreeItemUtilities.addChild

Adds a child tree item to the end of the the includedChildren or excludedChildren collection of its parent tree item.

Param Type DefaultValue Description
item object

The parent tree item.

childItem object

The child tree item.

childCollectionType sap.ui.vtm.ChildCollectionType

Controls which child collection to add the child tree item to.

The default value is sap.ui.vtm.ChildCollectionType.Included.

sap.ui.vtm.TreeItemUtilities.addExcludedChild

Adds a child tree item to the end of the the excludedChildren collection of its parent tree item.

Param Type DefaultValue Description
item object

The parent tree item.

childItem object

The child tree item.

sap.ui.vtm.TreeItemUtilities.addIncludedChild

Adds a child tree item to the end of the the includedChildren collection of its parent tree item.

Param Type DefaultValue Description
item object

The parent tree item.

childItem object

The child tree item.

sap.ui.vtm.TreeItemUtilities.addRoot

Adds a root item to the tree.

Param Type DefaultValue Description
rootItems object[]

The existing set of root items.

rootItemToAdd object

The root tree item to remove.

sap.ui.vtm.TreeItemUtilities.calculateAbsoluteMatrix

Calculates the absolute matrix that should be applied to a tree item given its relative matrix and the absolute matrix of its parent.

Param Type DefaultValue Description
relativeMatrix sap.ui.vtm.Matrix

The relative matrix of the tree item.

parentAbsoluteMatrix sap.ui.vtm.Matrix

The absolute matrix of the parent tree item.

sap.ui.vtm.TreeItemUtilities.calculateRelativeMatrix

Calculates the relative matrix that should be applied to a tree item given its absolute matrix and the absolute matrix of its parent.

Param Type DefaultValue Description
absoluteMatrix sap.ui.vtm.Matrix

The absolute matrix of the tree item.

parentAbsoluteMatrix sap.ui.vtm.Matrix

The absolute matrix of the parent tree item.

sap.ui.vtm.TreeItemUtilities.cloneAppData

Returns a cloned copy of the appData on the passed tree item.

Param Type DefaultValue Description
treeItem object

The tree item.

sap.ui.vtm.TreeItemUtilities.cloneIdentifiers

Returns a cloned copy of the identifiers on the passed tree item.

Param Type DefaultValue Description
treeItem object

The tree item.

sap.ui.vtm.TreeItemUtilities.cloneMetadata

Returns a cloned copy of the metadata on the passed tree item.

Param Type DefaultValue Description
treeItem object

The tree item.

sap.ui.vtm.TreeItemUtilities.excludeAllChildren

Moves all items from the includedChildren collection of a tree item (or set of tree items) to the excludedChildren collection.

Param Type DefaultValue Description
treeItems object[] object

The tree item or items.

recursive boolean

When true the items in the includedChildren collections of descendants are moved to the excludedChildren collection of the descendant tree item. Defaults to false.

sap.ui.vtm.TreeItemUtilities.getAppDataDescriptors

Gets the application data field descriptors for a given tree item.

Param Type DefaultValue Description
treeItem object

The tree item to get application data field descriptors from.

sap.ui.vtm.TreeItemUtilities.getAppDataValues

Gets the application data values associated with a particular descriptor for a tree item.

Param Type DefaultValue Description
treeItem object

The tree item to get application data values from.

descriptor string

The descriptor describing the application data value(s) to retrieve.

sap.ui.vtm.TreeItemUtilities.getChildren

Gets the children of a tree item from the includedChildren and/or excludedChildren collections.

Param Type DefaultValue Description
treeItem object

The tree item.

childCollectionType sap.ui.vtm.ChildCollectionType

Specifies which child item collections to get children from.

The default value is sap.ui.vtm.ChildCollectionType.Included.

sap.ui.vtm.TreeItemUtilities.getExcludedChildren

Gets the excluded children of a tree item.

Param Type DefaultValue Description
treeItem object

The tree item.

sap.ui.vtm.TreeItemUtilities.getIdentifierDescriptors

Gets the identifier descriptors for a given tree item.

Param Type DefaultValue Description
treeItem object

The tree item to get identifier descriptors from.

sap.ui.vtm.TreeItemUtilities.getIdentifierValues

Gets the identifier values associated with a particular descriptor for a tree item.

Param Type DefaultValue Description
treeItem object

The tree item to retrieve values from.

descriptor string

The descriptor describing the identifier value(s) to retrieve.

sap.ui.vtm.TreeItemUtilities.getIncludedChildren

Gets the included children of a tree item.

Param Type DefaultValue Description
treeItem object

The tree item.

sap.ui.vtm.TreeItemUtilities.getMessages

Gets the messages stored on a tree item.

Param Type DefaultValue Description
treeItem object

The tree item.

sap.ui.vtm.TreeItemUtilities.getMetadataDescriptors

Gets the metadata field descriptors for a given tree item.

Param Type DefaultValue Description
treeItem object

The tree item to get metadata field descriptors from.

sap.ui.vtm.TreeItemUtilities.getMetadataValues

Gets the metadata values associated with a particular descriptor for a tree item.

Param Type DefaultValue Description
treeItem object

The tree item to metadata values from.

descriptor string

The descriptor describing the metadata value(s) to retrieve.

sap.ui.vtm.TreeItemUtilities.getSceneNodeIds

Gets the IDs of the scene nodes associated with a tree item as an array of strings.

Param Type DefaultValue Description
treeItem object

The tree item.

sap.ui.vtm.TreeItemUtilities.hasChildren

Gets whether a tree item has items in the includedChildren and/or excludedChildren collections.

Param Type DefaultValue Description
treeItem object

The tree item.

childCollectionType sap.ui.vtm.ChildCollectionType

The child item collections to check.

The default value is sap.ui.vtm.ChildCollectionType.Included.

sap.ui.vtm.TreeItemUtilities.hasExcludedChildren

Gets whether a tree item has excluded children.

Param Type DefaultValue Description
treeItem object

The tree item.

sap.ui.vtm.TreeItemUtilities.hasIncludedChildren

Gets whether a tree item has included children.

Param Type DefaultValue Description
treeItem object

The tree item.

sap.ui.vtm.TreeItemUtilities.hasVisibility

Returns whether the tree item has a visibility value.

Param Type DefaultValue Description
treeItem object

The tree item.

sap.ui.vtm.TreeItemUtilities.includeAllChildren

Moves all items from the excludedChildren collection of a tree item (or set of tree items) to the includedChildren collection.

Param Type DefaultValue Description
treeItems object[] object

The tree item or items.

recursive boolean

When true the items in the excludedChildren collections of descendants are moved to the includedChildren collection of the descendant tree item. Defaults to false.

sap.ui.vtm.TreeItemUtilities.mapBranch

Applies a mapping function to each tree item in a branch of a tree to create a new tree branch.

Param Type DefaultValue Description
treeItem object

The tree item representing the branch to map.

mapFunc function

A function that takes a tree item and returns a new tree item.

sap.ui.vtm.TreeItemUtilities.mapTree

Applies a mapping function to each tree item in a tree to create a new tree.

Param Type DefaultValue Description
rootTreeItems object[]

The root tree items of the tree to map.

mapFunc function

A function that takes a tree item and returns a new tree item.

sap.ui.vtm.TreeItemUtilities.removeChild

Removes a child tree item from the includedChildren and/or excludedChildren collection of its parent tree item.

Param Type DefaultValue Description
item object

The parent tree item.

childItem string object

The child tree item to remove (or its id).

childCollectionType sap.ui.vtm.ChildCollectionType

Controls which child collection to remove the child tree item from.

The default value is sap.ui.vtm.ChildCollectionType.Included.

sap.ui.vtm.TreeItemUtilities.removeExcludedChild

Removes a child tree item from the excludedChildren collection of its parent tree item.

Param Type DefaultValue Description
item object

The parent tree item.

childItem string object

The child tree item to remove (or its id).

sap.ui.vtm.TreeItemUtilities.removeIncludedChild

Removes a child tree item from the includedChildren collection of its parent tree item.

Param Type DefaultValue Description
item object

The parent tree item.

childItem string object

The child tree item to remove (or its id).

sap.ui.vtm.TreeItemUtilities.removeRoot

Removes a root item from the tree.

Param Type DefaultValue Description
rootItems object[]

The existing set of root items.

rootItemToRemove string object

The root tree item to remove (or its id).

sap.ui.vtm.TreeItemUtilities.setAppDataValues

Set the application data values associated with a particular descriptor for a tree item (replacing any existing values).

Param Type DefaultValue Description
treeItem object

The tree item to update.

descriptor string

The descriptor describing the application data value(s) to update.

values undefined string string[] number number[] boolean boolean[] object object[]

The application data value or values to apply. A value of undefined clears all values for the descriptor.

sap.ui.vtm.TreeItemUtilities.setChildren

Sets either the includedChildren or excludedChildren collection of a tree item.

Param Type DefaultValue Description
treeItem object

The tree item.

children object[]

The items to set in the includedChildren or excludedChildren collection of the tree item.

childCollectionType sap.ui.vtm.ChildCollectionType

Controls which child collection to set on the tree item.

The default value is sap.ui.vtm.ChildCollectionType.Included.

sap.ui.vtm.TreeItemUtilities.setExcludedChildren

Sets the excludedChildren collection of a tree item.

Param Type DefaultValue Description
treeItem object

The tree item.

excludedChildren object[]

The items to set in the includedChildren collection of the tree item.

sap.ui.vtm.TreeItemUtilities.setIdentifierValues

Set the identifier values associated with a particular descriptor for a tree item (replacing any existing values).

Param Type DefaultValue Description
treeItem object

The tree item to update.

descriptor string

The descriptor describing the identifier value(s) to update.

values string string[] undefined

The identifier value or values to apply. A value of undefined clears all values for the descriptor.

sap.ui.vtm.TreeItemUtilities.setIncludedChildren

Sets the includedChildren collection of a tree item.

Param Type DefaultValue Description
treeItem object

The tree item.

includedChildren object[]

The items to set in the includedChildren collection of the tree item.

sap.ui.vtm.TreeItemUtilities.setMessages

Sets the messages stored on a tree item.

Param Type DefaultValue Description
treeItem object

The tree item.

messages sap.ui.core.Message[]

The set of messages to apply to the tree item.

sap.ui.vtm.TreeItemUtilities.setMetadataValues

Set the metadata values associated with a particular descriptor for a tree item (replacing any existing values).

Param Type DefaultValue Description
treeItem object

The tree item to update.

descriptor string

The descriptor describing the metadata value(s) to update.

values undefined string string[] number number[] boolean boolean[] object object[]

The metadata value or values to apply. A value of undefined clears all values for the descriptor.

sap.ui.vtm.TreeItemUtilities.setSceneNodeIds

Sets the IDs of the scene nodes to associate with a tree item in a memory efficient manner.

Param Type DefaultValue Description
treeItem object

The tree item.

sceneNodeIds string string[] undefined

The scene node IDs for the tree item. A value of undefined clears all values for the descriptor.

sap.ui.vtm.TreeItemUtilities.traverseBranch

Recursively traverses a tree branch calling a function on each item (including the tree item that is the root of the branch).

Param Type DefaultValue Description
treeItem object

The root of the branch to apply the function to.

callback function

The function to apply to tree items in the branch.
The first parameter to the callback function is the current tree item object (at the current point of the traversal.
The second parameter to the callback function is the set of ancestors of the current tree item.
The second parameter to the callback function will not be populated unless the ancestors parameter of traverseBranch is provided.
The function may return a sap.ui.vtm.ChildCollectionType value to specify which immediate children of the tree item to traverse.
If no such value is returned a default of sap.ui.vtm.ChildCollectionType.Included is used.

ancestors object[]

The ancestors of the tree item. If provided this will be used to calculate the set of ancestors of each tree item during traversal (to be passed into the callback function).

sap.ui.vtm.TreeItemUtilities.traverseTree

Recursively traverses a tree calling a function on each item.

Param Type DefaultValue Description
rootItems object[]

The root items of the tree.

callback function

The function to apply to tree items in the tree.
The first parameter to the callback function is the current tree item object (at the current point of the traversal.
The second parameter to the callback function is the set of ancestors of the current tree item.
The function may return a sap.ui.vtm.ChildCollectionType value to specify which immediate children to traverse. If no such value is returned a default of sap.ui.vtm.ChildCollectionType.Included is used.

sap.ui.vtm.TreeItemUtilities.validateTree

Validates a tree and returns a set of error messages.

Param Type DefaultValue Description
rootItems object[]

The root tree items.

sap.ui.vtm.TreeItemUtilities.validateTreeItem

Validates a tree item and returns a set of error messages.

Param Type DefaultValue Description
treeItem object

The tree item.