Stone_Red/docs-desktop
1
0
Fork 0
mirror of https://github.com/Stone-Red-Code/docs-desktop.git synced 2026-09-07 07:56:07 +02:00
Code Issues Packages Projects Releases Wiki Activity

Replace various WPF include files with content (#1335)

Browse Source 
* net-current-v30plus-md.md

* net-current-v40plus-md.md

* tla2sharptla-ui-md.md

* tla2sharptla-uiautomation-md.md

* tla2sharptla-winclient-md.md

* tla2sharptla-xaml-md.md

* tlasharptla-ui-md.md

* tlasharptla-uiautomation-md.md

* tlasharptla-winclient-md.md

* tlasharptla-xaml-md.md

* fix warnings
This commit is contained in:
Andy (Steve) De George
2022-03-16 12:14:11 -04:00
committed by GitHub
parent dd0052ecec
commit be103da07e
353 changed files with 1339 additions and 1349 deletions
Download Patch File Download Diff File Expand all files Collapse all files
dotnet-desktop-guide/framework/wpf/advanced/trees-in-wpf.md
+7 -7
View File
@@ -10,15 +10,15 @@ ms.assetid: e83f25e5-d66b-4fc7-92d2-50130c9a6649
---
# Trees in WPF
In many technologies, elements and components are organized in a tree structure where developers directly manipulate the object nodes in the tree to affect the rendering or behavior of an application. [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] also uses several tree structure metaphors to define relationships between program elements. For the most part WPF developers can create an application in code or define portions of the application in XAML while thinking conceptually about the object tree metaphor, but will be calling specific API or using specific markup to do so rather than some general object tree manipulation API such as you might use in XML DOM. WPF exposes two helper classes that provide a tree metaphor view, <xref:System.Windows.LogicalTreeHelper> and <xref:System.Windows.Media.VisualTreeHelper>. The terms visual tree and logical tree are also used in the WPF documentation because these same trees are useful for understanding the behavior of certain key WPF features. This topic defines what the visual tree and logical tree represent, discusses how such trees relate to an overall object tree concept, and introduces <xref:System.Windows.LogicalTreeHelper> and <xref:System.Windows.Media.VisualTreeHelper>s.
In many technologies, elements and components are organized in a tree structure where developers directly manipulate the object nodes in the tree to affect the rendering or behavior of an application. Windows Presentation Foundation (WPF) also uses several tree structure metaphors to define relationships between program elements. For the most part WPF developers can create an application in code or define portions of the application in XAML while thinking conceptually about the object tree metaphor, but will be calling specific API or using specific markup to do so rather than some general object tree manipulation API such as you might use in XML DOM. WPF exposes two helper classes that provide a tree metaphor view, <xref:System.Windows.LogicalTreeHelper> and <xref:System.Windows.Media.VisualTreeHelper>. The terms visual tree and logical tree are also used in the WPF documentation because these same trees are useful for understanding the behavior of certain key WPF features. This topic defines what the visual tree and logical tree represent, discusses how such trees relate to an overall object tree concept, and introduces <xref:System.Windows.LogicalTreeHelper> and <xref:System.Windows.Media.VisualTreeHelper>s.
<a name="element_tree"></a>
## Trees in WPF
The most complete tree structure in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] is the object tree. If you define an application page in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] and then load the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], the tree structure is created based on the nesting relationships of the elements in the markup. If you define an application or a portion of the 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 object. In [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)], there are two ways that the complete object tree is conceptualized and can be reported to its public API: as the logical tree and as the visual tree. The distinctions between logical tree and visual tree are not always necessarily important, but they can occasionally cause issues with certain [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] subsystems and affect choices you make in markup or code.
The most complete tree structure in WPF is the object tree. If you define an application page in WPF subsystems and affect choices you make in markup or code.
Even though you do not always manipulate either the logical tree or the visual tree directly, understanding the concepts of how the trees interact is useful for understanding WPF as a technology. Thinking of WPF as a tree metaphor of some kind is also crucial to understanding how property inheritance and event routing work in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)].
Even though you do not always manipulate either the logical tree or the visual tree directly, understanding the concepts of how the trees interact is useful for understanding WPF as a technology. Thinking of WPF as a tree metaphor of some kind is also crucial to understanding how property inheritance and event routing work in WPF.
> [!NOTE]
> Because the object tree is more of a concept than an actual API, another way to think of the concept is as an object graph. In practice, there are relationships between objects at run time where the tree metaphor will break down. Nevertheless, particularly with XAML-defined UI, the tree metaphor is relevant enough that most WPF documentation will use the term object tree when referencing this general concept.
@@ -27,9 +27,9 @@ In many technologies, elements and components are organized in a tree structure
## The Logical Tree
In [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], you add content to UI elements by setting properties of the objects that back those elements. For example, you add items to a <xref:System.Windows.Controls.ListBox> control by manipulating its <xref:System.Windows.Controls.ItemsControl.Items%2A> property. By doing this, you are placing items into the <xref:System.Windows.Controls.ItemCollection> that is the <xref:System.Windows.Controls.ItemsControl.Items%2A> property value. Similarly, to add objects to a <xref:System.Windows.Controls.DockPanel>, you manipulate its <xref:System.Windows.Controls.Panel.Children%2A> property value. Here, you are adding objects to the <xref:System.Windows.Controls.UIElementCollection>. For a code example, see [How to: Add an Element Dynamically](/previous-versions/dotnet/netframework-4.0/ms752374(v=vs.100)).
In WPF, you add content to UI elements by setting properties of the objects that back those elements. For example, you add items to a <xref:System.Windows.Controls.ListBox> control by manipulating its <xref:System.Windows.Controls.ItemsControl.Items%2A> property. By doing this, you are placing items into the <xref:System.Windows.Controls.ItemCollection> that is the <xref:System.Windows.Controls.ItemsControl.Items%2A> property value. Similarly, to add objects to a <xref:System.Windows.Controls.DockPanel>, you manipulate its <xref:System.Windows.Controls.Panel.Children%2A> property value. Here, you are adding objects to the <xref:System.Windows.Controls.UIElementCollection>. For a code example, see [How to: Add an Element Dynamically](/previous-versions/dotnet/netframework-4.0/ms752374(v=vs.100)).
In [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)], when you place list items in a <xref:System.Windows.Controls.ListBox> or controls or other UI elements in a <xref:System.Windows.Controls.DockPanel>, you also use the <xref:System.Windows.Controls.ItemsControl.Items%2A> and <xref:System.Windows.Controls.Panel.Children%2A> properties, either explicitly or implicitly, as in the following example.
In Extensible Application Markup Language (XAML), when you place list items in a <xref:System.Windows.Controls.ListBox> or controls or other UI elements in a <xref:System.Windows.Controls.DockPanel>, you also use the <xref:System.Windows.Controls.ItemsControl.Items%2A> and <xref:System.Windows.Controls.Panel.Children%2A> properties, either explicitly or implicitly, as in the following example.
[!code-xaml[TreeOvwsSupport#AllCode](~/samples/snippets/csharp/VS_Snippets_Wpf/TreeOvwsSupport/CS/page1.xaml#allcode)]
@@ -37,7 +37,7 @@ In many technologies, elements and components are organized in a tree structure
However, the logical tree is not the entire object graph that exists for your application UI at run time, even with the XAML implicit syntax items factored out. The main reason for this is visuals and templates. For example, consider the <xref:System.Windows.Controls.Button>. The logical tree reports the <xref:System.Windows.Controls.Button> object and also its string `Content`. But there is more to this button in the run-time object tree. In particular, the button only appears on screen the way it does because a specific <xref:System.Windows.Controls.Button> control template was applied. The visuals that come from an applied template (such as the template-defined <xref:System.Windows.Controls.Border> of dark gray around the visual button) are not reported in the logical tree, even if you are looking at the logical tree during run time (such as handling an input event from the visible UI and then reading the logical tree). To find the template visuals, you would instead need to examine the visual tree.
For more information about how [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] syntax maps to the created object graph, and implicit syntax in XAML, see [XAML Syntax In Detail](xaml-syntax-in-detail.md) or [XAML in WPF](xaml-in-wpf.md).
For more information about how XAML syntax maps to the created object graph, and implicit syntax in XAML, see [XAML Syntax In Detail](xaml-syntax-in-detail.md) or [XAML in WPF](xaml-in-wpf.md).
<a name="tree_property_inheritance_event_routing"></a>
@@ -69,7 +69,7 @@ In many technologies, elements and components are organized in a tree structure
## The Visual Tree
In addition to the concept of the logical tree, there is also the concept of the visual tree in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]. The visual tree describes the structure of visual objects, as represented by the <xref:System.Windows.Media.Visual> base class. When you write a template for a control, you are defining or redefining the visual tree that applies for that control. The visual tree is also of interest to developers who want lower-level control over drawing for performance and optimization reasons. One exposure of the visual tree as part of conventional [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application programming is that event routes for a routed event mostly travel along the visual tree, not the logical tree. This subtlety of routed event behavior might not be immediately apparent unless you are a control author. Routing events through the visual tree enables controls that implement composition at the visual level to handle events or create event setters.
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 visual objects, as represented by the <xref:System.Windows.Media.Visual> base class. When you write a template for a control, you are defining or redefining the visual tree that applies for that control. The visual tree is also of interest to developers who want lower-level control over drawing for performance and optimization reasons. 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 subtlety of routed event behavior might not be immediately apparent unless you are a control author. Routing events through the visual tree enables controls that implement composition at the visual level to handle events or create event setters.
<a name="trees_content"></a>