TreeNode - Dynamically Modifiable Tree Widget

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

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


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

See Tree.


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

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

``dojo.widget.HtmlWidget``


Properties also for HTML
--------------------------------------

``title``:
    Main label for the node; typically text, can be HTML.

``childIconSrc``:
    If specified, a string URL pointing to the icon for the node.

``afterLabel``:
    String containing HTML to be rendered following the node title.

``isFolder``:
    If this is set to true, the node will have an expander even if it
    has no children.   If it does not have a custom childIconSrc, it
    will display with a "folder" icon.  Currently only effective at
    initialization. (?)

``objectId``:
    String identifying the represented object, for access from JavaScript.


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

``tree``:
    Object. The containing tree.

``isTree``:
    ``False.``

``isTreeNode``:
    True.

``isExpanded``:
     Indicates whether the node is expanded.  Always false if there are no children.

``childIconFolderSrc``:
    Default URL, used for nodes that are folders if no childIconSrc is specified.

``childIconDocumentSrc``:
    Default URL, used for nodes that are not folders if no childIconSrc is specified.

``object``:
    Available to store application data, an object representing the
    represented object.


Initialization Protocol
-----------------------

This widget does not define any methods of the initialization
protocol, but finishes initializing a node when it is first attached
to a tree, either in the tree's ``postCreate`` method or in
``addChild``.


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

``addChild(child, index)``:

Adds the given child to this node.  You can apply this method to a
node removed from another tree or a newly-created node, and this will
adjust its display and tree relationships.  

    ``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.

``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.

``setFolder``:
    Asserts that this tree node is a folder, regardless of whether it
    has children currently or not.
    
``expand``:
    Show any children and mark the node as expanded.

``collapse``:
    Hide any children and mark the node as not expanded.

``edit``:
    Takes an object, which it treats as a collection of property-value
    mappings.  Updates both widget and DOM state for properties:


Events
-------

``onTreeClick``:
    Called when the expander icon is clicked.  Event properties are
    ``source``: the node; ``event`` the triggering click event.
    Also publishes to tree.eventNames.treeClick.

``onIconClick``:
    Called when the node's icon is clicked.  Event properties are
    ``source``: the node; ``event`` the triggering click event.
    Also publishes to tree.eventNames.iconClick.

``onTitleClick``:
    Called when the node's title is clicked.  Event properties are
    ``source``: the node; ``event`` the triggering click event.
    Also publishes to tree.eventNames.titleClick.

Topics
------

The events above automatically publish to topics.  Also when the node
is attached to a tree for the first time, it publishes an event with
property ``source`` to tree.eventNames.nodeCreate.