System.Web.UI.WebControls.TreeNode Class

Represents a node in the System.Web.UI.WebControls.TreeView control.

See Also: TreeNode Members


[System.Web.UI.ParseChildren(true, "ChildNodes")]
public class TreeNode : ICloneable, System.Web.UI.IStateManager


The System.Web.UI.WebControls.TreeView control is made up of nodes. Each entry in the tree is called a node and is represented by a System.Web.UI.WebControls.TreeNode object. A node that contains other nodes is called a parent node. A node that is contained by another node is called a child node. A node that has no child nodes is called a leaf node. A node that is not contained by any other node but is the ancestor to all the other nodes is the root node. A node can be both a parent and a child, but root, parent, and leaf nodes are mutually exclusive. Several visual and behavioral properties of nodes are determined by whether a node is a root, parent, or leaf node.

Although a typical tree has only one root node, the System.Web.UI.WebControls.TreeView control allows you to add multiple root nodes to your tree structure. This is useful when you want to display item listings without displaying a single main root node, as in a list of product categories.

A node primarily stores data in two properties, the TreeNode.Text property and the TreeNode.Value property. The value of the TreeNode.Text property is displayed in the System.Web.UI.WebControls.TreeView control, and the TreeNode.Value property is used to store any additional data about the node, such as data used for handling postback events. A node also stores the path from the node to its root node in the TreeNode.ValuePath property. The TreeNode.ValuePath property indicates the node's position relative to the root node.


Nodes at the same level must each have a unique value for the TreeNode.Value property; the System.Web.UI.WebControls.TreeView control cannot distinguish between different nodes at the same level that have the same value. In this scenario, if the user clicks a node that has a duplicate value, the node that appears first in the System.Web.UI.WebControls.TreeView control is selected.

A System.Web.UI.WebControls.TreeNode object is made up of the following four user interface (UI) elements, which can be customized or hidden:

You can specify a custom image for the expandable, collapsible, and non-expandable node indicators by setting the TreeView.ExpandImageUrl, TreeView.CollapseImageUrl, and TreeView.NoExpandImageUrl properties of the System.Web.UI.WebControls.TreeView class. The expansion node indicator icons can even be hidden entirely by setting the TreeView.ShowExpandCollapse property of the System.Web.UI.WebControls.TreeView class to false.

To display a check box next to a node, set the TreeView.ShowCheckBoxes property of the System.Web.UI.WebControls.TreeView class. When the TreeView.ShowCheckBoxes property is set to a value other than TreeNodeType.Node, check boxes are displayed next to the specified node type. You can selectively override the check box of an individual node by setting the node's TreeNode.ShowCheckBox property. When a check box is displayed, use the TreeNode.Checked property to determine whether the check box is selected.

You can display an image in a node by setting the TreeNode.ImageUrl property. This image is displayed next to the node text.

The text of a node in the System.Web.UI.WebControls.TreeView control can be in one of two modes: selection mode or navigation mode. By default, a node is in selection mode. To put a node into navigation mode, set the node's TreeNode.NavigateUrl property to a value other than an empty string (""). To put a node into selection mode, set the node's TreeNode.NavigateUrl property to an empty string.


Some Internet browsers have a limitation that can affect the performance of the System.Web.UI.WebControls.TreeView control. For example, Microsoft Internet Explorer 6.0 has a URL character limit of 2067 characters that it posts. If the number of characters in a URL of a node is larger than that number, expanding that node will fail and no exception is thrown.

By default, clicking a node that is in selection mode posts the page back to the server and raises the TreeView.SelectedNodeChanged event. You can optionally specify a different event to raise by setting the node's SelectAction property. For more information, see TreeNode.SelectAction. To determine which node was clicked in selection mode, use the TreeView.SelectedNode property of the System.Web.UI.WebControls.TreeView control.

When a node is in navigation mode, all selection events are disabled for that node. Clicking the node in navigation mode directs the user to the specified URL. You can optionally set the TreeNode.Target property to specify the window or frame in which to display the linked content.

The System.Web.UI.WebControls.TreeNode class contains several properties that are used to store the state of the node. Use the TreeNode.Selected property to determine whether a node is selected. To determine whether the node is expanded, use the TreeNode.Expanded property. The TreeNode.DataBound property is used to determine whether a node is bound to data. When a node is bound to data, you can access the underlying data item by using the TreeNode.DataItem property.

The class provides several properties that help to determine the position of a node relative to other nodes in the tree. Use the TreeNode.Depth property to determine the depth of the node. You can get the delimited list of nodes from the current node to its root node by using the TreeNode.ValuePath property. To determine the node's parent node, use the TreeNode.Parent property. Child nodes are accessed using the TreeNode.ChildNodes collection.

Sometimes, it is not practical to statically predefine the tree structure due to data size or custom content that depends on user input. Because of this, the System.Web.UI.WebControls.TreeView control supports dynamic node population. A node can be populated at run time when it is expanded. Note that you can get unexpected behavior if you persist asynchronously created nodes. For example, if you use a background worker thread to populate nodes asynchronously, the node tree might not be populated immediately though the control proceeds with the rest of the page life cycle. On postback, the delayed creation of the nodes can cause problems when the control's view state is loaded but the node tree is not fully populated. For more information on dynamic node population, see the TreeNode.PopulateOnDemand property.

For a list of initial property values for an instance of System.Web.UI.WebControls.TreeNode, see the TreeNode.#ctor constructor.


Namespace: System.Web.UI.WebControls
Assembly: System.Web (in System.Web.dll)
Assembly Versions:
Since: .NET 2.0