In this topic:

• Introduction

• Nodes

• Static Data

• Binding to Data

• Dynamic Node Population

• Customizing the User Interface

• Events

• Scrolling

• Accessibility

• Declarative Syntax

Introduction

The System.Web.UI.WebControls.TreeView control is used to display hierarchical data, such as a table of contents or file directory, in a tree structure and supports the following features:

• Data binding that allows the nodes of the control to be bound to XML, tabular, or relational data.

• Site navigation through integration with the System.Web.UI.WebControls.SiteMapDataSource control.

• Node text that can be displayed as either plain text or hyperlinks.

• Programmatic access to the System.Web.UI.WebControls.TreeView object model to create trees, populate nodes, set properties, and so on dynamically.

• Client-side node population (on supported browsers).

• The ability to display a check box next to each node.

• Customizable appearance through themes, user-defined images, and styles.

Nodes

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. Node types are defined as follows:

• A node that contains other nodes is called a parent node.

• The node that is contained by another node is called a child node.

• A node that has no children is called a leaf node.

• The 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, child, or leaf node.

Although a typical tree structure 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 root node, as in a list of product categories.

Each node has a TreeNode.Text property and a TreeNode.Value property. The value of the TreeNode.Text property is displayed in the System.Web.UI.WebControls.TreeView, while the TreeNode.Value property is used to store any additional data about the node, such as data that is passed to the postback event that is associated with the node.

A node can be in one of two modes: selection mode and navigation mode. By default, a node is in selection mode. To put a node into navigation mode, set the TreeNode.NavigateUrl property for the node to a value other than an empty string (""). To put a node into selection mode, set the TreeNode.NavigateUrl property for the node to an empty string ("").

Static Data

The simplest data model of the System.Web.UI.WebControls.TreeView control is static data. To display static data using declarative syntax, first nest opening and closing <Nodes> tags between the opening and closing tags of the System.Web.UI.WebControls.TreeView control. Next, create the tree structure by nesting <asp:TreeNode> elements between the opening and closing <Nodes> tags. Each <asp:TreeNode> element represents a node in the tree and maps to a System.Web.UI.WebControls.TreeNode object. You can set the properties of each node by setting the attributes of its <asp:TreeNode> element. To create child nodes, nest additional <asp:TreeNode> elements between the opening and closing <asp:TreeNode> tags of the parent node.

Binding to Data

The System.Web.UI.WebControls.TreeView control can also be bound to data. You can use either of two methods to bind the System.Web.UI.WebControls.TreeView control to the appropriate data source type:

• The System.Web.UI.WebControls.TreeView control can use any data source control that implements the System.Web.UI.IHierarchicalDataSource interface, such as an System.Web.UI.WebControls.XmlDataSource control or a System.Web.UI.WebControls.SiteMapDataSource control. To bind to a data source control, set the DataBoundControl.DataSourceID property of the System.Web.UI.WebControls.TreeView control to the System.Web.UI.Control.ID value of the data source control. The System.Web.UI.WebControls.TreeView control automatically binds to the specified data source control. This is the preferred method to bind to data.

• The System.Web.UI.WebControls.TreeView control can also be bound to an System.Xml.XmlDocument object or a System.Data.DataSet object with relations. To bind to one of these data sources, set the BaseDataBoundControl.DataSource property of the System.Web.UI.WebControls.TreeView control to the data source, and then call the BaseDataBoundControl.DataBind method.

When binding to a data source where each data item contains multiple properties (such as an XML element with several attributes), a node displays the value that is returned by the ToString method of the data item, by default. In the case of an XML element, the node displays the element name, which shows the underlying structure of the tree but is not very useful otherwise. You can bind a node to a specific data item property by specifying tree node bindings using the TreeView.DataBindings collection. The TreeView.DataBindings collection contains TreeNodeBinding objects that define the relationship between a data item and the node that it is binding to. You can specify the criteria for binding and the data item property to display in the node. For more information on tree node bindings, see System.Web.UI.WebControls.TreeNodeBinding.

Dynamic Node Population

Sometimes, it is not practical to statically define the tree structure because the data source returns too much data or because the data to display depends on information that you get at run time. Because of this, the System.Web.UI.WebControls.TreeView control supports dynamic node population. When the TreeNode.PopulateOnDemand property for a node is set to true, that node gets populated at run time when the node is expanded. To populate a node dynamically, you must define an event-handling method that contains the logic to populate a node for the TreeView.TreeNodePopulate event.

Browsers that support callback scripts can also take advantage of client-side node population. (This includes Internet Explorer 5.5 and later and some other browsers.) Client-side node population enables the System.Web.UI.WebControls.TreeView control to populate a node using client script when users expand the node, without requiring a round trip to the server. For more information on client-side node population, see TreeView.PopulateNodesFromClient.

Customizing the User Interface

There are many ways to customize the appearance of the System.Web.UI.WebControls.TreeView control. First, you can specify a different style (such as font size and color) for each of the node types.

If you use cascading style sheets (CSS) to customize the appearance of the control, use either inline styles or a separate CSS file, but not both. Using both inline styles and a separate CSS file could cause unexpected results. For more information on using style sheets with controls, see ASP.NET Web Server Controls and CSS Styles.

The following table lists the available node styles.

You can also control the style of nodes at specific depths within the tree by using the TreeView.LevelStyles collection. The first style in the collection corresponds to the style of the nodes at the first level in the tree. The second style in the collection corresponds to the style of the nodes at the second level in the tree, and so on. This is most often used to generate table of contents–style navigation menus where nodes at a certain depth should have the same appearance, regardless of whether they have child nodes.

Another way to alter the appearance of the control is to customize the images that are displayed in the System.Web.UI.WebControls.TreeView control. You can specify your own custom set of images for the different parts of the control by setting the properties shown in the following table.

The System.Web.UI.WebControls.TreeView control also allows you to display a check box next to a node. When the TreeView.ShowCheckBoxes property is set to a value other than TreeNodeTypes.None, check boxes are displayed next to the specified node types.

Each time the page is posted to the server, the TreeView.CheckedNodes collection is automatically populated with the selected nodes. When check boxes are displayed, you can use the TreeView.TreeNodeCheckChanged event to run a custom routine whenever the state of a check box changes between posts to the server.

Events

The System.Web.UI.WebControls.TreeView control provides several events that you can program against. This allows you to run a custom routine whenever an event occurs. The following table lists the events that are supported by the System.Web.UI.WebControls.TreeView control.

Scrolling

The System.Web.UI.WebControls.TreeView control does not have built-in scrolling. To add scrolling, place the System.Web.UI.WebControls.TreeView control in a System.Web.UI.WebControls.Panel control and add scrollbars to the System.Web.UI.WebControls.Panel control. For more information, see Panel Web Server Control Overview.

Accessibility

The markup rendered by default for this control might not conform to accessibility standards. For details about accessibility support for this control, see ASP.NET Controls and Accessibility.

Declarative Syntax

<asp:TreeView
    AccessKey="string"
    AutoGenerateDataBindings="