X-Git-Url: http://git.ithinksw.org/extjs.git/blobdiff_plain/25ef3491bd9ae007ff1fc2b0d7943e6eaaccf775..2e847cf21b8ab9d15fa167b315ca5b2fa92638fc:/src/data/Tree.js

diff --git a/src/data/Tree.js b/src/data/Tree.js
index a822ab31..f0c54796 100644
--- a/src/data/Tree.js
+++ b/src/data/Tree.js
@@ -1,6 +1,6 @@
 /*!
- * Ext JS Library 3.0.3
- * Copyright(c) 2006-2009 Ext JS, LLC
+ * Ext JS Library 3.1.1
+ * Copyright(c) 2006-2010 Ext JS, LLC
  * licensing@extjs.com
  * http://www.extjs.com/license
  */
@@ -417,9 +417,10 @@ Ext.extend(Ext.data.Node, Ext.util.Observable, {
     /**
      * Removes a child node from this node.
      * @param {Node} node The node to remove
+     * @param {Boolean} destroy <tt>true</tt> to destroy the node upon removal. Defaults to <tt>false</tt>.
      * @return {Node} The removed node
      */
-    removeChild : function(node){
+    removeChild : function(node, destroy){
         var index = this.childNodes.indexOf(node);
         if(index == -1){
             return false;
@@ -447,14 +448,35 @@ Ext.extend(Ext.data.Node, Ext.util.Observable, {
             this.setLastChild(node.previousSibling);
         }
 
-        node.setOwnerTree(null);
-        // clear any references from the node
-        node.parentNode = null;
-        node.previousSibling = null;
-        node.nextSibling = null;
+        node.clear();
         this.fireEvent("remove", this.ownerTree, this, node);
+        if(destroy){
+            node.destroy();
+        }
         return node;
     },
+    
+    // private
+    clear : function(destroy){
+        // clear any references from the node
+        this.setOwnerTree(null, destroy);
+        this.parentNode = this.previousSibling = this.nextSibling = null
+        if(destroy){
+            this.firstChild = this.lastChild = null; 
+        }
+    },
+    
+    /**
+     * Destroys the node.
+     */
+    destroy : function(){
+        this.purgeListeners();
+        this.clear(true);  
+        Ext.each(this.childNodes, function(n){
+            n.destroy();
+        });
+        this.childNodes = null;
+    },
 
     /**
      * Inserts the first node before the second node in this nodes childNodes collection.
@@ -514,10 +536,25 @@ Ext.extend(Ext.data.Node, Ext.util.Observable, {
 
     /**
      * Removes this node from its parent
+     * @param {Boolean} destroy <tt>true</tt> to destroy the node upon removal. Defaults to <tt>false</tt>.
+     * @return {Node} this
+     */
+    remove : function(destroy){
+        this.parentNode.removeChild(this, destroy);
+        return this;
+    },
+    
+    /**
+     * Removes all child nodes from this node.
+     * @param {Boolean} destroy <tt>true</tt> to destroy the node upon removal. Defaults to <tt>false</tt>.
      * @return {Node} this
      */
-    remove : function(){
-        this.parentNode.removeChild(this);
+    removeAll : function(destroy){
+        var cn = this.childNodes,
+            n;
+        while((n = cn[0])){
+            this.removeChild(n, destroy);
+        }
         return this;
     },
 
@@ -586,16 +623,18 @@ Ext.extend(Ext.data.Node, Ext.util.Observable, {
     },
 
     // private
-    setOwnerTree : function(tree){
+    setOwnerTree : function(tree, destroy){
         // if it is a move, we need to update everyone
         if(tree != this.ownerTree){
             if(this.ownerTree){
                 this.ownerTree.unregisterNode(this);
             }
             this.ownerTree = tree;
-            var cs = this.childNodes;
-            for(var i = 0, len = cs.length; i < len; i++) {
-            	cs[i].setOwnerTree(tree);
+            // If we're destroying, we don't need to recurse since it will be called on each child node
+            if(destroy !== true){
+                Ext.each(this.childNodes, function(n){
+                    n.setOwnerTree(tree);
+                });
             }
             if(tree){
                 tree.registerNode(this);
@@ -642,13 +681,12 @@ Ext.extend(Ext.data.Node, Ext.util.Observable, {
     },
 
     /**
-     * Bubbles up the tree from this node, calling the specified function with each node. The scope (<i>this</i>) of
-     * function call will be the scope provided or the current node. The arguments to the function
+     * Bubbles up the tree from this node, calling the specified function with each node. The arguments to the function
      * will be the args provided or the current node. If the function returns false at any point,
      * the bubble is stopped.
      * @param {Function} fn The function to call
-     * @param {Object} scope (optional) The scope of the function (defaults to current node)
-     * @param {Array} args (optional) The args to call the function with (default to passing the current node)
+     * @param {Object} scope (optional) The scope (<code>this</code> reference) in which the function is executed. Defaults to the current Node.
+     * @param {Array} args (optional) The args to call the function with (default to passing the current Node)
      */
     bubble : function(fn, scope, args){
         var p = this;
@@ -661,13 +699,12 @@ Ext.extend(Ext.data.Node, Ext.util.Observable, {
     },
 
     /**
-     * Cascades down the tree from this node, calling the specified function with each node. The scope (<i>this</i>) of
-     * function call will be the scope provided or the current node. The arguments to the function
+     * Cascades down the tree from this node, calling the specified function with each node. The arguments to the function
      * will be the args provided or the current node. If the function returns false at any point,
      * the cascade is stopped on that branch.
      * @param {Function} fn The function to call
-     * @param {Object} scope (optional) The scope of the function (defaults to current node)
-     * @param {Array} args (optional) The args to call the function with (default to passing the current node)
+     * @param {Object} scope (optional) The scope (<code>this</code> reference) in which the function is executed. Defaults to the current Node.
+     * @param {Array} args (optional) The args to call the function with (default to passing the current Node)
      */
     cascade : function(fn, scope, args){
         if(fn.apply(scope || this, args || [this]) !== false){
@@ -679,13 +716,12 @@ Ext.extend(Ext.data.Node, Ext.util.Observable, {
     },
 
     /**
-     * Interates the child nodes of this node, calling the specified function with each node. The scope (<i>this</i>) of
-     * function call will be the scope provided or the current node. The arguments to the function
+     * Interates the child nodes of this node, calling the specified function with each node. The arguments to the function
      * will be the args provided or the current node. If the function returns false at any point,
      * the iteration stops.
      * @param {Function} fn The function to call
-     * @param {Object} scope (optional) The scope of the function (defaults to current node)
-     * @param {Array} args (optional) The args to call the function with (default to passing the current node)
+     * @param {Object} scope (optional) The scope (<code>this</code> reference) in which the function is executed. Defaults to the current Node in the iteration.
+     * @param {Array} args (optional) The args to call the function with (default to passing the current Node)
      */
     eachChild : function(fn, scope, args){
         var cs = this.childNodes;
@@ -713,10 +749,9 @@ Ext.extend(Ext.data.Node, Ext.util.Observable, {
     },
 
     /**
-     * Finds the first child by a custom function. The child matches if the function passed
-     * returns true.
-     * @param {Function} fn
-     * @param {Object} scope (optional)
+     * Finds the first child by a custom function. The child matches if the function passed returns <code>true</code>.
+     * @param {Function} fn A function which must return <code>true</code> if the passed Node is the required Node.
+     * @param {Object} scope (optional) The scope (<code>this</code> reference) in which the function is executed. Defaults to the Node being tested.
      * @return {Node} The found child or null if none was found
      */
     findChildBy : function(fn, scope){
@@ -730,9 +765,9 @@ Ext.extend(Ext.data.Node, Ext.util.Observable, {
     },
 
     /**
-     * Sorts this nodes children using the supplied sort function
-     * @param {Function} fn
-     * @param {Object} scope (optional)
+     * Sorts this nodes children using the supplied sort function.
+     * @param {Function} fn A function which, when passed two Nodes, returns -1, 0 or 1 depending upon required sort order.
+     * @param {Object} scope (optional)The scope (<code>this</code> reference) in which the function is executed. Defaults to the browser window.
      */
     sort : function(fn, scope){
         var cs = this.childNodes;