The TreeView control provides a way to display information in a hierarchical structure by using collapsible nodes. This topic introduces the TreeView and TreeViewItem controls, and provides simple examples of their use.
This topic contains the following sections.
- What Is a TreeView?
- Creating a TreeView
- Expanding and Collapsing a TreeViewItem
- TreeViewItem Selection
- TreeView Style
- Adding Images and Other Content to TreeView Items
- Related Topics
What Is a TreeView?
TreeView is an ItemsControl that nests the items by using TreeViewItem controls. The following illustration is an example of a TreeView control that has nested TreeViewItem controls.
Nested TreeViewItems in a TreeView
The following example creates the TreeView that appears in the previous illustration.
<TreeView Name="myTreeViewEvent" SelectedItemChanged="SelectionChanged"> <TreeViewItem Header="Employee1" IsSelected="True"> <TreeViewItem Header="Jesper Aaberg"/> <TreeViewItem Header="Employee Number"> <TreeViewItem Header="12345"/> </TreeViewItem> <TreeViewItem Header="Work Days"> <TreeViewItem Header="Monday"/> <TreeViewItem Header="Tuesday"/> <TreeViewItem Header="Thursday"/> </TreeViewItem> </TreeViewItem> <TreeViewItem Header="Employee2"> <TreeViewItem Header="Dominik Paiha"/> <TreeViewItem Header="Employee Number"> <TreeViewItem Header="98765"/> </TreeViewItem> <TreeViewItem Header="Work Days"> <TreeViewItem Header="Tuesday"/> <TreeViewItem Header="Wednesday"/> <TreeViewItem Header="Friday"/> </TreeViewItem> </TreeViewItem> </TreeView>
Creating a TreeView
If you are defining a TreeView by using Extensible Application Markup Language (XAML), you can explicitly define the Header content of a TreeViewItem control and the items that make up its collection. The previous illustration demonstrates this method.
To define the layout of a TreeViewItem control, you can also use HierarchicalDataTemplate objects. For more information and an example, see How to: Use SelectedValue, SelectedValuePath, and SelectedItem.
If an item is not a TreeViewItem control, it is automatically enclosed by a TreeViewItem control when the TreeView control is displayed.
Expanding and Collapsing a TreeViewItem
If the user expands a TreeViewItem, the IsExpanded property is set to true. You can also expand or collapse a TreeViewItem without any direct user action by setting the IsExpanded property to true (expand) or false (collapse). When this property changes, an Expanded or Collapsed event occurs.
When the BringIntoView method is called on a TreeViewItem control, the TreeViewItem and its parent TreeViewItem controls expand. If a TreeViewItem is not visible or partially visible, the TreeView scrolls to make it visible.
When a user clicks a TreeViewItem control to select it, the Selected event occurs, and its IsSelected property is set to true. The TreeViewItem also becomes the SelectedItem of the TreeView control. Conversely, when the selection changes from a TreeViewItem control, its Unselected event occurs and its IsSelected property is set to false.
The SelectedItem property on the TreeView control is a read-only property; hence, you cannot explicitly set it. The SelectedItem property is set if the user clicks on a TreeViewItem control or when the IsSelected property is set to true on the TreeViewItem control.
Use the SelectedValue and SelectedValuePath properties to assign a value to a SelectedItem. For more information, see How to: Use SelectedValue, SelectedValuePath, and SelectedItem.
You can register an event handler on the SelectedItemChanged event in order to determine when a selected TreeViewItem changes. The RoutedPropertyChangedEventArgs that is provided to the event handler specifies the OldValue, which is the previous selection, and the NewValue, which is the current selection. Either value can be null if the application or user has not made a previous or current selection.
The default style for a TreeView control places it inside a StackPanel object that contains a ScrollViewer control. When you set the Width and Height properties for a TreeView, these values are used to size the StackPanel object that displays the TreeView. If the content to display is larger than the display area, a ScrollViewer automatically displays so that the user can scroll through the TreeView content.
Adding Images and Other Content to TreeView Items
You can include more than one object in the Header content of a TreeViewItem. To include multiple objects in Header content, enclose the objects inside a layout control, such as a Panel or StackPanel.
<TreeViewItem> <TreeViewItem.Header> <DockPanel> <CheckBox/> <TextBlock> TreeViewItem Text </TextBlock> </DockPanel> </TreeViewItem.Header> </TreeViewItem>
The following example shows how to define a DataTemplate that contains an Image and a TextBlock that are enclosed in a DockPanel control. You can use a DataTemplate to set the HeaderTemplate or ItemTemplate for a TreeViewItem.