lib/dijit/Tree.js.uncompressed.js

   1 require({cache:{
   2 'url:dijit/templates/TreeNode.html':"<div class=\"dijitTreeNode\" role=\"presentation\"\n\t><div data-dojo-attach-point=\"rowNode\" class=\"dijitTreeRow\" role=\"presentation\" data-dojo-attach-event=\"onmouseenter:_onMouseEnter, onmouseleave:_onMouseLeave, onclick:_onClick, ondblclick:_onDblClick\"\n\t\t><img src=\"${_blankGif}\" alt=\"\" data-dojo-attach-point=\"expandoNode\" class=\"dijitTreeExpando\" role=\"presentation\"\n\t\t/><span data-dojo-attach-point=\"expandoNodeText\" class=\"dijitExpandoText\" role=\"presentation\"\n\t\t></span\n\t\t><span data-dojo-attach-point=\"contentNode\"\n\t\t\tclass=\"dijitTreeContent\" role=\"presentation\">\n\t\t\t<img src=\"${_blankGif}\" alt=\"\" data-dojo-attach-point=\"iconNode\" class=\"dijitIcon dijitTreeIcon\" role=\"presentation\"\n\t\t\t/><span data-dojo-attach-point=\"labelNode\" class=\"dijitTreeLabel\" role=\"treeitem\" tabindex=\"-1\" aria-selected=\"false\" data-dojo-attach-event=\"onfocus:_onLabelFocus\"></span>\n\t\t</span\n\t></div>\n\t<div data-dojo-attach-point=\"containerNode\" class=\"dijitTreeContainer\" role=\"presentation\" style=\"display: none;\"></div>\n</div>\n",
   3 'url:dijit/templates/Tree.html':"<div class=\"dijitTree dijitTreeContainer\" role=\"tree\"\n\tdata-dojo-attach-event=\"onkeypress:_onKeyPress\">\n\t<div class=\"dijitInline dijitTreeIndent\" style=\"position: absolute; top: -9999px\" data-dojo-attach-point=\"indentDetector\"></div>\n</div>\n"}});
   4 define("dijit/Tree", [
   5         "dojo/_base/array", // array.filter array.forEach array.map
   6         "dojo/_base/connect",   // connect.isCopyKey()
   7         "dojo/cookie", // cookie
   8         "dojo/_base/declare", // declare
   9         "dojo/_base/Deferred", // Deferred
  10         "dojo/DeferredList", // DeferredList
  11         "dojo/dom", // dom.isDescendant
  12         "dojo/dom-class", // domClass.add domClass.remove domClass.replace domClass.toggle
  13         "dojo/dom-geometry", // domGeometry.setMarginBox domGeometry.position
  14         "dojo/dom-style",// domStyle.set
  15         "dojo/_base/event", // event.stop
  16         "dojo/fx", // fxUtils.wipeIn fxUtils.wipeOut
  17         "dojo/_base/kernel", // kernel.deprecated
  18         "dojo/keys",    // arrows etc.
  19         "dojo/_base/lang", // lang.getObject lang.mixin lang.hitch
  20         "dojo/topic",
  21         "./focus",
  22         "./registry",   // registry.getEnclosingWidget(), manager.defaultDuration
  23         "./_base/manager",      // manager.getEnclosingWidget(), manager.defaultDuration
  24         "./_Widget",
  25         "./_TemplatedMixin",
  26         "./_Container",
  27         "./_Contained",
  28         "./_CssStateMixin",
  29         "dojo/text!./templates/TreeNode.html",
  30         "dojo/text!./templates/Tree.html",
  31         "./tree/TreeStoreModel",
  32         "./tree/ForestStoreModel",
  33         "./tree/_dndSelector"
  34 ], function(array, connect, cookie, declare, Deferred, DeferredList,
  35                         dom, domClass, domGeometry, domStyle, event, fxUtils, kernel, keys, lang, topic,
  36                         focus, registry, manager, _Widget, _TemplatedMixin, _Container, _Contained, _CssStateMixin,
  37                         treeNodeTemplate, treeTemplate, TreeStoreModel, ForestStoreModel, _dndSelector){
  38
  39 /*=====
  40         var _Widget = dijit._Widget;
  41         var _TemplatedMixin = dijit._TemplatedMixin;
  42         var _CssStateMixin = dijit._CssStateMixin;
  43         var _Container = dijit._Container;
  44         var _Contained = dijit._Contained;
  45 =====*/
  46
  47 // module:
  48 //              dijit/Tree
  49 // summary:
  50 //              dijit.Tree widget, and internal dijit._TreeNode widget
  51
  52
  53 var TreeNode = declare(
  54         "dijit._TreeNode",
  55         [_Widget, _TemplatedMixin, _Container, _Contained, _CssStateMixin],
  56 {
  57         // summary:
  58         //              Single node within a tree.   This class is used internally
  59         //              by Tree and should not be accessed directly.
  60         // tags:
  61         //              private
  62
  63         // item: [const] Item
  64         //              the dojo.data entry this tree represents
  65         item: null,
  66
  67         // isTreeNode: [protected] Boolean
  68         //              Indicates that this is a TreeNode.   Used by `dijit.Tree` only,
  69         //              should not be accessed directly.
  70         isTreeNode: true,
  71
  72         // label: String
  73         //              Text of this tree node
  74         label: "",
  75         _setLabelAttr: {node: "labelNode", type: "innerText"},
  76
  77         // isExpandable: [private] Boolean
  78         //              This node has children, so show the expando node (+ sign)
  79         isExpandable: null,
  80
  81         // isExpanded: [readonly] Boolean
  82         //              This node is currently expanded (ie, opened)
  83         isExpanded: false,
  84
  85         // state: [private] String
  86         //              Dynamic loading-related stuff.
  87         //              When an empty folder node appears, it is "UNCHECKED" first,
  88         //              then after dojo.data query it becomes "LOADING" and, finally "LOADED"
  89         state: "UNCHECKED",
  90
  91         templateString: treeNodeTemplate,
  92
  93         baseClass: "dijitTreeNode",
  94
  95         // For hover effect for tree node, and focus effect for label
  96         cssStateNodes: {
  97                 rowNode: "dijitTreeRow",
  98                 labelNode: "dijitTreeLabel"
  99         },
 100
 101         // Tooltip is defined in _WidgetBase but we need to handle the mapping to DOM here
 102         _setTooltipAttr: {node: "rowNode", type: "attribute", attribute: "title"},
 103
 104         buildRendering: function(){
 105                 this.inherited(arguments);
 106
 107                 // set expand icon for leaf
 108                 this._setExpando();
 109
 110                 // set icon and label class based on item
 111                 this._updateItemClasses(this.item);
 112
 113                 if(this.isExpandable){
 114                         this.labelNode.setAttribute("aria-expanded", this.isExpanded);
 115                 }
 116
 117                 //aria-selected should be false on all selectable elements.
 118                 this.setSelected(false);
 119         },
 120
 121         _setIndentAttr: function(indent){
 122                 // summary:
 123                 //              Tell this node how many levels it should be indented
 124                 // description:
 125                 //              0 for top level nodes, 1 for their children, 2 for their
 126                 //              grandchildren, etc.
 127
 128                 // Math.max() is to prevent negative padding on hidden root node (when indent == -1)
 129                 var pixels = (Math.max(indent, 0) * this.tree._nodePixelIndent) + "px";
 130
 131                 domStyle.set(this.domNode, "backgroundPosition",        pixels + " 0px");
 132                 domStyle.set(this.rowNode, this.isLeftToRight() ? "paddingLeft" : "paddingRight", pixels);
 133
 134                 array.forEach(this.getChildren(), function(child){
 135                         child.set("indent", indent+1);
 136                 });
 137
 138                 this._set("indent", indent);
 139         },
 140
 141         markProcessing: function(){
 142                 // summary:
 143                 //              Visually denote that tree is loading data, etc.
 144                 // tags:
 145                 //              private
 146                 this.state = "LOADING";
 147                 this._setExpando(true);
 148         },
 149
 150         unmarkProcessing: function(){
 151                 // summary:
 152                 //              Clear markup from markProcessing() call
 153                 // tags:
 154                 //              private
 155                 this._setExpando(false);
 156         },
 157
 158         _updateItemClasses: function(item){
 159                 // summary:
 160                 //              Set appropriate CSS classes for icon and label dom node
 161                 //              (used to allow for item updates to change respective CSS)
 162                 // tags:
 163                 //              private
 164                 var tree = this.tree, model = tree.model;
 165                 if(tree._v10Compat && item === model.root){
 166                         // For back-compat with 1.0, need to use null to specify root item (TODO: remove in 2.0)
 167                         item = null;
 168                 }
 169                 this._applyClassAndStyle(item, "icon", "Icon");
 170                 this._applyClassAndStyle(item, "label", "Label");
 171                 this._applyClassAndStyle(item, "row", "Row");
 172         },
 173
 174         _applyClassAndStyle: function(item, lower, upper){
 175                 // summary:
 176                 //              Set the appropriate CSS classes and styles for labels, icons and rows.
 177                 //
 178                 // item:
 179                 //              The data item.
 180                 //
 181                 // lower:
 182                 //              The lower case attribute to use, e.g. 'icon', 'label' or 'row'.
 183                 //
 184                 // upper:
 185                 //              The upper case attribute to use, e.g. 'Icon', 'Label' or 'Row'.
 186                 //
 187                 // tags:
 188                 //              private
 189
 190                 var clsName = "_" + lower + "Class";
 191                 var nodeName = lower + "Node";
 192                 var oldCls = this[clsName];
 193
 194                 this[clsName] = this.tree["get" + upper + "Class"](item, this.isExpanded);
 195                 domClass.replace(this[nodeName], this[clsName] || "", oldCls || "");
 196
 197                 domStyle.set(this[nodeName], this.tree["get" + upper + "Style"](item, this.isExpanded) || {});
 198         },
 199
 200         _updateLayout: function(){
 201                 // summary:
 202                 //              Set appropriate CSS classes for this.domNode
 203                 // tags:
 204                 //              private
 205                 var parent = this.getParent();
 206                 if(!parent || !parent.rowNode || parent.rowNode.style.display == "none"){
 207                         /* if we are hiding the root node then make every first level child look like a root node */
 208                         domClass.add(this.domNode, "dijitTreeIsRoot");
 209                 }else{
 210                         domClass.toggle(this.domNode, "dijitTreeIsLast", !this.getNextSibling());
 211                 }
 212         },
 213
 214         _setExpando: function(/*Boolean*/ processing){
 215                 // summary:
 216                 //              Set the right image for the expando node
 217                 // tags:
 218                 //              private
 219
 220                 var styles = ["dijitTreeExpandoLoading", "dijitTreeExpandoOpened",
 221                                                 "dijitTreeExpandoClosed", "dijitTreeExpandoLeaf"],
 222                         _a11yStates = ["*","-","+","*"],
 223                         idx = processing ? 0 : (this.isExpandable ?     (this.isExpanded ? 1 : 2) : 3);
 224
 225                 // apply the appropriate class to the expando node
 226                 domClass.replace(this.expandoNode, styles[idx], styles);
 227
 228                 // provide a non-image based indicator for images-off mode
 229                 this.expandoNodeText.innerHTML = _a11yStates[idx];
 230
 231         },
 232
 233         expand: function(){
 234                 // summary:
 235                 //              Show my children
 236                 // returns:
 237                 //              Deferred that fires when expansion is complete
 238
 239                 // If there's already an expand in progress or we are already expanded, just return
 240                 if(this._expandDeferred){
 241                         return this._expandDeferred;            // dojo.Deferred
 242                 }
 243
 244                 // cancel in progress collapse operation
 245                 this._wipeOut && this._wipeOut.stop();
 246
 247                 // All the state information for when a node is expanded, maybe this should be
 248                 // set when the animation completes instead
 249                 this.isExpanded = true;
 250                 this.labelNode.setAttribute("aria-expanded", "true");
 251                 if(this.tree.showRoot || this !== this.tree.rootNode){
 252                         this.containerNode.setAttribute("role", "group");
 253                 }
 254                 domClass.add(this.contentNode,'dijitTreeContentExpanded');
 255                 this._setExpando();
 256                 this._updateItemClasses(this.item);
 257                 if(this == this.tree.rootNode){
 258                         this.tree.domNode.setAttribute("aria-expanded", "true");
 259                 }
 260
 261                 var def,
 262                         wipeIn = fxUtils.wipeIn({
 263                                 node: this.containerNode, duration: manager.defaultDuration,
 264                                 onEnd: function(){
 265                                         def.callback(true);
 266                                 }
 267                         });
 268
 269                 // Deferred that fires when expand is complete
 270                 def = (this._expandDeferred = new Deferred(function(){
 271                         // Canceller
 272                         wipeIn.stop();
 273                 }));
 274
 275                 wipeIn.play();
 276
 277                 return def;             // dojo.Deferred
 278         },
 279
 280         collapse: function(){
 281                 // summary:
 282                 //              Collapse this node (if it's expanded)
 283
 284                 if(!this.isExpanded){ return; }
 285
 286                 // cancel in progress expand operation
 287                 if(this._expandDeferred){
 288                         this._expandDeferred.cancel();
 289                         delete this._expandDeferred;
 290                 }
 291
 292                 this.isExpanded = false;
 293                 this.labelNode.setAttribute("aria-expanded", "false");
 294                 if(this == this.tree.rootNode){
 295                         this.tree.domNode.setAttribute("aria-expanded", "false");
 296                 }
 297                 domClass.remove(this.contentNode,'dijitTreeContentExpanded');
 298                 this._setExpando();
 299                 this._updateItemClasses(this.item);
 300
 301                 if(!this._wipeOut){
 302                         this._wipeOut = fxUtils.wipeOut({
 303                                 node: this.containerNode, duration: manager.defaultDuration
 304                         });
 305                 }
 306                 this._wipeOut.play();
 307         },
 308
 309         // indent: Integer
 310         //              Levels from this node to the root node
 311         indent: 0,
 312
 313         setChildItems: function(/* Object[] */ items){
 314                 // summary:
 315                 //              Sets the child items of this node, removing/adding nodes
 316                 //              from current children to match specified items[] array.
 317                 //              Also, if this.persist == true, expands any children that were previously
 318                 //              opened.
 319                 // returns:
 320                 //              Deferred object that fires after all previously opened children
 321                 //              have been expanded again (or fires instantly if there are no such children).
 322
 323                 var tree = this.tree,
 324                         model = tree.model,
 325                         defs = [];      // list of deferreds that need to fire before I am complete
 326
 327
 328                 // Orphan all my existing children.
 329                 // If items contains some of the same items as before then we will reattach them.
 330                 // Don't call this.removeChild() because that will collapse the tree etc.
 331                 array.forEach(this.getChildren(), function(child){
 332                         _Container.prototype.removeChild.call(this, child);
 333                 }, this);
 334
 335                 this.state = "LOADED";
 336
 337                 if(items && items.length > 0){
 338                         this.isExpandable = true;
 339
 340                         // Create _TreeNode widget for each specified tree node, unless one already
 341                         // exists and isn't being used (presumably it's from a DnD move and was recently
 342                         // released
 343                         array.forEach(items, function(item){
 344                                 var id = model.getIdentity(item),
 345                                         existingNodes = tree._itemNodesMap[id],
 346                                         node;
 347                                 if(existingNodes){
 348                                         for(var i=0;i<existingNodes.length;i++){
 349                                                 if(existingNodes[i] && !existingNodes[i].getParent()){
 350                                                         node = existingNodes[i];
 351                                                         node.set('indent', this.indent+1);
 352                                                         break;
 353                                                 }
 354                                         }
 355                                 }
 356                                 if(!node){
 357                                         node = this.tree._createTreeNode({
 358                                                         item: item,
 359                                                         tree: tree,
 360                                                         isExpandable: model.mayHaveChildren(item),
 361                                                         label: tree.getLabel(item),
 362                                                         tooltip: tree.getTooltip(item),
 363                                                         dir: tree.dir,
 364                                                         lang: tree.lang,
 365                                                         textDir: tree.textDir,
 366                                                         indent: this.indent + 1
 367                                                 });
 368                                         if(existingNodes){
 369                                                 existingNodes.push(node);
 370                                         }else{
 371                                                 tree._itemNodesMap[id] = [node];
 372                                         }
 373                                 }
 374                                 this.addChild(node);
 375
 376                                 // If node was previously opened then open it again now (this may trigger
 377                                 // more data store accesses, recursively)
 378                                 if(this.tree.autoExpand || this.tree._state(node)){
 379                                         defs.push(tree._expandNode(node));
 380                                 }
 381                         }, this);
 382
 383                         // note that updateLayout() needs to be called on each child after
 384                         // _all_ the children exist
 385                         array.forEach(this.getChildren(), function(child){
 386                                 child._updateLayout();
 387                         });
 388                 }else{
 389                         this.isExpandable=false;
 390                 }
 391
 392                 if(this._setExpando){
 393                         // change expando to/from dot or + icon, as appropriate
 394                         this._setExpando(false);
 395                 }
 396
 397                 // Set leaf icon or folder icon, as appropriate
 398                 this._updateItemClasses(this.item);
 399
 400                 // On initial tree show, make the selected TreeNode as either the root node of the tree,
 401                 // or the first child, if the root node is hidden
 402                 if(this == tree.rootNode){
 403                         var fc = this.tree.showRoot ? this : this.getChildren()[0];
 404                         if(fc){
 405                                 fc.setFocusable(true);
 406                                 tree.lastFocused = fc;
 407                         }else{
 408                                 // fallback: no nodes in tree so focus on Tree <div> itself
 409                                 tree.domNode.setAttribute("tabIndex", "0");
 410                         }
 411                 }
 412
 413                 return new DeferredList(defs);  // dojo.Deferred
 414         },
 415
 416         getTreePath: function(){
 417                 var node = this;
 418                 var path = [];
 419                 while(node && node !== this.tree.rootNode){
 420                                 path.unshift(node.item);
 421                                 node = node.getParent();
 422                 }
 423                 path.unshift(this.tree.rootNode.item);
 424
 425                 return path;
 426         },
 427
 428         getIdentity: function(){
 429                 return this.tree.model.getIdentity(this.item);
 430         },
 431
 432         removeChild: function(/* treeNode */ node){
 433                 this.inherited(arguments);
 434
 435                 var children = this.getChildren();
 436                 if(children.length == 0){
 437                         this.isExpandable = false;
 438                         this.collapse();
 439                 }
 440
 441                 array.forEach(children, function(child){
 442                                 child._updateLayout();
 443                 });
 444         },
 445
 446         makeExpandable: function(){
 447                 // summary:
 448                 //              if this node wasn't already showing the expando node,
 449                 //              turn it into one and call _setExpando()
 450
 451                 // TODO: hmm this isn't called from anywhere, maybe should remove it for 2.0
 452
 453                 this.isExpandable = true;
 454                 this._setExpando(false);
 455         },
 456
 457         _onLabelFocus: function(){
 458                 // summary:
 459                 //              Called when this row is focused (possibly programatically)
 460                 //              Note that we aren't using _onFocus() builtin to dijit
 461                 //              because it's called when focus is moved to a descendant TreeNode.
 462                 // tags:
 463                 //              private
 464                 this.tree._onNodeFocus(this);
 465         },
 466
 467         setSelected: function(/*Boolean*/ selected){
 468                 // summary:
 469                 //              A Tree has a (single) currently selected node.
 470                 //              Mark that this node is/isn't that currently selected node.
 471                 // description:
 472                 //              In particular, setting a node as selected involves setting tabIndex
 473                 //              so that when user tabs to the tree, focus will go to that node (only).
 474                 this.labelNode.setAttribute("aria-selected", selected);
 475                 domClass.toggle(this.rowNode, "dijitTreeRowSelected", selected);
 476         },
 477
 478         setFocusable: function(/*Boolean*/ selected){
 479                 // summary:
 480                 //              A Tree has a (single) node that's focusable.
 481                 //              Mark that this node is/isn't that currently focsuable node.
 482                 // description:
 483                 //              In particular, setting a node as selected involves setting tabIndex
 484                 //              so that when user tabs to the tree, focus will go to that node (only).
 485
 486                 this.labelNode.setAttribute("tabIndex", selected ? "0" : "-1");
 487         },
 488
 489         _onClick: function(evt){
 490                 // summary:
 491                 //              Handler for onclick event on a node
 492                 // tags:
 493                 //              private
 494                 this.tree._onClick(this, evt);
 495         },
 496         _onDblClick: function(evt){
 497                 // summary:
 498                 //              Handler for ondblclick event on a node
 499                 // tags:
 500                 //              private
 501                 this.tree._onDblClick(this, evt);
 502         },
 503
 504         _onMouseEnter: function(evt){
 505                 // summary:
 506                 //              Handler for onmouseenter event on a node
 507                 // tags:
 508                 //              private
 509                 this.tree._onNodeMouseEnter(this, evt);
 510         },
 511
 512         _onMouseLeave: function(evt){
 513                 // summary:
 514                 //              Handler for onmouseenter event on a node
 515                 // tags:
 516                 //              private
 517                 this.tree._onNodeMouseLeave(this, evt);
 518         },
 519
 520         _setTextDirAttr: function(textDir){
 521                 if(textDir &&((this.textDir != textDir) || !this._created)){
 522                         this._set("textDir", textDir);
 523                         this.applyTextDir(this.labelNode, this.labelNode.innerText || this.labelNode.textContent || "");
 524                         array.forEach(this.getChildren(), function(childNode){
 525                                 childNode.set("textDir", textDir);
 526                         }, this);
 527                 }
 528         }
 529 });
 530
 531 var Tree = declare("dijit.Tree", [_Widget, _TemplatedMixin], {
 532         // summary:
 533         //              This widget displays hierarchical data from a store.
 534
 535         // store: [deprecated] String||dojo.data.Store
 536         //              Deprecated.  Use "model" parameter instead.
 537         //              The store to get data to display in the tree.
 538         store: null,
 539
 540         // model: dijit.Tree.model
 541         //              Interface to read tree data, get notifications of changes to tree data,
 542         //              and for handling drop operations (i.e drag and drop onto the tree)
 543         model: null,
 544
 545         // query: [deprecated] anything
 546         //              Deprecated.  User should specify query to the model directly instead.
 547         //              Specifies datastore query to return the root item or top items for the tree.
 548         query: null,
 549
 550         // label: [deprecated] String
 551         //              Deprecated.  Use dijit.tree.ForestStoreModel directly instead.
 552         //              Used in conjunction with query parameter.
 553         //              If a query is specified (rather than a root node id), and a label is also specified,
 554         //              then a fake root node is created and displayed, with this label.
 555         label: "",
 556
 557         // showRoot: [const] Boolean
 558         //              Should the root node be displayed, or hidden?
 559         showRoot: true,
 560
 561         // childrenAttr: [deprecated] String[]
 562         //              Deprecated.   This information should be specified in the model.
 563         //              One ore more attributes that holds children of a tree node
 564         childrenAttr: ["children"],
 565
 566         // paths: String[][] or Item[][]
 567         //              Full paths from rootNode to selected nodes expressed as array of items or array of ids.
 568         //              Since setting the paths may be asynchronous (because ofwaiting on dojo.data), set("paths", ...)
 569         //              returns a Deferred to indicate when the set is complete.
 570         paths: [],
 571
 572         // path: String[] or Item[]
 573         //      Backward compatible singular variant of paths.
 574         path: [],
 575
 576         // selectedItems: [readonly] Item[]
 577         //              The currently selected items in this tree.
 578         //              This property can only be set (via set('selectedItems', ...)) when that item is already
 579         //              visible in the tree.   (I.e. the tree has already been expanded to show that node.)
 580         //              Should generally use `paths` attribute to set the selected items instead.
 581         selectedItems: null,
 582
 583         // selectedItem: [readonly] Item
 584         //      Backward compatible singular variant of selectedItems.
 585         selectedItem: null,
 586
 587         // openOnClick: Boolean
 588         //              If true, clicking a folder node's label will open it, rather than calling onClick()
 589         openOnClick: false,
 590
 591         // openOnDblClick: Boolean
 592         //              If true, double-clicking a folder node's label will open it, rather than calling onDblClick()
 593         openOnDblClick: false,
 594
 595         templateString: treeTemplate,
 596
 597         // persist: Boolean
 598         //              Enables/disables use of cookies for state saving.
 599         persist: true,
 600
 601         // autoExpand: Boolean
 602         //              Fully expand the tree on load.   Overrides `persist`.
 603         autoExpand: false,
 604
 605         // dndController: [protected] Function|String
 606         //              Class to use as as the dnd controller.  Specifying this class enables DnD.
 607         //              Generally you should specify this as dijit.tree.dndSource.
 608         //      Setting of dijit.tree._dndSelector handles selection only (no actual DnD).
 609         dndController: _dndSelector,
 610
 611         // parameters to pull off of the tree and pass on to the dndController as its params
 612         dndParams: ["onDndDrop","itemCreator","onDndCancel","checkAcceptance", "checkItemAcceptance", "dragThreshold", "betweenThreshold"],
 613
 614         //declare the above items so they can be pulled from the tree's markup
 615
 616         // onDndDrop: [protected] Function
 617         //              Parameter to dndController, see `dijit.tree.dndSource.onDndDrop`.
 618         //              Generally this doesn't need to be set.
 619         onDndDrop: null,
 620
 621         /*=====
 622         itemCreator: function(nodes, target, source){
 623                 // summary:
 624                 //              Returns objects passed to `Tree.model.newItem()` based on DnD nodes
 625                 //              dropped onto the tree.   Developer must override this method to enable
 626                 //              dropping from external sources onto this Tree, unless the Tree.model's items
 627                 //              happen to look like {id: 123, name: "Apple" } with no other attributes.
 628                 // description:
 629                 //              For each node in nodes[], which came from source, create a hash of name/value
 630                 //              pairs to be passed to Tree.model.newItem().  Returns array of those hashes.
 631                 // nodes: DomNode[]
 632                 //              The DOMNodes dragged from the source container
 633                 // target: DomNode
 634                 //              The target TreeNode.rowNode
 635                 // source: dojo.dnd.Source
 636                 //              The source container the nodes were dragged from, perhaps another Tree or a plain dojo.dnd.Source
 637                 // returns: Object[]
 638                 //              Array of name/value hashes for each new item to be added to the Tree, like:
 639                 // |    [
 640                 // |            { id: 123, label: "apple", foo: "bar" },
 641                 // |            { id: 456, label: "pear", zaz: "bam" }
 642                 // |    ]
 643                 // tags:
 644                 //              extension
 645                 return [{}];
 646         },
 647         =====*/
 648         itemCreator: null,
 649
 650         // onDndCancel: [protected] Function
 651         //              Parameter to dndController, see `dijit.tree.dndSource.onDndCancel`.
 652         //              Generally this doesn't need to be set.
 653         onDndCancel: null,
 654
 655 /*=====
 656         checkAcceptance: function(source, nodes){
 657                 // summary:
 658                 //              Checks if the Tree itself can accept nodes from this source
 659                 // source: dijit.tree._dndSource
 660                 //              The source which provides items
 661                 // nodes: DOMNode[]
 662                 //              Array of DOM nodes corresponding to nodes being dropped, dijitTreeRow nodes if
 663                 //              source is a dijit.Tree.
 664                 // tags:
 665                 //              extension
 666                 return true;    // Boolean
 667         },
 668 =====*/
 669         checkAcceptance: null,
 670
 671 /*=====
 672         checkItemAcceptance: function(target, source, position){
 673                 // summary:
 674                 //              Stub function to be overridden if one wants to check for the ability to drop at the node/item level
 675                 // description:
 676                 //              In the base case, this is called to check if target can become a child of source.
 677                 //              When betweenThreshold is set, position="before" or "after" means that we
 678                 //              are asking if the source node can be dropped before/after the target node.
 679                 // target: DOMNode
 680                 //              The dijitTreeRoot DOM node inside of the TreeNode that we are dropping on to
 681                 //              Use dijit.getEnclosingWidget(target) to get the TreeNode.
 682                 // source: dijit.tree.dndSource
 683                 //              The (set of) nodes we are dropping
 684                 // position: String
 685                 //              "over", "before", or "after"
 686                 // tags:
 687                 //              extension
 688                 return true;    // Boolean
 689         },
 690 =====*/
 691         checkItemAcceptance: null,
 692
 693         // dragThreshold: Integer
 694         //              Number of pixels mouse moves before it's considered the start of a drag operation
 695         dragThreshold: 5,
 696
 697         // betweenThreshold: Integer
 698         //              Set to a positive value to allow drag and drop "between" nodes.
 699         //
 700         //              If during DnD mouse is over a (target) node but less than betweenThreshold
 701         //              pixels from the bottom edge, dropping the the dragged node will make it
 702         //              the next sibling of the target node, rather than the child.
 703         //
 704         //              Similarly, if mouse is over a target node but less that betweenThreshold
 705         //              pixels from the top edge, dropping the dragged node will make it
 706         //              the target node's previous sibling rather than the target node's child.
 707         betweenThreshold: 0,
 708
 709         // _nodePixelIndent: Integer
 710         //              Number of pixels to indent tree nodes (relative to parent node).
 711         //              Default is 19 but can be overridden by setting CSS class dijitTreeIndent
 712         //              and calling resize() or startup() on tree after it's in the DOM.
 713         _nodePixelIndent: 19,
 714
 715         _publish: function(/*String*/ topicName, /*Object*/ message){
 716                 // summary:
 717                 //              Publish a message for this widget/topic
 718                 topic.publish(this.id, lang.mixin({tree: this, event: topicName}, message || {}));      // publish
 719         },
 720
 721         postMixInProperties: function(){
 722                 this.tree = this;
 723
 724                 if(this.autoExpand){
 725                         // There's little point in saving opened/closed state of nodes for a Tree
 726                         // that initially opens all it's nodes.
 727                         this.persist = false;
 728                 }
 729
 730                 this._itemNodesMap={};
 731
 732                 if(!this.cookieName && this.id){
 733                         this.cookieName = this.id + "SaveStateCookie";
 734                 }
 735
 736                 this._loadDeferred = new Deferred();
 737
 738                 this.inherited(arguments);
 739         },
 740
 741         postCreate: function(){
 742                 this._initState();
 743
 744                 // Create glue between store and Tree, if not specified directly by user
 745                 if(!this.model){
 746                         this._store2model();
 747                 }
 748
 749                 // monitor changes to items
 750                 this.connect(this.model, "onChange", "_onItemChange");
 751                 this.connect(this.model, "onChildrenChange", "_onItemChildrenChange");
 752                 this.connect(this.model, "onDelete", "_onItemDelete");
 753
 754                 this._load();
 755
 756                 this.inherited(arguments);
 757
 758                 if(this.dndController){
 759                         if(lang.isString(this.dndController)){
 760                                 this.dndController = lang.getObject(this.dndController);
 761                         }
 762                         var params={};
 763                         for(var i=0; i<this.dndParams.length;i++){
 764                                 if(this[this.dndParams[i]]){
 765                                         params[this.dndParams[i]] = this[this.dndParams[i]];
 766                                 }
 767                         }
 768                         this.dndController = new this.dndController(this, params);
 769                 }
 770         },
 771
 772         _store2model: function(){
 773                 // summary:
 774                 //              User specified a store&query rather than model, so create model from store/query
 775                 this._v10Compat = true;
 776                 kernel.deprecated("Tree: from version 2.0, should specify a model object rather than a store/query");
 777
 778                 var modelParams = {
 779                         id: this.id + "_ForestStoreModel",
 780                         store: this.store,
 781                         query: this.query,
 782                         childrenAttrs: this.childrenAttr
 783                 };
 784
 785                 // Only override the model's mayHaveChildren() method if the user has specified an override
 786                 if(this.params.mayHaveChildren){
 787                         modelParams.mayHaveChildren = lang.hitch(this, "mayHaveChildren");
 788                 }
 789
 790                 if(this.params.getItemChildren){
 791                         modelParams.getChildren = lang.hitch(this, function(item, onComplete, onError){
 792                                 this.getItemChildren((this._v10Compat && item === this.model.root) ? null : item, onComplete, onError);
 793                         });
 794                 }
 795                 this.model = new ForestStoreModel(modelParams);
 796
 797                 // For backwards compatibility, the visibility of the root node is controlled by
 798                 // whether or not the user has specified a label
 799                 this.showRoot = Boolean(this.label);
 800         },
 801
 802         onLoad: function(){
 803                 // summary:
 804                 //              Called when tree finishes loading and expanding.
 805                 // description:
 806                 //              If persist == true the loading may encompass many levels of fetches
 807                 //              from the data store, each asynchronous.   Waits for all to finish.
 808                 // tags:
 809                 //              callback
 810         },
 811
 812         _load: function(){
 813                 // summary:
 814                 //              Initial load of the tree.
 815                 //              Load root node (possibly hidden) and it's children.
 816                 this.model.getRoot(
 817                         lang.hitch(this, function(item){
 818                                 var rn = (this.rootNode = this.tree._createTreeNode({
 819                                         item: item,
 820                                         tree: this,
 821                                         isExpandable: true,
 822                                         label: this.label || this.getLabel(item),
 823                                         textDir: this.textDir,
 824                                         indent: this.showRoot ? 0 : -1
 825                                 }));
 826                                 if(!this.showRoot){
 827                                         rn.rowNode.style.display="none";
 828                                         // if root is not visible, move tree role to the invisible
 829                                         // root node's containerNode, see #12135
 830                                         this.domNode.setAttribute("role", "presentation");
 831
 832                                         rn.labelNode.setAttribute("role", "presentation");
 833                                         rn.containerNode.setAttribute("role", "tree");
 834                                 }
 835                                 this.domNode.appendChild(rn.domNode);
 836                                 var identity = this.model.getIdentity(item);
 837                                 if(this._itemNodesMap[identity]){
 838                                         this._itemNodesMap[identity].push(rn);
 839                                 }else{
 840                                         this._itemNodesMap[identity] = [rn];
 841                                 }
 842
 843                                 rn._updateLayout();             // sets "dijitTreeIsRoot" CSS classname
 844
 845                                 // load top level children and then fire onLoad() event
 846                                 this._expandNode(rn).addCallback(lang.hitch(this, function(){
 847                                         this._loadDeferred.callback(true);
 848                                         this.onLoad();
 849                                 }));
 850                         }),
 851                         function(err){
 852                                 console.error(this, ": error loading root: ", err);
 853                         }
 854                 );
 855         },
 856
 857         getNodesByItem: function(/*Item or id*/ item){
 858                 // summary:
 859                 //              Returns all tree nodes that refer to an item
 860                 // returns:
 861                 //              Array of tree nodes that refer to passed item
 862
 863                 if(!item){ return []; }
 864                 var identity = lang.isString(item) ? item : this.model.getIdentity(item);
 865                 // return a copy so widget don't get messed up by changes to returned array
 866                 return [].concat(this._itemNodesMap[identity]);
 867         },
 868
 869         _setSelectedItemAttr: function(/*Item or id*/ item){
 870                 this.set('selectedItems', [item]);
 871         },
 872
 873         _setSelectedItemsAttr: function(/*Items or ids*/ items){
 874                 // summary:
 875                 //              Select tree nodes related to passed items.
 876                 //              WARNING: if model use multi-parented items or desired tree node isn't already loaded
 877                 //              behavior is undefined. Use set('paths', ...) instead.
 878                 var tree = this;
 879                 this._loadDeferred.addCallback( lang.hitch(this, function(){
 880                         var identities = array.map(items, function(item){
 881                                 return (!item || lang.isString(item)) ? item : tree.model.getIdentity(item);
 882                         });
 883                         var nodes = [];
 884                         array.forEach(identities, function(id){
 885                                 nodes = nodes.concat(tree._itemNodesMap[id] || []);
 886                         });
 887                         this.set('selectedNodes', nodes);
 888                 }));
 889         },
 890
 891         _setPathAttr: function(/*Item[] || String[]*/ path){
 892                 // summary:
 893                 //      Singular variant of _setPathsAttr
 894                 if(path.length){
 895                         return this.set("paths", [path]);
 896                 }else{
 897                         // Empty list is interpreted as "select nothing"
 898                         return this.set("paths", []);
 899                 }
 900         },
 901
 902         _setPathsAttr: function(/*Item[][] || String[][]*/ paths){
 903                 // summary:
 904                 //              Select the tree nodes identified by passed paths.
 905                 // paths:
 906                 //              Array of arrays of items or item id's
 907                 // returns:
 908                 //              Deferred to indicate when the set is complete
 909                 var tree = this;
 910
 911                 // We may need to wait for some nodes to expand, so setting
 912                 // each path will involve a Deferred. We bring those deferreds
 913                 // together witha DeferredList.
 914                 return new DeferredList(array.map(paths, function(path){
 915                         var d = new Deferred();
 916
 917                         // normalize path to use identity
 918                         path = array.map(path, function(item){
 919                                 return lang.isString(item) ? item : tree.model.getIdentity(item);
 920                         });
 921
 922                         if(path.length){
 923                                 // Wait for the tree to load, if it hasn't already.
 924                                 tree._loadDeferred.addCallback(function(){ selectPath(path, [tree.rootNode], d); });
 925                         }else{
 926                                 d.errback("Empty path");
 927                         }
 928                         return d;
 929                 })).addCallback(setNodes);
 930
 931                 function selectPath(path, nodes, def){
 932                         // Traverse path; the next path component should be among "nodes".
 933                         var nextPath = path.shift();
 934                         var nextNode = array.filter(nodes, function(node){
 935                                 return node.getIdentity() == nextPath;
 936                         })[0];
 937                         if(!!nextNode){
 938                                 if(path.length){
 939                                         tree._expandNode(nextNode).addCallback(function(){ selectPath(path, nextNode.getChildren(), def); });
 940                                 }else{
 941                                         //Successfully reached the end of this path
 942                                         def.callback(nextNode);
 943                                 }
 944                         }else{
 945                                 def.errback("Could not expand path at " + nextPath);
 946                         }
 947                 }
 948
 949                 function setNodes(newNodes){
 950                         //After all expansion is finished, set the selection to
 951                         //the set of nodes successfully found.
 952                         tree.set("selectedNodes", array.map(
 953                                 array.filter(newNodes,function(x){return x[0];}),
 954                                 function(x){return x[1];}));
 955                 }
 956         },
 957
 958         _setSelectedNodeAttr: function(node){
 959                 this.set('selectedNodes', [node]);
 960         },
 961         _setSelectedNodesAttr: function(nodes){
 962                 this._loadDeferred.addCallback( lang.hitch(this, function(){
 963                         this.dndController.setSelection(nodes);
 964                 }));
 965         },
 966
 967
 968         ////////////// Data store related functions //////////////////////
 969         // These just get passed to the model; they are here for back-compat
 970
 971         mayHaveChildren: function(/*dojo.data.Item*/ /*===== item =====*/){
 972                 // summary:
 973                 //              Deprecated.   This should be specified on the model itself.
 974                 //
 975                 //              Overridable function to tell if an item has or may have children.
 976                 //              Controls whether or not +/- expando icon is shown.
 977                 //              (For efficiency reasons we may not want to check if an element actually
 978                 //              has children until user clicks the expando node)
 979                 // tags:
 980                 //              deprecated
 981         },
 982
 983         getItemChildren: function(/*===== parentItem, onComplete =====*/){
 984                 // summary:
 985                 //              Deprecated.   This should be specified on the model itself.
 986                 //
 987                 //              Overridable function that return array of child items of given parent item,
 988                 //              or if parentItem==null then return top items in tree
 989                 // tags:
 990                 //              deprecated
 991         },
 992
 993         ///////////////////////////////////////////////////////
 994         // Functions for converting an item to a TreeNode
 995         getLabel: function(/*dojo.data.Item*/ item){
 996                 // summary:
 997                 //              Overridable function to get the label for a tree node (given the item)
 998                 // tags:
 999                 //              extension
1000                 return this.model.getLabel(item);       // String
1001         },
1002
1003         getIconClass: function(/*dojo.data.Item*/ item, /*Boolean*/ opened){
1004                 // summary:
1005                 //              Overridable function to return CSS class name to display icon
1006                 // tags:
1007                 //              extension
1008                 return (!item || this.model.mayHaveChildren(item)) ? (opened ? "dijitFolderOpened" : "dijitFolderClosed") : "dijitLeaf"
1009         },
1010
1011         getLabelClass: function(/*===== item, opened =====*/){
1012                 // summary:
1013                 //              Overridable function to return CSS class name to display label
1014                 // item: dojo.data.Item
1015                 // opened: Boolean
1016                 // returns: String
1017                 //              CSS class name
1018                 // tags:
1019                 //              extension
1020         },
1021
1022         getRowClass: function(/*===== item, opened =====*/){
1023                 // summary:
1024                 //              Overridable function to return CSS class name to display row
1025                 // item: dojo.data.Item
1026                 // opened: Boolean
1027                 // returns: String
1028                 //              CSS class name
1029                 // tags:
1030                 //              extension
1031         },
1032
1033         getIconStyle: function(/*===== item, opened =====*/){
1034                 // summary:
1035                 //              Overridable function to return CSS styles to display icon
1036                 // item: dojo.data.Item
1037                 // opened: Boolean
1038                 // returns: Object
1039                 //              Object suitable for input to dojo.style() like {backgroundImage: "url(...)"}
1040                 // tags:
1041                 //              extension
1042         },
1043
1044         getLabelStyle: function(/*===== item, opened =====*/){
1045                 // summary:
1046                 //              Overridable function to return CSS styles to display label
1047                 // item: dojo.data.Item
1048                 // opened: Boolean
1049                 // returns:
1050                 //              Object suitable for input to dojo.style() like {color: "red", background: "green"}
1051                 // tags:
1052                 //              extension
1053         },
1054
1055         getRowStyle: function(/*===== item, opened =====*/){
1056                 // summary:
1057                 //              Overridable function to return CSS styles to display row
1058                 // item: dojo.data.Item
1059                 // opened: Boolean
1060                 // returns:
1061                 //              Object suitable for input to dojo.style() like {background-color: "#bbb"}
1062                 // tags:
1063                 //              extension
1064         },
1065
1066         getTooltip: function(/*dojo.data.Item*/ /*===== item =====*/){
1067                 // summary:
1068                 //              Overridable function to get the tooltip for a tree node (given the item)
1069                 // tags:
1070                 //              extension
1071                 return "";      // String
1072         },
1073
1074         /////////// Keyboard and Mouse handlers ////////////////////
1075
1076         _onKeyPress: function(/*Event*/ e){
1077                 // summary:
1078                 //              Translates keypress events into commands for the controller
1079                 if(e.altKey){ return; }
1080                 var treeNode = registry.getEnclosingWidget(e.target);
1081                 if(!treeNode){ return; }
1082
1083                 var key = e.charOrCode;
1084                 if(typeof key == "string" && key != " "){       // handle printables (letter navigation)
1085                         // Check for key navigation.
1086                         if(!e.altKey && !e.ctrlKey && !e.shiftKey && !e.metaKey){
1087                                 this._onLetterKeyNav( { node: treeNode, key: key.toLowerCase() } );
1088                                 event.stop(e);
1089                         }
1090                 }else{  // handle non-printables (arrow keys)
1091                         // clear record of recent printables (being saved for multi-char letter navigation),
1092                         // because "a", down-arrow, "b" shouldn't search for "ab"
1093                         if(this._curSearch){
1094                                 clearTimeout(this._curSearch.timer);
1095                                 delete this._curSearch;
1096                         }
1097
1098                         var map = this._keyHandlerMap;
1099                         if(!map){
1100                                 // setup table mapping keys to events
1101                                 map = {};
1102                                 map[keys.ENTER]="_onEnterKey";
1103                                 //On WebKit based browsers, the combination ctrl-enter
1104                                 //does not get passed through. To allow accessible
1105                                 //multi-select on those browsers, the space key is
1106                                 //also used for selection.
1107                                 map[keys.SPACE]= map[" "] = "_onEnterKey";
1108                                 map[this.isLeftToRight() ? keys.LEFT_ARROW : keys.RIGHT_ARROW]="_onLeftArrow";
1109                                 map[this.isLeftToRight() ? keys.RIGHT_ARROW : keys.LEFT_ARROW]="_onRightArrow";
1110                                 map[keys.UP_ARROW]="_onUpArrow";
1111                                 map[keys.DOWN_ARROW]="_onDownArrow";
1112                                 map[keys.HOME]="_onHomeKey";
1113                                 map[keys.END]="_onEndKey";
1114                                 this._keyHandlerMap = map;
1115                         }
1116                         if(this._keyHandlerMap[key]){
1117                                 this[this._keyHandlerMap[key]]( { node: treeNode, item: treeNode.item, evt: e } );
1118                                 event.stop(e);
1119                         }
1120                 }
1121         },
1122
1123         _onEnterKey: function(/*Object*/ message){
1124                 this._publish("execute", { item: message.item, node: message.node } );
1125                 this.dndController.userSelect(message.node, connect.isCopyKey( message.evt ), message.evt.shiftKey);
1126                 this.onClick(message.item, message.node, message.evt);
1127         },
1128
1129         _onDownArrow: function(/*Object*/ message){
1130                 // summary:
1131                 //              down arrow pressed; get next visible node, set focus there
1132                 var node = this._getNextNode(message.node);
1133                 if(node && node.isTreeNode){
1134                         this.focusNode(node);
1135                 }
1136         },
1137
1138         _onUpArrow: function(/*Object*/ message){
1139                 // summary:
1140                 //              Up arrow pressed; move to previous visible node
1141
1142                 var node = message.node;
1143
1144                 // if younger siblings
1145                 var previousSibling = node.getPreviousSibling();
1146                 if(previousSibling){
1147                         node = previousSibling;
1148                         // if the previous node is expanded, dive in deep
1149                         while(node.isExpandable && node.isExpanded && node.hasChildren()){
1150                                 // move to the last child
1151                                 var children = node.getChildren();
1152                                 node = children[children.length-1];
1153                         }
1154                 }else{
1155                         // if this is the first child, return the parent
1156                         // unless the parent is the root of a tree with a hidden root
1157                         var parent = node.getParent();
1158                         if(!(!this.showRoot && parent === this.rootNode)){
1159                                 node = parent;
1160                         }
1161                 }
1162
1163                 if(node && node.isTreeNode){
1164                         this.focusNode(node);
1165                 }
1166         },
1167
1168         _onRightArrow: function(/*Object*/ message){
1169                 // summary:
1170                 //              Right arrow pressed; go to child node
1171                 var node = message.node;
1172
1173                 // if not expanded, expand, else move to 1st child
1174                 if(node.isExpandable && !node.isExpanded){
1175                         this._expandNode(node);
1176                 }else if(node.hasChildren()){
1177                         node = node.getChildren()[0];
1178                         if(node && node.isTreeNode){
1179                                 this.focusNode(node);
1180                         }
1181                 }
1182         },
1183
1184         _onLeftArrow: function(/*Object*/ message){
1185                 // summary:
1186                 //              Left arrow pressed.
1187                 //              If not collapsed, collapse, else move to parent.
1188
1189                 var node = message.node;
1190
1191                 if(node.isExpandable && node.isExpanded){
1192                         this._collapseNode(node);
1193                 }else{
1194                         var parent = node.getParent();
1195                         if(parent && parent.isTreeNode && !(!this.showRoot && parent === this.rootNode)){
1196                                 this.focusNode(parent);
1197                         }
1198                 }
1199         },
1200
1201         _onHomeKey: function(){
1202                 // summary:
1203                 //              Home key pressed; get first visible node, and set focus there
1204                 var node = this._getRootOrFirstNode();
1205                 if(node){
1206                         this.focusNode(node);
1207                 }
1208         },
1209
1210         _onEndKey: function(){
1211                 // summary:
1212                 //              End key pressed; go to last visible node.
1213
1214                 var node = this.rootNode;
1215                 while(node.isExpanded){
1216                         var c = node.getChildren();
1217                         node = c[c.length - 1];
1218                 }
1219
1220                 if(node && node.isTreeNode){
1221                         this.focusNode(node);
1222                 }
1223         },
1224
1225         // multiCharSearchDuration: Number
1226         //              If multiple characters are typed where each keystroke happens within
1227         //              multiCharSearchDuration of the previous keystroke,
1228         //              search for nodes matching all the keystrokes.
1229         //
1230         //              For example, typing "ab" will search for entries starting with
1231         //              "ab" unless the delay between "a" and "b" is greater than multiCharSearchDuration.
1232         multiCharSearchDuration: 250,
1233
1234         _onLetterKeyNav: function(message){
1235                 // summary:
1236                 //              Called when user presses a prinatable key; search for node starting with recently typed letters.
1237                 // message: Object
1238                 //              Like { node: TreeNode, key: 'a' } where key is the key the user pressed.
1239
1240                 // Branch depending on whether this key starts a new search, or modifies an existing search
1241                 var cs = this._curSearch;
1242                 if(cs){
1243                         // We are continuing a search.  Ex: user has pressed 'a', and now has pressed
1244                         // 'b', so we want to search for nodes starting w/"ab".
1245                         cs.pattern = cs.pattern + message.key;
1246                         clearTimeout(cs.timer);
1247                 }else{
1248                         // We are starting a new search
1249                         cs = this._curSearch = {
1250                                         pattern: message.key,
1251                                         startNode: message.node
1252                         };
1253                 }
1254
1255                 // set/reset timer to forget recent keystrokes
1256                 var self = this;
1257                 cs.timer = setTimeout(function(){
1258                         delete self._curSearch;
1259                 }, this.multiCharSearchDuration);
1260
1261                 // Navigate to TreeNode matching keystrokes [entered so far].
1262                 var node = cs.startNode;
1263                 do{
1264                         node = this._getNextNode(node);
1265                         //check for last node, jump to first node if necessary
1266                         if(!node){
1267                                 node = this._getRootOrFirstNode();
1268                         }
1269                 }while(node !== cs.startNode && (node.label.toLowerCase().substr(0, cs.pattern.length) != cs.pattern));
1270                 if(node && node.isTreeNode){
1271                         // no need to set focus if back where we started
1272                         if(node !== cs.startNode){
1273                                 this.focusNode(node);
1274                         }
1275                 }
1276         },
1277
1278         isExpandoNode: function(node, widget){
1279                 // summary:
1280                 //              check whether a dom node is the expandoNode for a particular TreeNode widget
1281                 return dom.isDescendant(node, widget.expandoNode);
1282         },
1283         _onClick: function(/*TreeNode*/ nodeWidget, /*Event*/ e){
1284                 // summary:
1285                 //              Translates click events into commands for the controller to process
1286
1287                 var domElement = e.target,
1288                         isExpandoClick = this.isExpandoNode(domElement, nodeWidget);
1289
1290                 if( (this.openOnClick && nodeWidget.isExpandable) || isExpandoClick ){
1291                         // expando node was clicked, or label of a folder node was clicked; open it
1292                         if(nodeWidget.isExpandable){
1293                                 this._onExpandoClick({node:nodeWidget});
1294                         }
1295                 }else{
1296                         this._publish("execute", { item: nodeWidget.item, node: nodeWidget, evt: e } );
1297                         this.onClick(nodeWidget.item, nodeWidget, e);
1298                         this.focusNode(nodeWidget);
1299                 }
1300                 event.stop(e);
1301         },
1302         _onDblClick: function(/*TreeNode*/ nodeWidget, /*Event*/ e){
1303                 // summary:
1304                 //              Translates double-click events into commands for the controller to process
1305
1306                 var domElement = e.target,
1307                         isExpandoClick = (domElement == nodeWidget.expandoNode || domElement == nodeWidget.expandoNodeText);
1308
1309                 if( (this.openOnDblClick && nodeWidget.isExpandable) ||isExpandoClick ){
1310                         // expando node was clicked, or label of a folder node was clicked; open it
1311                         if(nodeWidget.isExpandable){
1312                                 this._onExpandoClick({node:nodeWidget});
1313                         }
1314                 }else{
1315                         this._publish("execute", { item: nodeWidget.item, node: nodeWidget, evt: e } );
1316                         this.onDblClick(nodeWidget.item, nodeWidget, e);
1317                         this.focusNode(nodeWidget);
1318                 }
1319                 event.stop(e);
1320         },
1321
1322         _onExpandoClick: function(/*Object*/ message){
1323                 // summary:
1324                 //              User clicked the +/- icon; expand or collapse my children.
1325                 var node = message.node;
1326
1327                 // If we are collapsing, we might be hiding the currently focused node.
1328                 // Also, clicking the expando node might have erased focus from the current node.
1329                 // For simplicity's sake just focus on the node with the expando.
1330                 this.focusNode(node);
1331
1332                 if(node.isExpanded){
1333                         this._collapseNode(node);
1334                 }else{
1335                         this._expandNode(node);
1336                 }
1337         },
1338
1339         onClick: function(/*===== item, node, evt =====*/){
1340                 // summary:
1341                 //              Callback when a tree node is clicked
1342                 // item: dojo.data.Item
1343                 // node: TreeNode
1344                 // evt: Event
1345                 // tags:
1346                 //              callback
1347         },
1348         onDblClick: function(/*===== item, node, evt =====*/){
1349                 // summary:
1350                 //              Callback when a tree node is double-clicked
1351                 // item: dojo.data.Item
1352                 // node: TreeNode
1353                 // evt: Event
1354                 // tags:
1355                 //              callback
1356         },
1357         onOpen: function(/*===== item, node =====*/){
1358                 // summary:
1359                 //              Callback when a node is opened
1360                 // item: dojo.data.Item
1361                 // node: TreeNode
1362                 // tags:
1363                 //              callback
1364         },
1365         onClose: function(/*===== item, node =====*/){
1366                 // summary:
1367                 //              Callback when a node is closed
1368                 // item: dojo.data.Item
1369                 // node: TreeNode
1370                 // tags:
1371                 //              callback
1372         },
1373
1374         _getNextNode: function(node){
1375                 // summary:
1376                 //              Get next visible node
1377
1378                 if(node.isExpandable && node.isExpanded && node.hasChildren()){
1379                         // if this is an expanded node, get the first child
1380                         return node.getChildren()[0];           // _TreeNode
1381                 }else{
1382                         // find a parent node with a sibling
1383                         while(node && node.isTreeNode){
1384                                 var returnNode = node.getNextSibling();
1385                                 if(returnNode){
1386                                         return returnNode;              // _TreeNode
1387                                 }
1388                                 node = node.getParent();
1389                         }
1390                         return null;
1391                 }
1392         },
1393
1394         _getRootOrFirstNode: function(){
1395                 // summary:
1396                 //              Get first visible node
1397                 return this.showRoot ? this.rootNode : this.rootNode.getChildren()[0];
1398         },
1399
1400         _collapseNode: function(/*_TreeNode*/ node){
1401                 // summary:
1402                 //              Called when the user has requested to collapse the node
1403
1404                 if(node._expandNodeDeferred){
1405                         delete node._expandNodeDeferred;
1406                 }
1407
1408                 if(node.isExpandable){
1409                         if(node.state == "LOADING"){
1410                                 // ignore clicks while we are in the process of loading data
1411                                 return;
1412                         }
1413
1414                         node.collapse();
1415                         this.onClose(node.item, node);
1416
1417                         this._state(node, false);
1418                 }
1419         },
1420
1421         _expandNode: function(/*_TreeNode*/ node, /*Boolean?*/ recursive){
1422                 // summary:
1423                 //              Called when the user has requested to expand the node
1424                 // recursive:
1425                 //              Internal flag used when _expandNode() calls itself, don't set.
1426                 // returns:
1427                 //              Deferred that fires when the node is loaded and opened and (if persist=true) all it's descendants
1428                 //              that were previously opened too
1429
1430                 if(node._expandNodeDeferred && !recursive){
1431                         // there's already an expand in progress (or completed), so just return
1432                         return node._expandNodeDeferred;        // dojo.Deferred
1433                 }
1434
1435                 var model = this.model,
1436                         item = node.item,
1437                         _this = this;
1438
1439                 switch(node.state){
1440                         case "UNCHECKED":
1441                                 // need to load all the children, and then expand
1442                                 node.markProcessing();
1443
1444                                 // Setup deferred to signal when the load and expand are finished.
1445                                 // Save that deferred in this._expandDeferred as a flag that operation is in progress.
1446                                 var def = (node._expandNodeDeferred = new Deferred());
1447
1448                                 // Get the children
1449                                 model.getChildren(
1450                                         item,
1451                                         function(items){
1452                                                 node.unmarkProcessing();
1453
1454                                                 // Display the children and also start expanding any children that were previously expanded
1455                                                 // (if this.persist == true).   The returned Deferred will fire when those expansions finish.
1456                                                 var scid = node.setChildItems(items);
1457
1458                                                 // Call _expandNode() again but this time it will just to do the animation (default branch).
1459                                                 // The returned Deferred will fire when the animation completes.
1460                                                 // TODO: seems like I can avoid recursion and just use a deferred to sequence the events?
1461                                                 var ed = _this._expandNode(node, true);
1462
1463                                                 // After the above two tasks (setChildItems() and recursive _expandNode()) finish,
1464                                                 // signal that I am done.
1465                                                 scid.addCallback(function(){
1466                                                         ed.addCallback(function(){
1467                                                                 def.callback();
1468                                                         })
1469                                                 });
1470                                         },
1471                                         function(err){
1472                                                 console.error(_this, ": error loading root children: ", err);
1473                                         }
1474                                 );
1475                                 break;
1476
1477                         default:        // "LOADED"
1478                                 // data is already loaded; just expand node
1479                                 def = (node._expandNodeDeferred = node.expand());
1480
1481                                 this.onOpen(node.item, node);
1482
1483                                 this._state(node, true);
1484                 }
1485
1486                 return def;     // dojo.Deferred
1487         },
1488
1489         ////////////////// Miscellaneous functions ////////////////
1490
1491         focusNode: function(/* _tree.Node */ node){
1492                 // summary:
1493                 //              Focus on the specified node (which must be visible)
1494                 // tags:
1495                 //              protected
1496
1497                 // set focus so that the label will be voiced using screen readers
1498                 focus.focus(node.labelNode);
1499         },
1500
1501         _onNodeFocus: function(/*dijit._Widget*/ node){
1502                 // summary:
1503                 //              Called when a TreeNode gets focus, either by user clicking
1504                 //              it, or programatically by arrow key handling code.
1505                 // description:
1506                 //              It marks that the current node is the selected one, and the previously
1507                 //              selected node no longer is.
1508
1509                 if(node && node != this.lastFocused){
1510                         if(this.lastFocused && !this.lastFocused._destroyed){
1511                                 // mark that the previously focsable node is no longer focusable
1512                                 this.lastFocused.setFocusable(false);
1513                         }
1514
1515                         // mark that the new node is the currently selected one
1516                         node.setFocusable(true);
1517                         this.lastFocused = node;
1518                 }
1519         },
1520
1521         _onNodeMouseEnter: function(/*dijit._Widget*/ /*===== node =====*/){
1522                 // summary:
1523                 //              Called when mouse is over a node (onmouseenter event),
1524                 //              this is monitored by the DND code
1525         },
1526
1527         _onNodeMouseLeave: function(/*dijit._Widget*/ /*===== node =====*/){
1528                 // summary:
1529                 //              Called when mouse leaves a node (onmouseleave event),
1530                 //              this is monitored by the DND code
1531         },
1532
1533         //////////////// Events from the model //////////////////////////
1534
1535         _onItemChange: function(/*Item*/ item){
1536                 // summary:
1537                 //              Processes notification of a change to an item's scalar values like label
1538                 var model = this.model,
1539                         identity = model.getIdentity(item),
1540                         nodes = this._itemNodesMap[identity];
1541
1542                 if(nodes){
1543                         var label = this.getLabel(item),
1544                                 tooltip = this.getTooltip(item);
1545                         array.forEach(nodes, function(node){
1546                                 node.set({
1547                                         item: item,             // theoretically could be new JS Object representing same item
1548                                         label: label,
1549                                         tooltip: tooltip
1550                                 });
1551                                 node._updateItemClasses(item);
1552                         });
1553                 }
1554         },
1555
1556         _onItemChildrenChange: function(/*dojo.data.Item*/ parent, /*dojo.data.Item[]*/ newChildrenList){
1557                 // summary:
1558                 //              Processes notification of a change to an item's children
1559                 var model = this.model,
1560                         identity = model.getIdentity(parent),
1561                         parentNodes = this._itemNodesMap[identity];
1562
1563                 if(parentNodes){
1564                         array.forEach(parentNodes,function(parentNode){
1565                                 parentNode.setChildItems(newChildrenList);
1566                         });
1567                 }
1568         },
1569
1570         _onItemDelete: function(/*Item*/ item){
1571                 // summary:
1572                 //              Processes notification of a deletion of an item
1573                 var model = this.model,
1574                         identity = model.getIdentity(item),
1575                         nodes = this._itemNodesMap[identity];
1576
1577                 if(nodes){
1578                         array.forEach(nodes,function(node){
1579                                 // Remove node from set of selected nodes (if it's selected)
1580                                 this.dndController.removeTreeNode(node);
1581
1582                                 var parent = node.getParent();
1583                                 if(parent){
1584                                         // if node has not already been orphaned from a _onSetItem(parent, "children", ..) call...
1585                                         parent.removeChild(node);
1586                                 }
1587                                 node.destroyRecursive();
1588                         }, this);
1589                         delete this._itemNodesMap[identity];
1590                 }
1591         },
1592
1593         /////////////// Miscellaneous funcs
1594
1595         _initState: function(){
1596                 // summary:
1597                 //              Load in which nodes should be opened automatically
1598                 this._openedNodes = {};
1599                 if(this.persist && this.cookieName){
1600                         var oreo = cookie(this.cookieName);
1601                         if(oreo){
1602                                 array.forEach(oreo.split(','), function(item){
1603                                         this._openedNodes[item] = true;
1604                                 }, this);
1605                         }
1606                 }
1607         },
1608         _state: function(node, expanded){
1609                 // summary:
1610                 //              Query or set expanded state for an node
1611                 if(!this.persist){
1612                         return false;
1613                 }
1614                 var path = array.map(node.getTreePath(), function(item){
1615                                 return this.model.getIdentity(item);
1616                         }, this).join("/");
1617                 if(arguments.length === 1){
1618                         return this._openedNodes[path];
1619                 }else{
1620                         if(expanded){
1621                                 this._openedNodes[path] = true;
1622                         }else{
1623                                 delete this._openedNodes[path];
1624                         }
1625                         var ary = [];
1626                         for(var id in this._openedNodes){
1627                                 ary.push(id);
1628                         }
1629                         cookie(this.cookieName, ary.join(","), {expires:365});
1630                 }
1631         },
1632
1633         destroy: function(){
1634                 if(this._curSearch){
1635                         clearTimeout(this._curSearch.timer);
1636                         delete this._curSearch;
1637                 }
1638                 if(this.rootNode){
1639                         this.rootNode.destroyRecursive();
1640                 }
1641                 if(this.dndController && !lang.isString(this.dndController)){
1642                         this.dndController.destroy();
1643                 }
1644                 this.rootNode = null;
1645                 this.inherited(arguments);
1646         },
1647
1648         destroyRecursive: function(){
1649                 // A tree is treated as a leaf, not as a node with children (like a grid),
1650                 // but defining destroyRecursive for back-compat.
1651                 this.destroy();
1652         },
1653
1654         resize: function(changeSize){
1655                 if(changeSize){
1656                         domGeometry.setMarginBox(this.domNode, changeSize);
1657                 }
1658
1659                 // The only JS sizing involved w/tree is the indentation, which is specified
1660                 // in CSS and read in through this dummy indentDetector node (tree must be
1661                 // visible and attached to the DOM to read this)
1662                 this._nodePixelIndent = domGeometry.position(this.tree.indentDetector).w;
1663
1664                 if(this.tree.rootNode){
1665                         // If tree has already loaded, then reset indent for all the nodes
1666                         this.tree.rootNode.set('indent', this.showRoot ? 0 : -1);
1667                 }
1668         },
1669
1670         _createTreeNode: function(/*Object*/ args){
1671                 // summary:
1672                 //              creates a TreeNode
1673                 // description:
1674                 //              Developers can override this method to define their own TreeNode class;
1675                 //              However it will probably be removed in a future release in favor of a way
1676                 //              of just specifying a widget for the label, rather than one that contains
1677                 //              the children too.
1678                 return new TreeNode(args);
1679         },
1680
1681         _setTextDirAttr: function(textDir){
1682                 if(textDir && this.textDir!= textDir){
1683                         this._set("textDir",textDir);
1684                         this.rootNode.set("textDir", textDir);
1685                 }
1686         }
1687 });
1688
1689 Tree._TreeNode = TreeNode;      // for monkey patching
1690
1691 return Tree;
1692 });