com.smartgwt.client.widgets.tree
Class Tree

java.lang.Object
  extended by com.smartgwt.client.core.BaseClass
      extended by com.smartgwt.client.widgets.tree.Tree
All Implemented Interfaces:
HasHandlers, HasDataChangedHandlers

public class Tree
extends BaseClass
implements HasDataChangedHandlers

A Tree is a data model representing a set of objects linked into a hierarchy.

A Tree has no visual presentation, it is displayed by a TreeGrid or ColumnTree when supplied as data or data.

A Tree can be constructed out of a List of objects with 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 com.smartgwt.client..ResultTree, which is a type of Tree that automatically handles loading data on demand. For information on DataBinding Trees, see TreeDataBinding.


Field Summary
 
Fields inherited from class com.smartgwt.client.core.BaseClass
config, id
 
Constructor Summary
Tree()
           
Tree(com.google.gwt.core.client.JavaScriptObject jsObj)
           
 
Method Summary
 TreeNode add(TreeNode node, java.lang.String parentPath)
          Add a single node under the specified parent
 TreeNode add(TreeNode node, java.lang.String parentPath, int position)
           
 TreeNode add(TreeNode node, TreeNode parent)
          Add a single node under the specified parent
 TreeNode add(TreeNode node, TreeNode parent, int position)
          Add a single node under the specified parent
 HandlerRegistration addDataChangedHandler(DataChangedHandler handler)
          Add a dataChanged handler.
 TreeNode[] addList(TreeNode[] nodeList, java.lang.String parentPath)
          Add a list of nodes to some parent.
 TreeNode[] addList(TreeNode[] nodeList, java.lang.String parentPath, int position)
          Add a list of nodes to some parent.
 TreeNode[] addList(TreeNode[] nodeList, TreeNode parent)
          Add a list of nodes to some parent.
 TreeNode[] addList(TreeNode[] nodeList, TreeNode parent, int position)
          Add a list of nodes to some parent.
 void closeAll()
          Close all nodes under a particular node
 void closeAll(TreeNode node)
          Close all nodes under a particular node
 void closeFolder(TreeNode node)
           Closes a folder
 void closeFolders(TreeNode[] nodeList)
          Close a set of folders, specified by path or as pointers to nodes.
 com.google.gwt.core.client.JavaScriptObject create()
           
 TreeNode find(java.lang.String fieldNameOrPath)
          Find a node within this tree using a string path or by attribute value(s).
 TreeNode find(java.lang.String fieldNameOrPath, java.lang.Object value)
          Find a node within this tree using a string path or by attribute value(s).
 TreeNode findById(java.lang.String id)
          Find the node with the specified ID.
 java.lang.Boolean getAutoOpenRoot()
          If true, the root node is automatically opened when the tree is created or setRoot(com.smartgwt.client.widgets.tree.TreeNode) is called.
 TreeNode[] getChildren(TreeNode node)
          Returns all children of a node.
 java.lang.String getChildrenProperty()
          For trees with the modelType "children", this property specifies the name of the property that contains the list of children for a node.
 ListGridRecord[] getData()
           
 java.lang.Boolean getDefaultIsFolder()
          Controls whether nodes are assumed to be folders or leaves by default.
 java.lang.String getDefaultNodeTitle()
          Title assigned to nodes without a titleProperty value or a nameProperty value.
 TreeNode[] getDescendantFolders()
          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[] getDescendantLeaves()
          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[] getDescendants()
          Returns the list of all descendants of a node.
 TreeNode[] getDescendants(TreeNode node)
          Returns the list of all descendants of a node.
 java.lang.Boolean getDiscardParentlessNodes()
          If this tree has modelType, should nodes in the data array for the tree be dropped if they have an explicitly specified value for the parentIdField which doesn't match any other nodes in the tree.
 TreeNode[] getFolders(TreeNode node)
          Returns all the first-level folders of a node.
 java.lang.String getIdField()
          Name of the property on a TreeNode that holds an id for the node which is unique across the entire Tree.
 java.lang.String getIsFolderProperty()
          Name of property that defines whether a node is a folder.
 TreeNode[] getLeaves(TreeNode node)
          Return all the first-level leaves of a node.
 int getLength()
           Returns the number of items in the current open list.
 int getLevel(TreeNode node)
           Return the number of levels deep this node is in the tree.
 TreeModelType getModelType()
          Selects the model used to construct the tree representation.
 java.lang.String getName(TreeNode node)
           Get the 'name' of a node.
 java.lang.String getNameProperty()
          Name of the property on a TreeNode that holds a name for the node that is unique among it's immediate siblings, thus allowing a unique path to be used to identify the node, similar to a file system.
 TreeNode[] getOpenList(TreeNode node)
          Return a flattened list of nodes that are open under some parent, including the parent itself.
 java.lang.String getOpenProperty()
          The property the default implementation of isOpen(com.smartgwt.client.widgets.tree.TreeNode) consules to determine if the node is open or not.
static Tree getOrCreateRef(com.google.gwt.core.client.JavaScriptObject jsObj)
           
 TreeNode getParent(TreeNode node)
          Returns the parent of this node.
 java.lang.String getParentIdField()
          For trees with modelType "parent", this property specifies the name of the property that contains the unique parent ID of a node.
 java.lang.String getParentPath(TreeNode node)
           Given a node, return the path to it's parent.
 TreeNode[] getParents(TreeNode node)
          Given a node, return an array of the node's parents with the immediate parent first.
 java.lang.String getPath(TreeNode node)
           Returns the path of a node - a path has the following format: ([name][pathDelim]?)*

For example, in this tree:
 java.lang.String getPathDelim()
          Specifies the delimiter between node names.
 java.lang.Boolean getReportCollisions()
          If new nodes are added to a tree with modelType:"parent" which have the same idField as an existing node, the existing node is removed when the new node is added.
 TreeNode getRoot()
          If you're using the "parent" modelType, you can provide the root node configuration via this property.
 java.lang.String getRootValue()
           
 java.lang.Boolean getShowRoot()
          Controls whether a call to getOpenList(com.smartgwt.client.widgets.tree.TreeNode) includes the root node.
 java.lang.String getTitle(TreeNode node)
           Return the title of a node -- the name as it should be presented to the user.
 java.lang.String getTitleProperty()
          Name of the property on a TreeNode that holds the title of the node as it should be shown to the user.
 java.lang.Boolean hasChildren(TreeNode node)
           Returns true if this node has any children.
 java.lang.Boolean hasFolders(TreeNode node)
           Return true if this this node has any children that are folders.
 java.lang.Boolean hasLeaves(TreeNode node)
           Return whether this node has any children that are leaves.
 java.lang.Boolean isDescendantOf(TreeNode child, TreeNode parent)
          Is one node a descendant of the other?
 java.lang.Boolean isFolder(TreeNode node)
           Determines whether a particular node is a folder.
 java.lang.Boolean isLeaf(TreeNode node)
           Returns true if the passed in node is a leaf.
 java.lang.Boolean isOpen(TreeNode node)
           Is a particular node open or closed (works for leaves and folders).
 java.lang.Boolean isRoot(TreeNode node)
           Return true if the passed node is the root node.
 void linkNodes(TreeNode[] nodes)
          This method is provided as a mechanism to link new nodes into the tree of modelType "parent".
 void move(TreeNode node, TreeNode newParent)
           Moves the specified node to a new parent.
 void move(TreeNode node, TreeNode newParent, int position)
           Moves the specified node to a new parent.
static TreeNode nodeForRecord(ListGridRecord record)
          A TreeNode and ListGridRecord represent similar datastructures and it is possible that certain TreeGrid operations return a ListGridRecord since TreeGrid extends ListGrid.
 void openAll()
           Open all nodes under a particular node.
 void openAll(TreeNode node)
           Open all nodes under a particular node.
 void openFolder(TreeNode node)
           Open a particular node
 void openFolders(TreeNode[] nodeList)
          Open a set of folders, specified by path or as pointers to nodes.
 void reloadChildren(TreeNode node)
          Reload the children of a node
 java.lang.Boolean remove(TreeNode node)
           Removes a node, along with all its children.
 java.lang.Boolean removeList(TreeNode[] nodeList)
          Remove a list of nodes (not necessarily from the same parent), and all children of those nodes.
 void setAutoOpenRoot(java.lang.Boolean autoOpenRoot)
          If true, the root node is automatically opened when the tree is created or setRoot(com.smartgwt.client.widgets.tree.TreeNode) is called.
 void setChildrenProperty(java.lang.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.
 void setData(TreeNode[] nodes)
          Optional initial data for the tree.
 void setDefaultIsFolder(java.lang.Boolean defaultIsFolder)
          Controls whether nodes are assumed to be folders or leaves by default.
 void setDefaultNodeTitle(java.lang.String defaultNodeTitle)
          Title assigned to nodes without a titleProperty value or a nameProperty value.
 void setDiscardParentlessNodes(java.lang.Boolean discardParentlessNodes)
          If this tree has modelType, should nodes in the data array for the tree be dropped if they have an explicitly specified value for the parentIdField which doesn't match any other nodes in the tree.
 void setIdField(java.lang.String idField)
          Name of the property on a TreeNode that holds an id for the node which is unique across the entire Tree.
 void setIsFolderProperty(java.lang.String isFolderProperty)
          Name of property that defines whether a node is a folder.
 void setModelType(TreeModelType modelType)
          Selects the model used to construct the tree representation.
 void setNameProperty(java.lang.String nameProperty)
          Name of the property on a TreeNode that holds a name for the node that is unique among it's immediate siblings, thus allowing a unique path to be used to identify the node, similar to a file system.
 void setOpenProperty(java.lang.String openProperty)
          The property the default implementation of isOpen(com.smartgwt.client.widgets.tree.TreeNode) consules to determine if the node is open or not.
 void setParentIdField(java.lang.String parentIdField)
          For trees with modelType "parent", this property specifies the name of the property that contains the unique parent ID of a node.
 void setPathDelim(java.lang.String pathDelim)
          Specifies the delimiter between node names.
 void setReportCollisions(java.lang.Boolean reportCollisions)
          If new nodes are added to a tree with modelType:"parent" which have the same idField as an existing node, the existing node is removed when the new node is added.
 void setRoot(TreeNode root)
          If you're using the "parent" modelType, you can provide the root node configuration via this property.
 void setRootValue(int rootValue)
          If you are using the "parent" modelType and did not specify a root node via root with an id (idField), then you can provide the root node's id via this property.
 void setRootValue(java.lang.String rootValue)
          If you are using the "parent" modelType and did not specify a root node via root with an id (idField), then you can provide the root node's id via this property.
 void setShowRoot(java.lang.Boolean showRoot)
          Controls whether a call to getOpenList(com.smartgwt.client.widgets.tree.TreeNode) includes the root node.
 void setTitleProperty(java.lang.String titleProperty)
          Name of the property on a TreeNode that holds the title of the node as it should be shown to the user.
 
Methods inherited from class com.smartgwt.client.core.BaseClass
destroy, doAddHandler, error, errorIfNotCreated, fireEvent, getAttribute, getAttributeAsBoolean, getAttributeAsDouble, getAttributeAsElement, getAttributeAsFloat, getAttributeAsInt, getAttributeAsJavaScriptObject, getAttributeAsString, getConfig, getHandlerCount, getID, getJsObj, getOrCreateJsObj, getRef, isCreated, onInit, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setID, setProperty, setProperty, setProperty, setProperty
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.google.gwt.event.shared.HasHandlers
fireEvent
 

Constructor Detail

Tree

public Tree()

Tree

public Tree(com.google.gwt.core.client.JavaScriptObject jsObj)
Method Detail

getOrCreateRef

public static Tree getOrCreateRef(com.google.gwt.core.client.JavaScriptObject jsObj)

create

public com.google.gwt.core.client.JavaScriptObject create()
Specified by:
create in class BaseClass

setModelType

public void setModelType(TreeModelType modelType)
Selects the model used to construct the tree representation. See TreeModelType for 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 data attribute. If the "children" modelType is used, you can provide the initial tree structure to the Tree via the root attribute.

Note : This is an advanced setting

Parameters:
modelType - modelType Default value is "children"

getModelType

public TreeModelType getModelType()
Selects the model used to construct the tree representation. See TreeModelType for 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 data attribute. If the "children" modelType is used, you can provide the initial tree structure to the Tree via the root attribute.

Returns:
TreeModelType

setIsFolderProperty

public void setIsFolderProperty(java.lang.String isFolderProperty)
Name of property that defines whether a node is a folder. By default this is set to isFolder.

Parameters:
isFolderProperty - isFolderProperty Default value is "isFolder"

getIsFolderProperty

public java.lang.String getIsFolderProperty()
Name of property that defines whether a node is a folder. By default this is set to isFolder.

Returns:
String

setDefaultIsFolder

public void setDefaultIsFolder(java.lang.Boolean defaultIsFolder)
                        throws java.lang.IllegalStateException
Controls whether nodes are assumed to be folders or leaves by default.

Nodes that have children or have the isFolderProperty set to true will be considered folders by default. Other nodes will be considered folders or leaves by default according to this setting.

Parameters:
defaultIsFolder - defaultIsFolder Default value is null
Throws:
java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

getDefaultIsFolder

public java.lang.Boolean getDefaultIsFolder()
Controls whether nodes are assumed to be folders or leaves by default.

Nodes that have children or have the isFolderProperty set to true will be considered folders by default. Other nodes will be considered folders or leaves by default according to this setting.

Returns:
Boolean

setReportCollisions

public void setReportCollisions(java.lang.Boolean reportCollisions)
                         throws java.lang.IllegalStateException
If new nodes are added to a tree with modelType:"parent" which have the same idField as an existing node, the existing node is removed when the new node is 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 - reportCollisions Default value is true
Throws:
java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

getReportCollisions

public java.lang.Boolean getReportCollisions()
If new nodes are added to a tree with modelType:"parent" which have the same idField as an existing node, the existing node is removed when the new node is 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:
Boolean

setPathDelim

public void setPathDelim(java.lang.String pathDelim)
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 calling getPath(com.smartgwt.client.widgets.tree.TreeNode) and can be used to find any node in the tree by calling find(java.lang.String). Note that you can also hand-construct a path - in other words you are not required to call getPath(com.smartgwt.client.widgets.tree.TreeNode) in order to later use find(java.lang.String) 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 the nameProperty that's used for naming the nodes. So for example, if you have the following tree:
 one
   two
     three/four
 
Then you will be unable to find the three/four node using find(java.lang.String) 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 the three/four node in the tree above by calling tree.find("one|two|three/four").

The pathDelim is used only by getPath(com.smartgwt.client.widgets.tree.TreeNode) and find(java.lang.String) and does not affect any aspect of the tree structure or other forms of tree navigation (such as via getChildren(com.smartgwt.client.widgets.tree.TreeNode)).

Note : This is an advanced setting

Parameters:
pathDelim - pathDelim Default value is "/"

getPathDelim

public java.lang.String 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 calling getPath(com.smartgwt.client.widgets.tree.TreeNode) and can be used to find any node in the tree by calling find(java.lang.String). Note that you can also hand-construct a path - in other words you are not required to call getPath(com.smartgwt.client.widgets.tree.TreeNode) in order to later use find(java.lang.String) 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 the nameProperty that's used for naming the nodes. So for example, if you have the following tree:
 one
   two
     three/four
 
Then you will be unable to find the three/four node using find(java.lang.String) 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 the three/four node in the tree above by calling tree.find("one|two|three/four").

The pathDelim is used only by getPath(com.smartgwt.client.widgets.tree.TreeNode) and find(java.lang.String) and does not affect any aspect of the tree structure or other forms of tree navigation (such as via getChildren(com.smartgwt.client.widgets.tree.TreeNode)).

Returns:
String

setNameProperty

public void setNameProperty(java.lang.String nameProperty)
Name of the property on a TreeNode that holds a name for the node that is unique among it's immediate siblings, thus allowing a unique path to be used to identify the node, similar to a file system. Default value is "name". See name for usage.

Parameters:
nameProperty - nameProperty Default value is "name"

getNameProperty

public java.lang.String getNameProperty()
Name of the property on a TreeNode that holds a name for the node that is unique among it's immediate siblings, thus allowing a unique path to be used to identify the node, similar to a file system. Default value is "name". See name for usage.

Returns:
String

setTitleProperty

public void setTitleProperty(java.lang.String titleProperty)
Name of the property on a TreeNode that holds the title of the node as it should be shown to the user. Default value is "title". See title for usage.

Parameters:
titleProperty - titleProperty Default value is "title"

getTitleProperty

public java.lang.String getTitleProperty()
Name of the property on a TreeNode that holds the title of the node as it should be shown to the user. Default value is "title". See title for usage.

Returns:
String

setIdField

public void setIdField(java.lang.String idField)
                throws java.lang.IllegalStateException
Name of the property on a TreeNode that 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". See id for usage.

Note : This is an advanced setting

Parameters:
idField - idField Default value is "id"
Throws:
java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

getIdField

public java.lang.String getIdField()
Name of the property on a TreeNode that 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". See id for usage.

Returns:
String

setParentIdField

public void setParentIdField(java.lang.String parentIdField)
                      throws java.lang.IllegalStateException
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". See parentId for usage.

Note : This is an advanced setting

Parameters:
parentIdField - parentIdField Default value is "parentId"
Throws:
java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

getParentIdField

public java.lang.String 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". See parentId for usage.

Returns:
String

setChildrenProperty

public void setChildrenProperty(java.lang.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.

Parameters:
childrenProperty - childrenProperty Default value is "children"

getChildrenProperty

public java.lang.String 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:
String

setOpenProperty

public void setOpenProperty(java.lang.String openProperty)
The property the default implementation of isOpen(com.smartgwt.client.widgets.tree.TreeNode) consules 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 - see SharingNodes for more info on this.

Note : This is an advanced setting

Parameters:
openProperty - openProperty Default value is null

getOpenProperty

public java.lang.String getOpenProperty()
The property the default implementation of isOpen(com.smartgwt.client.widgets.tree.TreeNode) consules 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 - see SharingNodes for more info on this.

Returns:
String

setRoot

public void setRoot(TreeNode root)
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
 zoo
 
You would initialize the tree as follows:
 Tree.create({
     root: { name:"root", children: [
         { name:"foo", children: [
             { name: "bar" }
         ]},
         { name: "zoo" }
     ]}
 });
 
Note that if you provide a name property for the root node, then the path to any node underneath it will start with that name. So in the example above, the path to the bar node would be root/foo/bar (assuming you're using the default pathDelim. If you omit the name attribute on the root node, then it's name is automatically set to the pathDelim value. So in the example above, if you omitted name:"root", then the path to the bar node would be /foo/bar.

Note: if you initialize a Tree with no root value, a root node will be auto-created for you. You can then call add(com.smartgwt.client.widgets.tree.TreeNode, com.smartgwt.client.widgets.tree.TreeNode) to construct the tree. Set the root of the tree.

Parameters:
root - new root node. Default value is null

getRoot

public TreeNode 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
 zoo
 
You would initialize the tree as follows:
 Tree.create({
     root: { name:"root", children: [
         { name:"foo", children: [
             { name: "bar" }
         ]},
         { name: "zoo" }
     ]}
 });
 
Note that if you provide a name property for the root node, then the path to any node underneath it will start with that name. So in the example above, the path to the bar node would be root/foo/bar (assuming you're using the default pathDelim. If you omit the name attribute on the root node, then it's name is automatically set to the pathDelim value. So in the example above, if you omitted name:"root", then the path to the bar node would be /foo/bar.

Note: if you initialize a Tree with no root value, a root node will be auto-created for you. You can then call add(com.smartgwt.client.widgets.tree.TreeNode, com.smartgwt.client.widgets.tree.TreeNode) to construct the tree.

Returns:
Returns the root node of the tree.

setDiscardParentlessNodes

public void setDiscardParentlessNodes(java.lang.Boolean discardParentlessNodes)
                               throws java.lang.IllegalStateException
If this tree has modelType, should nodes in the data array for the tree be dropped if they have an explicitly specified value for the parentIdField which 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 - discardParentlessNodes Default value is false
Throws:
java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

getDiscardParentlessNodes

public java.lang.Boolean getDiscardParentlessNodes()
If this tree has modelType, should nodes in the data array for the tree be dropped if they have an explicitly specified value for the parentIdField which 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:
Boolean

setShowRoot

public void setShowRoot(java.lang.Boolean showRoot)
Controls whether a call to getOpenList(com.smartgwt.client.widgets.tree.TreeNode) includes the root node. Since view components such as a TreeGrid use getOpenList() to display the currently visible tree, showRoot controls whether the root node is shown to the user.

All Trees must have a single, logical root, however, most applications want to show multiple nodes at top level. showRoot:false, the default setting, prevents the logical root from being shown, so that the displayed tree begins with the children of root.

You can set showRoot:true to show the single, logical root node as the only top-level node. This property is only meaningful for Trees where you supplied a value for root, otherwise, you will see an automatically generated root node that is meaningless to the user.

Parameters:
showRoot - showRoot Default value is false

getShowRoot

public java.lang.Boolean getShowRoot()
Controls whether a call to getOpenList(com.smartgwt.client.widgets.tree.TreeNode) includes the root node. Since view components such as a TreeGrid use getOpenList() to display the currently visible tree, showRoot controls whether the root node is shown to the user.

All Trees must have a single, logical root, however, most applications want to show multiple nodes at top level. showRoot:false, the default setting, prevents the logical root from being shown, so that the displayed tree begins with the children of root.

You can set showRoot:true to show the single, logical root node as the only top-level node. This property is only meaningful for Trees where you supplied a value for root, otherwise, you will see an automatically generated root node that is meaningless to the user.

Returns:
Boolean

setAutoOpenRoot

public void setAutoOpenRoot(java.lang.Boolean autoOpenRoot)
If true, the root node is automatically opened when the tree is created or setRoot(com.smartgwt.client.widgets.tree.TreeNode) is called.

Parameters:
autoOpenRoot - autoOpenRoot Default value is true

getAutoOpenRoot

public java.lang.Boolean getAutoOpenRoot()
If true, the root node is automatically opened when the tree is created or setRoot(com.smartgwt.client.widgets.tree.TreeNode) is called.

Returns:
Boolean

setDefaultNodeTitle

public void setDefaultNodeTitle(java.lang.String defaultNodeTitle)
Title assigned to nodes without a titleProperty value or a nameProperty value.

Parameters:
defaultNodeTitle - defaultNodeTitle Default value is "Untitled"

getDefaultNodeTitle

public java.lang.String getDefaultNodeTitle()
Title assigned to nodes without a titleProperty value or a nameProperty value.

Returns:
String

isRoot

public java.lang.Boolean isRoot(TreeNode node)
Return true if the passed node is the root node.

Parameters:
node - node to test
Returns:
true if the node is the root node

getName

public java.lang.String getName(TreeNode node)
Get the 'name' of a node. This is node[nameProperty]. If that value has not been set on the node, a unique value (within this parent) will be auto-generated and returned.

Parameters:
node - node in question
Returns:
name of the node

getTitle

public java.lang.String getTitle(TreeNode node)
Return the title of a node -- the name as it should be presented to the user. This method works as follows: You can override this method to return the title of your choice for a given node.

To override the title for an autoconstructed tree (for example, in a databound TreeGrid), override TreeGrid.getNodeTitle(com.smartgwt.client.widgets.tree.TreeNode, int, com.smartgwt.client.widgets.grid.ListGridField) instead.

Parameters:
node - node for which the title is being requested
Returns:
title to display

getPath

public java.lang.String getPath(TreeNode node)
Returns the path of a node - a path has the following format: ([name][pathDelim]?)*

For example, in this tree:
 root
   foo
     bar
 
Assuming that pathDelim is the default /, the bar node would have the path root/foo/bar and the path for the foo node would be root/foo.

Once you have a path to a node, you can call find(path) to retrieve a reference to the node later.

Parameters:
node - node in question
Returns:
path to the node

getParentPath

public java.lang.String getParentPath(TreeNode node)
Given a node, return the path to it's parent. This works just like getPath(com.smartgwt.client.widgets.tree.TreeNode) except the node itself is not reported as part of the path.

Parameters:
node - node in question
Returns:
path to the node's parent

getLevel

public int getLevel(TreeNode node)
Return the number of levels deep this node is in the tree. For example, for this tree:
 root
   foo
     bar
 
Calling tree.getLevel(bar) will return 2.

Parameters:
node - node in question
Returns:
number of parents the node has

isFolder

public java.lang.Boolean isFolder(TreeNode node)
Determines whether a particular node is a folder. The logic works as follows:

You can override this method to provide your own intepretation of what constitutes a folder.

Parameters:
node - node in question
Returns:
true if the node is a folder

isLeaf

public java.lang.Boolean isLeaf(TreeNode node)
Returns true if the passed in node is a leaf.

Parameters:
node - node in question
Returns:
true if the node is a leaf

hasChildren

public java.lang.Boolean hasChildren(TreeNode node)
Returns true if this node has any children.

Parameters:
node - node in question
Returns:
true if the node has children

hasFolders

public java.lang.Boolean hasFolders(TreeNode node)
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

public java.lang.Boolean hasLeaves(TreeNode node)
Return whether this node has any children that are leaves.

Parameters:
node - node in question
Returns:
true fi the node has children that are leaves

isDescendantOf

public java.lang.Boolean isDescendantOf(TreeNode child,
                                        TreeNode parent)
Is one node a descendant of the other?

Parameters:
child - child node
parent - parent node
Returns:
true == parent is an ancestor of child

addDataChangedHandler

public HandlerRegistration addDataChangedHandler(DataChangedHandler handler)
Add a dataChanged handler.

Called when the structure of this tree is changed in any way. Intended to be observed.

Note that on a big change (many items being added or deleted) this may be called multiple times

Specified by:
addDataChangedHandler in interface HasDataChangedHandlers
Parameters:
handler - the dataChanged handler
Returns:
HandlerRegistration used to remove this handler

move

public void move(TreeNode node,
                 TreeNode newParent)
Moves the specified node to a new parent.

Parameters:
node - node to move
newParent - new parent to move the node to

move

public void move(TreeNode node,
                 TreeNode newParent,
                 int position)
Moves the specified node to a new parent.

Parameters:
node - node to move
newParent - new parent to move the node to
position - Position of the new node in the children list. If not specified, the node will be added at the end of the list.

remove

public java.lang.Boolean remove(TreeNode node)
Removes a node, along with all its children.

Parameters:
node - node to remove
Returns:
true if the tree was changed as a result of this call

reloadChildren

public void reloadChildren(TreeNode node)
Reload the children of a node

Parameters:
node - node in question

isOpen

public java.lang.Boolean isOpen(TreeNode node)
Is a particular node open or closed (works for leaves and folders).

Parameters:
node - node in question
Returns:
true if the node is open

openFolder

public void openFolder(TreeNode node)
Open a particular node

Parameters:
node - node to open

closeFolder

public void closeFolder(TreeNode node)
Closes a folder

Parameters:
node - folder to close

openAll

public void openAll()
Open all nodes under a particular node.


openAll

public void openAll(TreeNode node)
Open all nodes under a particular node.

Parameters:
node - node from which to open folders (if not specified, the root node is used)

closeAll

public void closeAll()
Close all nodes under a particular node


closeAll

public void closeAll(TreeNode node)
Close all nodes under a particular node

Parameters:
node - node from which to close folders (if not specified, the root node is used)

getLength

public int getLength()
Returns the number of items in the current open list.

Returns:
number of items in open list

setData

public void setData(TreeNode[] nodes)
Optional initial data for the tree. How this data is interpreted depends on this tree's modelType.

If modelType is "parent", the list that you provide will be passed to linkNodes(com.smartgwt.client.widgets.tree.TreeNode[]), integrating the nodes into the tree.

In this case the root node must be supplied separately via root, or you may instead provide the id of the root node via rootValue. So for example, to create this tree:

 foo   bar zoo 
with modelType:"parent", you can do this:
 Tree.create({   root: {id:
 "root"},   data: [     {name: "foo", id: "foo", parentId: "root"},     {name: "bar", id: "bar", parentId:
 "foo"},
 {name: "zoo", id: "zoo", parentId: "root"} }); 
Or this:
 Tree.create({   rootValue: "root",
 data: [     {name: "foo", id: "foo", parentId: "root"},     {name: "bar", id: "bar", parentId: "foo"},     {name:
 "zoo", id: "zoo", parentId: "root"} }); 
Specifying the root node explicitly allows you to give it a name, changing the way path derivation works (see root for more on naming the root node).

For modelType:"children" trees, the data passed in will be assumed to be an array of children the tree's root node.

Parameters:
data - data Default value is null
Throws:
java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

getData

public ListGridRecord[] getData()

setRootValue

public void setRootValue(java.lang.String rootValue)
If you are using the "parent" modelType and did not specify a root node via root with an id (idField), then you can provide the root node's id via this property. See the example in data for more info.

Parameters:
rootValue - rootValue Default value is null
Throws:
java.lang.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 via root with an id (idField), then you can provide the root node's id via this property. See the example in data for more info.

Parameters:
rootValue - rootValue Default value is null
Throws:
java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

getRootValue

public java.lang.String getRootValue()

getParent

public TreeNode getParent(TreeNode node)
Returns the parent of this node.

Parameters:
node - node in question
Returns:
parent of this node

linkNodes

public void linkNodes(TreeNode[] nodes)
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 by idField) and a parent ID (keyed by parentIdField). 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

public TreeNode[] getParents(TreeNode node)
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 
Calling tree.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

public TreeNode findById(java.lang.String id)
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

public TreeNode find(java.lang.String fieldNameOrPath)
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 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 where node[fieldName]matches the second argument. So for example, given this tree:
 foo   zoo
   bar   moo     bar 
Assuming your pathDelim is the default / and foo is the name of the root node, then tree.find("foo/moo/bar") would return the bar node under the moo node.

tree.find("name", "bar") would return the first bar node because it is the first one in the list whose name (default value of nameProperty) property matches the value bar. 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 call tree.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 example tree.find("foo/zoo/bar") is equivalent to tree.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

public TreeNode find(java.lang.String fieldNameOrPath,
                     java.lang.Object value)
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 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 where node[fieldName]matches the second argument. So for example, given this tree:
 foo   zoo
   bar   moo     bar 
Assuming your pathDelim is the default / and foo is the name of the root node, then tree.find("foo/moo/bar") would return the bar node under the moo node.

tree.find("name", "bar") would return the first bar node because it is the first one in the list whose name (default value of nameProperty) property matches the value bar. 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 call tree.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 example tree.find("foo/zoo/bar") is equivalent to tree.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
value - If specified, this is the desired value for the appropriate field
Returns:
the node matching the supplied criteria or null if not found

getChildren

public TreeNode[] getChildren(TreeNode node)
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), this method will return only nodes that have already been loaded from the server. Furthermore, for databound trees the return value will be a com.smartgwt.client.data.ResultSet, so it's ${isc.DocUtils.linkForRef('interface:List')} interface instead of as a native Javascript Array.

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

public TreeNode[] getFolders(TreeNode node)
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. Furthermore, for databound trees the return value will be a com.smartgwt.client.data.ResultSet, so it's ${isc.DocUtils.linkForRef('interface:List')} interface instead of as a native Javascript Array.

Parameters:
node - node in question
Returns:
List of immediate children that are folders

getLeaves

public TreeNode[] getLeaves(TreeNode node)
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. Furthermore, for databound trees the return value will be a com.smartgwt.client.data.ResultSet, so it's ${isc.DocUtils.linkForRef('interface:List')} interface instead of as a native Javascript Array.

Parameters:
node - node in question
Returns:
List of immediate children that are leaves.

getDescendants

public TreeNode[] 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 with getChildren(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. Furthermore, for databound trees the return value will be a com.smartgwt.client.data.ResultSet, so it's to access the return value using the ${isc.DocUtils.linkForRef('interface:List')} interface instead of as a native Javascript Array.

Returns:
List of descendants of the node.

getDescendants

public TreeNode[] getDescendants(TreeNode node)
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 with getChildren(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. Furthermore, for databound trees the return value will be a com.smartgwt.client.data.ResultSet, so it's to access the return value using the ${isc.DocUtils.linkForRef('interface:List')} interface instead of as a native Javascript Array.

Parameters:
node - node in question (the root node is asumed if none specified)
Returns:
List of descendants of the node.

getDescendantFolders

public TreeNode[] getDescendantFolders()
Ruturns the list of all descendants of a node that are folders. This works just like getDescendants(), except leaf nodes are not part of the returned list. Like getDescendants(), this method can be very slow for large trees. Generally, find(java.lang.String) in combination with getFolders(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. Furthermore, for databound trees the return value will be a com.smartgwt.client.data.ResultSet, so it's ${isc.DocUtils.linkForRef('interface:List')} interface instead of as a native Javascript Array.

Returns:
List of descendants of the node that are folders.

getDescendantFolders

public TreeNode[] getDescendantFolders(TreeNode node)
Ruturns the list of all descendants of a node that are folders. This works just like getDescendants(), except leaf nodes are not part of the returned list. Like getDescendants(), this method can be very slow for large trees. Generally, find(java.lang.String) in combination with getFolders(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. Furthermore, for databound trees the return value will be a com.smartgwt.client.data.ResultSet, so it's ${isc.DocUtils.linkForRef('interface:List')} interface instead of as a native Javascript Array.

Parameters:
node - node in question (the root node is assumed if none specified)
Returns:
List of descendants of the node that are folders.

getDescendantLeaves

public TreeNode[] getDescendantLeaves()
Returns the list of all descendants of a node that are leaves. This works just like getDescendants(), except folders are not part of the returned list. Folders are still recursed into, just not returned. Like getDescendants(), this method can be very slow for large trees. Generally, find(java.lang.String) in combination with getLeaves(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. Furthermore, for databound trees the return value will be a com.smartgwt.client.data.ResultSet, so it's ${isc.DocUtils.linkForRef('interface:List')} interface instead of as a native Javascript Array.

Returns:
List of descendants of the node that are leaves.

getDescendantLeaves

public TreeNode[] getDescendantLeaves(TreeNode node)
Returns the list of all descendants of a node that are leaves. This works just like getDescendants(), except folders are not part of the returned list. Folders are still recursed into, just not returned. Like getDescendants(), this method can be very slow for large trees. Generally, find(java.lang.String) in combination with getLeaves(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. Furthermore, for databound trees the return value will be a com.smartgwt.client.data.ResultSet, so it's ${isc.DocUtils.linkForRef('interface:List')} interface instead of as a native Javascript Array.

Parameters:
node - node in question (the root node is assumed if none specified)
Returns:
List of descendants of the node that are leaves.

add

public TreeNode add(TreeNode node,
                    TreeNode parent)
Add a single node under the specified parent

Parameters:
node - node to add
parent - Parent of the node being added. You can pass in either the TreeNode itself, or a path to the node (as a String), in which case a find(java.lang.String) is performed to find the node.
Returns:
The added node.

add

public TreeNode add(TreeNode node,
                    java.lang.String parentPath)
Add a single node under the specified parent

Parameters:
node - node to add
parentPath - Parent of the node being added. You can pass in either the TreeNode itself, or a path to the node (as a String), in which case a find(java.lang.String) is performed to find the node.
Returns:
The added node.

add

public TreeNode add(TreeNode node,
                    TreeNode parent,
                    int position)
Add a single node under the specified parent

Parameters:
node - node to add
parent - Parent of the node being added. You can pass in either the TreeNode itself, or a path to the node (as a String), in which case a find(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

public TreeNode add(TreeNode node,
                    java.lang.String parentPath,
                    int position)

addList

public TreeNode[] addList(TreeNode[] nodeList,
                          TreeNode parent)
Add a list of nodes to some parent.

Parameters:
nodeList - The list of nodes to add
parent - Parent of the node being added. You can pass in either the TreeNode itself, or a path to the node (as a String), in which case a find(java.lang.String) is performed to find the node.
Returns:
List of added nodes.

addList

public TreeNode[] addList(TreeNode[] nodeList,
                          java.lang.String parentPath)
Add a list of nodes to some parent.

Parameters:
nodeList - The list of nodes to add
parentPath - Parent of the node being added. You can pass in either the TreeNode itself, or a path to the node (as a String), in which case a find(java.lang.String) is performed to find the node.
Returns:
List of added nodes.

addList

public TreeNode[] addList(TreeNode[] nodeList,
                          TreeNode parent,
                          int position)
Add a list of nodes to some parent.

Parameters:
nodeList - The list of nodes to add
parent - Parent of the node being added. You can pass in either the TreeNode itself, or a path to the node (as a String), in which case a find(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

public TreeNode[] addList(TreeNode[] nodeList,
                          java.lang.String parentPath,
                          int position)
Add a list of nodes to some parent.

Parameters:
nodeList - The list of nodes to add
parentPath - Parent of the node being added. You can pass in either the TreeNode itself, or a path to the node (as a String), in which case a find(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

public java.lang.Boolean removeList(TreeNode[] nodeList)
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

public void openFolders(TreeNode[] nodeList)
Open a set of folders, specified by path or as pointers to nodes.

Parameters:
nodeList - List of nodes or node paths.

closeFolders

public void closeFolders(TreeNode[] nodeList)
Close a set of folders, specified by path or as pointers to nodes.

Parameters:
nodeList - List of nodes or node paths.

getOpenList

public TreeNode[] getOpenList(TreeNode node)
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

public static TreeNode nodeForRecord(ListGridRecord record)
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