.. title:: dojo.widget.Tree -- The Dojo Manual

Name
===============================================================================

dojo.widget.Tree - Dynamically Modifiable Tree Widget


Summary and Overview
===============================================================================

This class, together with TreeNode, TreeSelector, and
TreeController, provide a tree widget with nodes that can be
dynamically added, modified, and deleted.


Usage
===============================================================================

The Tree widget displays itself through its child nodes.  In the
API it also functions as a root node.

::

    dojo.require("dojo.widget.Tree");
    dojo.require("dojo.widget.TreeNode");
    dojo.require("dojo.widget.TreeController");
    dojo.require("dojo.widget.TreeSelector");

    var controller = dojo.widget.createWidget("TreeController",
					      {id: "controller"});

    var tree = dojo.widget.createWidget("Tree", {});
    for (var i=0; i<3; i++) {
      var node = dojo.widget.createWidget("TreeNode",
					  {title: "node"+i});
      tree.addChild(node);
    }


API Reference
===============================================================================

Inherits From
--------------------------------------

``dojo.widget.HtmlWidget``


Initialization Properties
--------------------------------

These are not widget properties, but you can pass them through markup
or to dojo.widget.createWidget.

``controller``:
    Widget ID of an TreeController that adds additional
    functionality to this tree through event handlers.  During
    initialization, the widget's ``subscribeTree`` method will be
    called with this tree as its argument.

``selector``:
    Optional widget ID of an TreeSelector.  If none is
    specified, initialization will build one and assign it to the
    ``selector`` property of this tree.  The default selector only
    supplies a ``selectedNode`` property for use by the tree's
    controller.  I think this object's purpose is to allow one
    selected node for an entire set of trees.


Properties
---------------------------------------

``tree``:
    Object. This tree.  Also used by ``TreeNode``.

``isExpanded``:
    Boolean. ``true``.  The tree root node is considered to be always expanded.

``tree``:
    Object. This tree.  Also used by ``TreeNode``.

``isTree``:
    Boolean. Always ``true``.

``showGrid``:
    Boolean, default:``true``.  Controls display of grid lines
    connecting tree nodes.  Settable only on creation.

``showRootGrid``:
    Boolean, default: ``true``.  Controls display of grid lines to
    top-level tree nodes.  Settable only on creation.

``tree``:
    Object. This tree.  Also used by ``TreeNode``.

``selector``:
    Object.  Associated ``TreeSelector``.  Created automatically
    by default.

Methods
---------------------------------------

``removeChild(child)``:

    Removes the given child from this tree.

    ``child``:
        TreeNode.  It must be a direct child of the
        tree.  Removes the child and its display.

    *return*:
        Unspecified.

``addChild(child, index)``:

Adds the given child to this tree.

    ``child``:
        TreeNode.  It must not be currently attached to a tree.

    ``index``:
        Integer, optional.  Index for insertion of the child.  If not
        specified, appends the child to the list of children.

``initialize``:
    Initialization protocol.  Interprets arguments ``selector`` and
    ``controller``, etc..  TBD.

``postCreate``: 
    Completes initialization of all tree nodes attached to this tree.

``getInfo``:
    Returns an object with properties ``widgetId``, this tree's widget
    ID; and ``objectId``, this tree's ``objectId`` property.  Overridable.