Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / docs / source / Tree.html
index e600ff0..f87d813 100644 (file)
@@ -3,8 +3,8 @@
 <head>
   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   <title>The source code</title>
-  <link href="../prettify/prettify.css" type="text/css" rel="stylesheet" />
-  <script type="text/javascript" src="../prettify/prettify.js"></script>
+  <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
+  <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
   <style type="text/css">
     .highlight { display: block; background-color: #ddd; }
   </style>
   </script>
 </head>
 <body onload="prettyPrint(); highlight();">
-  <pre class="prettyprint lang-js"><span id='Ext-data-Tree-method-constructor'><span id='Ext-data-Tree'>/**
-</span></span> * @class Ext.data.Tree
- * 
+  <pre class="prettyprint lang-js"><span id='Ext-data-Tree'>/**
+</span> * @class Ext.data.Tree
+ *
  * This class is used as a container for a series of nodes. The nodes themselves maintain
  * the relationship between parent/child. The tree itself acts as a manager. It gives functionality
- * to retrieve a node by its identifier: {@link #getNodeById}. 
+ * to retrieve a node by its identifier: {@link #getNodeById}.
  *
- * The tree also relays events from any of it's child nodes, allowing them to be handled in a 
- * centralized fashion. In general this class is not used directly, rather used internally 
+ * The tree also relays events from any of it's child nodes, allowing them to be handled in a
+ * centralized fashion. In general this class is not used directly, rather used internally
  * by other parts of the framework.
  *
- * @constructor
- * @param {Node} root (optional) The root node
  */
 Ext.define('Ext.data.Tree', {
     alias: 'data.tree',
-    
+
     mixins: {
         observable: &quot;Ext.util.Observable&quot;
     },
 
 <span id='Ext-data-Tree-property-root'>    /**
-</span>     * The root node for this tree
-     * @type Node
+</span>     * @property {Ext.data.NodeInterface}
+     * The root node for this tree
      */
     root: null,
-        
+
+<span id='Ext-data-Tree-method-constructor'>    /**
+</span>     * Creates new Tree object.
+     * @param {Ext.data.NodeInterface} root (optional) The root node
+     */
     constructor: function(root) {
         var me = this;
+
         
-        me.nodeHash = {};
 
         me.mixins.observable.constructor.call(me);
-                        
+
         if (root) {
             me.setRootNode(root);
         }
@@ -69,119 +71,84 @@ Ext.define('Ext.data.Tree', {
      */
     setRootNode : function(node) {
         var me = this;
-        
+
         me.root = node;
         Ext.data.NodeInterface.decorate(node);
-        
+
         if (me.fireEvent('beforeappend', null, node) !== false) {
             node.set('root', true);
             node.updateInfo();
-            
+
             me.relayEvents(node, [
 <span id='Ext-data-Tree-event-append'>                /**
 </span>                 * @event append
-                 * Fires when a new child node is appended to a node in this tree.
-                 * @param {Tree} tree The owner tree
-                 * @param {Node} parent The parent node
-                 * @param {Node} node The newly appended node
-                 * @param {Number} index The index of the newly appended node
+                 * @alias Ext.data.NodeInterface#append
                  */
                 &quot;append&quot;,
 
 <span id='Ext-data-Tree-event-remove'>                /**
 </span>                 * @event remove
-                 * Fires when a child node is removed from a node in this tree.
-                 * @param {Tree} tree The owner tree
-                 * @param {Node} parent The parent node
-                 * @param {Node} node The child node removed
+                 * @alias Ext.data.NodeInterface#remove
                  */
                 &quot;remove&quot;,
 
 <span id='Ext-data-Tree-event-move'>                /**
 </span>                 * @event move
-                 * Fires when a node is moved to a new location in the tree
-                 * @param {Tree} tree The owner tree
-                 * @param {Node} node The node moved
-                 * @param {Node} oldParent The old parent of this node
-                 * @param {Node} newParent The new parent of this node
-                 * @param {Number} index The index it was moved to
+                 * @alias Ext.data.NodeInterface#move
                  */
                 &quot;move&quot;,
 
 <span id='Ext-data-Tree-event-insert'>                /**
 </span>                 * @event insert
-                 * Fires when a new child node is inserted in a node in this tree.
-                 * @param {Tree} tree The owner tree
-                 * @param {Node} parent The parent node
-                 * @param {Node} node The child node inserted
-                 * @param {Node} refNode The child node the node was inserted before
+                 * @alias Ext.data.NodeInterface#insert
                  */
                 &quot;insert&quot;,
 
 <span id='Ext-data-Tree-event-beforeappend'>                /**
 </span>                 * @event beforeappend
-                 * Fires before a new child is appended to a node in this tree, return false to cancel the append.
-                 * @param {Tree} tree The owner tree
-                 * @param {Node} parent The parent node
-                 * @param {Node} node The child node to be appended
+                 * @alias Ext.data.NodeInterface#beforeappend
                  */
                 &quot;beforeappend&quot;,
 
 <span id='Ext-data-Tree-event-beforeremove'>                /**
 </span>                 * @event beforeremove
-                 * Fires before a child is removed from a node in this tree, return false to cancel the remove.
-                 * @param {Tree} tree The owner tree
-                 * @param {Node} parent The parent node
-                 * @param {Node} node The child node to be removed
+                 * @alias Ext.data.NodeInterface#beforeremove
                  */
                 &quot;beforeremove&quot;,
 
 <span id='Ext-data-Tree-event-beforemove'>                /**
 </span>                 * @event beforemove
-                 * Fires before a node is moved to a new location in the tree. Return false to cancel the move.
-                 * @param {Tree} tree The owner tree
-                 * @param {Node} node The node being moved
-                 * @param {Node} oldParent The parent of the node
-                 * @param {Node} newParent The new parent the node is moving to
-                 * @param {Number} index The index it is being moved to
+                 * @alias Ext.data.NodeInterface#beforemove
                  */
                 &quot;beforemove&quot;,
 
 <span id='Ext-data-Tree-event-beforeinsert'>                /**
 </span>                 * @event beforeinsert
-                 * Fires before a new child is inserted in a node in this tree, return false to cancel the insert.
-                 * @param {Tree} tree The owner tree
-                 * @param {Node} parent The parent node
-                 * @param {Node} node The child node to be inserted
-                 * @param {Node} refNode The child node the node is being inserted before
+                 * @alias Ext.data.NodeInterface#beforeinsert
                  */
                 &quot;beforeinsert&quot;,
 
 <span id='Ext-data-Tree-event-expand'>                 /**
 </span>                  * @event expand
-                  * Fires when this node is expanded.
-                  * @param {Node} this The expanding node
+                  * @alias Ext.data.NodeInterface#expand
                   */
                  &quot;expand&quot;,
 
 <span id='Ext-data-Tree-event-collapse'>                 /**
 </span>                  * @event collapse
-                  * Fires when this node is collapsed.
-                  * @param {Node} this The collapsing node
+                  * @alias Ext.data.NodeInterface#collapse
                   */
                  &quot;collapse&quot;,
 
 <span id='Ext-data-Tree-event-beforeexpand'>                 /**
 </span>                  * @event beforeexpand
-                  * Fires before this node is expanded.
-                  * @param {Node} this The expanding node
+                  * @alias Ext.data.NodeInterface#beforeexpand
                   */
                  &quot;beforeexpand&quot;,
 
 <span id='Ext-data-Tree-event-beforecollapse'>                 /**
 </span>                  * @event beforecollapse
-                  * Fires before this node is collapsed.
-                  * @param {Node} this The collapsing node
+                  * @alias Ext.data.NodeInterface#beforecollapse
                   */
                  &quot;beforecollapse&quot; ,
 
@@ -192,7 +159,7 @@ Ext.define('Ext.data.Tree', {
                   */
                  &quot;rootchange&quot;
             ]);
-            
+
             node.on({
                 scope: me,
                 insert: me.onNodeInsert,
@@ -200,24 +167,25 @@ Ext.define('Ext.data.Tree', {
                 remove: me.onNodeRemove
             });
 
-            me.registerNode(node);        
+            me.nodeHash = {};
+            me.registerNode(node);
             me.fireEvent('append', null, node);
             me.fireEvent('rootchange', node);
         }
-            
+
         return node;
     },
-    
+
 <span id='Ext-data-Tree-method-flatten'>    /**
 </span>     * Flattens all the nodes in the tree into an array.
      * @private
-     * @return {Array} The flattened nodes.
+     * @return {Ext.data.NodeInterface[]} The flattened nodes.
      */
     flatten: function(){
         var nodes = [],
             hash = this.nodeHash,
             key;
-            
+
         for (key in hash) {
             if (hash.hasOwnProperty(key)) {
                 nodes.push(hash[key]);
@@ -225,7 +193,7 @@ Ext.define('Ext.data.Tree', {
         }
         return nodes;
     },
-    
+
 <span id='Ext-data-Tree-method-onNodeInsert'>    /**
 </span>     * Fired when a node is inserted into the root or one of it's children
      * @private
@@ -233,9 +201,9 @@ Ext.define('Ext.data.Tree', {
      * @param {Ext.data.NodeInterface} node The inserted node
      */
     onNodeInsert: function(parent, node) {
-        this.registerNode(node);
+        this.registerNode(node, true);
     },
-    
+
 <span id='Ext-data-Tree-method-onNodeAppend'>    /**
 </span>     * Fired when a node is appended into the root or one of it's children
      * @private
@@ -243,9 +211,9 @@ Ext.define('Ext.data.Tree', {
      * @param {Ext.data.NodeInterface} node The appended node
      */
     onNodeAppend: function(parent, node) {
-        this.registerNode(node);
+        this.registerNode(node, true);
     },
-    
+
 <span id='Ext-data-Tree-method-onNodeRemove'>    /**
 </span>     * Fired when a node is removed from the root or one of it's children
      * @private
@@ -253,7 +221,7 @@ Ext.define('Ext.data.Tree', {
      * @param {Ext.data.NodeInterface} node The removed node
      */
     onNodeRemove: function(parent, node) {
-        this.unregisterNode(node);
+        this.unregisterNode(node, true);
     },
 
 <span id='Ext-data-Tree-method-getNodeById'>    /**
@@ -269,20 +237,32 @@ Ext.define('Ext.data.Tree', {
 </span>     * Registers a node with the tree
      * @private
      * @param {Ext.data.NodeInterface} The node to register
+     * @param {Boolean} [includeChildren] True to unregister any child nodes
      */
-    registerNode : function(node) {
+    registerNode : function(node, includeChildren) {
         this.nodeHash[node.getId() || node.internalId] = node;
+        if (includeChildren === true) {
+            node.eachChild(function(child){
+                this.registerNode(child, true);
+            }, this);
+        }
     },
 
 <span id='Ext-data-Tree-method-unregisterNode'>    /**
 </span>     * Unregisters a node with the tree
      * @private
      * @param {Ext.data.NodeInterface} The node to unregister
+     * @param {Boolean} [includeChildren] True to unregister any child nodes
      */
-    unregisterNode : function(node) {
+    unregisterNode : function(node, includeChildren) {
         delete this.nodeHash[node.getId() || node.internalId];
+        if (includeChildren === true) {
+            node.eachChild(function(child){
+                this.unregisterNode(child, true);
+            }, this);
+        }
     },
-    
+
 <span id='Ext-data-Tree-method-sort'>    /**
 </span>     * Sorts this tree
      * @private
@@ -292,7 +272,7 @@ Ext.define('Ext.data.Tree', {
     sort: function(sorterFn, recursive) {
         this.getRootNode().sort(sorterFn, recursive);
     },
-    
+
 <span id='Ext-data-Tree-method-filter'>     /**
 </span>     * Filters this tree
      * @private