mirror of
https://github.com/Stone-Red-Code/docs-desktop.git
synced 2026-09-06 07:56:06 +02:00
Replace various WPF include files with content (#1335)
* 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
@@ -7,20 +7,20 @@ helpviewer_keywords:
|
||||
ms.assetid: 2c997092-72c6-4767-bc84-74267f4eee72
|
||||
---
|
||||
# Base Elements Overview
|
||||
A high percentage of classes in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] are derived from four classes which are commonly referred to in the SDK documentation as the base element classes. These classes are <xref:System.Windows.UIElement>, <xref:System.Windows.FrameworkElement>, <xref:System.Windows.ContentElement>, and <xref:System.Windows.FrameworkContentElement>. The <xref:System.Windows.DependencyObject> class is also related, because it is a common base class of both <xref:System.Windows.UIElement> and <xref:System.Windows.ContentElement>
|
||||
A high percentage of classes in Windows Presentation Foundation (WPF) are derived from four classes which are commonly referred to in the SDK documentation as the base element classes. These classes are <xref:System.Windows.UIElement>, <xref:System.Windows.FrameworkElement>, <xref:System.Windows.ContentElement>, and <xref:System.Windows.FrameworkContentElement>. The <xref:System.Windows.DependencyObject> class is also related, because it is a common base class of both <xref:System.Windows.UIElement> and <xref:System.Windows.ContentElement>
|
||||
|
||||
<a name="base_apis"></a>
|
||||
## Base Element APIs in WPF Classes
|
||||
Both <xref:System.Windows.UIElement> and <xref:System.Windows.ContentElement> are derived from <xref:System.Windows.DependencyObject>, through somewhat different pathways. The split at this level deals with how a <xref:System.Windows.UIElement> or <xref:System.Windows.ContentElement> are used in a user interface and what purpose they serve in an application. <xref:System.Windows.UIElement> also has <xref:System.Windows.Media.Visual> in its class hierarchy, which is a class that exposes the lower-level graphics support underlying the [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)]. <xref:System.Windows.Media.Visual> provides a rendering framework by defining independent rectangular screen regions. In practice, <xref:System.Windows.UIElement> is for elements that will support a larger object model, are intended to render and layout into regions that can be described as rectangular screen regions, and where the content model is deliberately more open, to allow different combinations of elements. <xref:System.Windows.ContentElement> does not derive from <xref:System.Windows.Media.Visual>; its model is that a <xref:System.Windows.ContentElement> would be consumed by something else, such as a reader or viewer that would then interpret the elements and produce the complete <xref:System.Windows.Media.Visual> for [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] to consume. Certain <xref:System.Windows.UIElement> classes are intended to be content hosts: they provide the hosting and rendering for one or more <xref:System.Windows.ContentElement> classes (<xref:System.Windows.Controls.DocumentViewer> is an example of such a class). <xref:System.Windows.ContentElement> is used as base class for elements with somewhat smaller object models and that more address the text, information, or document content that might be hosted within a <xref:System.Windows.UIElement>.
|
||||
Both <xref:System.Windows.UIElement> and <xref:System.Windows.ContentElement> are derived from <xref:System.Windows.DependencyObject>, through somewhat different pathways. The split at this level deals with how a <xref:System.Windows.UIElement> or <xref:System.Windows.ContentElement> are used in a user interface and what purpose they serve in an application. <xref:System.Windows.UIElement> also has <xref:System.Windows.Media.Visual> in its class hierarchy, which is a class that exposes the lower-level graphics support underlying the Windows Presentation Foundation (WPF). <xref:System.Windows.Media.Visual> provides a rendering framework by defining independent rectangular screen regions. In practice, <xref:System.Windows.UIElement> is for elements that will support a larger object model, are intended to render and layout into regions that can be described as rectangular screen regions, and where the content model is deliberately more open, to allow different combinations of elements. <xref:System.Windows.ContentElement> does not derive from <xref:System.Windows.Media.Visual>; its model is that a <xref:System.Windows.ContentElement> would be consumed by something else, such as a reader or viewer that would then interpret the elements and produce the complete <xref:System.Windows.Media.Visual> for Windows Presentation Foundation (WPF) to consume. Certain <xref:System.Windows.UIElement> classes are intended to be content hosts: they provide the hosting and rendering for one or more <xref:System.Windows.ContentElement> classes (<xref:System.Windows.Controls.DocumentViewer> is an example of such a class). <xref:System.Windows.ContentElement> is used as base class for elements with somewhat smaller object models and that more address the text, information, or document content that might be hosted within a <xref:System.Windows.UIElement>.
|
||||
|
||||
### Framework-Level and Core-Level
|
||||
<xref:System.Windows.UIElement> serves as the base class for <xref:System.Windows.FrameworkElement>, and <xref:System.Windows.ContentElement> serves as the base class for <xref:System.Windows.FrameworkContentElement>. The reason for this next level of classes is to support a WPF core level that is separate from a WPF framework level, with this division also existing in how the APIs are divided between the PresentationCore and PresentationFramework assemblies. The WPF framework level presents a more complete solution for basic application needs, including the implementation of the layout manager for presentation. The WPF core level provides a way to use much of [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] without taking the overhead of the additional assembly. The distinction between these levels very rarely matters for most typical application development scenarios, and in general you should think of the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] APIs as a whole and not concern yourself with the difference between WPF framework level and WPF core level. You might need to know about the level distinctions if your application design chooses to replace substantial quantities of WPF framework level functionality, for instance if your overall solution already has its own implementations of [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] composition and layout.
|
||||
<xref:System.Windows.UIElement> serves as the base class for <xref:System.Windows.FrameworkElement>, and <xref:System.Windows.ContentElement> serves as the base class for <xref:System.Windows.FrameworkContentElement>. The reason for this next level of classes is to support a WPF core level that is separate from a WPF framework level, with this division also existing in how the APIs are divided between the PresentationCore and PresentationFramework assemblies. The WPF framework level presents a more complete solution for basic application needs, including the implementation of the layout manager for presentation. The WPF core level provides a way to use much of WPF without taking the overhead of the additional assembly. The distinction between these levels very rarely matters for most typical application development scenarios, and in general you should think of the WPF APIs as a whole and not concern yourself with the difference between WPF framework level and WPF core level. You might need to know about the level distinctions if your application design chooses to replace substantial quantities of WPF framework level functionality, for instance if your overall solution already has its own implementations of user interface (UI) composition and layout.
|
||||
|
||||
<a name="subclassing_elements"></a>
|
||||
## Choosing Which Element to Derive From
|
||||
The most practical way to create a custom class that extends [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] is by deriving from one of the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] classes where you get as much as possible of your desired functionality through the existing class hierarchy. This section lists the functionality that comes with three of the most important element classes to help you decide which class to inherit from.
|
||||
The most practical way to create a custom class that extends WPF is by deriving from one of the WPF classes where you get as much as possible of your desired functionality through the existing class hierarchy. This section lists the functionality that comes with three of the most important element classes to help you decide which class to inherit from.
|
||||
|
||||
If you are implementing a control, which is really one of the more common reasons for deriving from a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] class, you probably want to derive from a class that is a practical control, a control family base class, or at least from the <xref:System.Windows.Controls.Control> base class. For some guidance and practical examples, see [Control Authoring Overview](../controls/control-authoring-overview.md).
|
||||
If you are implementing a control, which is really one of the more common reasons for deriving from a WPF class, you probably want to derive from a class that is a practical control, a control family base class, or at least from the <xref:System.Windows.Controls.Control> base class. For some guidance and practical examples, see [Control Authoring Overview](../controls/control-authoring-overview.md).
|
||||
|
||||
If you are not creating a control and need to derive from a class that is higher in the hierarchy, the following sections are intended as a guide for what characteristics are defined in each base element class.
|
||||
|
||||
@@ -76,7 +76,7 @@ A high percentage of classes in [!INCLUDE[TLA#tla_winclient](../../../includes/t
|
||||
## Other Base Classes
|
||||
|
||||
### DispatcherObject
|
||||
<xref:System.Windows.Threading.DispatcherObject> provides support for the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] threading model and enables all objects created for [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications to be associated with a <xref:System.Windows.Threading.Dispatcher>. Even if you do not derive from <xref:System.Windows.UIElement>, <xref:System.Windows.DependencyObject>, or <xref:System.Windows.Media.Visual>, you should consider deriving from <xref:System.Windows.Threading.DispatcherObject> in order to get this threading model support. For more information, see [Threading Model](threading-model.md).
|
||||
<xref:System.Windows.Threading.DispatcherObject> provides support for the WPF threading model and enables all objects created for WPF applications to be associated with a <xref:System.Windows.Threading.Dispatcher>. Even if you do not derive from <xref:System.Windows.UIElement>, <xref:System.Windows.DependencyObject>, or <xref:System.Windows.Media.Visual>, you should consider deriving from <xref:System.Windows.Threading.DispatcherObject> in order to get this threading model support. For more information, see [Threading Model](threading-model.md).
|
||||
|
||||
### Visual
|
||||
<xref:System.Windows.Media.Visual> implements the concept of a 2D object that generally requires visual presentation in a roughly rectangular region. The actual rendering of a <xref:System.Windows.Media.Visual> happens in other classes (it is not self-contained), but the <xref:System.Windows.Media.Visual> class provides a known type that is used by rendering processes at various levels. <xref:System.Windows.Media.Visual> implements hit testing, but it does not expose events that report hit-testing positives (these are in <xref:System.Windows.UIElement>). For more information, see [Visual Layer Programming](../graphics-multimedia/visual-layer-programming.md).
|
||||
@@ -89,7 +89,7 @@ A high percentage of classes in [!INCLUDE[TLA#tla_winclient](../../../includes/t
|
||||
<xref:System.Windows.Media.Animation.Animatable> is a <xref:System.Windows.Freezable> derived class that specifically adds the animation control layer and some utility members so that currently animated properties can be distinguished from nonanimated properties.
|
||||
|
||||
### Control
|
||||
<xref:System.Windows.Controls.Control> is the intended base class for the type of object that is variously termed a control or component, depending on the technology. In general, [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] control classes are classes that either directly represent a UI control or participate closely in control composition. The primary functionality that <xref:System.Windows.Controls.Control> enables is control templating.
|
||||
<xref:System.Windows.Controls.Control> is the intended base class for the type of object that is variously termed a control or component, depending on the technology. In general, WPF control classes are classes that either directly represent a UI control or participate closely in control composition. The primary functionality that <xref:System.Windows.Controls.Control> enables is control templating.
|
||||
|
||||
## See also
|
||||
|
||||
|
||||
Reference in New Issue
Block a user