Base Elements Overview

  • Article

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 are UIElement, FrameworkElement, ContentElement, and FrameworkContentElement.

This topic contains the following sections.

  • Base Element APIs in WPF Classes
  • Choosing Which Element to Derive From
  • Related Topics

Base Element APIs in WPF Classes

Both UIElement and ContentElement are derived from DependencyObject, through somewhat different pathways. The split at this level deals with how a UIElement or ContentElement are used in a user interface and what purpose they serve in an application. UIElement also has Visual in its class hierarchy, which is a class that exposes the lower-level graphics support underlying the Windows Presentation Foundation (WPF). Visual provides a rendering framework by defining independent rectangular screen regions. In practice, 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. ContentElement does not derive from Visual; its model is that a ContentElement would be consumed by something else, such as a reader or viewer that would then interpret the elements and produce the complete Visual for Windows Presentation Foundation (WPF) to consume. Certain UIElement classes are intended to be content hosts: they provide the hosting and rendering for one or more ContentElement classes (DocumentViewer is an example of such a class). 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 UIElement.

Framework-Level and Core-Level

UIElement serves as the base class for FrameworkElement, and ContentElement serves as the base class for 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 within "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 consider the WPF APIs as a whole. 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.

Choosing Which Element to Derive From

The most practical way to create a custom class that extends WPF is by deriving from one of the WPF classes such you get the desired functionality through the 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 create a class that derives from DependencyObject, you inherit the following functionality:

  • GetValue and SetValue support, and general property system support.

  • Ability to use dependency properties and attached properties that are implemented as dependency properties.

If you create a class that derives from UIElement, you inherit the following functionality in addition to that provided by DependencyObject:

  • Basic support for animated property values. For more information, see Animation Overview.

  • Basic input event support, and commanding support. For more information, see Input Overview and Commanding Overview.

  • Virtual methods that can be overridden to provide information to a layout system.

If you create a class that derives from FrameworkElement, you inherit the following functionality in addition to that provided by UIElement:

  • Support for styling and storyboards. For more information, see Style and Storyboards Overview.

  • Support for databinding. For more information, see Data Binding Overview.

  • Support for dynamic resource references. For more information, see Resources Overview.

  • Property value inheritance support, and other flags in the metadata that help report conditions about properties to framework services such as databinding, styles, or the framework implementation of layout. For more information, see Framework Property Metadata.

  • The concept of the logical tree. For more information, see Element Tree.

  • Support for the practical WPF framework-level implementation of the layout system, including an OnPropertyChanged override that can detect changes to properties that influence layout.

If you create a class that derives from ContentElement, you inherit the following functionality in addition to that provided by DependencyObject:

If you create a class that derives from FrameworkContentElement, you get the following functionality in addition to that provided by ContentElement:

  • Support for styling and storyboards. For more information, see Style and Animation Overview.

  • Support for databinding. For more information, see Data Binding Overview.

  • Support for dynamic resource references. For more information, see Resources Overview.

  • Property value inheritance support, and other flags in the metadata that help report conditions about properties to framework services like databinding, styles, or the framework implementation of layout. For more information, see Framework Property Metadata.

  • You do not inherit access to layout system modifications (such as ArrangeOverride). Layout system implementations are only available on FrameworkElement. However, you inherit an OnPropertyChanged override that can detect changes to properties that influence layout and report these to any content hosts.

If you are implementing a control, you probably want to derive from a class that is a practical control, a control family base class, or at least from the Control base class. For some guidance and practical examples, see Control Authoring Overview.

Content models are documented for a variety of classes. The content model for a class is one possible factor you should consider if you want to find an appropriate class to derive from. For more information, see Content Models.

See Also

Reference

Control

Concepts

Dependency Properties Overview
Control Authoring Overview
WPF Architecture