Upgrade to ExtJS 3.1.0 - Released 12/16/2009
[extjs.git] / docs / source / TreeNode.html
index ff39011..c766ccb 100644 (file)
@@ -1,5 +1,6 @@
 <html>\r
 <head>\r
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />    \r
   <title>The source code</title>\r
     <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />\r
     <script type="text/javascript" src="../resources/prettify/prettify.js"></script>\r
  * @cfg {Boolean} draggable True to make this node draggable (defaults to false)\r
  * @cfg {Boolean} isTarget False to not allow this node to act as a drop target (defaults to true)\r
  * @cfg {Boolean} allowChildren False to not allow this node to have child nodes (defaults to true)\r
- * @cfg {Boolean} editable False to not allow this node to be edited by an (@link Ext.tree.TreeEditor} (defaults to true)\r
+ * @cfg {Boolean} editable False to not allow this node to be edited by an {@link Ext.tree.TreeEditor} (defaults to true)\r
  * @constructor\r
  * @param {Object/String} attributes The attributes/config for the node or just a string with the text for the node\r
  */\r
 Ext.tree.TreeNode = function(attributes){\r
     attributes = attributes || {};\r
-    if(typeof attributes == "string"){\r
+    if(Ext.isString(attributes)){\r
         attributes = {text: attributes};\r
     }\r
     this.childrenRendered = false;\r
@@ -48,7 +49,7 @@ Ext.tree.TreeNode = function(attributes){
     this.allowChildren = attributes.allowChildren !== false && attributes.allowDrop !== false;\r
 \r
     /**\r
-     * Read-only. The text for this node. To change it use setText().\r
+     * Read-only. The text for this node. To change it use <code>{@link #setText}</code>.\r
      * @type String\r
      */\r
     this.text = attributes.text;\r
@@ -71,7 +72,7 @@ Ext.tree.TreeNode = function(attributes){
         * @param {String} text The new text\r
         * @param {String} oldText The old text\r
         */\r
-        "textchange",\r
+        'textchange',\r
         /**\r
         * @event beforeexpand\r
         * Fires before this node is expanded, return false to cancel.\r
@@ -79,7 +80,7 @@ Ext.tree.TreeNode = function(attributes){
         * @param {Boolean} deep\r
         * @param {Boolean} anim\r
         */\r
-        "beforeexpand",\r
+        'beforeexpand',\r
         /**\r
         * @event beforecollapse\r
         * Fires before this node is collapsed, return false to cancel.\r
@@ -87,67 +88,74 @@ Ext.tree.TreeNode = function(attributes){
         * @param {Boolean} deep\r
         * @param {Boolean} anim\r
         */\r
-        "beforecollapse",\r
+        'beforecollapse',\r
         /**\r
         * @event expand\r
         * Fires when this node is expanded\r
         * @param {Node} this This node\r
         */\r
-        "expand",\r
+        'expand',\r
         /**\r
         * @event disabledchange\r
         * Fires when the disabled status of this node changes\r
         * @param {Node} this This node\r
         * @param {Boolean} disabled\r
         */\r
-        "disabledchange",\r
+        'disabledchange',\r
         /**\r
         * @event collapse\r
         * Fires when this node is collapsed\r
         * @param {Node} this This node\r
         */\r
-        "collapse",\r
+        'collapse',\r
         /**\r
         * @event beforeclick\r
         * Fires before click processing. Return false to cancel the default action.\r
         * @param {Node} this This node\r
         * @param {Ext.EventObject} e The event object\r
         */\r
-        "beforeclick",\r
+        'beforeclick',\r
         /**\r
         * @event click\r
         * Fires when this node is clicked\r
         * @param {Node} this This node\r
         * @param {Ext.EventObject} e The event object\r
         */\r
-        "click",\r
+        'click',\r
         /**\r
         * @event checkchange\r
         * Fires when a node with a checkbox's checked property changes\r
         * @param {Node} this This node\r
         * @param {Boolean} checked\r
         */\r
-        "checkchange",\r
+        'checkchange',\r
+        /**\r
+        * @event beforedblclick\r
+        * Fires before double click processing. Return false to cancel the default action.\r
+        * @param {Node} this This node\r
+        * @param {Ext.EventObject} e The event object\r
+        */\r
+        'beforedblclick',\r
         /**\r
         * @event dblclick\r
         * Fires when this node is double clicked\r
         * @param {Node} this This node\r
         * @param {Ext.EventObject} e The event object\r
         */\r
-        "dblclick",\r
+        'dblclick',\r
         /**\r
         * @event contextmenu\r
         * Fires when this node is right clicked\r
         * @param {Node} this This node\r
         * @param {Ext.EventObject} e The event object\r
         */\r
-        "contextmenu",\r
+        'contextmenu',\r
         /**\r
         * @event beforechildrenrendered\r
         * Fires right before the child nodes for this node are rendered\r
         * @param {Node} this This node\r
         */\r
-        "beforechildrenrendered"\r
+        'beforechildrenrendered'\r
     );\r
 \r
     var uiClass = this.attributes.uiProvider || this.defaultUI || Ext.tree.TreeNodeUI;\r
@@ -159,7 +167,7 @@ Ext.tree.TreeNode = function(attributes){
     this.ui = new uiClass(this);\r
 };\r
 Ext.extend(Ext.tree.TreeNode, Ext.data.Node, {\r
-    preventHScroll: true,\r
+    preventHScroll : true,\r
     /**\r
      * Returns true if this node is expanded\r
      * @return {Boolean}\r
@@ -180,7 +188,7 @@ Ext.extend(Ext.tree.TreeNode, Ext.data.Node, {
 \r
     getLoader : function(){\r
         var owner;\r
-        return this.loader || ((owner = this.getOwnerTree()) && owner.loader ? owner.loader : new Ext.tree.TreeLoader());\r
+        return this.loader || ((owner = this.getOwnerTree()) && owner.loader ? owner.loader : (this.loader = new Ext.tree.TreeLoader()));\r
     },\r
 \r
     // private override\r
@@ -222,11 +230,11 @@ Ext.extend(Ext.tree.TreeNode, Ext.data.Node, {
     },\r
 \r
     // private override\r
-    removeChild : function(node){\r
+    removeChild : function(node, destroy){\r
         this.ownerTree.getSelectionModel().unselect(node);\r
         Ext.tree.TreeNode.superclass.removeChild.apply(this, arguments);\r
         // if it's been rendered remove dom node\r
-        if(this.childrenRendered){\r
+        if(node.ui.rendered){\r
             node.ui.remove();\r
         }\r
         if(this.childNodes.length < 1){\r
@@ -242,7 +250,7 @@ Ext.extend(Ext.tree.TreeNode, Ext.data.Node, {
 \r
     // private override\r
     insertBefore : function(node, refNode){\r
-        if(!node.render){ \r
+        if(!node.render){\r
             node = this.getLoader().createNode(node);\r
         }\r
         var newNode = Ext.tree.TreeNode.superclass.insertBefore.call(this, node, refNode);\r
@@ -259,26 +267,32 @@ Ext.extend(Ext.tree.TreeNode, Ext.data.Node, {
      */\r
     setText : function(text){\r
         var oldText = this.text;\r
-        this.text = text;\r
-        this.attributes.text = text;\r
+        this.text = this.attributes.text = text;\r
         if(this.rendered){ // event without subscribing\r
             this.ui.onTextChange(this, text, oldText);\r
         }\r
-        this.fireEvent("textchange", this, text, oldText);\r
+        this.fireEvent('textchange', this, text, oldText);\r
     },\r
 \r
     /**\r
      * Triggers selection of this node\r
      */\r
     select : function(){\r
-        this.getOwnerTree().getSelectionModel().select(this);\r
+        var t = this.getOwnerTree();\r
+        if(t){\r
+            t.getSelectionModel().select(this);\r
+        }\r
     },\r
 \r
     /**\r
      * Triggers deselection of this node\r
+     * @param {Boolean} silent (optional) True to stop selection change events from firing.\r
      */\r
-    unselect : function(){\r
-        this.getOwnerTree().getSelectionModel().unselect(this);\r
+    unselect : function(silent){\r
+        var t = this.getOwnerTree();\r
+        if(t){\r
+            t.getSelectionModel().unselect(this, silent);\r
+        }\r
     },\r
 \r
     /**\r
@@ -286,7 +300,8 @@ Ext.extend(Ext.tree.TreeNode, Ext.data.Node, {
      * @return {Boolean}\r
      */\r
     isSelected : function(){\r
-        return this.getOwnerTree().getSelectionModel().isSelected(this);\r
+        var t = this.getOwnerTree();\r
+        return t ? t.getSelectionModel().isSelected(this) : false;\r
     },\r
 \r
     /**\r
@@ -296,11 +311,11 @@ Ext.extend(Ext.tree.TreeNode, Ext.data.Node, {
      * @param {Function} callback (optional) A callback to be called when\r
      * expanding this node completes (does not wait for deep expand to complete).\r
      * Called with 1 parameter, this node.\r
-     * @param {Object} scope (optional) The scope in which to execute the callback.\r
+     * @param {Object} scope (optional) The scope (<code>this</code> reference) in which the callback is executed. Defaults to this TreeNode.\r
      */\r
     expand : function(deep, anim, callback, scope){\r
         if(!this.expanded){\r
-            if(this.fireEvent("beforeexpand", this, deep, anim) === false){\r
+            if(this.fireEvent('beforeexpand', this, deep, anim) === false){\r
                 return;\r
             }\r
             if(!this.childrenRendered){\r
@@ -309,7 +324,7 @@ Ext.extend(Ext.tree.TreeNode, Ext.data.Node, {
             this.expanded = true;\r
             if(!this.isHiddenRoot() && (this.getOwnerTree().animate && anim !== false) || anim){\r
                 this.ui.animExpand(function(){\r
-                    this.fireEvent("expand", this);\r
+                    this.fireEvent('expand', this);\r
                     this.runCallback(callback, scope || this, [this]);\r
                     if(deep === true){\r
                         this.expandChildNodes(true);\r
@@ -318,7 +333,7 @@ Ext.extend(Ext.tree.TreeNode, Ext.data.Node, {
                 return;\r
             }else{\r
                 this.ui.expand();\r
-                this.fireEvent("expand", this);\r
+                this.fireEvent('expand', this);\r
                 this.runCallback(callback, scope || this, [this]);\r
             }\r
         }else{\r
@@ -328,8 +343,8 @@ Ext.extend(Ext.tree.TreeNode, Ext.data.Node, {
             this.expandChildNodes(true);\r
         }\r
     },\r
-    \r
-    runCallback: function(cb, scope, args){\r
+\r
+    runCallback : function(cb, scope, args){\r
         if(Ext.isFunction(cb)){\r
             cb.apply(scope, args);\r
         }\r
@@ -346,17 +361,17 @@ Ext.extend(Ext.tree.TreeNode, Ext.data.Node, {
      * @param {Function} callback (optional) A callback to be called when\r
      * expanding this node completes (does not wait for deep expand to complete).\r
      * Called with 1 parameter, this node.\r
-     * @param {Object} scope (optional) The scope in which to execute the callback.\r
+     * @param {Object} scope (optional) The scope (<code>this</code> reference) in which the callback is executed. Defaults to this TreeNode.\r
      */\r
     collapse : function(deep, anim, callback, scope){\r
         if(this.expanded && !this.isHiddenRoot()){\r
-            if(this.fireEvent("beforecollapse", this, deep, anim) === false){\r
+            if(this.fireEvent('beforecollapse', this, deep, anim) === false){\r
                 return;\r
             }\r
             this.expanded = false;\r
             if((this.getOwnerTree().animate && anim !== false) || anim){\r
                 this.ui.animCollapse(function(){\r
-                    this.fireEvent("collapse", this);\r
+                    this.fireEvent('collapse', this);\r
                     this.runCallback(callback, scope || this, [this]);\r
                     if(deep === true){\r
                         this.collapseChildNodes(true);\r
@@ -365,7 +380,7 @@ Ext.extend(Ext.tree.TreeNode, Ext.data.Node, {
                 return;\r
             }else{\r
                 this.ui.collapse();\r
-                this.fireEvent("collapse", this);\r
+                this.fireEvent('collapse', this);\r
                 this.runCallback(callback, scope || this, [this]);\r
             }\r
         }else if(!this.expanded){\r
@@ -409,7 +424,7 @@ Ext.extend(Ext.tree.TreeNode, Ext.data.Node, {
      * Ensures all parent nodes are expanded, and if necessary, scrolls\r
      * the node into view.\r
      * @param {Function} callback (optional) A function to call when the node has been made visible.\r
-     * @param {Object} scope (optional) The scope in which to execute the callback.\r
+     * @param {Object} scope (optional) The scope (<code>this</code> reference) in which the callback is executed. Defaults to this TreeNode.\r
      */\r
     ensureVisible : function(callback, scope){\r
         var tree = this.getOwnerTree();\r
@@ -451,7 +466,7 @@ Ext.extend(Ext.tree.TreeNode, Ext.data.Node, {
         if(this.rendered && this.ui.onDisableChange){ // event without subscribing\r
             this.ui.onDisableChange(this, true);\r
         }\r
-        this.fireEvent("disabledchange", this, true);\r
+        this.fireEvent('disabledchange', this, true);\r
     },\r
 \r
     /**\r
@@ -462,13 +477,13 @@ Ext.extend(Ext.tree.TreeNode, Ext.data.Node, {
         if(this.rendered && this.ui.onDisableChange){ // event without subscribing\r
             this.ui.onDisableChange(this, false);\r
         }\r
-        this.fireEvent("disabledchange", this, false);\r
+        this.fireEvent('disabledchange', this, false);\r
     },\r
 \r
     // private\r
     renderChildren : function(suppressEvent){\r
         if(suppressEvent !== false){\r
-            this.fireEvent("beforechildrenrendered", this);\r
+            this.fireEvent('beforechildrenrendered', this);\r
         }\r
         var cs = this.childNodes;\r
         for(var i = 0, len = cs.length; i < len; i++){\r
@@ -527,19 +542,14 @@ Ext.extend(Ext.tree.TreeNode, Ext.data.Node, {
     },\r
 \r
     destroy : function(){\r
-        if(this.childNodes){\r
-            for(var i = 0,l = this.childNodes.length; i < l; i++){\r
-                this.childNodes[i].destroy();\r
-            }\r
-            this.childNodes = null;\r
-        }\r
-        if(this.ui.destroy){\r
-            this.ui.destroy();\r
-        }\r
+        this.unselect(true);\r
+        Ext.tree.TreeNode.superclass.destroy.call(this);\r
+        Ext.destroy(this.ui, this.loader);\r
+        this.ui = this.loader = null;\r
     },\r
-    \r
+\r
     // private\r
-    onIdChange: function(id){\r
+    onIdChange : function(id){\r
         this.ui.onIdChange(id);\r
     }\r
 });\r