Element Tree

Article
11/03/2006

In many technologies, elements and components are organized in a tree structure where developers directly manipulate the tree to affect the rendering of an application. Windows Presentation Foundation (WPF) also uses a tree structure metaphor to define relationships between program elements.

This topic contains the following sections. Element Trees in WPFThe Logical TreeThe Visual TreeTrees, Content Elements, and Content HostsThe Purpose of the Logical TreeTree TraversalOverriding the Logical TreeRelated Topics

Element Trees in WPF

The tree structures in WPF are known as the element tree. If you create an application page in XAML, then the tree structure is created based on the nesting relationships of the elements in the markup. If you create an application in code, then the tree structure is created based on how you assign property values for properties that implement the content model for a given element. In Windows Presentation Foundation (WPF), there are really two types of element trees: the logical tree and the visual tree. In most cases, it is the logical tree that provides the intuitive view of the element relationships in an application, and it is this tree that you typically are creating when writing markup or code. But occasionally it is the visual tree that controls or defines a tree-related behavior.

Even though you do not always manipulate either the logical tree or the visual tree directly, understanding the concepts is a way to understand how property inheritance and event routing work in WPF.

The Logical Tree

In WPF, you add content to elements using properties. For example, you add items to a ListBox control using its Items property. By doing this, you are placing items into the ItemCollection of the ListBox control. To add elements to a DockPanel, you use its Children property. Here, you are adding elements to the UIElementCollection of the DockPanel. For a code example, see How to: Add an Element Dynamically.

In Extensible Application Markup Language (XAML), when you place list items in a ListBox or controls or other elements in a DockPanel, you also use the Items and Children properties, either explicitly or implicitly, as in the following example.

<DockPanel
  Name="ParentElement"
  xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
  xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml"
  >

  <!--implicit: <DockPanel.Children>-->
  <ListBox DockPanel.Dock="Top">
    <!--implicit: <ListBox.Items>-->
    <ListItem>
      <Paragraph>Dog</Paragraph>
    </ListItem>
    <ListItem>
      <Paragraph>Cat</Paragraph>
    </ListItem>
    <ListItem>
      <Paragraph>Fish</Paragraph>
    </ListItem>
    <!--implicit: </ListBox.Items>-->
  </ListBox>
  <Button Height="20" Width="100" DockPanel.Dock="Top">Buy a Pet</Button>

  <!--implicit: </DockPanel.Children>-->
</DockPanel>

Note that the property element tags are not explicitly needed because the XAML reader infers the property elements when it creates the objects that create the executable's runtime object representation of the application. For more information about how XAML syntax maps to the created logical tree, and inferred tags, see XAML Syntax Terminology or XAML Overview. The following graphic provides a conceptual view of the logical tree that is constructed at run time (the branch for the button is omitted from the graphic).

Schematic of what the generic logical tree looks like

Tree diagram

The Visual Tree

In addition to the concept of the logical tree, there is also the concept of the visual tree in WPF. The visual tree describes the structure of visuals represented by the Visual base class. The visual tree is of greatest interest to developers who want lower-level control over drawing for performance and optimization reasons, and generally is not a concept that is exposed to developers working primarily with existing controls and with Extensible Application Markup Language (XAML). One exposure of the visual tree as part of conventional WPF application programming is that event routes for a routed event mostly travel along the visual tree, not the logical tree. This sublety of routed event behavior might not be immediately apparent unless you are a control author. Routing through the visual tree enables controls that implement composition at the visual level to handle events or create event setters.

Trees, Content Elements, and Content Hosts

Content elements (derived classes of ContentElement) are not part of the visual tree; they do not inherit from Visual and have no visual representation. In order to appear in a UI at all, a ContentElement must be hosted within a content host that is a Visual, usually a FrameworkElement. You can conceptualize that the content host is somewhat like a "browser" for the content and chooses how to display that content within the screen region the host controls. Once the content is hosted, the content can be made a participant in certain tree processes that are normally associated with the visual tree. Generally the FrameworkElement host class include implementation code that adds any hosted ContentElement to the event route through subnodes of the content logical tree, even though the hosted content is not part of the true visual tree. This is necessary so that a ContentElement can source a routed event that routes to any element other than itself.

The Purpose of the Logical Tree

Understanding the concept of the logical tree will help you understand how property inheritance works in WPF. Consider a DockPanel that contains a Button control and a TextBlock control. If you set the FontWeight property on the DockPanel, the TextBlock control inherits the FontWeight property value from the parent DockPanel element. A property is inherited through either its logical parent or visual parent, but the logical parent is used if both parents are present.

In addition, resource references are resolved by looking upwards through the logical tree for Resources collections. Similar to property value inheritance, the logical tree is used for resource lookup when both the logical tree and the visual tree are present. For more information on resources, see Resources Overview.

Tree Traversal

The LogicalTreeHelper class provides the GetChildren, GetParent, and FindLogicalNode methods for tree traversal. In most cases, you should not have to traverse the logical tree of existing controls, because these controls almost always expose their logical child elements as a dedicated collection property, which will support collection APIs such as Add, an indexer, and so on. Tree traversal is mainly a scenario that is used by control authors who choose not to derive from intended control patterns such as ItemsControl or Panel where collection properties are already defined, and who intend to provide their own collection property support.

The visual tree also supports a helper class for tree traversal, VisualTreeHelper. The visual tree is not exposed as conveniently through control-specific properties, so the VisualTreeHelper class is the recommended way to traverse the visual tree if that is necessary for your programming scenario. For more information, see Windows Presentation Foundation Graphics Rendering Overview.

Overriding the Logical Tree

Advanced control authors can override the logical tree by overriding several APIs that define how a general object or content model adds or removes elements within the logical tree. For an example of how to override the logical tree, see How to: Override the Logical Tree.