Class Tree
- All Implemented Interfaces:
HasHandlers,HasDataChangedHandlers,HasDataChangedHandlers
- Direct Known Subclasses:
ResultTree
A Tree has no visual presentation, it
is displayed by a TreeGrid or ColumnTree when supplied as TreeGrid.data or ColumnTree.data.
A Tree can be
constructed out of a List of objects interlinked by IDs or via explicitly specified Arrays of child objects. See modelType for an explanation of how to pass data to a Tree.
Typical usage is to call TreeGrid.fetchData() to cause
automatic creation of a ResultTree, which is a type of Tree that automatically
handles loading data on demand. For information on DataBinding Trees, see TreeDataBinding.
-
Nested Class Summary
Nested classes/interfaces inherited from class com.smartgwt.client.data.RecordList
RecordList.SortNormalizer -
Field Summary
Fields inherited from class com.smartgwt.client.data.RecordList
jsObjFields inherited from class com.smartgwt.client.core.BaseClass
config, configOnly, factoryCreated, factoryProperties, id, scClassName -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionAdd a single node under the specified parentAdd a single node under the specified parentAdd a single node under the specified parentaddDataChangedHandler(DataChangedHandler handler) Add a dataChanged handler.TreeNode[]Add a list of nodes to some parent.TreeNode[]Add a list of nodes to some parent.TreeNode[]Add a list of nodes to some parent.TreeNode[]Add a list of nodes to some parent.allChildrenLoaded(TreeNode node) For a databound tree, do the children of this folder form a ResultSet with a full cache.voidcloseAll()Close all nodes under a particular nodevoidcloseAll(NodeLocator node) Close all nodes under a particular nodevoidClose all nodes under a particular nodevoidcloseFolder(NodeLocator node) Closes a folder.voidcloseFolder(TreeNode node) Closes a folder.voidcloseFolder(Integer node) Closes a folder.voidcloseFolder(String node) Closes a folder.voidcloseFolders(TreeNode[] nodeList) Close a set of folders, specified by path or as pointers to nodes.create()voidcreateNodeLocator(TreeNode node, TreeNode parent, Integer position, String path) Returns aNodeLocatorobject suitable for passing to methods, such asgetParent(), which require aNodeLocatorwhen the tree ismulti-linked.voidcreateNodeLocator(TreeNode node, TreeNode parent, Integer position, String path, Integer openListIndex) Returns aNodeLocatorobject suitable for passing to methods, such asgetParent(), which require aNodeLocatorwhen the tree ismulti-linked.static voiddiscoverTree(TreeNode[] nodes, DiscoverTreeSettings settings, String parentChildrenField) given a hierarchy of objects with children under mixed names, heuristically discover the property that holds children and copy it to a single, uniform childrenProperty.Find a node within this tree using a string path or by attribute value(s).Find a node within this tree using a string path or by attribute value(s).Find a node within this tree using a string path or by attribute value(s).Find the node with the specified ID.static StringfindChildrenProperty(TreeNode node, ChildrenPropertyMode mode) heuristically find a property that appears to contain child objects.intfindIndex(AdvancedCriteria propertyName) LikeList.findIndex(), but operates only on the list of currently opened nodes.intLikeList.findIndex(), but operates only on the list of currently opened nodes.intLikeList.findIndex(), but operates only on the list of currently opened nodes.intLikeList.findIndex(), but operates only on the list of currently opened nodes.intfindNextIndex(int startIndex, String propertyName) intfindNextIndex(int startIndex, String propertyName, Object value) intfindNextIndex(int startIndex, String propertyName, Object value, int endIndex) intfindNextNodeIndex(int startIndex, String propertyName) LikefindNextIndex(), but includes both open and closed nodes.intfindNextNodeIndex(int startIndex, String propertyName, Object value) intfindNextNodeIndex(int startIndex, String propertyName, Object value, int endIndex) LikefindNextIndex(), but includes both open and closed nodes.intfindNodeIndex(AdvancedCriteria propertyName) LikefindIndex(), but searches all tree nodes regardless of their open/closed state.intfindNodeIndex(String propertyName) LikefindIndex(), but searches all tree nodes regardless of their open/closed state.intfindNodeIndex(String propertyName, Object value) LikefindIndex(), but searches all tree nodes regardless of their open/closed state.intfindNodeIndex(Map propertyName) LikefindIndex(), but searches all tree nodes regardless of their open/closed state.TreeNode[]Get all the nodes that exist in the tree under a particular node, as a flat list, in depth-first traversal order.TreeNode[]getAllNodes(TreeNode node) Get all the nodes that exist in the tree under a particular node, as a flat list, in depth-first traversal order.For amulti-link tree, indicates whether client-side filtering is allowed on the fields of thelinkDataSource.If true, the root node is automatically opened when the tree is created orsetRoot()is called.TreeNode[]getChildren(TreeNode node) Returns all children of a node.For trees with the modelType "children", this property specifies the name of the property that contains the list of children for a node.getChildrenResultSet(TreeNode node) Returns a ResultSet that provides access to any partially-loaded children of a node.getData()Specifies whatDataSourcethis tree is associated with.Specifies whatDataSourcethis tree is associated with.Controls whether nodes are assumed to be folders or leaves by default.Title assigned to nodes without atitlePropertyvalue or anamePropertyvalue.TreeNode[]Ruturns the list of all descendants of a node that are folders.TreeNode[]getDescendantFolders(TreeNode node) Ruturns the list of all descendants of a node that are folders.TreeNode[]Returns the list of all descendants of a node that are leaves.TreeNode[]getDescendantLeaves(TreeNode node) Returns the list of all descendants of a node that are leaves.TreeNode[]Returns a list of link{type:NodeLocator)s identifying all descendants of a node (identified by the parameterNodeLocator).TreeNode[]Returns a list of link{type:NodeLocator)s identifying all descendants of a node (identified by the parameterNodeLocator).TreeNode[]Returns the list of all descendants of a node.TreeNode[]getDescendants(TreeNode node) Returns the list of all descendants of a node.If this tree hasmodelType:"parent", should nodes in the data array for the tree be dropped if they have an explicitly specified value for theparentIdFieldwhich doesn't match any other nodes in the tree.getFilteredTree(Criteria criteria) Filters this tree by the provided criteria, returning a new Tree containing just the nodes that match the criteria.getFilteredTree(Criteria criteria, TreeFilterMode filterMode, DataSource dataSource) Filters this tree by the provided criteria, returning a new Tree containing just the nodes that match the criteria.TreeNode[]getFolders(TreeNode node) Returns all the first-level folders of a node.Name of the property on aTreeNodethat holds an id for the node which is unique across the entire Tree.Name of property that defines whether a node is a folder.TreeNode[]Return all the first-level leaves of a node.intReturns the number of items in the current open list.intgetLevel(NodeLocator node) Return the number of levels deep this node is in the tree.intReturn the number of levels deep this node is in the tree.Record[]The name of the "position" field in thismulti-link tree's link data.getLoadState(TreeNode node) What is the loadState of a given folder?Selects the model used to construct the tree representation.TreeNode[]getMultiLinkParents(TreeNode node) FormultiLink trees, returns the array of this node's direct parents (the actual node objects, not the IDs).getName(NodeLocator node) Get the 'name' of a node.Get the 'name' of a node.Name of the property on aTreeNodethat holds a name for the node that is unique among its immediate siblings, thus allowing a unique path to be used to identify the node, similar to a file system.getNodeLocator(Integer recordIndex) For amulti-link tree, this method returns thenodeLocatorassociated with the particular occurence of the node at the specified index within the currentopen listof nodes in the tree.TreeNode[]getOpenList(TreeNode node) Return a flattened list of nodes that are open under some parent, including the parent itself.The property consulted by the default implementation ofisOpen()to determine if the node is open or not.static TreegetOrCreateRef(JavaScriptObject jsObj) Returns the parent of this node.For trees with modelType "parent", this property specifies the name of the property that contains the unique parent ID of a node.getParentPath(TreeNode node) Given a node, return the path to its parent.TreeNode[]getParents(TreeNode node) Given a node, return an array of the node's parents with the immediate parent first.Record[]FormultiLink trees, returns the array of this node's direct parents and the node's position within each parent.Returns the path of a node - a path has the following format:([name][pathDelim]?)*
For example, in this tree:Specifies the delimiter between node names.getPathForOpenListIndex(Integer recordIndex) This method returns the path to the node at the specified index within the current open list of nodes in this tree.If new nodes are added to a tree with modelType:"parent" which have the sameid field valueas existing nodes, the existing nodes are removed when the new nodes are added.getRoot()If you're using the "parent" modelType, you can provide the root node configuration via this property.Should folders be sorted separately from leaves or should nodes be ordered according to their sort field value regardless of whether the node is a leaf or folder?Controls whether the implicit root node is returned as part of the visible tree, specifically, whether it is returned ingetOpenList(), which is the API view components typically use to get the list of visible nodes.IfseparateFoldersis true, should folders be displayed above or below leaves? When set totruefolders will appear above leaves when thesortDirectionapplied to the tree is"ascending"Return the title of a node -- the name as it should be presented to the user.Name of the property on aTreeNodethat holds the title of the node as it should be shown to the user.hasChildren(TreeNode node) Returns true if this node has any children.hasFolders(TreeNode node) Return true if this this node has any children that are folders.Return whether this node has any children that are leaves.isDescendantOf(TreeNode child, TreeNode parent) Is one node a descendant of the other?Determines whether a particular node is a folder.voidReturns true if the passed-in node ID is already present in the parent's ancestor chain.Returns true if the passed in node is a leaf.For a databound tree, has this folder either already loaded its children or is it in the process of loading them.voidReturns true if this is a multi-link tree - ie, one that can contain the same node in more than one place.isOpen(NodeLocator node) Whether a particular node is open or closed (works for leaves and folders).Whether a particular node is open or closed (works for leaves and folders).Whether a particular node is open or closed (works for leaves and folders).Whether a particular node is open or closed (works for leaves and folders).Returns true if "parent" is the parent of "node".Return true if the passed node is the root node.voidFormulti-link trees only, called when links are added to or removed form the tree.voidThis method is provided as a mechanism to link new nodes into the tree of modelType "parent".voidloadChildren(TreeNode node) Load the children of a given node.voidloadChildren(TreeNode node, DSCallback callback) Load the children of a given node.voidMoves the specified node to a new parent.voidMoves the specified node to a new parent.static TreeNodenodeForRecord(ListGridRecord record) A TreeNode and ListGridRecord represent similar datastructures and it is possible that certain TreeGrid operations return a ListGridRecord since TreeGrid extends ListGrid.voidopenAll()Open all nodes under a particular node.voidopenAll(NodeLocator node) Open all nodes under a particular node.voidOpen all nodes under a particular node.voidOpen all nodes under a particular node.voidOpen all nodes under a particular node.voidopenFolder(TreeNode node) 
 Open a particular node

voidopenFolders(TreeNode[] nodeList) Open a set of folders, specified by path or as pointers to nodes.voidreloadChildren(TreeNode node) Reload the children of a folder.remove(NodeLocator node) Removes a node, along with all its children.Removes a node, along with all its children.Removes a node, along with all its children.Removes a node, along with all its children.voidremoveChildren(TreeNode node) Removes all children of the node and sets it to a loaded state.removeList(TreeNode[] nodeList) Remove a list of nodes (not necessarily from the same parent), and all children of those nodes.setAllowFilterOnLinkFields(Boolean allowFilterOnLinkFields) For amulti-link tree, indicates whether client-side filtering is allowed on the fields of thelinkDataSource.setAutoOpenRoot(Boolean autoOpenRoot) If true, the root node is automatically opened when the tree is created orsetRoot()is called.voidsetChildren(TreeNode parent, List newChildren) Replaces the existing children of a parent node, leaving the node in the loaded state.setChildrenProperty(String childrenProperty) For trees with the modelType "children", this property specifies the name of the property that contains the list of children for a node.Optional initial data for the tree.setDataSource(DataSource dataSource) Specifies whatDataSourcethis tree is associated with.setDataSource(String dataSource) Specifies whatDataSourcethis tree is associated with.setDefaultIsFolder(Boolean defaultIsFolder) Controls whether nodes are assumed to be folders or leaves by default.setDefaultNodeTitle(String defaultNodeTitle) Title assigned to nodes without atitlePropertyvalue or anamePropertyvalue.static voidsetDefaultProperties(Tree treeProperties) Class level method to set the default properties of this class.setDiscardParentlessNodes(Boolean discardParentlessNodes) If this tree hasmodelType:"parent", should nodes in the data array for the tree be dropped if they have an explicitly specified value for theparentIdFieldwhich doesn't match any other nodes in the tree.setIdField(String idField) Name of the property on aTreeNodethat holds an id for the node which is unique across the entire Tree.setIsFolderProperty(String isFolderProperty) Name of property that defines whether a node is a folder.voidvoidsetLinkData(Record[] linkData) For amulti-link tree, this property specifies the parent-child relationships between the nodes.setLinkPositionField(String linkPositionField) The name of the "position" field in thismulti-link tree's link data.setModelType(TreeModelType modelType) Selects the model used to construct the tree representation.voidsetMultiLinkTree(Boolean multiLinkTree) Set to true to indicate that this is a multi-link tree - ie, one that can contain the same node in more than one place.setNameProperty(String nameProperty) Name of the property on aTreeNodethat holds a name for the node that is unique among its immediate siblings, thus allowing a unique path to be used to identify the node, similar to a file system.setOpenProperty(String openProperty) The property consulted by the default implementation ofisOpen()to determine if the node is open or not.setParentIdField(String parentIdField) For trees with modelType "parent", this property specifies the name of the property that contains the unique parent ID of a node.setPathDelim(String pathDelim) Specifies the delimiter between node names.setReportCollisions(Boolean reportCollisions) If new nodes are added to a tree with modelType:"parent" which have the sameid field valueas existing nodes, the existing nodes are removed when the new nodes are added.If you're using the "parent" modelType, you can provide the root node configuration via this property.voidsetRootValue(int rootValue) voidsetRootValue(String rootValue) setSeparateFolders(Boolean separateFolders) Should folders be sorted separately from leaves or should nodes be ordered according to their sort field value regardless of whether the node is a leaf or folder?
If this method is called after the component has been drawn/initialized: Setter forseparateFolders.setShowRoot(Boolean showRoot) Controls whether the implicit root node is returned as part of the visible tree, specifically, whether it is returned ingetOpenList(), which is the API view components typically use to get the list of visible nodes.setSortFoldersBeforeLeaves(Boolean sortFoldersBeforeLeaves) IfseparateFoldersis true, should folders be displayed above or below leaves? When set totruefolders will appear above leaves when thesortDirectionapplied to the tree is"ascending"
If this method is called after the component has been drawn/initialized: Setter forsortFoldersBeforeLeaves.setTitleProperty(String titleProperty) Name of the property on aTreeNodethat holds the title of the node as it should be shown to the user.voidunloadChildren(TreeNode node) Deprecated.Methods inherited from class com.smartgwt.client.data.RecordList
add, addAt, addDataChangedHandler, addList, addList, addListAt, contains, contains, containsAll, duplicate, equals, find, find, find, findAll, findAll, findAll, findAll, findAll, findAll, findAll, findAll, findIndex, findIndex, findIndex, findIndex, findIndex, findIndex, findNextIndex, findNextIndex, findNextIndex, findNextIndex, findNextIndex, findNextIndex, findNextIndex, findNextIndex, findNextIndex, first, get, getItems, getJsObj, getOrCreateJsObj, getProperty, getRange, getRangeList, getValueMap, indexOf, indexOf, intersect, isARecordList, isCreated, isEmpty, last, lastIndexOf, lastIndexOf, remove, removeAt, removeList, set, setLength, setSort, sort, sort, sortByProperty, sortByProperty, toArrayMethods inherited from class com.smartgwt.client.core.BaseClass
addDynamicProperty, addDynamicProperty, addDynamicProperty, addDynamicProperty, applyFactoryProperties, asSGWTComponent, clearDynamicProperty, createJsObj, destroy, doAddHandler, doInit, error, error, errorIfNotCreated, fireEvent, getAttribute, getAttributeAsBoolean, getAttributeAsDate, getAttributeAsDouble, getAttributeAsElement, getAttributeAsFloat, getAttributeAsInt, getAttributeAsJavaScriptObject, getAttributeAsMap, getAttributeAsString, getAttributeAsStringArray, getClassName, getConfig, getHandlerCount, getID, getRef, getRuleScope, getScClassName, getTestInstance, hasAutoAssignedID, hasDynamicProperty, internalSetID, internalSetID, isConfigOnly, isFactoryCreated, onBind, onInit, registerID, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setConfig, setConfigOnly, setFactoryCreated, setID, setProperty, setProperty, setProperty, setProperty, setRuleScope, setScClassNameMethods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, waitMethods inherited from interface com.google.gwt.event.shared.HasHandlers
fireEvent
-
Constructor Details
-
Tree
public Tree() -
Tree
-
-
Method Details
-
getOrCreateRef
-
setJavaScriptObject
- Overrides:
setJavaScriptObjectin classBaseClass
-
create
- Overrides:
createin classRecordList
-
setAllowFilterOnLinkFields
public Tree setAllowFilterOnLinkFields(Boolean allowFilterOnLinkFields) throws IllegalStateException For amulti-link tree, indicates whether client-side filtering is allowed on the fields of thelinkDataSource. When this property is true, filtering operations involving link fields work as expected (ie, as if those fields were present on the maindataSource); when this value is not true, criterions involving link fields are simply ignored.Note, setting this property true causes filtering operations to perform an additional record duplication per node in the dataset to be filtered. This adds some overhead, so you should consider likely data volumes before enabling it (though in fact, client-side filtering of trees is relatively expensive anyway, so acceptable use cases probably already involve quite low data volumes)
This property has no effect for regular, non-multiLink trees.
- Parameters:
allowFilterOnLinkFields- New allowFilterOnLinkFields value. Default value is null- Returns:
Treeinstance, for chaining setter calls- Throws:
IllegalStateException- this property cannot be changed after the underlying component has been created
-
getAllowFilterOnLinkFields
For amulti-link tree, indicates whether client-side filtering is allowed on the fields of thelinkDataSource. When this property is true, filtering operations involving link fields work as expected (ie, as if those fields were present on the maindataSource); when this value is not true, criterions involving link fields are simply ignored.Note, setting this property true causes filtering operations to perform an additional record duplication per node in the dataset to be filtered. This adds some overhead, so you should consider likely data volumes before enabling it (though in fact, client-side filtering of trees is relatively expensive anyway, so acceptable use cases probably already involve quite low data volumes)
This property has no effect for regular, non-multiLink trees.
- Returns:
- Current allowFilterOnLinkFields value. Default value is null
-
setAutoOpenRoot
If true, the root node is automatically opened when the tree is created orsetRoot()is called.- Parameters:
autoOpenRoot- New autoOpenRoot value. Default value is true- Returns:
Treeinstance, for chaining setter calls
-
getAutoOpenRoot
If true, the root node is automatically opened when the tree is created orsetRoot()is called.- Returns:
- Current autoOpenRoot value. Default value is true
-
setChildrenProperty
For trees with the modelType "children", this property specifies the name of the property that contains the list of children for a node.- Parameters:
childrenProperty- New childrenProperty value. Default value is "children"- Returns:
Treeinstance, for chaining setter calls- See Also:
-
getChildrenProperty
For trees with the modelType "children", this property specifies the name of the property that contains the list of children for a node.- Returns:
- Current childrenProperty value. Default value is "children"
- See Also:
-
setDataSource
Specifies whatDataSourcethis tree is associated with.A
DataSourceis required when filtering a tree, even if it isn't aResultTree, though it may be passed togetFilteredTree()rather than set on the tree itself. If aDataSourceis specified it will also affect sorting, where relevant, such as if the tree is set asTreeGrid.data.- Parameters:
dataSource- New dataSource value. Default value is null- Returns:
Treeinstance, for chaining setter calls- Throws:
IllegalStateException- this property cannot be changed after the underlying component has been created
-
getDataSource
Specifies whatDataSourcethis tree is associated with.A
DataSourceis required when filtering a tree, even if it isn't aResultTree, though it may be passed togetFilteredTree()rather than set on the tree itself. If aDataSourceis specified it will also affect sorting, where relevant, such as if the tree is set asTreeGrid.data.- Returns:
- Current dataSource value. Default value is null
-
setDataSource
Specifies whatDataSourcethis tree is associated with.A
DataSourceis required when filtering a tree, even if it isn't aResultTree, though it may be passed togetFilteredTree()rather than set on the tree itself. If aDataSourceis specified it will also affect sorting, where relevant, such as if the tree is set asTreeGrid.data.- Parameters:
dataSource- New dataSource value. Default value is null- Returns:
Treeinstance, for chaining setter calls- Throws:
IllegalStateException- this property cannot be changed after the underlying component has been created
-
getDataSourceAsString
Specifies whatDataSourcethis tree is associated with.A
DataSourceis required when filtering a tree, even if it isn't aResultTree, though it may be passed togetFilteredTree()rather than set on the tree itself. If aDataSourceis specified it will also affect sorting, where relevant, such as if the tree is set asTreeGrid.data.- Returns:
- Current dataSource value. Default value is null
-
setDefaultIsFolder
Controls whether nodes are assumed to be folders or leaves by default.Nodes that have children or have the
isFolderPropertyset to true will be considered folders by default. Other nodes will be considered folders or leaves by default according to this setting.See also
ResultTree.defaultIsFolderfor more details on howdefaultIsFolderinteracts withloading data on demand.- Parameters:
defaultIsFolder- New defaultIsFolder value. Default value is null- Returns:
Treeinstance, for chaining setter calls- Throws:
IllegalStateException- this property cannot be changed after the underlying component has been created
-
getDefaultIsFolder
Controls whether nodes are assumed to be folders or leaves by default.Nodes that have children or have the
isFolderPropertyset to true will be considered folders by default. Other nodes will be considered folders or leaves by default according to this setting.See also
ResultTree.defaultIsFolderfor more details on howdefaultIsFolderinteracts withloading data on demand.- Returns:
- Current defaultIsFolder value. Default value is null
-
setDefaultNodeTitle
Title assigned to nodes without atitlePropertyvalue or anamePropertyvalue.- Parameters:
defaultNodeTitle- New defaultNodeTitle value. Default value is "Untitled"- Returns:
Treeinstance, for chaining setter calls
-
getDefaultNodeTitle
Title assigned to nodes without atitlePropertyvalue or anamePropertyvalue.- Returns:
- Current defaultNodeTitle value. Default value is "Untitled"
-
setDiscardParentlessNodes
If this tree hasmodelType:"parent", should nodes in the data array for the tree be dropped if they have an explicitly specified value for theparentIdFieldwhich doesn't match any other nodes in the tree. If set to false these nodes will be added as children of the root node.Note : This is an advanced setting
- Parameters:
discardParentlessNodes- New discardParentlessNodes value. Default value is false- Returns:
Treeinstance, for chaining setter calls- Throws:
IllegalStateException- this property cannot be changed after the underlying component has been created
-
getDiscardParentlessNodes
If this tree hasmodelType:"parent", should nodes in the data array for the tree be dropped if they have an explicitly specified value for theparentIdFieldwhich doesn't match any other nodes in the tree. If set to false these nodes will be added as children of the root node.- Returns:
- Current discardParentlessNodes value. Default value is false
-
setIdField
Name of the property on aTreeNodethat holds an id for the node which is unique across the entire Tree. Required for all nodes for trees with modelType "parent". Default value is "id". SeeTreeNode.idfor usage.Note : This is an advanced setting
- Parameters:
idField- New idField value. Default value is "id"- Returns:
Treeinstance, for chaining setter calls- Throws:
IllegalStateException- this property cannot be changed after the underlying component has been created- See Also:
-
com.smartgwt.client.widgets.tree.TreeNode#setId- Node Titles Example
-
getIdField
Name of the property on aTreeNodethat holds an id for the node which is unique across the entire Tree. Required for all nodes for trees with modelType "parent". Default value is "id". SeeTreeNode.idfor usage.- Returns:
- Current idField value. Default value is "id"
- See Also:
-
com.smartgwt.client.widgets.tree.TreeNode#getId- Node Titles Example
-
setIsFolderProperty
Name of property that defines whether a node is a folder. By default this is set toTreeNode.isFolder.- Parameters:
isFolderProperty- New isFolderProperty value. Default value is "isFolder"- Returns:
Treeinstance, for chaining setter calls- See Also:
-
getIsFolderProperty
Name of property that defines whether a node is a folder. By default this is set toTreeNode.isFolder.- Returns:
- Current isFolderProperty value. Default value is "isFolder"
- See Also:
-
com.smartgwt.client.widgets.tree.TreeNode#getIsFolder
-
setLinkPositionField
The name of the "position" field in thismulti-link tree's link data. Ignored if this tree is not a multi-link tree. Note, these values are only used to order the nodes within a parent - so a node with link position -123 will appear before a node with link position 87, but that is the only significance of the link position values- Parameters:
linkPositionField- New linkPositionField value. Default value is "position"- Returns:
Treeinstance, for chaining setter calls- Throws:
IllegalStateException- this property cannot be changed after the underlying component has been created
-
getLinkPositionField
The name of the "position" field in thismulti-link tree's link data. Ignored if this tree is not a multi-link tree. Note, these values are only used to order the nodes within a parent - so a node with link position -123 will appear before a node with link position 87, but that is the only significance of the link position values- Returns:
- Current linkPositionField value. Default value is "position"
-
setModelType
Selects the model used to construct the tree representation. SeeTreeModelTypefor the available options and their implications.If the "parent" modelType is used, you can provide the initial parent-linked data set to the tree via the
dataattribute. If the "children" modelType is used, you can provide the initial tree structure to the Tree via therootattribute.Note : This is an advanced setting
- Parameters:
modelType- New modelType value. Default value is "children"- Returns:
Treeinstance, for chaining setter calls- See Also:
-
getModelType
Selects the model used to construct the tree representation. SeeTreeModelTypefor the available options and their implications.If the "parent" modelType is used, you can provide the initial parent-linked data set to the tree via the
dataattribute. If the "children" modelType is used, you can provide the initial tree structure to the Tree via therootattribute.- Returns:
- Current modelType value. Default value is "children"
- See Also:
-
setNameProperty
Name of the property on aTreeNodethat holds a name for the node that is unique among its immediate siblings, thus allowing a unique path to be used to identify the node, similar to a file system. Default value is "name". SeeTreeNode.namefor usage.- Parameters:
nameProperty- New nameProperty value. Default value is "name"- Returns:
Treeinstance, for chaining setter calls- See Also:
-
getNameProperty
Name of the property on aTreeNodethat holds a name for the node that is unique among its immediate siblings, thus allowing a unique path to be used to identify the node, similar to a file system. Default value is "name". SeeTreeNode.namefor usage.- Returns:
- Current nameProperty value. Default value is "name"
- See Also:
-
setOpenProperty
The property consulted by the default implementation ofisOpen()to determine if the node is open or not. By default, this property is auto-generated for you, but you can set it to a custom value if you want to declaratively specify this state, but be careful - if you display this Tree in multiple TreeGrids at the same time, the open state will not be tracked independently - seeSharingNodesfor more info on this.For
multi-link trees, we do not track open state on the nodes themselves, because this would mean that multiple instances of a node in the tree would open and close in lockstep. Instead, open state is tracked in an internal index structure, and theopenPropertyis not used at all.Note : This is an advanced setting
- Parameters:
openProperty- New openProperty value. Default value is null- Returns:
Treeinstance, for chaining setter calls- See Also:
-
getOpenProperty
The property consulted by the default implementation ofisOpen()to determine if the node is open or not. By default, this property is auto-generated for you, but you can set it to a custom value if you want to declaratively specify this state, but be careful - if you display this Tree in multiple TreeGrids at the same time, the open state will not be tracked independently - seeSharingNodesfor more info on this.For
multi-link trees, we do not track open state on the nodes themselves, because this would mean that multiple instances of a node in the tree would open and close in lockstep. Instead, open state is tracked in an internal index structure, and theopenPropertyis not used at all.- Returns:
- Current openProperty value. Default value is null
- See Also:
-
setParentIdField
For trees with modelType "parent", this property specifies the name of the property that contains the unique parent ID of a node. Default value is "parentId". SeeTreeNode.parentIdfor usage.Note : This is an advanced setting
- Parameters:
parentIdField- New parentIdField value. Default value is "parentId"- Returns:
Treeinstance, for chaining setter calls- Throws:
IllegalStateException- this property cannot be changed after the underlying component has been created- See Also:
-
com.smartgwt.client.widgets.tree.TreeNode#setParentId- Node Titles Example
-
getParentIdField
For trees with modelType "parent", this property specifies the name of the property that contains the unique parent ID of a node. Default value is "parentId". SeeTreeNode.parentIdfor usage.- Returns:
- Current parentIdField value. Default value is "parentId"
- See Also:
-
com.smartgwt.client.widgets.tree.TreeNode#getParentId- Node Titles Example
-
setPathDelim
Specifies the delimiter between node names. The pathDelim is used to construct a unique path to each node. A path can be obtained for any node by callinggetPath()and can be used to find any node in the tree by callingfind(). Note that you can also hand-construct a path - in other words you are not required to callgetPath()in order to later usefind()to retrieve it.
The pathDelim can be any character or sequence of characters, but must be a unique string with respect to the text that can appear in thenamePropertythat's used for naming the nodes. So for example, if you have the following tree:one two three/fourThen you will be unable to find thethree/fournode usingfind()if your tree is using the default pathDelim of /. In such a case, you can use a different pathDelim for the tree. For example if you used | for the path delim, then you can find thethree/fournode in the tree above by callingtree.find("one|two|three/four").
The pathDelim is used only bygetPath()andfind()and does not affect any aspect of the tree structure or other forms of tree navigation (such as viagetChildren()).Note : This is an advanced setting
- Parameters:
pathDelim- New pathDelim value. Default value is "/"- Returns:
Treeinstance, for chaining setter calls- See Also:
-
getPathDelim
Specifies the delimiter between node names. The pathDelim is used to construct a unique path to each node. A path can be obtained for any node by callinggetPath()and can be used to find any node in the tree by callingfind(). Note that you can also hand-construct a path - in other words you are not required to callgetPath()in order to later usefind()to retrieve it.
The pathDelim can be any character or sequence of characters, but must be a unique string with respect to the text that can appear in thenamePropertythat's used for naming the nodes. So for example, if you have the following tree:one two three/fourThen you will be unable to find thethree/fournode usingfind()if your tree is using the default pathDelim of /. In such a case, you can use a different pathDelim for the tree. For example if you used | for the path delim, then you can find thethree/fournode in the tree above by callingtree.find("one|two|three/four").
The pathDelim is used only bygetPath()andfind()and does not affect any aspect of the tree structure or other forms of tree navigation (such as viagetChildren()).- Returns:
- Current pathDelim value. Default value is "/"
- See Also:
-
setReportCollisions
If new nodes are added to a tree with modelType:"parent" which have the sameid field valueas existing nodes, the existing nodes are removed when the new nodes are added.If reportCollisions is true, the Tree will log a warning in the developer console about this.
Note that if an id collision occurs between a new node and its ancestor, the ancestor will be removed and the new node will not be added to the tree.
- Parameters:
reportCollisions- New reportCollisions value. Default value is true- Returns:
Treeinstance, for chaining setter calls- Throws:
IllegalStateException- this property cannot be changed after the underlying component has been created
-
getReportCollisions
If new nodes are added to a tree with modelType:"parent" which have the sameid field valueas existing nodes, the existing nodes are removed when the new nodes are added.If reportCollisions is true, the Tree will log a warning in the developer console about this.
Note that if an id collision occurs between a new node and its ancestor, the ancestor will be removed and the new node will not be added to the tree.
- Returns:
- Current reportCollisions value. Default value is true
-
setRoot
If you're using the "parent" modelType, you can provide the root node configuration via this property. If you don't provide it, one will be auto-created for you with an empty name. Read on for a description of what omitting the name property on the root node means for path derivation.If you're using the "children" modelType, you can provide the initial tree data via this property. So, for example, to construct the following tree:
foo bar zooYou would initialize the tree as follows:Tree tree = new Tree(); tree.setRoot( new TreeNode("root", new TreeNode("foo", new TreeNode("bar")), new TreeNode("zoo") ) );
Note: if you initialize a Tree with norootvalue, a root node will be auto-created for you. You can then calladd()to construct the tree.
If this method is called after the component has been drawn/initialized: Set the root node of the tree. Called automatically on this Tree during initialization and on the Tree returned from a call toduplicate().- Parameters:
root- new root node. Default value is null- Returns:
Treeinstance, for chaining setter calls- See Also:
-
getRoot
If you're using the "parent" modelType, you can provide the root node configuration via this property. If you don't provide it, one will be auto-created for you with an empty name. Read on for a description of what omitting the name property on the root node means for path derivation.If you're using the "children" modelType, you can provide the initial tree data via this property. So, for example, to construct the following tree:
foo bar zooYou would initialize the tree as follows:Tree tree = new Tree(); tree.setRoot( new TreeNode("root", new TreeNode("foo", new TreeNode("bar")), new TreeNode("zoo") ) );
Note: if you initialize a Tree with norootvalue, a root node will be auto-created for you. You can then calladd()to construct the tree.- Returns:
- Returns the root node of the tree. Default value is null
- See Also:
-
setSeparateFolders
Should folders be sorted separately from leaves or should nodes be ordered according to their sort field value regardless of whether the node is a leaf or folder?
If this method is called after the component has been drawn/initialized: Setter forseparateFolders.- Parameters:
separateFolders- newseparateFoldersvalue. Default value is false- Returns:
Treeinstance, for chaining setter calls- See Also:
-
getSeparateFolders
Should folders be sorted separately from leaves or should nodes be ordered according to their sort field value regardless of whether the node is a leaf or folder?- Returns:
- Current separateFolders value. Default value is false
- See Also:
-
setShowRoot
Controls whether the implicit root node is returned as part of the visible tree, specifically, whether it is returned ingetOpenList(), which is the API view components typically use to get the list of visible nodes.Default is to have the root node be implicit and not included in the open list, which means that the visible tree begins with the children of root. This allows multiple nodes to appear at the top level of the tree.
You can set
showRoot:trueto show the single, logical root node as the only top-level node. This property is only meaningful for Trees where you supplied a value forroot, otherwise, you will see an automatically generated root node that is meaningless to the user.
If this method is called after the component has been drawn/initialized: Setter forshowRoot.- Parameters:
showRoot- newshowRootvalue. Default value is false- Returns:
Treeinstance, for chaining setter calls
-
getShowRoot
Controls whether the implicit root node is returned as part of the visible tree, specifically, whether it is returned ingetOpenList(), which is the API view components typically use to get the list of visible nodes.Default is to have the root node be implicit and not included in the open list, which means that the visible tree begins with the children of root. This allows multiple nodes to appear at the top level of the tree.
You can set
showRoot:trueto show the single, logical root node as the only top-level node. This property is only meaningful for Trees where you supplied a value forroot, otherwise, you will see an automatically generated root node that is meaningless to the user.- Returns:
- Current showRoot value. Default value is false
-
setSortFoldersBeforeLeaves
IfseparateFoldersis true, should folders be displayed above or below leaves? When set totruefolders will appear above leaves when thesortDirectionapplied to the tree is"ascending"
If this method is called after the component has been drawn/initialized: Setter forsortFoldersBeforeLeaves.- Parameters:
sortFoldersBeforeLeaves- newsortFoldersBeforeLeavesvalue. Default value is true- Returns:
Treeinstance, for chaining setter calls
-
getSortFoldersBeforeLeaves
IfseparateFoldersis true, should folders be displayed above or below leaves? When set totruefolders will appear above leaves when thesortDirectionapplied to the tree is"ascending"- Returns:
- Current sortFoldersBeforeLeaves value. Default value is true
-
setTitleProperty
Name of the property on aTreeNodethat holds the title of the node as it should be shown to the user. Default value is "title". SeeTreeNode.titlefor usage.- Parameters:
titleProperty- New titleProperty value. Default value is "title"- Returns:
Treeinstance, for chaining setter calls
-
getTitleProperty
Name of the property on aTreeNodethat holds the title of the node as it should be shown to the user. Default value is "title". SeeTreeNode.titlefor usage.- Returns:
- Current titleProperty value. Default value is "title"
-
allChildrenLoaded
For a databound tree, do the children of this folder form a ResultSet with a full cache.Note that this method only applies to
ResultTree.fetchMode"paged".- Parameters:
node- folder in question- Returns:
- folder's children are a ResultSet with a full cache
- See Also:
-
closeAll
public void closeAll()Close all nodes under a particular node -
closeAll
Close all nodes under a particular node- Parameters:
node- node from which to close folders (if not specified, the root node is used). If this is amulti-link tree, you must provide aNodeLocatorfor any node other than the root node
-
closeAll
Close all nodes under a particular node- Parameters:
node- node from which to close folders (if not specified, the root node is used). If this is amulti-link tree, you must provide aNodeLocatorfor any node other than the root node
-
closeFolder
Closes a folder. Note, formulti-link trees, passing aNodeLocatoris the only unambiguous way to specify the node.- Parameters:
node- the node to open, or its ID, or a NodeLocator object
-
closeFolder
Closes a folder. Note, formulti-link trees, passing aNodeLocatoris the only unambiguous way to specify the node.- Parameters:
node- the node to open, or its ID, or a NodeLocator object
-
closeFolder
Closes a folder. Note, formulti-link trees, passing aNodeLocatoris the only unambiguous way to specify the node.- Parameters:
node- the node to open, or its ID, or a NodeLocator object
-
closeFolder
Closes a folder. Note, formulti-link trees, passing aNodeLocatoris the only unambiguous way to specify the node.- Parameters:
node- the node to open, or its ID, or a NodeLocator object
-
createNodeLocator
Returns aNodeLocatorobject suitable for passing to methods, such asgetParent(), which require aNodeLocatorwhen the tree ismulti-linked. Note,NodeLocators are specific to multiLink trees; they are never required for regular trees.- Parameters:
node- the child nodeparent- the parent nodeposition- the child node's position within the parentpath- the full path to the child node
-
createNodeLocator
public void createNodeLocator(TreeNode node, TreeNode parent, Integer position, String path, Integer openListIndex) Returns aNodeLocatorobject suitable for passing to methods, such asgetParent(), which require aNodeLocatorwhen the tree ismulti-linked. Note,NodeLocators are specific to multiLink trees; they are never required for regular trees.- Parameters:
node- the child nodeparent- the parent nodeposition- the child node's position within the parentpath- the full path to the child nodeopenListIndex- the index of the node occurence in the tree's current openList. This is the same as the record index of the node in an associatedTreeGrid
-
addDataChangedHandler
Add a dataChanged handler.Called when the structure of this tree is changed in any way.
Note that on a big change (many items being added or deleted) this may be called multiple times- Specified by:
addDataChangedHandlerin interfaceHasDataChangedHandlers- Parameters:
handler- the dataChanged handler- Returns:
HandlerRegistrationused to remove this handler
-
findIndex
LikeList.findIndex(), but operates only on the list of currently opened nodes. To search all loaded nodes open or closed, usefindNodeIndex().- Parameters:
propertyName- property to match, or if an Object is passed, set of properties and values to match- Returns:
- index of the first matching Object or -1 if not found
-
findIndex
LikeList.findIndex(), but operates only on the list of currently opened nodes. To search all loaded nodes open or closed, usefindNodeIndex().- Overrides:
findIndexin classRecordList- Parameters:
propertyName- property to match, or if an Object is passed, set of properties and values to match- Returns:
- index of the first matching Object or -1 if not found
-
findIndex
LikeList.findIndex(), but operates only on the list of currently opened nodes. To search all loaded nodes open or closed, usefindNodeIndex().- Overrides:
findIndexin classRecordList- Parameters:
propertyName- property to match, or if an Object is passed, set of properties and values to match- Returns:
- index of the first matching Object or -1 if not found
-
findIndex
LikeList.findIndex(), but operates only on the list of currently opened nodes. To search all loaded nodes open or closed, usefindNodeIndex().- Parameters:
propertyName- property to match, or if an Object is passed, set of properties and values to matchvalue- value to compare against (if propertyName is a string)- Returns:
- index of the first matching Object or -1 if not found
-
findNextIndex
LikefindIndex(), but inspects a range fromstartIndextoendIndex. Note that as infindIndex(), only open nodes are included. To include both open and closed nodes, usefindNextNodeIndex().- Overrides:
findNextIndexin classRecordList- Parameters:
startIndex- first index to consider.propertyName- property to match; or, if an object is passed, set of properties and values to match.- Returns:
- index of the first matching value or -1 if not found.
-
findNextIndex
- See Also:
-
findNextIndex
LikefindIndex(), but inspects a range fromstartIndextoendIndex. Note that as infindIndex(), only open nodes are included. To include both open and closed nodes, usefindNextNodeIndex().- Parameters:
startIndex- first index to consider.propertyName- property to match; or, if an object is passed, set of properties and values to match.value- value to compare against (ifpropertyNameis a string)endIndex- last index to consider (inclusive).- Returns:
- index of the first matching value or -1 if not found.
-
findNextNodeIndex
LikefindNextIndex(), but includes both open and closed nodes.- Parameters:
startIndex- first index to consider.propertyName- property to match; or, if an object is passed, set of properties and values to match.- Returns:
- index of the first matching value or -1 if not found.
-
findNextNodeIndex
- See Also:
-
findNextNodeIndex
LikefindNextIndex(), but includes both open and closed nodes.- Parameters:
startIndex- first index to consider.propertyName- property to match; or, if an object is passed, set of properties and values to match.value- value to compare against (ifpropertyNameis a string)endIndex- last index to consider (inclusive).- Returns:
- index of the first matching value or -1 if not found.
-
findNodeIndex
LikefindIndex(), but searches all tree nodes regardless of their open/closed state.- Parameters:
propertyName- property to match, or if an Object is passed, set of properties and values to match- Returns:
- index of the first matching Object or -1 if not found
-
findNodeIndex
LikefindIndex(), but searches all tree nodes regardless of their open/closed state.- Parameters:
propertyName- property to match, or if an Object is passed, set of properties and values to match- Returns:
- index of the first matching Object or -1 if not found
-
findNodeIndex
LikefindIndex(), but searches all tree nodes regardless of their open/closed state.- Parameters:
propertyName- property to match, or if an Object is passed, set of properties and values to match- Returns:
- index of the first matching Object or -1 if not found
-
findNodeIndex
LikefindIndex(), but searches all tree nodes regardless of their open/closed state.- Parameters:
propertyName- property to match, or if an Object is passed, set of properties and values to matchvalue- value to compare against (if propertyName is a string)- Returns:
- index of the first matching Object or -1 if not found
-
getChildrenResultSet
Returns a ResultSet that provides access to any partially-loaded children of a node. If the node is a leaf, this method returns null.- Parameters:
node- The node whose children you want to fetch.- Returns:
- List of children for the node, including an empty ResultSet if the node has no children. For a leaf, returns null.
- See Also:
-
getDescendantNodeLocators
Returns a list of link{type:NodeLocator)s identifying all descendants of a node (identified by the parameterNodeLocator). This method is the equivalent ofgetDescendants(), but formulti-link trees. The list of descendant nodes returned from both methods is identical - a node's descendants are the same regardless of where or how many times that node appears in the tree - but theNodeLocators returned by this method provide additional context that allows you to determine particular occurences of descendant nodes. This is necessary for some use cases - for example, when trying to determine if a particular node occurence is open, or selected.- Returns:
- List of descendants of the node.
-
getDescendantNodeLocators
Returns a list of link{type:NodeLocator)s identifying all descendants of a node (identified by the parameterNodeLocator). This method is the equivalent ofgetDescendants(), but formulti-link trees. The list of descendant nodes returned from both methods is identical - a node's descendants are the same regardless of where or how many times that node appears in the tree - but theNodeLocators returned by this method provide additional context that allows you to determine particular occurences of descendant nodes. This is necessary for some use cases - for example, when trying to determine if a particular node occurence is open, or selected.- Parameters:
node- node in question (root node is assumed if none is specified)- Returns:
- List of descendants of the node.
-
getLength
public int getLength()Returns the number of items in the current open list.- Overrides:
getLengthin classRecordList- Returns:
- number of items in open list
- See Also:
-
getLevel
Return the number of levels deep this node is in the tree. For example, for this tree:root foo barCallingtree.getLevel(bar)will return2.Note
showRootdefaults to false so that multiple nodes can be shown at top level. In this case, the top-level nodes still have root as a parent, so have level 1, even though they have no visible parents.For
multi-link trees, passing aTreeNodeto this method will return the level of one of that node's occurences; it is not predictable which occurence will be used. For multi-link trees, therefore, you should pass aNodeLocatorwith a path that unambiguously identifies the node occurence you are interested in- Parameters:
node- node in question, or a suitableNodeLocator- Returns:
- number of parents the node has
-
getLevel
Return the number of levels deep this node is in the tree. For example, for this tree:root foo barCallingtree.getLevel(bar)will return2.Note
showRootdefaults to false so that multiple nodes can be shown at top level. In this case, the top-level nodes still have root as a parent, so have level 1, even though they have no visible parents.For
multi-link trees, passing aTreeNodeto this method will return the level of one of that node's occurences; it is not predictable which occurence will be used. For multi-link trees, therefore, you should pass aNodeLocatorwith a path that unambiguously identifies the node occurence you are interested in- Parameters:
node- node in question, or a suitableNodeLocator- Returns:
- number of parents the node has
-
getLoadState
What is the loadState of a given folder?- Parameters:
node- folder in question- Returns:
- state of the node
-
getMultiLinkParents
FormultiLink trees, returns the array of this node's direct parents (the actual node objects, not the IDs). For non-multiLink trees, returns an array containing the single parent of this node. See alsogetParentsAndPositions().- Parameters:
node- node in question- Returns:
- the parents of this node
-
getName
Get the 'name' of a node. This is node[nameProperty]. If that value has not been set on the node, the node's 'ID' value will be tried (this is node[idField]). If that value is not present on the node, a unique value (within this parent) will be auto-generated and returned.- Parameters:
node- node in question, or a suitableNodeLocator- Returns:
- name of the node
-
getName
Get the 'name' of a node. This is node[nameProperty]. If that value has not been set on the node, the node's 'ID' value will be tried (this is node[idField]). If that value is not present on the node, a unique value (within this parent) will be auto-generated and returned.- Parameters:
node- node in question, or a suitableNodeLocator- Returns:
- name of the node
-
getNodeLocator
For amulti-link tree, this method returns thenodeLocatorassociated with the particular occurence of the node at the specified index within the currentopen listof nodes in the tree. Not applicable to non-multilink trees (always returns null)- Parameters:
recordIndex- position of a node occurence within the open list of the tree- Returns:
- NodeLocator unambiguously identifying the specific node occurence
-
getParentPath
Given a node, return the path to its parent. This works just likegetPath()except the node itself is not reported as part of the path.- Parameters:
node- node in question- Returns:
- path to the node's parent
- See Also:
-
getParentsAndPositions
FormultiLink trees, returns the array of this node's direct parents and the node's position within each parent. Each entry is a record like this:[ {parent: [reference-to-parent-node], position: [this-node's-position-within-the-parent]}, {parent: [reference-to-parent-node], position: [this-node's-position-within-the-parent]} ]For non-multiLink trees, returns null (calling this method makes no sense for non-multiLink trees).- Parameters:
node- node in question- Returns:
- the parents and positions of this node
-
getPath
Returns the path of a node - a path has the following format:([name][pathDelim]?)*
For example, in this tree:root foo barAssuming thatpathDelimis the default/, thebarnode would have the pathroot/foo/barand the path for thefoonode would beroot/foo.
Once you have a path to a node, you can call find(path) to retrieve a reference to the node later.Note: Nodes in
multi-link treesdo not have a single path, because a given node can occur in multiple places in the tree. Therefore, if you pass aTreeNodeinstance to this method, it returns the path to one occurence of the node; which particular occurence it chooses is not predictable, and there may be other paths to other occurences of the same node in the tree. The only way to obtain an unambiguous path for a particular occurence of a node is to callgetPathForOpenListIndex(), passing in the position of the node occurence in the tree's openList (which will be the same as the record number of the node's visual occurence in atreeGrid); if the node occurence is not yet in the tree's openList - either because its parent has not yet been opened, or because the tree is in the process of being built - the tree is not able to provide a path to the node occurence. In this case, you would have to obtain the path in application code, by reference to the originaldataandlinkData- Parameters:
node- node in question- Returns:
- path to the node
- See Also:
-
getPathForOpenListIndex
This method returns the path to the node at the specified index within the current open list of nodes in this tree. Note that for a node that appears in more than one place in amulti-link tree, the returned path will be the visible path to the node in the specified index.See
getPath()for more information on paths for TreeNodes.- Parameters:
recordIndex- position of a node within the open list of the tree- Returns:
- path to the node
-
getTitle
Return the title of a node -- the name as it should be presented to the user. This method works as follows:-
If a
titlePropertyis set on the node, the value of that property is returned. - Otherwise, if the
namePropertyis set on the node, that value is returned, minus any trailingpathDelim. - Finally, if none of the above yielded a title, the value of
defaultNodeTitleis returned.
To override the title for an auto-constructed tree (for example, in a databound TreeGrid), overrideTreeGrid.getNodeTitle()instead.- Parameters:
node- node for which the title is being requested- Returns:
- title to display
- See Also:
-
If a
-
hasChildren
Returns true if this node has any children.- Parameters:
node- node in question- Returns:
- true if the node has children
-
hasFolders
Return true if this this node has any children that are folders.- Parameters:
node- node in question- Returns:
- true if the node has children that are folders
-
hasLeaves
Return whether this node has any children that are leaves.- Parameters:
node- node in question- Returns:
- true if the node has children that are leaves
-
isDescendantOf
Is one node a descendant of the other?- Parameters:
child- child nodeparent- parent node- Returns:
- true == parent is an ancestor of child
-
isFolder
Determines whether a particular node is a folder. The logic works as follows:
- If the
TreeNodehas a value for theisFolderProperty(TreeNode.isFolderby default) that value is returned. - Next,
the existence of the
childrenProperty(by defaultTreeNode.children) is checked on theTreeNode. If the node has the children property defined (regardless of whether it actually has any children), then isFolder() returns true for that node.
- Parameters:
node- node in question- Returns:
- true if the node is a folder
- If the
-
isInAncestorChain
public void isInAncestorChain()Returns true if the passed-in node ID is already present in the parent's ancestor chain. This means that either the parent node itself, or its parent, grandparent, and so on, has the same ID as the one passed in. This method is used when linking new nodes into a tree, to ensure that we don't link in nodes that will lead to circular references by virtue of a node being its own parent (or its own child, depending which way round you prefer to think of it)Note that
multi-link treespotentially have more than one ancestor chain for any given node, so this method returns true if the parameter ID is used by any node in any of the parent's ancestor chains. -
isLeaf
Returns true if the passed in node is a leaf.- Parameters:
node- node in question- Returns:
- true if the node is a leaf
- See Also:
-
isLoaded
For a databound tree, has this folder either already loaded its children or is it in the process of loading them.- Parameters:
node- folder in question- Returns:
- folder is loaded or is currently loading
-
isMultiLinkTree
public void isMultiLinkTree()Returns true if this is a multi-link tree - ie, one that can contain the same node in more than one place. Otherwise, returns false.See
linkDataandResultTree.linkDataSourcefor further details of multiLink trees. -
isOpen
Whether a particular node is open or closed (works for leaves and folders). Note, formulti-link trees, passing aNodeLocatoris the only unambiguous way to specify the node.- Parameters:
node- the node in question, or the the node's ID, or a NodeLocator object- Returns:
- true if the node is open
-
isOpen
Whether a particular node is open or closed (works for leaves and folders). Note, formulti-link trees, passing aNodeLocatoris the only unambiguous way to specify the node.- Parameters:
node- the node in question, or the the node's ID, or a NodeLocator object- Returns:
- true if the node is open
-
isOpen
Whether a particular node is open or closed (works for leaves and folders). Note, formulti-link trees, passing aNodeLocatoris the only unambiguous way to specify the node.- Parameters:
node- the node in question, or the the node's ID, or a NodeLocator object- Returns:
- true if the node is open
-
isOpen
Whether a particular node is open or closed (works for leaves and folders). Note, formulti-link trees, passing aNodeLocatoris the only unambiguous way to specify the node.- Parameters:
node- the node in question, or the the node's ID, or a NodeLocator object- Returns:
- true if the node is open
-
isParent
Returns true if "parent" is the parent of "node". This is straightforward and definitive for ordinary trees, because nodes can only have one parent. InmultiLink trees, however, nodes can have multiple parents, so this method returning true only means that "parent" is a parent of "node" - there may or may not be others.- Parameters:
node- the node in questionparent- the node to query to see if is a parent of the other node- Returns:
- true if "parent" is a parent of "node"; otherwise false
-
isRoot
Return true if the passed node is the root node.- Parameters:
node- node to test- Returns:
- true if the node is the root node
-
linkDataChanged
public void linkDataChanged()Formulti-link trees only, called when links are added to or removed form the tree.
Note that on a big change (many items being added or deleted) this may be called multiple times -
loadChildren
Load the children of a given node.For a databound tree this will trigger a fetch against the Tree's DataSource.
- Parameters:
node- node in question
-
loadChildren
Load the children of a given node.For a databound tree this will trigger a fetch against the Tree's DataSource.
- Parameters:
node- node in questioncallback- Optional callback (stringMethod) to fire when loading completes. Has a single paramnode- the node whose children have been loaded, and is fired in the scope of the Tree.
-
move
Moves the specified node to a new parent.- Parameters:
node- node to movenewParent- new parent to move the node to
-
move
Moves the specified node to a new parent.- Parameters:
node- node to movenewParent- new parent to move the node toposition- Position of the new node in the children list. If not specified, the node will be added at the end of the list.
-
openAll
public void openAll()Open all nodes under a particular node.- See Also:
-
openAll
Open all nodes under a particular node.- Parameters:
node- node from which to open folders, or the node's ID, or a NodeLocator object (if not specified, the root node is used)- See Also:
-
openAll
Open all nodes under a particular node.- Parameters:
node- node from which to open folders, or the node's ID, or a NodeLocator object (if not specified, the root node is used)- See Also:
-
openAll
Open all nodes under a particular node.- Parameters:
node- node from which to open folders, or the node's ID, or a NodeLocator object (if not specified, the root node is used)- See Also:
-
openAll
Open all nodes under a particular node.- Parameters:
node- node from which to open folders, or the node's ID, or a NodeLocator object (if not specified, the root node is used)- See Also:
-
reloadChildren
Reload the children of a folder.- Parameters:
node- node in question- See Also:
-
remove
Removes a node, along with all its children. See"Modifying ResultTrees"when working with aResultTreefor limitations. Note, if this is amulti-link tree, you must pass in aNodeLocatorrather than a node or id.- Parameters:
node- node to remove, or the node's ID, or a NodeLocator- Returns:
- true if the tree was changed as a result of this call
-
remove
Removes a node, along with all its children. See"Modifying ResultTrees"when working with aResultTreefor limitations. Note, if this is amulti-link tree, you must pass in aNodeLocatorrather than a node or id.- Parameters:
node- node to remove, or the node's ID, or a NodeLocator- Returns:
- true if the tree was changed as a result of this call
-
remove
Removes a node, along with all its children. See"Modifying ResultTrees"when working with aResultTreefor limitations. Note, if this is amulti-link tree, you must pass in aNodeLocatorrather than a node or id.- Parameters:
node- node to remove, or the node's ID, or a NodeLocator- Returns:
- true if the tree was changed as a result of this call
-
remove
Removes a node, along with all its children. See"Modifying ResultTrees"when working with aResultTreefor limitations. Note, if this is amulti-link tree, you must pass in aNodeLocatorrather than a node or id.- Parameters:
node- node to remove, or the node's ID, or a NodeLocator- Returns:
- true if the tree was changed as a result of this call
-
removeChildren
Removes all children of the node and sets it to a loaded state. For non-ResultTrees, or non-pagedResultTrees,add()oraddList()can then be used to provide new children. ForpagedResultTrees,DataSource.updateCaches()must be used to insert nodes into the cache as local data, since suchResultTrees are considered read-only, andadd()andaddList()are not perrmitted.- Parameters:
node- folder in question- See Also:
-
setChildren
Replaces the existing children of a parent node, leaving the node in the loaded state. Only a flat list of children nodes is supported, as inaddList().- Parameters:
parent- parent of childrennewChildren- children to be set- See Also:
-
unloadChildren
Deprecated.It's recommended that you instead usereloadChildren()to reload the children of a folder, orremoveChildren()if you need to clear the cached children of a folder to add specific local data.Unload the children of a folder, returning the folder to the "unloaded" state.- Parameters:
node- folder in question
-
discoverTree
public static void discoverTree(TreeNode[] nodes, DiscoverTreeSettings settings, String parentChildrenField) given a hierarchy of objects with children under mixed names, heuristically discover the property that holds children and copy it to a single, uniform childrenProperty. Label each discovered child with a configurable "typeProperty" set to the value of the property that held the children.- Parameters:
nodes- list of nodes to link into the tree.settings- configures how the tree will be exploredparentChildrenField-
-
findChildrenProperty
heuristically find a property that appears to contain child objects. Searches through a node and find a property that is either Array or Object valued.- Parameters:
node- the node to checkmode- determines how to chose the property that appears to contain child objects- Returns:
- the name of the property that holds the children
-
setDefaultProperties
Class level method to set the default properties of this class. If set, then all existing and subsequently created instances of this class will automatically have default properties corresponding to the properties set on the SmartGWT class instance passed to this function before its underlying SmartClient JS object was created. This is a powerful feature that eliminates the need for users to create a separate hierarchy of subclasses that only alter the default properties of this class. Can also be used for skinning / styling purposes.Note: This method is intended for setting default attributes only and will affect all instances of the underlying class (including those automatically generated in JavaScript). This method should not be used to apply standard EventHandlers or override methods for a class - use a custom subclass instead. Calling this method after instances have been created can result in undefined behavior, since it bypasses any setters and a class instance may have already examined a particular property and not be expecting any changes through this route.
- Parameters:
treeProperties- properties that should be used as new defaults when instances of this class are created- See Also:
-
setData
Optional initial data for the tree. How this data is interpreted depends on this tree'smodelType.If
modelTypeis"parent", the list that you provide will be passed tolinkNodes(com.smartgwt.client.widgets.tree.TreeNode[]), integrating the nodes into the tree.In this case the root node must be supplied separately via
root. So for example, to create this tree:foo bar zoowith modelType:"parent", you can do this:TreeNode root = new TreeNode("root"); Tree tree = new Tree(); tree.setRoot(root); tree.setModelType(TreeModelType.PARENT); TreeNode data[] = new TreeNode[3]; data[0] = new TreeNode("foo"); data[0].setID("foo"); data[0].setParentID("root"); data[1] = new TreeNode("bar"); data[1].setID("bar"); data[1].setParentID("foo"); data[2] = new TreeNode("zoo"); data[2].setID("zoo"); data[2].setParentID("bar"); tree.setData(data);Specifying the root node explicitly allows you to give it a name, changing the way path derivation works (seerootfor more on naming the root node).For
modelType:"children"trees, the data passed in will be assumed to be an array of children of the tree's root node.- Parameters:
nodes- data- Returns:
Treeinstance, for chaining setter calls
-
getData
-
setLinkData
For amulti-link tree, this property specifies the parent-child relationships between the nodes. The nodes themselves are provided inthe regular tree data. Note that multi-link trees must specify amodelTypeof "parent".For a regular, non-multiLink tree,
linkDatais ignored.Minimally, the link data should include a node id, parent id and optionally the position of the child within that parent (only required if
allowDuplicateChildrenis set). To describe this multi-link tree:foo bar baz zoo bar bazyou would provide node information in the tree'sdatalike this:TreeNode data[] = new TreeNode[4]; data[0] = new TreeNode("foo"); data[0].setID("foo"); data[1] = new TreeNode("bar"); data[1].setID("bar"); data[2] = new TreeNode("baz"); data[2].setID("baz"); data[3] = new TreeNode("zoo"); data[3].setID("zoo"); tree.setData(data);and link information inlinkDatalike this:Record linkData[] = new Record[4]; linkData[0] = new Record(); linkData[0].setAttribute("id", "bar"); linkData[0].setAttribute("parentId", "foo"); linkData[1] = new Record(); linkData[1].setAttribute("id", "baz"); linkData[1].setAttribute("parentId", "bar"); linkData[2] = new Record(); linkData[2].setAttribute("id", "zoo"); linkData[2].setAttribute("parentId", "foo"); linkData[3] = new Record(); linkData[3].setAttribute("id", "bar"); linkData[3].setAttribute("parentId", "zoo"); tree.setLinkData(linkData);For information on databinding multi-link trees, and further discussion on multi-link trees generally, seeResultTree.linkDataSource- Parameters:
linkData- The link data
-
getLinkData
-
setMultiLinkTree
Set to true to indicate that this is a multi-link tree - ie, one that can contain the same node in more than one place. SeeTree.linkDataandResultTree.linkDataSourcefor more information on multi-link trees- Parameters:
multiLinkTree- True indicates that this will be a multi-link tree- Throws:
IllegalStateException- this property cannot be changed after the underlying component has been created
-
setRootValue
If you are using the "parent" modelType and did not specify a root node viarootwith an id (idField), then you can provide the root node's id via this property. See the example indatafor more info.- Parameters:
rootValue- rootValue Default value is null- Throws:
IllegalStateException- this property cannot be changed after the underlying component has been created
-
setRootValue
public void setRootValue(int rootValue) If you are using the "parent" modelType and did not specify a root node viarootwith an id (idField), then you can provide the root node's id via this property. See the example indatafor more info.- Parameters:
rootValue- rootValue Default value is null- Throws:
IllegalStateException- this property cannot be changed after the underlying component has been created
-
getRootValue
-
getParent
Returns the parent of this node.- Parameters:
node- node in question- Returns:
- parent of this node
-
getFilteredTree
Filters this tree by the provided criteria, returning a new Tree containing just the nodes that match the criteria.If
filterModeis "keepParents", parents are retained if any of their children match the criteria even if those parents do not match the criteria.- Parameters:
criteria- criteria to filter by- Returns:
- filtered tree
-
getFilteredTree
Filters this tree by the provided criteria, returning a new Tree containing just the nodes that match the criteria.If
filterModeis "keepParents", parents are retained if any of their children match the criteria even if those parents do not match the criteria.- Parameters:
criteria- criteria to filter byfilterMode- mode to use for filtering, defaults to "strict"dataSource- dataSource to use for filtering, if this Tree does not already have one- Returns:
- filtered tree
-
linkNodes
This method is provided as a mechanism to link new nodes into the tree of modelType "parent". This method takes a list of nodes that must contain at a minimum a unique ID (keyed byidField) and a parent ID (keyed byparentIdField). Based on this information, the list of nodes is integrated into the tree structure.- Parameters:
nodes- list of nodes to link into the tree.
-
getParents
Given a node, return an array of the node's parents with the immediate parent first. The node itself is not included in the result. For example, for the following tree:root foo bar
Callingtree.getParents(bar)would return:[foo, root]. Note that the returned array will contain references to the nodes, not the names.- Parameters:
node- node in question- Returns:
- array of node's parents
-
findById
Find the node with the specified ID. Specifically, it returns the node whose idField matches the id passed to this method. If the tree is using the "parent" modelType, this lookup will be constant-time. For all other modelTypes, the tree will be searched recursively.- Parameters:
id- ID of the node to return.- Returns:
- node with appropriate ID, or null if not found.
-
find
Find a node within this tree using a string path or by attribute value(s). This method can be called with 1 or 2 arguments. If a single String argument is supplied, the value of the argument is treated as the path to the node. if a single argument of type Object is provided, it is treated as a set of field name/value pairs to search for (see {@link com.smartgwt.client..List#find}).
If 2 arguments are supplied, this method will treat the first argument as a fieldName, and return the first node encountered wherenode[fieldName]matches the second argument. So for example, given this tree:foo zoo bar moo bar
Assuming yourpathDelimis the default/andfoois the name of the root node, thentree.find("foo/moo/bar")would return thebarnode under themoonode.
tree.find("name", "bar")would return the firstbarnode because it is the first one in the list whosename(default value ofnameProperty) property matches the valuebar. The two argument usage is generally more interesting when your tree nodes have some custom unique property that you wish to search on. For example if your tree nodes had a unique field called "UID", their serialized form would look something like this:{ name: "foo", children: [...], UID:"someUniqueId"}You could then calltree.find("UID", "someUniqueId")to find that node. Note that the value doesn't have to be a string - it can be any valid JS value, but since this data generally comes from the server, the typical types are string, number, and boolean.
The usage where you pass a single object is interesting when your tree nodes have a number of custom properties that you want to search for in combination. Say your tree nodes had properties for "color" and "shape";tree.find({color: "green", shape: "circle"})would return the first node in the tree where both properties matched.
When searching by path, trailing path delimiters are ignored. So for exampletree.find("foo/zoo/bar")is equivalent totree.find("foo/zoo/bar/")- Parameters:
fieldNameOrPath- Either the path to the node to be found, or the name of a field which should match the value passed as a second parameter- Returns:
- the node matching the supplied criteria or null if not found
-
find
Find a node within this tree using a string path or by attribute value(s).- Overrides:
findin classRecordList- Parameters:
fieldNameOrPath- Either the path to the node to be found, or the name of a field which should match the value passed as a second parametervalue- If specified, this is the desired value for the appropriate field- Returns:
- the node matching the supplied criteria or null if not found
- See Also:
-
find
Find a node within this tree using a string path or by attribute value(s).- Overrides:
findin classRecordList- Parameters:
fieldNameOrPath- Either the path to the node to be found, or the name of a field which should match the value passed as a second parametervalue- If specified, this is the desired value for the appropriate field- Returns:
- the node matching the supplied criteria or null if not found
- See Also:
-
getChildren
Returns all children of a node. If the node is a leaf, this method returns null.
For load on demand trees (those that only have a partial representation client-side) or for databound tree where the underlying set of children is incomplete, this method will return only those nodes that have already been loaded from the server.- Parameters:
node- The node whose children you want to fetch.- Returns:
- List of children for the node (empty List if node is a leaf or has no children)
-
getFolders
Returns all the first-level folders of a node.
For load on demand trees (those that only have a partial representation client-side), this method will return only nodes that have already been loaded from the server.- Parameters:
node- node in question- Returns:
- List of immediate children that are folders
-
getLeaves
Return all the first-level leaves of a node.
For load on demand trees (those that only have a partial representation client-side), this method will return only nodes that have already been loaded from the server.- Parameters:
node- node in question- Returns:
- List of immediate children that are leaves.
-
getDescendants
Returns the list of all descendants of a node. Note: this method can be very slow, especially on large trees because it assembles a list of all descendants recursively. Generally,find(java.lang.String)in combination withgetChildren(com.smartgwt.client.widgets.tree.TreeNode)will be much faster.
For load on demand trees (those that only have a partial representation client-side), this method will return only nodes that have already been loaded from the server.- Returns:
- List of descendants of the node.
-
getDescendants
Returns the list of all descendants of a node. Note: this method can be very slow, especially on large trees because it assembles a list of all descendants recursively. Generally,find(java.lang.String)in combination withgetChildren(com.smartgwt.client.widgets.tree.TreeNode)will be much faster.
For load on demand trees (those that only have a partial representation client-side), this method will return only nodes that have already been loaded from the server.- Parameters:
node- node in question (the root node is asumed if none specified)- Returns:
- List of descendants of the node.
-
getDescendantFolders
Ruturns the list of all descendants of a node that are folders. This works just likegetDescendants(), except leaf nodes are not part of the returned list. LikegetDescendants(), this method can be very slow for large trees. Generally,find(java.lang.String)in combination withgetFolders(com.smartgwt.client.widgets.tree.TreeNode)be much faster.
For load on demand trees (those that only have a partial representation client-side), this method will return only nodes that have already been loaded from the server.- Returns:
- List of descendants of the node that are folders.
-
getDescendantFolders
Ruturns the list of all descendants of a node that are folders. This works just likegetDescendants(), except leaf nodes are not part of the returned list. LikegetDescendants(), this method can be very slow for large trees. Generally,find(java.lang.String)in combination withgetFolders(com.smartgwt.client.widgets.tree.TreeNode)be much faster.
For load on demand trees (those that only have a partial representation client-side), this method will return only nodes that have already been loaded from the server.- Parameters:
node- node in question (the root node is assumed if none specified)- Returns:
- List of descendants of the node that are folders.
-
getDescendantLeaves
Returns the list of all descendants of a node that are leaves. This works just likegetDescendants(), except folders are not part of the returned list. Folders are still recursed into, just not returned. LikegetDescendants(), this method can be very slow for large trees. Generally,find(java.lang.String)in combination withgetLeaves(com.smartgwt.client.widgets.tree.TreeNode)be much faster.
For load on demand trees (those that only have a partial representation client-side), this method will return only nodes that have already been loaded from the server.- Returns:
- List of descendants of the node that are leaves.
-
getDescendantLeaves
Returns the list of all descendants of a node that are leaves. This works just likegetDescendants(), except folders are not part of the returned list. Folders are still recursed into, just not returned. LikegetDescendants(), this method can be very slow for large trees. Generally,find(java.lang.String)in combination withgetLeaves(com.smartgwt.client.widgets.tree.TreeNode)be much faster.
For load on demand trees (those that only have a partial representation client-side), this method will return only nodes that have already been loaded from the server.- Parameters:
node- node in question (the root node is assumed if none specified)- Returns:
- List of descendants of the node that are leaves.
-
add
Add a single node under the specified parent- Parameters:
node- node to addparent- Parent of the node being added. You can pass in either theTreeNodeitself, or a path to the node (as a String), in which case afind(java.lang.String)is performed to find the node.- Returns:
- The added node.
-
add
Add a single node under the specified parent- Parameters:
node- node to addparentPath- Parent of the node being added. You can pass in either theTreeNodeitself, or a path to the node (as a String), in which case afind(java.lang.String)is performed to find the node.- Returns:
- The added node.
-
add
Add a single node under the specified parent- Parameters:
node- node to addparent- Parent of the node being added. You can pass in either theTreeNodeitself, or a path to the node (as a String), in which case afind(java.lang.String)is performed to find the node.position- Position of the new node in the children list. If not specified, the node will be added at the end of the list.- Returns:
- The added node.
-
add
-
addList
Add a list of nodes to some parent.- Parameters:
nodeList- The list of nodes to addparent- Parent of the node being added. You can pass in either theTreeNodeitself, or a path to the node (as a String), in which case afind(java.lang.String)is performed to find the node.- Returns:
- List of added nodes.
-
addList
Add a list of nodes to some parent.- Parameters:
nodeList- The list of nodes to addparentPath- Parent of the node being added. You can pass in either theTreeNodeitself, or a path to the node (as a String), in which case afind(java.lang.String)is performed to find the node.- Returns:
- List of added nodes.
-
addList
Add a list of nodes to some parent.- Parameters:
nodeList- The list of nodes to addparent- Parent of the node being added. You can pass in either theTreeNodeitself, or a path to the node (as a String), in which case afind(java.lang.String)is performed to find the node.position- Position of the new node in the children list. If not specified, the node will be added at the end of the list.- Returns:
- List of added nodes.
-
addList
Add a list of nodes to some parent.- Parameters:
nodeList- The list of nodes to addparentPath- Parent of the node being added. You can pass in either theTreeNodeitself, or a path to the node (as a String), in which case afind(java.lang.String)is performed to find the node.position- Position of the new node in the children list. If not specified, the node will be added at the end of the list.- Returns:
- List of added nodes.
-
removeList
Remove a list of nodes (not necessarily from the same parent), and all children of those nodes.- Parameters:
nodeList- list of nodes to remove- Returns:
- true if the tree was changed as a result of this call
-
openFolders
Open a set of folders, specified by path or as pointers to nodes.- Parameters:
nodeList- List of nodes or node paths.
-
closeFolders
Close a set of folders, specified by path or as pointers to nodes.- Parameters:
nodeList- List of nodes or node paths.
-
getOpenList
Return a flattened list of nodes that are open under some parent, including the parent itself. If the passed in node is a leaf, this method returns null- Parameters:
node- node in question- Returns:
- flattened list of open nodes
-
nodeForRecord
A TreeNode and ListGridRecord represent similar datastructures and it is possible that certain TreeGrid operations return a ListGridRecord since TreeGrid extends ListGrid. So in order to call several of the methods in this Tree class, you need to coerce a ListGridRecord to a TreeNode. This can be done by calling this method.- Parameters:
record- the record- Returns:
- the TreeNode representation of the record
-
openFolder

 Open a particular node

- Parameters:
node- node to open
-
getAllNodes
Get all the nodes that exist in the tree under a particular node, as a flat list, in depth-first traversal order.- Returns:
- all the nodes that exist in the tree
-
getAllNodes
Get all the nodes that exist in the tree under a particular node, as a flat list, in depth-first traversal order.- Parameters:
node- optional node to start from. Default is root.- Returns:
- all the nodes that exist in the tree
-
reloadChildren()to reload the children of a folder, orremoveChildren()if you need to clear the cached children of a folder to add specific local data.