| -api-id | -api-type |
|---|---|
T:Microsoft.UI.Xaml.FrameworkElement |
winrt class |
Provides a base element class for Windows Runtime UI objects. FrameworkElement defines common API that support UI interaction and the automatic layout system. FrameworkElement also defines API related to data binding, defining and examining the object tree, and tracking object lifetime.
FrameworkElement is a base element: it's a class that many other Windows Runtime classes inherit from in order to support the XAML UI element model. Properties, methods and events that FrameworkElement defines are inherited by hundreds of other Windows Runtime classes.
Many common XAML UI classes derive from FrameworkElement, either directly or through intermediate base classes such as Panel or Control. Typically, you don't derive classes directly from FrameworkElement, because certain expected services for a class that is intended for a UI representation (such as template support) are not fully implemented there. More commonly used base classes for derived custom classes are:
- Specific controls that are not sealed (for example, TextBox).
- Control base classes (Control, ContentControl, UserControl).
- Navigation elements (Page, Frame).
- Panel classes (the base class Panel, or specific non-sealed implementations such as Grid).
FrameworkElement extends UIElement, which is another base element, and adds support for various Windows Runtime feature areas.
The layout system recognizes all objects that derive from FrameworkElement to be elements that potentially participate in layout and should have a display area in the app UI. The layout system reads various properties that are defined at FrameworkElement level, such as MinWidth. Most UI elements use the FrameworkElement-defined Width and Height for their basic sizing information. FrameworkElement provides extensible methods for specialized layout behavior that panels and controls with content can override in their class implementations. For more info, see Define layouts with XAML.
Prominent API of FrameworkElement that support layout: Height, Width, ActualHeight, ActualWidth, Margin, MeasureOverride, ArrangeOverride, HorizontalAlignment, VerticalAlignment, LayoutUpdated.
You often want to know when an object is first loaded (loaded is defined as when an object becomes attached to an object tree that connects to the root visual). FrameworkElement defines events related to object lifetime that provide useful hooks for code-behind operations. For example you need object lifetime info to add child objects to a collection or set properties on child objects just prior to use, with assurance that the necessary objects in the object tree have already been instantiated from XAML markup. For more info, see Events and routed events overview.
Prominent API of FrameworkElement that support object lifetime events: Loaded, SizeChanged, Unloaded, OnApplyTemplate.
The ability to set a value for a potentially inherited data context for a data binding is implemented by FrameworkElement. FrameworkElement also has API for establishing data binding in code rather than in XAML. For more info, see Data binding in depth.
Prominent API of FrameworkElement that support data binding: DataContext, DataContextChanged, SetBinding, GetBindingExpression.
Usually your app's element structure resembles the XAML markup that you defined to create the UI, but sometimes that structure changes after the XAML was parsed. FrameworkElement defines the Name property and related API, which are useful for finding elements and element relationships at run-time. For more info, see XAML namescopes.
Prominent API of FrameworkElement that support XAML and programming model: Name, FindName, Parent, BaseUri, OnApplyTemplate.
The FrameworkElement class defines the Language property and the FlowDirection property. For more info, see Globalizing your app.
The FrameworkElement class defines the Style property and the RequestedTheme property. Also, the Resources property is used to define the page-level XAML resource dictionaries that typically define styles and templates, as well as other shared resources. For more info, see Styling controls and ResourceDictionary and XAML resource references.
Many of the read-write properties of the FrameworkElement base element class are dependency properties. Dependency properties support some of the basic programming model features for a Windows App SDK app using C++ or C#, such as styles and templates, data binding, XAML resource references, and property-changed logic. For more info on dependency properties and the features they support, see Dependency properties overview.
FrameworkElement is the parent class for several immediately derived classes that distinguish several broad classifications of UI elements. Here are some of the notable derived classes:
- Control: Control has many more derived control classes, basically all of the XAML controls that you use for a Windows Runtime UI are derived from Control.
- Presenters: A presenter is a class that imparts a visual appearance, usually by contributing to some control scenario, but the presenter itself isn't typically interactive. For example: Border, ContentPresenter (parent of ScrollContentPresenter and others), ItemsPresenter, Viewbox.
- Media and web elements: Image, WebView, MediaPlayerElement. These display content and have some level of interactivity that happens within their content, but they aren't actually controls.
- Text display elements: TextBlock, RichTextBlock, RichTextBlockOverflow, Glyphs. (Text elements like Run and Hyperlink, which often declare the content of a text display element, are not derived from FrameworkElement.)
- The Panel base class: Panel is the parent class for the common panels such as Grid, StackPanel and so on.
- The Shape base class: Shape is the parent class for Path, Rectangle and so on.
- The IconElement base class: parent class for FontIcon, SymbolIcon and so on.
- Miscellaneous UI elements: Popup, TickBar, Viewbox.
UIElement, Creating a UI, Dependency properties overview