com.smartgwt.client.widgets.tree

## Class ResultTree

- java.lang.Object
- - com.smartgwt.client.core.BaseClass
  - - com.smartgwt.client.data.RecordList
    - - com.smartgwt.client.widgets.tree.Tree
      - - com.smartgwt.client.widgets.tree.ResultTree

- All Implemented Interfaces:
    com.google.gwt.event.shared.HasHandlers, HasDataChangedHandlers

      public class ResultTree
      extends Tree

  ResultTrees are an implementation of the `Tree` API, used to handle hierarchical data, whose nodes are DataSource records which are retrieved from a server.

  Modifying ResultTrees

  `ResultTree` nodes cannot be directly added or removed from a `paged` `ResultTree` via `Tree` APIs such as `Tree.add()` or `Tree.remove()`, since such trees are considered to be read-only by virtue of containing `ResultSet`s, which are read-only data structures. Even in other `FetchMode`s, calling such APIs will only update the local cache of the ResultTree, rather than triggering any server traffict to update the DataSource.

  Use `DataSource.addData()`/`removeData()` to add/remove rows from the `DataSource`, and the `ResultTree` will reflect the changes automatically. Alternatively, the `DataSource.updateCaches()` method may be called to only update local caches of the DataSource in question, without generating any server traffic.

  To create a locally modifiable cache of records from a DataSource, you can use `DataSource.fetchData()` to retrieve a List of records which can be modified directly, or you can create a client-only `DataSource` from the retrieved data to share a modifiable cache between several DataBoundComponents.

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class com.smartgwt.client.data.RecordList

      `RecordList.SortNormalizer`

  - ### Field Summary

    - ### Fields inherited from class com.smartgwt.client.data.RecordList

      `jsObj`

    - ### Fields inherited from class com.smartgwt.client.core.BaseClass

      `config, configOnly, factoryCreated, factoryProperties, id, scClassName`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ResultTree()`
    `ResultTree(com.google.gwt.core.client.JavaScriptObject jsObj)`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `Tree` | `applyFilter(Tree tree, Criteria criteria, TreeFilterMode filterMode, DataSource dataSource)` The ResultTree will call applyFilter() when it needs to locally filter the tree using the current filter criteria.
    `Tree` | `applyFilter(Tree tree, Criteria criteria, TreeFilterMode filterMode, DataSource dataSource, DSRequest requestProperties)` The ResultTree will call applyFilter() when it needs to locally filter the tree using the current filter criteria.
    `int` | `compareCriteria(Criteria newCriteria, Criteria oldCriteria)` Default behavior is to call `DataSource.compareCriteria()` to determine whether new criteria is equivalent to the old criteria (returns 0) or not.
    `int` | `compareCriteria(Criteria newCriteria, Criteria oldCriteria, DSRequest requestProperties)` Default behavior is to call `DataSource.compareCriteria()` to determine whether new criteria is equivalent to the old criteria (returns 0) or not.
    `com.google.gwt.core.client.JavaScriptObject` | `create()`
    `void` | `dataArrived(TreeNode parentNode)` This callback fires whenever the resultTree receives new nodes from the server, after the new nodes have been integrated into the tree.
    `TreeNode` | `get(int pos)` Get the item in the openList at a particular position.
    `PreserveOpenState` | `getAutoPreserveOpenState()` Controls what happens to the `"open state"` - the set of nodes opened or closed by the end user after tree data is loaded - when an entirely new tree of nodes is loaded from the server, as a consequence of calling `invalidateCache()` or of changing criteria such that the current cache of nodes is dropped.
    `boolean` | `getCanReturnOpenFolders()` When using `fetchMode:"paged"` and providing multiple levels of the tree in one DSResponse, this property specifies the default value assumed for the `canReturnOpenSubfoldersProperty` when no value for that property is provided for a node.
    `java.lang.String` | `getCanReturnOpenSubfoldersProperty()` When using `fetchMode:"paged"` and providing multiple levels of the tree in one DSResponse, `canReturnOpenSubfoldersProperty` may be set on any folder to indicate whether child folders might be returned by the server already open.
    `java.lang.String` | `getChildCountProperty()` When using `fetchMode:"paged"` and providing multiple levels of the tree in one DSResponse, `childCountProperty` must be set for any folders that include only a partial list of children.
    `Criteria` | `getCriteria()` The filter criteria to use when fetching rows.
    `TreeNode[]` | `getData()` Optional initial data for the tree.
    `DataSource` | `getDataSource()` What `DataSource` is this resultTree associated with?
    `java.lang.Boolean` | `getDefaultIsFolder()` Controls whether nodes are assumed to be folders or leaves by default.
    `java.lang.Boolean` | `getDefaultNewNodesToRoot()` This attribute governs how to handle cache-synch when a new node is added to this dataSource with no explicit parentId.
    `java.lang.Boolean` | `getDisableCacheSync()` By default when the data of this ResultTree's dataSource is modified, the ResultTree will be updated to display these changes.
    `java.lang.Boolean` | `getDiscardParentlessNodes()` When data is loaded from the server, should nodes with an explicit value for the `Tree.parentIdField` which doesn't map to a valid parent node be dropped? If set to false, for `TreeGrid.loadDataOnDemand`:false trees, parentless nodes will be added as children of the root node - for `TreeGrid.loadDataOnDemand`:true, they will be added as children of the folder currently requesting children.
    `FetchMode` | `getFetchMode()` Mode of fetching records from server.
    `Criteria` | `getImplicitCriteria()` Criteria that are never shown to or edited by the user and are cumulative with any criteria provided via `DataBoundComponent.initialCriteria`, `setCriteria()` etc.
    `java.lang.Boolean` | `getKeepParentsOnFilter()` If set, tree-based filtering is performed such that parent nodes are kept as long as they have children that match the filter criteria, even if the parents themselves do not match the filter criteria.
    `java.lang.Boolean` | `getLoadDataOnDemand()` Does this resultTree load data incrementally as folders within the tree are opened, or is it all loaded in a single request? Must be true if `fetchMode` is "paged".
    `TreeModelType` | `getModelType()` Selects the model used to construct the tree representation.
    `java.lang.String` | `getOpenState()` Returns a snapshot of the current open state of this tree's data as a `TreeGridOpenState` object.
    `static ResultTree` | `getOrCreateRef(com.google.gwt.core.client.JavaScriptObject jsObj)`
    `java.util.Map` | `getPaletteDefaults()` This method returns a Map of config properties suitable for use as the "defaults" attribute of a `PaletteNode`.
    `java.lang.Boolean` | `getProgressiveLoading()` Sets `progressive loading mode` for this ResultTree.
    `TreeNode[]` | `getRange(int start, int end)` Get a range of items from the open list
    `java.lang.Integer` | `getResultSize()` How many tree nodes to retrieve at once from each large set of children in the tree.
    `com.google.gwt.core.client.JavaScriptObject` | `getRootNode()` This attribute may be used to specify a root value for the parentIdField of this resultTree.
    `java.lang.String[]` | `getServerFilterFields()` When `keepParentsOnFilter` is enabled for `fetchMode:"local"` ResultTrees, this property lists field names that will be sent to the server if they are present in the criteria.
    `java.lang.Boolean` | `getUpdateCacheFromRequest()` When a successful Add, Update or Remove type operation fires on this ResultTree's dataSource, if `DSResponse.data` is unset, should we integrate the submitted data values (from the request) into our data-set?
    `boolean` | `getUseSimpleCriteriaLOD()` Whether or not we should skip promotion of a simple criteria to an `AdvancedCriteria` when sending the `DSRequest` to load the children of a node in a `loadDataOnDemand` or `fetchMode:"paged"` `ResultTree`.
    `void` | `invalidateCache()` Manually invalidate this ResultTree's cache.
    `void` | `setAutoPreserveOpenState(PreserveOpenState autoPreserveOpenState)` Controls what happens to the `"open state"` - the set of nodes opened or closed by the end user after tree data is loaded - when an entirely new tree of nodes is loaded from the server, as a consequence of calling `invalidateCache()` or of changing criteria such that the current cache of nodes is dropped.
    `void` | `setCanReturnOpenFolders(boolean canReturnOpenFolders)` When using `fetchMode:"paged"` and providing multiple levels of the tree in one DSResponse, this property specifies the default value assumed for the `canReturnOpenSubfoldersProperty` when no value for that property is provided for a node.
    `void` | `setCanReturnOpenSubfoldersProperty(java.lang.String canReturnOpenSubfoldersProperty)` When using `fetchMode:"paged"` and providing multiple levels of the tree in one DSResponse, `canReturnOpenSubfoldersProperty` may be set on any folder to indicate whether child folders might be returned by the server already open.
    `void` | `setChildCountProperty(java.lang.String childCountProperty)` When using `fetchMode:"paged"` and providing multiple levels of the tree in one DSResponse, `childCountProperty` must be set for any folders that include only a partial list of children.
    `void` | `setChildren(TreeNode parent, java.util.List newChildren)` Replaces the existing children of a parent node.
    `void` | `setChildren(TreeNode parent, java.util.List newChildren, java.lang.Integer totalChildren)` Replaces the existing children of a parent node.
    `void` | `setCriteria(Criteria criteria)` The filter criteria to use when fetching rows.
    `void` | `setData(TreeNode... data)` Optional initial data for the tree.
    `void` | `setDataSource(DataSource dataSource)` What `DataSource` is this resultTree associated with?
    `void` | `setDefaultIsFolder(java.lang.Boolean defaultIsFolder)` Controls whether nodes are assumed to be folders or leaves by default.
    `void` | `setDefaultNewNodesToRoot(java.lang.Boolean defaultNewNodesToRoot)` This attribute governs how to handle cache-synch when a new node is added to this dataSource with no explicit parentId.
    `static void` | `setDefaultProperties(ResultTree resultTreeProperties)` Class level method to set the default properties of this class.
    `void` | `setDisableCacheSync(java.lang.Boolean disableCacheSync)` By default when the data of this ResultTree's dataSource is modified, the ResultTree will be updated to display these changes.
    `void` | `setDiscardParentlessNodes(java.lang.Boolean discardParentlessNodes)` When data is loaded from the server, should nodes with an explicit value for the `Tree.parentIdField` which doesn't map to a valid parent node be dropped? If set to false, for `TreeGrid.loadDataOnDemand`:false trees, parentless nodes will be added as children of the root node - for `TreeGrid.loadDataOnDemand`:true, they will be added as children of the folder currently requesting children.
    `void` | `setFetchMode(FetchMode fetchMode)` Mode of fetching records from server.
    `void` | `setImplicitCriteria(Criteria implicitCriteria)` Criteria that are never shown to or edited by the user and are cumulative with any criteria provided via `DataBoundComponent.initialCriteria`, `setCriteria()` etc.
    `void` | `setKeepParentsOnFilter(java.lang.Boolean keepParentsOnFilter)` If set, tree-based filtering is performed such that parent nodes are kept as long as they have children that match the filter criteria, even if the parents themselves do not match the filter criteria.
    `void` | `setLoadDataOnDemand(java.lang.Boolean loadDataOnDemand)` Does this resultTree load data incrementally as folders within the tree are opened, or is it all loaded in a single request? Must be true if `fetchMode` is "paged".
    `void` | `setModelType(TreeModelType modelType)` Selects the model used to construct the tree representation.
    `void` | `setOpenState(java.lang.String openState)` Reset the set of open folders within this tree's data to match the `TreeGridOpenState` object passed in.
    `void` | `setProgressiveLoading(java.lang.Boolean progressiveLoading)` Sets `progressive loading mode` for this ResultTree.
    `void` | `setResultSize(java.lang.Integer resultSize)` How many tree nodes to retrieve at once from each large set of children in the tree.
    `void` | `setRootNode(com.google.gwt.core.client.JavaScriptObject rootNode)` This attribute may be used to specify a root value for the parentIdField of this resultTree.
    `void` | `setServerFilterFields(java.lang.String... serverFilterFields)` When `keepParentsOnFilter` is enabled for `fetchMode:"local"` ResultTrees, this property lists field names that will be sent to the server if they are present in the criteria.
    `void` | `setUpdateCacheFromRequest(java.lang.Boolean updateCacheFromRequest)` When a successful Add, Update or Remove type operation fires on this ResultTree's dataSource, if `DSResponse.data` is unset, should we integrate the submitted data values (from the request) into our data-set?
    `void` | `setUseSimpleCriteriaLOD(boolean useSimpleCriteriaLOD)` Whether or not we should skip promotion of a simple criteria to an `AdvancedCriteria` when sending the `DSRequest` to load the children of a node in a `loadDataOnDemand` or `fetchMode:"paged"` `ResultTree`.
    `void` | `unloadChildren(TreeNode node)` Deprecated. It's recommended that you instead use `Tree.reloadChildren()` to reload the children of a folder, or `Tree.removeChildren()` if you need to clear the cached children of a folder to add specific local data.
    `java.lang.Boolean` | `willFetchData(Criteria newCriteria)` Will changing the criteria for this resultTree require fetching new data from the server or can the new criteria be satisfied from data already cached on the client?

    - ### Methods inherited from class com.smartgwt.client.widgets.tree.Tree

      `add, add, add, add, addDataChangedHandler, addList, addList, addList, addList, allChildrenLoaded, closeAll, closeAll, closeFolder, closeFolders, discoverTree, find, find, find, findById, findChildrenProperty, findIndex, findIndex, findIndex, findIndex, findNextIndex, findNextIndex, findNextIndex, findNextNodeIndex, findNextNodeIndex, findNextNodeIndex, findNodeIndex, findNodeIndex, findNodeIndex, findNodeIndex, getAllNodes, getAllNodes, getAutoOpenRoot, getChildren, getChildrenProperty, getChildrenResultSet, getDataSourceAsString, getDefaultNodeTitle, getDescendantFolders, getDescendantFolders, getDescendantLeaves, getDescendantLeaves, getDescendants, getDescendants, getFilteredTree, getFilteredTree, getFolders, getIdField, getIsFolderProperty, getLeaves, getLength, getLevel, getLoadState, getName, getNameProperty, getOpenList, getOpenProperty, getParent, getParentIdField, getParentPath, getParents, getPath, getPathDelim, getReportCollisions, getRoot, getRootValue, getSeparateFolders, getShowRoot, getSortFoldersBeforeLeaves, getTitle, getTitleProperty, hasChildren, hasFolders, hasLeaves, isDescendantOf, isFolder, isLeaf, isLoaded, isOpen, isRoot, linkNodes, loadChildren, loadChildren, move, move, nodeForRecord, openAll, openAll, openFolder, openFolders, reloadChildren, remove, removeChildren, removeList, setAutoOpenRoot, setChildrenProperty, setDataSource, setDefaultNodeTitle, setDefaultProperties, setIdField, setIsFolderProperty, setJavaScriptObject, setNameProperty, setOpenProperty, setParentIdField, setPathDelim, setReportCollisions, setRoot, setRootValue, setRootValue, setSeparateFolders, setShowRoot, setSortFoldersBeforeLeaves, setTitleProperty`

    - ### Methods inherited from class com.smartgwt.client.data.RecordList

      `add, addAt, addDataChangedHandler, addList, addList, addListAt, contains, contains, containsAll, duplicate, equals, find, find, find, findAll, findAll, findAll, findAll, findAll, findAll, findAll, findAll, findIndex, findIndex, findIndex, findIndex, findIndex, findIndex, findNextIndex, findNextIndex, findNextIndex, findNextIndex, findNextIndex, findNextIndex, findNextIndex, findNextIndex, findNextIndex, first, getItems, getJsObj, getOrCreateJsObj, getProperty, getRangeList, getValueMap, indexOf, indexOf, intersect, isARecordList, isCreated, isEmpty, last, lastIndexOf, lastIndexOf, remove, removeAt, removeList, set, setLength, setSort, sort, sort, sortByProperty, sortByProperty, toArray`

    - ### Methods inherited from class com.smartgwt.client.core.BaseClass

      `applyFactoryProperties, asSGWTComponent, createJsObj, destroy, doAddHandler, doInit, error, error, errorIfNotCreated, fireEvent, getAttribute, getAttributeAsBoolean, getAttributeAsDate, getAttributeAsDouble, getAttributeAsElement, getAttributeAsFloat, getAttributeAsInt, getAttributeAsJavaScriptObject, getAttributeAsMap, getAttributeAsString, getAttributeAsStringArray, getClassName, getConfig, getHandlerCount, getID, getRef, getScClassName, getTestInstance, hasAutoAssignedID, internalSetID, internalSetID, isConfigOnly, isFactoryCreated, onBind, onInit, registerID, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setConfig, setConfigOnly, setFactoryCreated, setID, setProperty, setProperty, setProperty, setProperty, setScClassName`

    - ### 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

    - #### ResultTree

          public ResultTree()

    - #### ResultTree

          public ResultTree(com.google.gwt.core.client.JavaScriptObject jsObj)

  - ### Method Detail

    - #### getOrCreateRef

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

    - #### getPaletteDefaults

          public java.util.Map getPaletteDefaults()

      This method returns a Map of config properties suitable for use as the "defaults" attribute of a `PaletteNode`. Use it when you need to work with PaletteNodes indirectly, such when setting up `TileRecord`s that will be used in a `TilePalette`. See `the dev tools overview` for examples of how to assemble and acquire a suitable defaults object when you are creating a PaletteNode indirectly

    - #### create

          public com.google.gwt.core.client.JavaScriptObject create()

      Overrides:
        `create` in class `Tree`

    - #### setAutoPreserveOpenState

          public void setAutoPreserveOpenState(PreserveOpenState autoPreserveOpenState)

      Controls what happens to the `"open state"` - the set of nodes opened or closed by the end user after tree data is loaded - when an entirely new tree of nodes is loaded from the server, as a consequence of calling `invalidateCache()` or of changing criteria such that the current cache of nodes is dropped.
      Parameters:
        `autoPreserveOpenState` - New autoPreserveOpenState value. Default value is "whenUnique"

    - #### getAutoPreserveOpenState

          public PreserveOpenState getAutoPreserveOpenState()

      Controls what happens to the `"open state"` - the set of nodes opened or closed by the end user after tree data is loaded - when an entirely new tree of nodes is loaded from the server, as a consequence of calling `invalidateCache()` or of changing criteria such that the current cache of nodes is dropped.
      Returns:
        Current autoPreserveOpenState value. Default value is "whenUnique"

    - #### setCanReturnOpenFolders

          public void setCanReturnOpenFolders(boolean canReturnOpenFolders)
                                       throws java.lang.IllegalStateException

      When using `fetchMode:"paged"` and providing multiple levels of the tree in one DSResponse, this property specifies the default value assumed for the `canReturnOpenSubfoldersProperty` when no value for that property is provided for a node.
      Parameters:
        `canReturnOpenFolders` - New canReturnOpenFolders value. Default value is false
      Throws:
        `java.lang.IllegalStateException` - this property cannot be changed after the underlying component has been created

    - #### getCanReturnOpenFolders

          public boolean getCanReturnOpenFolders()

      When using `fetchMode:"paged"` and providing multiple levels of the tree in one DSResponse, this property specifies the default value assumed for the `canReturnOpenSubfoldersProperty` when no value for that property is provided for a node.
      Returns:
        Current canReturnOpenFolders value. Default value is false

    - #### setCanReturnOpenSubfoldersProperty

          public void setCanReturnOpenSubfoldersProperty(java.lang.String canReturnOpenSubfoldersProperty)
                                                  throws java.lang.IllegalStateException

      When using `fetchMode:"paged"` and providing multiple levels of the tree in one DSResponse, `canReturnOpenSubfoldersProperty` may be set on any folder to indicate whether child folders might be returned by the server already open. If the property is set to false on a folder then subfolders of that folder are never allowed to be returned already open. This enables the paging mechanism to be more efficient in the amount of data that it requests from the server.

      For example, setting the `canReturnOpenSubfoldersProperty` value to `false` on a node is appropriate if the server-side code determines that the the node's children consist of entirely leaf nodes.

      Parameters:
        `canReturnOpenSubfoldersProperty` - New canReturnOpenSubfoldersProperty value. Default value is "canReturnOpenSubfolders"
      Throws:
        `java.lang.IllegalStateException` - this property cannot be changed after the underlying component has been created
      See Also:
        `setCanReturnOpenFolders(boolean)`

    - #### getCanReturnOpenSubfoldersProperty

          public java.lang.String getCanReturnOpenSubfoldersProperty()

      When using `fetchMode:"paged"` and providing multiple levels of the tree in one DSResponse, `canReturnOpenSubfoldersProperty` may be set on any folder to indicate whether child folders might be returned by the server already open. If the property is set to false on a folder then subfolders of that folder are never allowed to be returned already open. This enables the paging mechanism to be more efficient in the amount of data that it requests from the server.

      For example, setting the `canReturnOpenSubfoldersProperty` value to `false` on a node is appropriate if the server-side code determines that the the node's children consist of entirely leaf nodes.

      Returns:
        Current canReturnOpenSubfoldersProperty value. Default value is "canReturnOpenSubfolders"
      See Also:
        `getCanReturnOpenFolders()`

    - #### setChildCountProperty

          public void setChildCountProperty(java.lang.String childCountProperty)
                                     throws java.lang.IllegalStateException

      When using `fetchMode:"paged"` and providing multiple levels of the tree in one DSResponse, `childCountProperty` must be set for any folders that include only a partial list of children. For a deeper discussion see the Paging large sets of children section of the `TreeDataBinding` overview.
      Parameters:
        `childCountProperty` - New childCountProperty value. Default value is "childCount"
      Throws:
        `java.lang.IllegalStateException` - this property cannot be changed after the underlying component has been created
      See Also:
        Multi-Level Child Paging Example

    - #### getChildCountProperty

          public java.lang.String getChildCountProperty()

      When using `fetchMode:"paged"` and providing multiple levels of the tree in one DSResponse, `childCountProperty` must be set for any folders that include only a partial list of children. For a deeper discussion see the Paging large sets of children section of the `TreeDataBinding` overview.
      Returns:
        Current childCountProperty value. Default value is "childCount"
      See Also:
        Multi-Level Child Paging Example

    - #### setCriteria

          public void setCriteria(Criteria criteria)

      The filter criteria to use when fetching rows. For usage see `setCriteria()`.
      If this method is called after the component has been drawn/initialized: Set the filter criteria to use when fetching rows.

      Depending on the result of `compareCriteria()` and setting for `fetchMode`, setting criteria may cause a trip to the server to get a new set of nodes, or may simply cause already-fetched nodes to be re-filtered according to the new criteria.

      For a basic overview on when server fetches are generally performed, see `fetchMode`. However, this is not the final determination of when server fetches occur. Criteria can be split into local criteria and server criteria by specifying `serverFilterFields`. Thus, even when using fetchMode:"local" a new server fetch will occur if the server criteria changes. For details on how the criteria is split, see `DataSource.splitCriteria()`.

      Note: if criteria is being split to retrieve server criteria portion and the criteria is an `AdvancedCriteria`, the criteria must consist of a single "and" operator and one or more simple criteria below it. No other logical operators may be used. In other words, the `AdvancedCriteria` provided must be exactly representable by a simple criteria.

      Parameters:
        `criteria` - the filter criteria. Default value is null

    - #### getCriteria

          public Criteria getCriteria()

      The filter criteria to use when fetching rows. For usage see `setCriteria()`.
      Returns:
        Current criteria value. Default value is null

    - #### setData

          public void setData(TreeNode... data)
                       throws java.lang.IllegalStateException

      Optional initial data for the tree. If the `fetchMode` is `"basic"` or `"local"` then the format of this data is exactly the same `parentId`-linked list of tree nodes as documented on `Tree.data` (when the `modelType` is set to `"parent"`). If the `fetchMode` is `"paged"` then the format is extended to allow the `childCountProperty` to be set on folder nodes.

      Providing an initial set of nodes in this way does not affect the behavior of the ResultTree in its loading of unloaded folders. An equivalent result is achieved if the first fetch from the server returns this same data.

      If `fetchMode` is `"paged"` then you may make folder-by-folder choices as to whether to use paging for the childen of each folder. If you would like to use paging in a folder then you may include a partial list of that folder's children with the data, provided that you set the `childCountProperty` to the total number of children. Otherwise you will need to include either all children of the folder or none of the children. Open folders without any children provided will cause immediate, new fetches for the children, as usual.

      Because the initial data is treated exactly as though it were returned from the tree's first server fetch, the order of the initial data must match the initial sort order of the TreeGrid displaying the data or, if no such sort is specified, the native storage order on the server. For example, consider initial data containing `n` records having the `parentId` `"X"`, meaning they are all in the same folder. These `n` records are the records at indices `0` through `(n - 1)` that are stored on the server under the parent node. If the `childCountProperty` set on the parent node indicates that there are `m > n` total rows under the parent node then the records at indices `n` to `(m - 1)` will be fetched from the server as the user scrolls the additional rows into view.

      Note : This is an advanced setting

      Overrides:
        `setData` in class `Tree`
      Parameters:
        `data` - New data value. Default value is null
      Throws:
        `java.lang.IllegalStateException` - this property cannot be changed after the underlying component has been created
      See Also:
        `Tree.setData(com.smartgwt.client.widgets.tree.TreeNode[])`, `TreeNode`, `TreeDataBinding overview and related methods`

    - #### getData

          public TreeNode[] getData()

      Optional initial data for the tree. If the `fetchMode` is `"basic"` or `"local"` then the format of this data is exactly the same `parentId`-linked list of tree nodes as documented on `Tree.data` (when the `modelType` is set to `"parent"`). If the `fetchMode` is `"paged"` then the format is extended to allow the `childCountProperty` to be set on folder nodes.

      Providing an initial set of nodes in this way does not affect the behavior of the ResultTree in its loading of unloaded folders. An equivalent result is achieved if the first fetch from the server returns this same data.

      If `fetchMode` is `"paged"` then you may make folder-by-folder choices as to whether to use paging for the childen of each folder. If you would like to use paging in a folder then you may include a partial list of that folder's children with the data, provided that you set the `childCountProperty` to the total number of children. Otherwise you will need to include either all children of the folder or none of the children. Open folders without any children provided will cause immediate, new fetches for the children, as usual.

      Because the initial data is treated exactly as though it were returned from the tree's first server fetch, the order of the initial data must match the initial sort order of the TreeGrid displaying the data or, if no such sort is specified, the native storage order on the server. For example, consider initial data containing `n` records having the `parentId` `"X"`, meaning they are all in the same folder. These `n` records are the records at indices `0` through `(n - 1)` that are stored on the server under the parent node. If the `childCountProperty` set on the parent node indicates that there are `m > n` total rows under the parent node then the records at indices `n` to `(m - 1)` will be fetched from the server as the user scrolls the additional rows into view.

      Overrides:
        `getData` in class `Tree`
      Returns:
        Current data value. Default value is null
      See Also:
        `Tree.getData()`, `TreeNode`, `TreeDataBinding overview and related methods`

    - #### 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 always be considered folders. Other nodes will be considered folders or leaves by default according to this setting.

      If `defaultIsFolder` is unset, the ResultTree will automatically set it to match the value of `loadDataOnDemand`. This means that, when using folder-by-folder load on demand (`loadDataOnDemand:true`), by default a newly loaded node will be considered to be a folder that has not loaded its children yet.

      When not using folder-by-folder load on demand, by default a newly loaded node is considered a leaf. If you set `defaultIsFolder:true` explicitly, by default a newly loaded node is considered to be a folder with no children.

      See `Tree.isFolder()` for details on how to explicitly mark nodes as folders or leaves.

      Overrides:
        `setDefaultIsFolder` in class `Tree`
      Parameters:
        `defaultIsFolder` - New defaultIsFolder value. Default value is null
      Throws:
        `java.lang.IllegalStateException` - this property cannot be changed after the underlying component has been created
      See Also:
        `TreeGrid.setLoadDataOnDemand(java.lang.Boolean)`

    - #### 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 always be considered folders. Other nodes will be considered folders or leaves by default according to this setting.

      If `defaultIsFolder` is unset, the ResultTree will automatically set it to match the value of `loadDataOnDemand`. This means that, when using folder-by-folder load on demand (`loadDataOnDemand:true`), by default a newly loaded node will be considered to be a folder that has not loaded its children yet.

      When not using folder-by-folder load on demand, by default a newly loaded node is considered a leaf. If you set `defaultIsFolder:true` explicitly, by default a newly loaded node is considered to be a folder with no children.

      See `Tree.isFolder()` for details on how to explicitly mark nodes as folders or leaves.

      Overrides:
        `getDefaultIsFolder` in class `Tree`
      Returns:
        Current defaultIsFolder value. Default value is null
      See Also:
        `TreeGrid.getLoadDataOnDemand()`

    - #### setDefaultNewNodesToRoot

          public void setDefaultNewNodesToRoot(java.lang.Boolean defaultNewNodesToRoot)

      This attribute governs how to handle cache-synch when a new node is added to this dataSource with no explicit parentId.

      If set to `true`, when a new node is added to this dataSource via `DataSource.addData()`, with no explicit parentId, the node will be added as a child of the root node of this result tree. Otherwise it will be ignored.

      Similar logic applies to `updated nodes` - if this property is true and the parentId of an updated node is cleared, it will be moved to become a child of root, otherwise it will be dropped from the tree.

      Note : This is an advanced setting

      Parameters:
        `defaultNewNodesToRoot` - New defaultNewNodesToRoot value. Default value is false

    - #### getDefaultNewNodesToRoot

          public java.lang.Boolean getDefaultNewNodesToRoot()

      This attribute governs how to handle cache-synch when a new node is added to this dataSource with no explicit parentId.

      If set to `true`, when a new node is added to this dataSource via `DataSource.addData()`, with no explicit parentId, the node will be added as a child of the root node of this result tree. Otherwise it will be ignored.

      Similar logic applies to `updated nodes` - if this property is true and the parentId of an updated node is cleared, it will be moved to become a child of root, otherwise it will be dropped from the tree.

      Returns:
        Current defaultNewNodesToRoot value. Default value is false

    - #### setDisableCacheSync

          public void setDisableCacheSync(java.lang.Boolean disableCacheSync)
                                   throws java.lang.IllegalStateException

      By default when the data of this ResultTree's dataSource is modified, the ResultTree will be updated to display these changes. Set this flag to true to disable this behavior.

      Note : This is an advanced setting

      Parameters:
        `disableCacheSync` - New disableCacheSync value. Default value is false
      Throws:
        `java.lang.IllegalStateException` - this property cannot be changed after the underlying component has been created

    - #### getDisableCacheSync

          public java.lang.Boolean getDisableCacheSync()

      By default when the data of this ResultTree's dataSource is modified, the ResultTree will be updated to display these changes. Set this flag to true to disable this behavior.
      Returns:
        Current disableCacheSync value. Default value is false

    - #### setDiscardParentlessNodes

          public void setDiscardParentlessNodes(java.lang.Boolean discardParentlessNodes)
                                         throws java.lang.IllegalStateException

      When data is loaded from the server, should nodes with an explicit value for the `Tree.parentIdField` which doesn't map to a valid parent node be dropped? If set to false, for `TreeGrid.loadDataOnDemand`:false trees, parentless nodes will be added as children of the root node - for `TreeGrid.loadDataOnDemand`:true, they will be added as children of the folder currently requesting children.

      This effectively allows nodes to be loaded into the current (or root) folder without needing an explicit `parentIdField value` that matches the folder's ID or `rootValue` for the resultTree.

      Note: For `loadDataOnDemand:false` trees, if this property is unset at init time, it will default to `true` if an explicit `rootNode` has been specified. This ensures that if the data tree retrieved from the server includes ancestors of the desired root-node we don't display them. Otherwise this property always defaults to false.

      Note : This is an advanced setting

      Overrides:
        `setDiscardParentlessNodes` in class `Tree`
      Parameters:
        `discardParentlessNodes` - New discardParentlessNodes value. Default value is null
      Throws:
        `java.lang.IllegalStateException` - this property cannot be changed after the underlying component has been created

    - #### getDiscardParentlessNodes

          public java.lang.Boolean getDiscardParentlessNodes()

      When data is loaded from the server, should nodes with an explicit value for the `Tree.parentIdField` which doesn't map to a valid parent node be dropped? If set to false, for `TreeGrid.loadDataOnDemand`:false trees, parentless nodes will be added as children of the root node - for `TreeGrid.loadDataOnDemand`:true, they will be added as children of the folder currently requesting children.

      This effectively allows nodes to be loaded into the current (or root) folder without needing an explicit `parentIdField value` that matches the folder's ID or `rootValue` for the resultTree.

      Note: For `loadDataOnDemand:false` trees, if this property is unset at init time, it will default to `true` if an explicit `rootNode` has been specified. This ensures that if the data tree retrieved from the server includes ancestors of the desired root-node we don't display them. Otherwise this property always defaults to false.

      Overrides:
        `getDiscardParentlessNodes` in class `Tree`
      Returns:
        Current discardParentlessNodes value. Default value is null

    - #### setFetchMode

          public void setFetchMode(FetchMode fetchMode)
                            throws java.lang.IllegalStateException

      Mode of fetching records from server.

      fetchMode:"local" implies that local filtering will always be performed. See `keepParentsOnFilter` for additional filtering details.

      fetchMode:"basic" or "paged" implies that if search criteria change, the entire tree will be discarded and re-fetched from the server. When retrieving the replacement tree data, the default behavior will be to preserve the `openState` for any nodes that the server returns which were previously opened by the user. Note that this implies that if `loadDataOnDemand` is enabled and the server returns only root-level nodes, open state will be preserved only for root-level nodes, and children of open root-level nodes will be immediately fetched from the server if they are not included in the server's initial response.

      fetchMode:"paged" enables paging for nodes that have very large numbers of children. Whenever the children of a folder are loaded, the `resultTree` will set `DSRequest.startRow` and `endRow` when requesting children from the DataSource, and will manage loading of further children on demand, similar to how a `ResultSet` manages paging for lists. For a deeper discussion see the Paging large sets of children section of the `TreeDataBinding` overview.

      Parameters:
        `fetchMode` - New fetchMode value. Default value is "basic"
      Throws:
        `java.lang.IllegalStateException` - this property cannot be changed after the underlying component has been created
      See Also:
        `setLoadDataOnDemand(java.lang.Boolean)`, `setUseSimpleCriteriaLOD(boolean)`, `TreeDataBinding overview and related methods`, Paging for Children Example

    - #### getFetchMode

          public FetchMode getFetchMode()

      Mode of fetching records from server.

      fetchMode:"local" implies that local filtering will always be performed. See `keepParentsOnFilter` for additional filtering details.

      fetchMode:"basic" or "paged" implies that if search criteria change, the entire tree will be discarded and re-fetched from the server. When retrieving the replacement tree data, the default behavior will be to preserve the `openState` for any nodes that the server returns which were previously opened by the user. Note that this implies that if `loadDataOnDemand` is enabled and the server returns only root-level nodes, open state will be preserved only for root-level nodes, and children of open root-level nodes will be immediately fetched from the server if they are not included in the server's initial response.

      fetchMode:"paged" enables paging for nodes that have very large numbers of children. Whenever the children of a folder are loaded, the `resultTree` will set `DSRequest.startRow` and `endRow` when requesting children from the DataSource, and will manage loading of further children on demand, similar to how a `ResultSet` manages paging for lists. For a deeper discussion see the Paging large sets of children section of the `TreeDataBinding` overview.

      Returns:
        Current fetchMode value. Default value is "basic"
      See Also:
        `getLoadDataOnDemand()`, `getUseSimpleCriteriaLOD()`, `TreeDataBinding overview and related methods`, Paging for Children Example

    - #### setImplicitCriteria

          public void setImplicitCriteria(Criteria implicitCriteria)

      Criteria that are never shown to or edited by the user and are cumulative with any criteria provided via `DataBoundComponent.initialCriteria`, `setCriteria()` etc.
      Parameters:
        `implicitCriteria` - New implicitCriteria value. Default value is null

    - #### getImplicitCriteria

          public Criteria getImplicitCriteria()

      Criteria that are never shown to or edited by the user and are cumulative with any criteria provided via `DataBoundComponent.initialCriteria`, `setCriteria()` etc.
      Returns:
        Current implicitCriteria value. Default value is null

    - #### setKeepParentsOnFilter

          public void setKeepParentsOnFilter(java.lang.Boolean keepParentsOnFilter)
                                      throws java.lang.IllegalStateException

      If set, tree-based filtering is performed such that parent nodes are kept as long as they have children that match the filter criteria, even if the parents themselves do not match the filter criteria. If not set, filtering will exclude parent nodes not matching the criteria and all nodes below it in the tree.

      When `keepParentsOnFilter` is enabled for paged ResultTrees, server-side filtering is required.

      When enabled for non-paged trees, `fetchMode:"local"` is automatically enabled so that all filtering behavior shifts to the client-side and full criteria are no longer sent to the server. Instead, server fetches will always load all nodes, or with `loadDataOnDemand`:true, will always load all nodes under a given parent. This means that the server does not need to implement special tree filtering logic.

      Optionally, `serverFilterFields` can be set to a list of field names that will be sent to the server whenever they are present in the criteria.

      Parameters:
        `keepParentsOnFilter` - New keepParentsOnFilter value. Default value is null
      Throws:
        `java.lang.IllegalStateException` - this property cannot be changed after the underlying component has been created
      See Also:
        `TreeDataBinding overview and related methods`

    - #### getKeepParentsOnFilter

          public java.lang.Boolean getKeepParentsOnFilter()

      If set, tree-based filtering is performed such that parent nodes are kept as long as they have children that match the filter criteria, even if the parents themselves do not match the filter criteria. If not set, filtering will exclude parent nodes not matching the criteria and all nodes below it in the tree.

      When `keepParentsOnFilter` is enabled for paged ResultTrees, server-side filtering is required.

      When enabled for non-paged trees, `fetchMode:"local"` is automatically enabled so that all filtering behavior shifts to the client-side and full criteria are no longer sent to the server. Instead, server fetches will always load all nodes, or with `loadDataOnDemand`:true, will always load all nodes under a given parent. This means that the server does not need to implement special tree filtering logic.

      Optionally, `serverFilterFields` can be set to a list of field names that will be sent to the server whenever they are present in the criteria.

      Returns:
        Current keepParentsOnFilter value. Default value is null
      See Also:
        `TreeDataBinding overview and related methods`

    - #### setLoadDataOnDemand

          public void setLoadDataOnDemand(java.lang.Boolean loadDataOnDemand)
                                   throws java.lang.IllegalStateException

      Does this resultTree load data incrementally as folders within the tree are opened, or is it all loaded in a single request? Must be true if `fetchMode` is "paged".
      Parameters:
        `loadDataOnDemand` - New loadDataOnDemand value. Default value is true
      Throws:
        `java.lang.IllegalStateException` - this property cannot be changed after the underlying component has been created
      See Also:
        `TreeGrid.setLoadDataOnDemand(java.lang.Boolean)`, `setUseSimpleCriteriaLOD(boolean)`

    - #### getLoadDataOnDemand

          public java.lang.Boolean getLoadDataOnDemand()

      Does this resultTree load data incrementally as folders within the tree are opened, or is it all loaded in a single request? Must be true if `fetchMode` is "paged".
      Returns:
        Current loadDataOnDemand value. Default value is true
      See Also:
        `TreeGrid.getLoadDataOnDemand()`, `getUseSimpleCriteriaLOD()`

    - #### 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 `Tree.data` attribute. If the "children" modelType is used, you can provide the initial tree structure to the Tree via the `Tree.root` attribute.

      Note : This is an advanced setting

      Overrides:
        `setModelType` in class `Tree`
      Parameters:
        `modelType` - New modelType value. Default value is "parent"
      See Also:
        `Tree.setData(com.smartgwt.client.widgets.tree.TreeNode[])`, `Tree.setRoot(com.smartgwt.client.widgets.tree.TreeNode)`, Node Titles Example

    - #### 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 `Tree.data` attribute. If the "children" modelType is used, you can provide the initial tree structure to the Tree via the `Tree.root` attribute.

      Overrides:
        `getModelType` in class `Tree`
      Returns:
        Current modelType value. Default value is "parent"
      See Also:
        `Tree.getData()`, `Tree.getRoot()`, Node Titles Example

    - #### setProgressiveLoading

          public void setProgressiveLoading(java.lang.Boolean progressiveLoading)

      Sets `progressive loading mode` for this ResultTree. The ResultTree will copy this setting onto the `DSRequest`s that it issues, overriding the OperationBinding- and DataSource-level settings, in cases where the use of progressive loading does not affect the correctness of the tree's paging algorithm.

      This setting is applied automatically by `DataBoundComponent`s that have their own explicit setting for `progressiveLoading`.

      Note: This property only has an effect for `fetchMode:"paged"` ResultTrees.

      Parameters:
        `progressiveLoading` - New progressiveLoading value. Default value is null
      See Also:
        `DataSource.setProgressiveLoading(java.lang.Boolean)`, `OperationBinding.progressiveLoading`, `DSRequest.setProgressiveLoading(java.lang.Boolean)`, `ProgressiveLoading overview and related methods`

    - #### getProgressiveLoading

          public java.lang.Boolean getProgressiveLoading()

      Sets `progressive loading mode` for this ResultTree. The ResultTree will copy this setting onto the `DSRequest`s that it issues, overriding the OperationBinding- and DataSource-level settings, in cases where the use of progressive loading does not affect the correctness of the tree's paging algorithm.

      This setting is applied automatically by `DataBoundComponent`s that have their own explicit setting for `progressiveLoading`.

      Note: This property only has an effect for `fetchMode:"paged"` ResultTrees.

      Returns:
        Current progressiveLoading value. Default value is null
      See Also:
        `DataSource.getProgressiveLoading()`, `OperationBinding.progressiveLoading`, `DSRequest.getProgressiveLoading()`, `ProgressiveLoading overview and related methods`

    - #### setResultSize

          public void setResultSize(java.lang.Integer resultSize)
                             throws java.lang.IllegalStateException

      How many tree nodes to retrieve at once from each large set of children in the tree.

      Applicable only with `fetchMode: "paged"`. When a paged ResultTree is asked for rows that have not yet been loaded, it will fetch adjacent rows that are likely to be required soon, in batches of this size.

      Note : This is an advanced setting

      Parameters:
        `resultSize` - New resultSize value. Default value is 75
      Throws:
        `java.lang.IllegalStateException` - this property cannot be changed after the underlying component has been created
      See Also:
        `TreeDataBinding overview and related methods`

    - #### getResultSize

          public java.lang.Integer getResultSize()

      How many tree nodes to retrieve at once from each large set of children in the tree.

      Applicable only with `fetchMode: "paged"`. When a paged ResultTree is asked for rows that have not yet been loaded, it will fetch adjacent rows that are likely to be required soon, in batches of this size.

      Returns:
        Current resultSize value. Default value is 75
      See Also:
        `TreeDataBinding overview and related methods`

    - #### setServerFilterFields

          public void setServerFilterFields(java.lang.String... serverFilterFields)
                                     throws java.lang.IllegalStateException

      When `keepParentsOnFilter` is enabled for `fetchMode:"local"` ResultTrees, this property lists field names that will be sent to the server if they are present in the criteria.
      Parameters:
        `serverFilterFields` - New serverFilterFields value. Default value is null
      Throws:
        `java.lang.IllegalStateException` - this property cannot be changed after the underlying component has been created

    - #### getServerFilterFields

          public java.lang.String[] getServerFilterFields()

      When `keepParentsOnFilter` is enabled for `fetchMode:"local"` ResultTrees, this property lists field names that will be sent to the server if they are present in the criteria.
      Returns:
        Current serverFilterFields value. Default value is null

    - #### setUpdateCacheFromRequest

          public void setUpdateCacheFromRequest(java.lang.Boolean updateCacheFromRequest)
                                         throws java.lang.IllegalStateException

      When a successful Add, Update or Remove type operation fires on this ResultTree's dataSource, if `DSResponse.data` is unset, should we integrate the submitted data values (from the request) into our data-set?

      Note : This is an advanced setting

      Parameters:
        `updateCacheFromRequest` - New updateCacheFromRequest value. Default value is true
      Throws:
        `java.lang.IllegalStateException` - this property cannot be changed after the underlying component has been created

    - #### getUpdateCacheFromRequest

          public java.lang.Boolean getUpdateCacheFromRequest()

      When a successful Add, Update or Remove type operation fires on this ResultTree's dataSource, if `DSResponse.data` is unset, should we integrate the submitted data values (from the request) into our data-set?
      Returns:
        Current updateCacheFromRequest value. Default value is true

    - #### setUseSimpleCriteriaLOD

          public void setUseSimpleCriteriaLOD(boolean useSimpleCriteriaLOD)

      Whether or not we should skip promotion of a simple criteria to an `AdvancedCriteria` when sending the `DSRequest` to load the children of a node in a `loadDataOnDemand` or `fetchMode:"paged"` `ResultTree`. If the `DSRequest.textMatchStyle` is not "exact", we normally convert the simple criteria to an `AdvancedCriteria` for correctness in matching the node name, but setting this property to `true` will allow that to be skipped for backcompat with older releases.

      Note : This is an advanced setting

      Parameters:
        `useSimpleCriteriaLOD` - New useSimpleCriteriaLOD value. Default value is false
      See Also:
        `TreeGrid.setAutoFetchTextMatchStyle(com.smartgwt.client.types.TextMatchStyle)`, `DataSource.setDefaultTextMatchStyle(com.smartgwt.client.types.TextMatchStyle)`

    - #### getUseSimpleCriteriaLOD

          public boolean getUseSimpleCriteriaLOD()

      Whether or not we should skip promotion of a simple criteria to an `AdvancedCriteria` when sending the `DSRequest` to load the children of a node in a `loadDataOnDemand` or `fetchMode:"paged"` `ResultTree`. If the `DSRequest.textMatchStyle` is not "exact", we normally convert the simple criteria to an `AdvancedCriteria` for correctness in matching the node name, but setting this property to `true` will allow that to be skipped for backcompat with older releases.
      Returns:
        Current useSimpleCriteriaLOD value. Default value is false
      See Also:
        `TreeGrid.getAutoFetchTextMatchStyle()`, `DataSource.getDefaultTextMatchStyle()`

    - #### applyFilter

          public Tree applyFilter(Tree tree,
                                  Criteria criteria,
                                  TreeFilterMode filterMode,
                                  DataSource dataSource)

      The ResultTree will call applyFilter() when it needs to locally filter the tree using the current filter criteria.

      Default behavior is to call `Tree.getFilteredTree()` to obtain a new, filtered tree.

      Override this method or `Tree.getFilteredTree()` to implement your own client-side filtering behavior. Note that the original tree should not be affected.

      Parameters:
        `tree` - the source tree to be filtered
        `criteria` - the filter criteria
        `filterMode` - mode to use for filtering
        `dataSource` - dataSource for filtering if the Tree does not already have one
      Returns:
        the filtered tree (copy)

    - #### applyFilter

          public Tree applyFilter(Tree tree,
                                  Criteria criteria,
                                  TreeFilterMode filterMode,
                                  DataSource dataSource,
                                  DSRequest requestProperties)

      The ResultTree will call applyFilter() when it needs to locally filter the tree using the current filter criteria.

      Default behavior is to call `Tree.getFilteredTree()` to obtain a new, filtered tree.

      Override this method or `Tree.getFilteredTree()` to implement your own client-side filtering behavior. Note that the original tree should not be affected.

      Parameters:
        `tree` - the source tree to be filtered
        `criteria` - the filter criteria
        `filterMode` - mode to use for filtering
        `dataSource` - dataSource for filtering if the Tree does not already have one
        `requestProperties` - Request properties block. This allows developers to specify properties that would impact the filter such as `DSRequest.textMatchStyle`
      Returns:
        the filtered tree (copy)

    - #### compareCriteria

          public int compareCriteria(Criteria newCriteria,
                                     Criteria oldCriteria)

      Default behavior is to call `DataSource.compareCriteria()` to determine whether new criteria is equivalent to the old criteria (returns 0) or not.

      See `DataSource.compareCriteria()` for a full explanation of the default behavior. The `CriteriaPolicy` used is "dropOnChange".

      Override this method or `DataSource.compareCriteria()` to implement your own client-side filtering behavior.

      Parameters:
        `newCriteria` - new filter criteria
        `oldCriteria` - old filter criteria
      Returns:
        0 if the criteria are equivalent, -1 if the criteria are different
      See Also:
        `CriteriaPolicy`

    - #### compareCriteria

          public int compareCriteria(Criteria newCriteria,
                                     Criteria oldCriteria,
                                     DSRequest requestProperties)

      Default behavior is to call `DataSource.compareCriteria()` to determine whether new criteria is equivalent to the old criteria (returns 0) or not.

      See `DataSource.compareCriteria()` for a full explanation of the default behavior. The `CriteriaPolicy` used is "dropOnChange".

      Override this method or `DataSource.compareCriteria()` to implement your own client-side filtering behavior.

      Parameters:
        `newCriteria` - new filter criteria
        `oldCriteria` - old filter criteria
        `requestProperties` - dataSource request properties
      Returns:
        0 if the criteria are equivalent, -1 if the criteria are different
      See Also:
        `CriteriaPolicy`

    - #### dataArrived

          public void dataArrived(TreeNode parentNode)

      This callback fires whenever the resultTree receives new nodes from the server, after the new nodes have been integrated into the tree.
      Parameters:
        `parentNode` - The parentNode for which children were just loaded

    - #### get

          public TreeNode get(int pos)

      Get the item in the openList at a particular position.
      Overrides:
        `get` in class `RecordList`
      Parameters:
        `pos` - position of the node to get
      Returns:
        node at that position

    - #### getOpenState

          public java.lang.String getOpenState()

      Returns a snapshot of the current open state of this tree's data as a `TreeGridOpenState` object.

      This object can be passed to `setOpenState()` or `TreeGrid.setOpenState()` to open the same set of folders within the tree's data (assuming the nodes are still present in the data).

      Returns:
        current open state for the grid. See `TreeGridOpenState`
      See Also:
        `setOpenState(java.lang.String)`

    - #### getRange

          public TreeNode[] getRange(int start,
                                     int end)

      Get a range of items from the open list
      Overrides:
        `getRange` in class `RecordList`
      Parameters:
        `start` - start position
        `end` - end position (NOT inclusive)
      Returns:
        list of nodes in the open list

    - #### invalidateCache

          public void invalidateCache()

      Manually invalidate this ResultTree's cache.

      Generally a ResultTree will observe and incorporate updates to the DataSource that provides its records, but when this is not possible, `invalidateCache()` allows manual cache invalidation.

      Components bound to this ResultTree will typically re-request the currently visible portion of the dataset, causing the ResultTree to re-fetch data from the server.

    - #### setChildren

          public void setChildren(TreeNode parent,
                                  java.util.List newChildren)

      Replaces the existing children of a parent node. This leaves the node in the loaded state (unless a partially loaded set of children is specified using the optional `totalChildren` argument). The supplied array of children may be null or empty to indicate there are none, but if present must be in the standard format as would be sent from the server, as described by `TreeDataBinding`.

      In particular, note that for a `paged` `ResultTree`, each child node:

      :
      - can have nested children spcified under the `Tree.childrenProperty` (but not via `TreeNode.id`/`TreeNode.parentId` linking)
      - cannot be open unless it includes either a complete set of children, or partial set of children and a childCount
      Overrides:
        `setChildren` in class `Tree`
      Parameters:
        `parent` - parent of children
        `newChildren` - children to be set
      See Also:
        `Tree.removeChildren(com.smartgwt.client.widgets.tree.TreeNode)`, `DataSource.updateCaches(com.smartgwt.client.data.DSResponse)`

    - #### setChildren

          public void setChildren(TreeNode parent,
                                  java.util.List newChildren,
                                  java.lang.Integer totalChildren)

      Replaces the existing children of a parent node. This leaves the node in the loaded state (unless a partially loaded set of children is specified using the optional `totalChildren` argument). The supplied array of children may be null or empty to indicate there are none, but if present must be in the standard format as would be sent from the server, as described by `TreeDataBinding`.

      In particular, note that for a `paged` `ResultTree`, each child node:

      :
      - can have nested children spcified under the `Tree.childrenProperty` (but not via `TreeNode.id`/`TreeNode.parentId` linking)
      - cannot be open unless it includes either a complete set of children, or partial set of children and a childCount
      Parameters:
        `parent` - parent of children
        `newChildren` - children to be set
        `totalChildren` - number of total children (if not all have been provided as newChildren); only allowed if paging
      See Also:
        `Tree.removeChildren(com.smartgwt.client.widgets.tree.TreeNode)`, `DataSource.updateCaches(com.smartgwt.client.data.DSResponse)`

    - #### setOpenState

          public void setOpenState(java.lang.String openState)

      Reset the set of open folders within this tree's data to match the `TreeGridOpenState` object passed in.

      Used to restore previous state retrieved from the tree by a call to `getOpenState()`.

      Parameters:
        `openState` - Object describing the desired set of open folders. See `TreeGridOpenState`
      See Also:
        `getOpenState()`, `TreeGridOpenState`

    - #### unloadChildren

          public void unloadChildren(TreeNode node)

      Deprecated. It's recommended that you instead use `Tree.reloadChildren()` to reload the children of a folder, or `Tree.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.
      Overrides:
        `unloadChildren` in class `Tree`
      Parameters:
        `node` - folder in question

    - #### willFetchData

          public java.lang.Boolean willFetchData(Criteria newCriteria)

      Will changing the criteria for this resultTree require fetching new data from the server or can the new criteria be satisfied from data already cached on the client?

      This method can be used to determine whether `TreeGrid.fetchData()` or `TreeGrid.filterData()` will cause a server side fetch when passed a certain set of criteria.

      Parameters:
        `newCriteria` - new criteria to test.
      Returns:
        true if server fetch would be required to satisfy new criteria.

    - #### setDefaultProperties

          public static void setDefaultProperties(ResultTree resultTreeProperties)

      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:
        `resultTreeProperties` - properties that should be used as new defaults when instances of this class are created
      See Also:
        `SGWTProperties`

    - #### setDataSource

          public void setDataSource(DataSource dataSource)
                             throws java.lang.IllegalStateException

      What `DataSource` is this resultTree associated with?
      Overrides:
        `setDataSource` in class `Tree`
      Parameters:
        `dataSource` - dataSource Default value is null
      Throws:
        `java.lang.IllegalStateException` - this property cannot be changed after the underlying component has been created
      See Also:
        `Databinding overview and related methods`, DataSource fields Example

    - #### getDataSource

          public DataSource getDataSource()

      What `DataSource` is this resultTree associated with?
      Overrides:
        `getDataSource` in class `Tree`
      Returns:
        DataSource
      See Also:
        `Databinding overview and related methods`, DataSource fields Example

    - #### setRootNode

          public void setRootNode(com.google.gwt.core.client.JavaScriptObject rootNode)
                           throws java.lang.IllegalStateException

      This attribute may be used to specify a root value for the parentIdField of this resultTree. This overrides the default `rootValue` for this tree, allowing a component to navigate a tree starting at a specific node.

      May be overridden via `treeRootValue` for ResultTrees generated by a TreeGrid component.

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

    - #### getRootNode

          public com.google.gwt.core.client.JavaScriptObject getRootNode()

      This attribute may be used to specify a root value for the parentIdField of this resultTree. This overrides the default `rootValue` for this tree, allowing a component to navigate a tree starting at a specific node.

      May be overridden via `treeRootValue` for ResultTrees generated by a TreeGrid component.

      Returns:
        Object