Package com.smartgwt.client.widgets.tree

Class Tree

java.lang.Object
com.smartgwt.client.core.BaseClass
com.smartgwt.client.data.RecordList
com.smartgwt.client.widgets.tree.Tree
All Implemented Interfaces:
HasHandlers, HasDataChangedHandlers, HasDataChangedHandlers
Direct Known Subclasses:
ResultTree
public class Tree extends RecordList 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 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.

  • Constructor Details

  • Method Details

    • getOrCreateRef

      public static Tree getOrCreateRef(JavaScriptObject jsObj)

    • setJavaScriptObject

      public void setJavaScriptObject(JavaScriptObject jsObj)
      Overrides:
      setJavaScriptObject in class BaseClass

    • create

      public JavaScriptObject create()
      Overrides:
      create in class RecordList

    • setAllowFilterOnLinkFields

      public Tree setAllowFilterOnLinkFields(Boolean allowFilterOnLinkFields) throws IllegalStateException
      For a multi-link tree, indicates whether client-side filtering is allowed on the fields of the linkDataSource. When this property is true, filtering operations involving link fields work as expected (ie, as if those fields were present on the main dataSource); 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:
      Tree instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created

    • getAllowFilterOnLinkFields

      public Boolean getAllowFilterOnLinkFields()
      For a multi-link tree, indicates whether client-side filtering is allowed on the fields of the linkDataSource. When this property is true, filtering operations involving link fields work as expected (ie, as if those fields were present on the main dataSource); 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

      public Tree setAutoOpenRoot(Boolean autoOpenRoot)
      If true, the root node is automatically opened when the tree is created or setRoot() is called.
      Parameters:
      autoOpenRoot - New autoOpenRoot value. Default value is true
      Returns:
      Tree instance, for chaining setter calls

    • getAutoOpenRoot

      public Boolean getAutoOpenRoot()
      If true, the root node is automatically opened when the tree is created or setRoot() is called.
      Returns:
      Current autoOpenRoot value. Default value is true

    • setChildrenProperty

      public Tree 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.
      Parameters:
      childrenProperty - New childrenProperty value. Default value is "children"
      Returns:
      Tree instance, for chaining setter calls
      See Also:

    • getChildrenProperty

      public 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:
      Current childrenProperty value. Default value is "children"
      See Also:

    • setDataSource

      public Tree setDataSource(DataSource dataSource) throws IllegalStateException
      Specifies what DataSource this tree is associated with.

      A DataSource is required when filtering a tree, even if it isn't a ResultTree, though it may be passed to getFilteredTree() rather than set on the tree itself. If a DataSource is specified it will also affect sorting, where relevant, such as if the tree is set as TreeGrid.data.

      Parameters:
      dataSource - New dataSource value. Default value is null
      Returns:
      Tree instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created

    • getDataSource

      public DataSource getDataSource()
      Specifies what DataSource this tree is associated with.

      A DataSource is required when filtering a tree, even if it isn't a ResultTree, though it may be passed to getFilteredTree() rather than set on the tree itself. If a DataSource is specified it will also affect sorting, where relevant, such as if the tree is set as TreeGrid.data.

      Returns:
      Current dataSource value. Default value is null

    • setDataSource

      public Tree setDataSource(String dataSource) throws IllegalStateException
      Specifies what DataSource this tree is associated with.

      A DataSource is required when filtering a tree, even if it isn't a ResultTree, though it may be passed to getFilteredTree() rather than set on the tree itself. If a DataSource is specified it will also affect sorting, where relevant, such as if the tree is set as TreeGrid.data.

      Parameters:
      dataSource - New dataSource value. Default value is null
      Returns:
      Tree instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created

    • getDataSourceAsString

      public String getDataSourceAsString()
      Specifies what DataSource this tree is associated with.

      A DataSource is required when filtering a tree, even if it isn't a ResultTree, though it may be passed to getFilteredTree() rather than set on the tree itself. If a DataSource is specified it will also affect sorting, where relevant, such as if the tree is set as TreeGrid.data.

      Returns:
      Current dataSource value. Default value is null

    • setDefaultIsFolder

      public Tree setDefaultIsFolder(Boolean defaultIsFolder) throws 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.

      See also ResultTree.defaultIsFolder for more details on how defaultIsFolder interacts with loading data on demand.

      Parameters:
      defaultIsFolder - New defaultIsFolder value. Default value is null
      Returns:
      Tree instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created

    • getDefaultIsFolder

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

      See also ResultTree.defaultIsFolder for more details on how defaultIsFolder interacts with loading data on demand.

      Returns:
      Current defaultIsFolder value. Default value is null

    • setDefaultNodeTitle

      public Tree setDefaultNodeTitle(String defaultNodeTitle)
      Title assigned to nodes without a titleProperty value or a nameProperty value.
      Parameters:
      defaultNodeTitle - New defaultNodeTitle value. Default value is "Untitled"
      Returns:
      Tree instance, for chaining setter calls

    • getDefaultNodeTitle

      public String getDefaultNodeTitle()
      Title assigned to nodes without a titleProperty value or a nameProperty value.
      Returns:
      Current defaultNodeTitle value. Default value is "Untitled"

    • setDiscardParentlessNodes

      public Tree setDiscardParentlessNodes(Boolean discardParentlessNodes) throws IllegalStateException
      If this tree has modelType:"parent", 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 - New discardParentlessNodes value. Default value is false
      Returns:
      Tree instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created

    • getDiscardParentlessNodes

      public Boolean getDiscardParentlessNodes()
      If this tree has modelType:"parent", 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:
      Current discardParentlessNodes value. Default value is false

    • setIdField

      public Tree setIdField(String idField) throws 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 TreeNode.id for usage.

      Note : This is an advanced setting

      Parameters:
      idField - New idField value. Default value is "id"
      Returns:
      Tree instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created
      See Also:

    • getIdField

      public 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 TreeNode.id for usage.
      Returns:
      Current idField value. Default value is "id"
      See Also:

    • setIsFolderProperty

      public Tree setIsFolderProperty(String isFolderProperty)
      Name of property that defines whether a node is a folder. By default this is set to TreeNode.isFolder.
      Parameters:
      isFolderProperty - New isFolderProperty value. Default value is "isFolder"
      Returns:
      Tree instance, for chaining setter calls
      See Also:

    • getIsFolderProperty

      public String getIsFolderProperty()
      Name of property that defines whether a node is a folder. By default this is set to TreeNode.isFolder.
      Returns:
      Current isFolderProperty value. Default value is "isFolder"
      See Also:
      • com.smartgwt.client.widgets.tree.TreeNode#getIsFolder

    • setLinkPositionField

      public Tree setLinkPositionField(String linkPositionField) throws IllegalStateException
      The name of the "position" field in this multi-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:
      Tree instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created

    • getLinkPositionField

      public String getLinkPositionField()
      The name of the "position" field in this multi-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

      public Tree 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 - New modelType value. Default value is "children"
      Returns:
      Tree instance, for chaining setter calls
      See Also:

    • 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:
      Current modelType value. Default value is "children"
      See Also:

    • setNameProperty

      public Tree setNameProperty(String nameProperty)
      Name of the property on a TreeNode that 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". See TreeNode.name for usage.
      Parameters:
      nameProperty - New nameProperty value. Default value is "name"
      Returns:
      Tree instance, for chaining setter calls
      See Also:

    • getNameProperty

      public String getNameProperty()
      Name of the property on a TreeNode that 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". See TreeNode.name for usage.
      Returns:
      Current nameProperty value. Default value is "name"
      See Also:

    • setOpenProperty

      public Tree setOpenProperty(String openProperty)
      The property consulted by the default implementation of isOpen() 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.

      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 the openProperty is not used at all.

      Note : This is an advanced setting

      Parameters:
      openProperty - New openProperty value. Default value is null
      Returns:
      Tree instance, for chaining setter calls
      See Also:

    • getOpenProperty

      public String getOpenProperty()
      The property consulted by the default implementation of isOpen() 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.

      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 the openProperty is not used at all.

      Returns:
      Current openProperty value. Default value is null
      See Also:

    • setParentIdField

      public Tree setParentIdField(String parentIdField) throws 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 TreeNode.parentId for usage.

      Note : This is an advanced setting

      Parameters:
      parentIdField - New parentIdField value. Default value is "parentId"
      Returns:
      Tree instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created
      See Also:

    • getParentIdField

      public 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 TreeNode.parentId for usage.
      Returns:
      Current parentIdField value. Default value is "parentId"
      See Also:

    • setPathDelim

      public Tree setPathDelim(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() and can be used to find any node in the tree by calling find(). Note that you can also hand-construct a path - in other words you are not required to call getPath() in order to later use find() 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() 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() and find() and does not affect any aspect of the tree structure or other forms of tree navigation (such as via getChildren()).

      Note : This is an advanced setting

      Parameters:
      pathDelim - New pathDelim value. Default value is "/"
      Returns:
      Tree instance, for chaining setter calls
      See Also:

    • getPathDelim

      public 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() and can be used to find any node in the tree by calling find(). Note that you can also hand-construct a path - in other words you are not required to call getPath() in order to later use find() 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() 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() and find() and does not affect any aspect of the tree structure or other forms of tree navigation (such as via getChildren()).
      Returns:
      Current pathDelim value. Default value is "/"
      See Also:

    • setReportCollisions

      public Tree setReportCollisions(Boolean reportCollisions) throws IllegalStateException
      If new nodes are added to a tree with modelType:"parent" which have the same id field value as 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:
      Tree instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created

    • getReportCollisions

      public Boolean getReportCollisions()
      If new nodes are added to a tree with modelType:"parent" which have the same id field value as 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

      public Tree 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 tree = new Tree();
  tree.setRoot(
      new TreeNode("root",
          new TreeNode("foo",
              new TreeNode("bar")),
          new TreeNode("zoo")
      )
  );


      Note: if you initialize a Tree with no root value, a root node will be auto-created for you. You can then call add() 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 to duplicate().
      Parameters:
      root - new root node. Default value is null
      Returns:
      Tree instance, for chaining setter calls
      See Also:

    • 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 tree = new Tree();
  tree.setRoot(
      new TreeNode("root",
          new TreeNode("foo",
              new TreeNode("bar")),
          new TreeNode("zoo")
      )
  );


      Note: if you initialize a Tree with no root value, a root node will be auto-created for you. You can then call add() to construct the tree.
      Returns:
      Returns the root node of the tree. Default value is null
      See Also:

    • setSeparateFolders

      public Tree 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 for separateFolders.
      Parameters:
      separateFolders - new separateFolders value. Default value is false
      Returns:
      Tree instance, for chaining setter calls
      See Also:

    • getSeparateFolders

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

      public Tree setShowRoot(Boolean showRoot)
      Controls whether the implicit root node is returned as part of the visible tree, specifically, whether it is returned in getOpenList(), 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: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.

      If this method is called after the component has been drawn/initialized: Setter for showRoot.

      Parameters:
      showRoot - new showRoot value. Default value is false
      Returns:
      Tree instance, for chaining setter calls

    • getShowRoot

      public Boolean getShowRoot()
      Controls whether the implicit root node is returned as part of the visible tree, specifically, whether it is returned in getOpenList(), 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: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:
      Current showRoot value. Default value is false

    • setSortFoldersBeforeLeaves

      public Tree setSortFoldersBeforeLeaves(Boolean sortFoldersBeforeLeaves)
      If separateFolders is true, should folders be displayed above or below leaves? When set to true folders will appear above leaves when the sortDirection applied to the tree is "ascending"

      If this method is called after the component has been drawn/initialized: Setter for sortFoldersBeforeLeaves.
      Parameters:
      sortFoldersBeforeLeaves - new sortFoldersBeforeLeaves value. Default value is true
      Returns:
      Tree instance, for chaining setter calls

    • getSortFoldersBeforeLeaves

      public Boolean getSortFoldersBeforeLeaves()
      If separateFolders is true, should folders be displayed above or below leaves? When set to true folders will appear above leaves when the sortDirection applied to the tree is "ascending"
      Returns:
      Current sortFoldersBeforeLeaves value. Default value is true

    • setTitleProperty

      public Tree setTitleProperty(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 TreeNode.title for usage.
      Parameters:
      titleProperty - New titleProperty value. Default value is "title"
      Returns:
      Tree instance, for chaining setter calls

    • getTitleProperty

      public 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 TreeNode.title for usage.
      Returns:
      Current titleProperty value. Default value is "title"

    • allChildrenLoaded

      public Boolean allChildrenLoaded(TreeNode node)
      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

      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). If this is a multi-link tree, you must provide a NodeLocator for any node other than the root node

    • closeAll

      public void closeAll(NodeLocator node)
      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 a multi-link tree, you must provide a NodeLocator for any node other than the root node

    • closeFolder

      public void closeFolder(TreeNode node)
      Closes a folder. Note, for multi-link trees, passing a NodeLocator is the only unambiguous way to specify the node.
      Parameters:
      node - the node to open, or its ID, or a NodeLocator object

    • closeFolder

      public void closeFolder(String node)
      Closes a folder. Note, for multi-link trees, passing a NodeLocator is the only unambiguous way to specify the node.
      Parameters:
      node - the node to open, or its ID, or a NodeLocator object

    • closeFolder

      public void closeFolder(Integer node)
      Closes a folder. Note, for multi-link trees, passing a NodeLocator is the only unambiguous way to specify the node.
      Parameters:
      node - the node to open, or its ID, or a NodeLocator object

    • closeFolder

      public void closeFolder(NodeLocator node)
      Closes a folder. Note, for multi-link trees, passing a NodeLocator is the only unambiguous way to specify the node.
      Parameters:
      node - the node to open, or its ID, or a NodeLocator object

    • createNodeLocator

      public void createNodeLocator(TreeNode node, TreeNode parent, Integer position, String path)
      Returns a NodeLocator object suitable for passing to methods, such as getParent(), which require a NodeLocator when the tree is multi-linked. Note, NodeLocators are specific to multiLink trees; they are never required for regular trees.
      Parameters:
      node - the child node
      parent - the parent node
      position - the child node's position within the parent
      path - the full path to the child node

    • createNodeLocator

      public void createNodeLocator(TreeNode node, TreeNode parent, Integer position, String path, Integer openListIndex)
      Returns a NodeLocator object suitable for passing to methods, such as getParent(), which require a NodeLocator when the tree is multi-linked. Note, NodeLocators are specific to multiLink trees; they are never required for regular trees.
      Parameters:
      node - the child node
      parent - the parent node
      position - the child node's position within the parent
      path - the full path to the child node
      openListIndex - 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 associated TreeGrid

    • addDataChangedHandler

      public HandlerRegistration addDataChangedHandler(DataChangedHandler handler)
      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:
      addDataChangedHandler in interface HasDataChangedHandlers
      Parameters:
      handler - the dataChanged handler
      Returns:
      HandlerRegistration used to remove this handler

    • findIndex

      public int findIndex(String propertyName)
      Like List.findIndex(), but operates only on the list of currently opened nodes. To search all loaded nodes open or closed, use findNodeIndex().
      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

      public int findIndex(Map propertyName)
      Like List.findIndex(), but operates only on the list of currently opened nodes. To search all loaded nodes open or closed, use findNodeIndex().
      Overrides:
      findIndex in class RecordList
      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

      public int findIndex(AdvancedCriteria propertyName)
      Like List.findIndex(), but operates only on the list of currently opened nodes. To search all loaded nodes open or closed, use findNodeIndex().
      Overrides:
      findIndex in class RecordList
      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

      public int findIndex(String propertyName, Object value)
      Like List.findIndex(), but operates only on the list of currently opened nodes. To search all loaded nodes open or closed, use findNodeIndex().
      Parameters:
      propertyName - property to match, or if an Object is passed, set of properties and values to match
      value - value to compare against (if propertyName is a string)
      Returns:
      index of the first matching Object or -1 if not found

    • findNextIndex

      public int findNextIndex(int startIndex, String propertyName)
      Like findIndex(), but inspects a range from startIndex to endIndex. Note that as in findIndex(), only open nodes are included. To include both open and closed nodes, use findNextNodeIndex().
      Overrides:
      findNextIndex in class RecordList
      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

      public int findNextIndex(int startIndex, String propertyName, Object value)
      See Also:

    • findNextIndex

      public int findNextIndex(int startIndex, String propertyName, Object value, int endIndex)
      Like findIndex(), but inspects a range from startIndex to endIndex. Note that as in findIndex(), only open nodes are included. To include both open and closed nodes, use findNextNodeIndex().
      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 (if propertyName is a string)
      endIndex - last index to consider (inclusive).
      Returns:
      index of the first matching value or -1 if not found.

    • findNextNodeIndex

      public int findNextNodeIndex(int startIndex, String propertyName)
      Like findNextIndex(), 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

      public int findNextNodeIndex(int startIndex, String propertyName, Object value)
      See Also:

    • findNextNodeIndex

      public int findNextNodeIndex(int startIndex, String propertyName, Object value, int endIndex)
      Like findNextIndex(), 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 (if propertyName is a string)
      endIndex - last index to consider (inclusive).
      Returns:
      index of the first matching value or -1 if not found.

    • findNodeIndex

      public int findNodeIndex(String propertyName)
      Like findIndex(), 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

      public int findNodeIndex(Map propertyName)
      Like findIndex(), 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

      public int findNodeIndex(AdvancedCriteria propertyName)
      Like findIndex(), 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

      public int findNodeIndex(String propertyName, Object value)
      Like findIndex(), 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
      value - value to compare against (if propertyName is a string)
      Returns:
      index of the first matching Object or -1 if not found

    • getChildrenResultSet

      public ResultSet getChildrenResultSet(TreeNode node)
      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

      public TreeNode[] getDescendantNodeLocators()
      Returns a list of link{type:NodeLocator)s identifying all descendants of a node (identified by the parameter NodeLocator). This method is the equivalent of getDescendants(), but for multi-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 the NodeLocators 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

      public TreeNode[] getDescendantNodeLocators(TreeNode node)
      Returns a list of link{type:NodeLocator)s identifying all descendants of a node (identified by the parameter NodeLocator). This method is the equivalent of getDescendants(), but for multi-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 the NodeLocators 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:
      getLength in class RecordList
      Returns:
      number of items in open list
      See Also:

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

      Note showRoot defaults 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 a TreeNode to 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 a NodeLocator with a path that unambiguously identifies the node occurence you are interested in

      Parameters:
      node - node in question, or a suitable NodeLocator
      Returns:
      number of parents the node has

    • getLevel

      public int getLevel(NodeLocator 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.

      Note showRoot defaults 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 a TreeNode to 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 a NodeLocator with a path that unambiguously identifies the node occurence you are interested in

      Parameters:
      node - node in question, or a suitable NodeLocator
      Returns:
      number of parents the node has

    • getLoadState

      public LoadState getLoadState(TreeNode node)
      What is the loadState of a given folder?
      Parameters:
      node - folder in question
      Returns:
      state of the node

    • getMultiLinkParents

      public TreeNode[] getMultiLinkParents(TreeNode node)
      For multiLink 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 also getParentsAndPositions().
      Parameters:
      node - node in question
      Returns:
      the parents of this node

    • getName

      public String getName(TreeNode node)
      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 suitable NodeLocator
      Returns:
      name of the node

    • getName

      public String getName(NodeLocator node)
      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 suitable NodeLocator
      Returns:
      name of the node

    • getNodeLocator

      public NodeLocator getNodeLocator(Integer recordIndex)
      For a multi-link tree, this method returns the nodeLocator associated with the particular occurence of the node at the specified index within the current open list of 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

      public String getParentPath(TreeNode node)
      Given a node, return the path to its parent. This works just like getPath() 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

      public Record[] getParentsAndPositions(TreeNode node)
      For multiLink 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

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

      Note: Nodes in multi-link trees do not have a single path, because a given node can occur in multiple places in the tree. Therefore, if you pass a TreeNode instance 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 call getPathForOpenListIndex(), 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 a treeGrid); 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 original data and linkData

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

    • getPathForOpenListIndex

      public String 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. Note that for a node that appears in more than one place in a multi-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

      public 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:
      • If a titleProperty is set on the node, the value of that property is returned.
      • Otherwise, if the nameProperty is set on the node, that value is returned, minus any trailing pathDelim.
      • Finally, if none of the above yielded a title, the value of defaultNodeTitle is returned.
      You can override this method to return the title of your choice for a given node.

      To override the title for an auto-constructed tree (for example, in a databound TreeGrid), override TreeGrid.getNodeTitle() instead.
      Parameters:
      node - node for which the title is being requested
      Returns:
      title to display
      See Also:

    • hasChildren

      public 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 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 Boolean hasLeaves(TreeNode node)
      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

      public 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

    • isFolder

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

      • If the TreeNode has a value for the isFolderProperty (TreeNode.isFolder by default) that value is returned.
      • Next, the existence of the childrenProperty (by default TreeNode.children) is checked on the TreeNode. 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

    • 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 trees potentially 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

      public 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
      See Also:

    • isLoaded

      public Boolean isLoaded(TreeNode node)
      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 linkData and ResultTree.linkDataSource for further details of multiLink trees.

    • isOpen

      public Boolean isOpen(TreeNode node)
      Whether a particular node is open or closed (works for leaves and folders). Note, for multi-link trees, passing a NodeLocator is 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

      public Boolean isOpen(String node)
      Whether a particular node is open or closed (works for leaves and folders). Note, for multi-link trees, passing a NodeLocator is 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

      public Boolean isOpen(Integer node)
      Whether a particular node is open or closed (works for leaves and folders). Note, for multi-link trees, passing a NodeLocator is 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

      public Boolean isOpen(NodeLocator node)
      Whether a particular node is open or closed (works for leaves and folders). Note, for multi-link trees, passing a NodeLocator is 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

      public Boolean isParent(TreeNode node, TreeNode parent)
      Returns true if "parent" is the parent of "node". This is straightforward and definitive for ordinary trees, because nodes can only have one parent. In multiLink 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 question
      parent - 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

      public 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

    • linkDataChanged

      public void linkDataChanged()
      For multi-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

      public void loadChildren(TreeNode node)
      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

      public void loadChildren(TreeNode node, DSCallback callback)
      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
      callback - Optional callback (stringMethod) to fire when loading completes. Has a single param node - the node whose children have been loaded, and is fired in the scope of the Tree.

    • 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, Integer 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.

    • openAll

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

    • openAll

      public void openAll(TreeNode node)
      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

      public void openAll(String node)
      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

      public void openAll(Integer node)
      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

      public void openAll(NodeLocator node)
      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

      public void reloadChildren(TreeNode node)
      Reload the children of a folder.
      Parameters:
      node - node in question
      See Also:

    • remove

      public Boolean remove(TreeNode node)
      Removes a node, along with all its children. See "Modifying ResultTrees" when working with a ResultTree for limitations. Note, if this is a multi-link tree, you must pass in a NodeLocator rather 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

      public Boolean remove(String node)
      Removes a node, along with all its children. See "Modifying ResultTrees" when working with a ResultTree for limitations. Note, if this is a multi-link tree, you must pass in a NodeLocator rather 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

      public Boolean remove(Integer node)
      Removes a node, along with all its children. See "Modifying ResultTrees" when working with a ResultTree for limitations. Note, if this is a multi-link tree, you must pass in a NodeLocator rather 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

      public Boolean remove(NodeLocator node)
      Removes a node, along with all its children. See "Modifying ResultTrees" when working with a ResultTree for limitations. Note, if this is a multi-link tree, you must pass in a NodeLocator rather 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

      public void removeChildren(TreeNode node)
      Removes all children of the node and sets it to a loaded state. For non-ResultTrees, or non-paged ResultTrees, add() or addList() can then be used to provide new children. For paged ResultTrees, DataSource.updateCaches() must be used to insert nodes into the cache as local data, since such ResultTrees are considered read-only, and add() and addList() are not perrmitted.
      Parameters:
      node - folder in question
      See Also:

    • setChildren

      public void setChildren(TreeNode parent, List newChildren)
      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 in addList().
      Parameters:
      parent - parent of children
      newChildren - children to be set
      See Also:

    • unloadChildren

      public void unloadChildren(TreeNode node)
      Deprecated.
      It's recommended that you instead use reloadChildren() to reload the children of a folder, or removeChildren() 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 explored
      parentChildrenField -

    • findChildrenProperty

      public static String findChildrenProperty(TreeNode node, ChildrenPropertyMode mode)
      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 check
      mode - determines how to chose the property that appears to contain child objects
      Returns:
      the name of the property that holds the children

    • setDefaultProperties

      public static void setDefaultProperties(Tree treeProperties)
      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

      public Tree 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. So for example, to create this tree: 

      foo
    bar
        zoo
      with 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 (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 of the tree's root node.

      Parameters:
      nodes - data
      Returns:
      Tree instance, for chaining setter calls

    • getData

      public ListGridRecord[] getData()

    • setLinkData

      public void setLinkData(Record[] linkData)
      For a multi-link tree, this property specifies the parent-child relationships between the nodes. The nodes themselves are provided in the regular tree data. Note that multi-link trees must specify a modelType of "parent".

      For a regular, non-multiLink tree, linkData is 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 allowDuplicateChildren is set). To describe this multi-link tree:

         foo
     bar
       baz
     zoo
       bar
         baz
      you would provide node information in the tree's data like 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 in linkData like 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, see ResultTree.linkDataSource
      Parameters:
      linkData - The link data

    • getLinkData

      public Record[] getLinkData()

    • setMultiLinkTree

      public void setMultiLinkTree(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. See Tree.linkData and ResultTree.linkDataSource for 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

      public void setRootValue(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:
      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:
      IllegalStateException - this property cannot be changed after the underlying component has been created

    • getRootValue

      public String getRootValue()

    • getParent

      public TreeNode getParent(TreeNode node)
      Returns the parent of this node.
      Parameters:
      node - node in question
      Returns:
      parent of this node

    • getFilteredTree

      public Tree getFilteredTree(Criteria criteria)
      Filters this tree by the provided criteria, returning a new Tree containing just the nodes that match the criteria.

      If filterMode is "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

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

      If filterMode is "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
      filterMode - 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

      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(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(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 {@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 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(String fieldNameOrPath, Object value)
      Find a node within this tree using a string path or by attribute value(s).
      Overrides:
      find in class RecordList
      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
      See Also:

    • find

      public TreeNode find(String propertyName, Date value)
      Find a node within this tree using a string path or by attribute value(s).
      Overrides:
      find in class RecordList
      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
      See Also:

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

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

    • openFolder

      public void openFolder(TreeNode node)
      &#010 Open a particular node&#010&#010
      Parameters:
      node - node to open

    • getAllNodes

      public TreeNode[] 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

      public 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.
      Parameters:
      node - optional node to start from. Default is root.
      Returns:
      all the nodes that exist in the tree