/**
* @class Ext.data.Tree
* @extends Ext.util.Observable
* Represents a tree data structure and bubbles all the events for its nodes. The nodes
@@ -424,9 +419,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 true to destroy the node upon removal. Defaults to false.
* @return {Node} The removed node
*/
- removeChild : function(node){
+ removeChild : function(node, destroy){
var index = this.childNodes.indexOf(node);
if(index == -1){
return false;
@@ -454,14 +450,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.
@@ -521,10 +538,25 @@ Ext.extend(Ext.data.Node, Ext.util.Observable, {
/**
* Removes this node from its parent
+ * @param {Boolean} destroy true to destroy the node upon removal. Defaults to false.
+ * @return {Node} this
+ */
+ remove : function(destroy){
+ this.parentNode.removeChild(this, destroy);
+ return this;
+ },
+
+ /**
+ * Removes all child nodes from this node.
+ * @param {Boolean} destroy true to destroy the node upon removal. Defaults to false.
* @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;
},
@@ -593,16 +625,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);
@@ -649,13 +683,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 (this) 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 (this 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;
@@ -668,13 +701,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 (this) 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 (this 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){
@@ -686,13 +718,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 (this) 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 (this 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;
@@ -720,10 +751,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 true.
+ * @param {Function} fn A function which must return true if the passed Node is the required Node.
+ * @param {Object} scope (optional) The scope (this 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){
@@ -737,9 +767,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 (this reference) in which the function is executed. Defaults to the browser window.
*/
sort : function(fn, scope){
var cs = this.childNodes;
@@ -789,6 +819,6 @@ Ext.extend(Ext.data.Node, Ext.util.Observable, {
toString : function(){
return "[Node"+(this.id?" "+this.id:"")+"]";
}
-});