# Yahoo! UI Library

### TreeView Widget 2.5.0

Yahoo! UI Library > treeview > YAHOO.widget.TreeView

Show Private Show Protected

## Class YAHOO.widget.TreeView - uses YAHOO.util.EventProvider

Contains the tree view state data and the root node.

### Constructor

YAHOO.widget.TreeView `( id )`

Parameters:
  `id <string|HTMLElement>` The id of the element, or the element itself that the tree will be inserted into.

### Properties

#### _animCount `- private int`

The current number of animations that are executing

#### _collapseAnim `- private string`

The animation to use for collapsing children, if any

#### _el `- private object`

The host element for this tree

#### _expandAnim `- private string`

The animation to use for expanding children, if any

#### _nodes `- private Node[]`

Flat collection of all nodes in this tree. This is a sparse array, so the length property can't be relied upon for a node count for the tree.

#### id `- String`

The id of tree container element

#### locked `- boolean`

We lock the tree control while waiting for the dynamic loader to return

#### maxAnim `- int`

The maximum number of animations to run at one time.

#### YAHOO.widget.TreeView.counter `- private static object`

Counter for generating a new unique element id

#### YAHOO.widget.TreeView.nodeCount `- static int`

Running count of all nodes created in all trees. This is used to provide unique identifies for all nodes. Deleting nodes does not change the nodeCount.

#### YAHOO.widget.TreeView.trees `- private static Array`

Global cache of tree instances

#### Properties inherited from YAHOO.util.EventProvider:

`__yui_events, __yui_subscribers`

### Methods

#### _deleteNode

`private void _deleteNode ( )`
Deletes the node and recurses children

Returns: `void`

#### _removeChildren_animComplete

`private void _removeChildren_animComplete ( o )`
wait until the animation is complete before deleting to avoid javascript errors

Parameters:
  `o <object>` the custom event payload

Returns: `void`

#### animateCollapse

`boolean animateCollapse ( el , node )`
Perform the collapse animation if configured, or just show the element if not configured or too many animations are in progress

Parameters:
  `el <HTMLElement>` the element to animate
  `node <YAHOO.util.Node>` the node that was expanded

Returns: `boolean`
  true if animation could be invoked, false otherwise

#### animateExpand

`boolean animateExpand ( el , node )`
Perform the expand animation if configured, or just show the element if not configured or too many animations are in progress

Parameters:
  `el <HTMLElement>` the element to animate
  `node <YAHOO.util.Node>` the node that was expanded

Returns: `boolean`
  true if animation could be invoked, false otherwise

#### collapseAll

`void collapseAll ( )`
Collapses all expanded child nodes in the entire tree.

Returns: `void`

#### collapseComplete

`void collapseComplete ( )`
Function executed when the collapse animation completes

Returns: `void`

#### draw

`void draw ( )`
Renders the tree boilerplate and visible nodes

Returns: `void`

#### expandAll

`void expandAll ( )`
Expands all child nodes. Note: this conflicts with the "multiExpand" node property. If expand all is called in a tree with nodes that do not allow multiple siblings to be displayed, only the last sibling will be expanded.

Returns: `void`

#### expandComplete

`void expandComplete ( )`
Function executed when the expand animation completes

Returns: `void`

#### generateId

`private void generateId ( )`
Generates an unique id for an element if it doesn't yet have one

Returns: `void`

#### getEl

`HTMLElement getEl ( )`
Returns the tree's host element

Returns: `HTMLElement`
  the host element

#### getNodeByElement

`YAHOO.widget.Node getNodeByElement ( the )`
Returns the treeview node reference for an anscestor element of the node, or null if it is not contained within any node in this tree.

Parameters:
  `the <HTMLElement>` element to test

Returns: `YAHOO.widget.Node`
  a node reference or null

#### getNodeByIndex

`Node getNodeByIndex ( nodeIndex )`
Returns a node in the tree that has the specified index (this index is created internally, so this function probably will only be used in html generated for a given node.)

Parameters:
  `nodeIndex <int>` the index of the node wanted

Returns: `Node`
  the node with index=nodeIndex, null if no match

#### getNodeByProperty

`Node getNodeByProperty ( property , value )`
Returns a node that has a matching property and value in the data object that was passed into its constructor.

Parameters:
  `property <object>` the property to search (usually a string)
  `value <object>` the value we want to find (usuall an int or string)

Returns: `Node`
  the matching node, null if no match

#### getNodesByProperty

`Array getNodesByProperty ( property , value )`
Returns a collection of nodes that have a matching property and value in the data object that was passed into its constructor.

Parameters:
  `property <object>` the property to search (usually a string)
  `value <object>` the value we want to find (usuall an int or string)

Returns: `Array`
  the matching collection of nodes, null if no match

#### getRoot

`Node getRoot ( )`
Returns the root node of this tree

Returns: `Node`
  the root node

#### init

`private void init ( )`
Initializes the tree

Returns: `void`

#### onCollapse

`void onCollapse ( node )`
Abstract method that is executed when a node is collapsed.

Parameters:
  `node <Node>` the node that was collapsed.

Returns: `void`

Deprecated use treeobj.subscribe("collapse") instead

#### onExpand

`void onExpand ( node )`
Abstract method that is executed when a node is expanded

Parameters:
  `node <Node>` the node that was expanded

Returns: `void`

Deprecated use treeobj.subscribe("expand") instead

#### popNode

`void popNode ( the )`
Removes the node from the tree, preserving the child collection to make it possible to insert the branch into another part of the tree, or another tree.

Parameters:
  `the <Node>` node to remove

Returns: `void`

#### regNode

`private void regNode ( node )`
Nodes register themselves with the tree instance when they are created.

Parameters:
  `node <Node>` the node to register

Returns: `void`

#### removeChildren

`void removeChildren ( node )`
Deletes this nodes child collection, recursively. Also collapses the node, and resets the dynamic load flag. The primary use for this method is to purge a node and allow it to fetch its data dynamically again.

Parameters:
  `node <Node>` the node to purge

Returns: `void`

#### removeNode

`boolean removeNode ( The , autoRefresh )`
Removes the node and its children, and optionally refreshes the branch of the tree that was affected.

Parameters:
  `The <Node>` node to remove
  `autoRefresh <boolean>` automatically refreshes branch if true

Returns: `boolean`
  False is there was a problem, true otherwise.

#### setCollapseAnim

`void setCollapseAnim ( the )`
Sets up the animation for collapsing children

Parameters:
  `the <string>` type of animation (acceptable values defined in YAHOO.widget.TVAnim)

Returns: `void`

#### setDynamicLoad

`void setDynamicLoad ( fnDataLoader , iconMode )`
Configures this tree to dynamically load all child data

Parameters:
  `fnDataLoader <function>` the function that will be called to get the data
  `iconMode <int>` configures the icon that is displayed when a dynamic load node is expanded the first time without children. By default, the "collapse" icon will be used. If set to 1, the leaf node icon will be displayed.

Returns: `void`

#### setExpandAnim

`void setExpandAnim ( type )`
Sets up the animation for expanding children

Parameters:
  `type <string>` the type of animation (acceptable values defined in YAHOO.widget.TVAnim)

Returns: `void`

#### setUpLabel

`void setUpLabel ( oData )`
Sets up the node label

Parameters:
  `oData <object>` string containing the label, or an object with a label property

Returns: `void`

#### toString

`string toString ( )`
TreeView instance toString

Returns: `string`
  string representation of the tree

#### YAHOO.widget.TreeView.addHandler

`static void YAHOO.widget.TreeView.addHandler ( el , sType , fn )`
Add a DOM event

Parameters:
  `el <object>` the elment to bind the handler to
  `sType <string>` the type of event handler
  `fn <function>` the callback to invoke

Returns: `void`

#### YAHOO.widget.TreeView.getNode

`static Node YAHOO.widget.TreeView.getNode ( treeId , nodeIndex )`
Global method for getting a node by its id. Used in the generated tree html.

Parameters:
  `treeId <String>` the id of the tree instance
  `nodeIndex <String>` the index of the node to return

Returns: `Node`
  the node instance requested, null if not found

#### YAHOO.widget.TreeView.getTree

`static TreeView YAHOO.widget.TreeView.getTree ( treeId )`
Global method for getting a tree by its id. Used in the generated tree html.

Parameters:
  `treeId <String>` the id of the tree instance

Returns: `TreeView`
  the tree instance requested, null if not found.

#### YAHOO.widget.TreeView.preload

`static void YAHOO.widget.TreeView.preload ( prefix )`
Attempts to preload the images defined in the styles used to draw the tree by rendering off-screen elements that use the styles.

Parameters:
  `prefix <string>` the prefix to use to generate the names of the images to preload, default is ygtv

Returns: `void`

#### YAHOO.widget.TreeView.removeHandler

`static void YAHOO.widget.TreeView.removeHandler ( el , sType , fn )`
Remove a DOM event

Parameters:
  `el <object>` the elment to bind the handler to
  `sType <string>` the type of event handler
  `fn <function>` the callback to invoke

Returns: `void`

#### Methods inherited from YAHOO.util.EventProvider:

`createEvent, fireEvent, hasEvent, subscribe, unsubscribe, unsubscribeAll`

### Events

#### animComplete

`animComplete ( node )`
When animation is enabled, this event fires when the animation completes

Parameters:
  `node <YAHOO.widget.Node>` the node that is expanding/collapsing

#### animStart

`animStart ( node )`
When animation is enabled, this event fires when the animation starts

Parameters:
  `node <YAHOO.widget.Node>` the node that is expanding/collapsing

#### collapse

`collapse ( node )`
Fires when a node is going to be collapsed. Return false to stop the collapse.

Parameters:
  `node <YAHOO.widget.Node>` the node that is collapsing

#### collapseComplete

`collapseComplete ( node )`
Fires after a node is successfully collapsed. This event will not fire if the "collapse" event was cancelled.

Parameters:
  `node <YAHOO.widget.Node>` the node that was collapsed

#### expand

`expand ( node )`
Fires when a node is going to be expanded. Return false to stop the collapse.

Parameters:
  `node <YAHOO.widget.Node>` the node that is expanding

#### expandComplete

`expandComplete ( node )`
Fires after a node is successfully expanded. This event will not fire if the "expand" event was cancelled.

Parameters:
  `node <YAHOO.widget.Node>` the node that was expanded

#### labelClick

`labelClick ( node )`
Custom event that is fired when the text node label is clicked. The custom event is defined on the tree instance, so there is a single event that handles all nodes in the tree. The node clicked is provided as an argument

Parameters:
  `node <YAHOO.widget.Node>` the node clicked

Copyright © 2007 Yahoo! Inc. All rights reserved.