Edit

TreeView Overview

  • Article

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.

What Is a TreeView?

TreeView is an ItemsControl that nests the items by using TreeViewItem controls. The following example creates a TreeView.

<TreeView Name="myTreeViewEvent" >
  <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

The TreeView control contains a hierarchy of TreeViewItem controls. A TreeViewItem control is a HeaderedItemsControl that has a Header and an Items collection.

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.

You can also specify an ItemsSource as a data source and then specify a HeaderTemplate and ItemTemplate to define the TreeViewItem content.

To define the layout of a TreeViewItem control, you can also use HierarchicalDataTemplate objects. For more information and an example, see 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.

TreeViewItem Selection

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 SelectedValuePath property to specify a SelectedValue of a SelectedItem. For more information, see 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<T> 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.

TreeView Style

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.

To customize the appearance of a TreeViewItem control, set the Style property to a custom Style.

The following example shows how to set the Foreground and FontSize property values for a TreeViewItem control by using a Style.

<Style TargetType="{x:Type TreeViewItem}">
  <Setter Property="Foreground" Value="Blue"/>
  <Setter Property="FontSize" Value="12"/>
</Style>

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.

The following example shows how to define the Header of a TreeViewItem as a CheckBox and TextBlock that are both enclosed in a DockPanel control.

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

<DataTemplate x:Key="NewspaperTVItem">
  <DockPanel>
    <Image Source="images\icon.jpg"/>
    <TextBlock VerticalAlignment="center" Text ="{Binding Path=Name}"/>
  </DockPanel>
</DataTemplate>

See also