UIElement is a base class for most of the Windows Runtime UI objects that have visual appearance and can process basic input as part of your app's user interface.
public ref class UIElement : DependencyObject, IAnimationObject, IVisualElement, IVisualElement2
/// [Windows.Foundation.Metadata.Composable(Microsoft.UI.Xaml.IUIElementFactory, Windows.Foundation.Metadata.CompositionType.Public, 65536, "Microsoft.UI.Xaml.WinUIContract")] /// [Windows.Foundation.Metadata.ContractVersion(Microsoft.UI.Xaml.WinUIContract, 65536)] /// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)] /// [Windows.Foundation.Metadata.Static(Microsoft.UI.Xaml.IUIElementStatics, 65536, "Microsoft.UI.Xaml.WinUIContract")] /// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)] /// [Windows.Foundation.Metadata.WebHostHidden] class UIElement : DependencyObject, IAnimationObject, IVisualElement, IVisualElement2
[Windows.Foundation.Metadata.Composable(typeof(Microsoft.UI.Xaml.IUIElementFactory), Windows.Foundation.Metadata.CompositionType.Public, 65536, "Microsoft.UI.Xaml.WinUIContract")] [Windows.Foundation.Metadata.ContractVersion(typeof(Microsoft.UI.Xaml.WinUIContract), 65536)] [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)] [Windows.Foundation.Metadata.Static(typeof(Microsoft.UI.Xaml.IUIElementStatics), 65536, "Microsoft.UI.Xaml.WinUIContract")] [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)] [Windows.Foundation.Metadata.WebHostHidden] public class UIElement : DependencyObject, IAnimationObject, IVisualElement, IVisualElement2
Public Class UIElement Inherits DependencyObject Implements IAnimationObject, IVisualElement, IVisualElement2
Windows.Foundation.Metadata.ComposableAttribute Windows.Foundation.Metadata.ContractVersionAttribute Windows.Foundation.Metadata.MarshalingBehaviorAttribute Windows.Foundation.Metadata.StaticAttribute Windows.Foundation.Metadata.ThreadingAttribute Windows.Foundation.Metadata.WebHostHiddenAttribute
UIElement 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 UIElement defines are inherited by hundreds of other Windows Runtime classes.
Although UIElement defines the events for focus reporting (@"Microsoft.UI.Xaml.UIElement.GotFocus?text=GotFocus", LostFocus ), UIElement does not define an API for programmatically setting the focus. This capability is defined by the Control class.
UIElement does not expose a public constructor. Typically, you don't derive classes from either UIElement or FrameworkElement directly. More typically used base classes for derived custom classes are these classes:
- Specific controls that are not sealed (for example, TextBox )
- Control base classes (@"Microsoft.UI.Xaml.Controls.Control?text=Control", ContentControl, UserControl )
- Navigation elements (@"Microsoft.UI.Xaml.Controls.Page?text=Page", Frame )
- Panel classes (the base class Panel, or specific non-sealed implementations such as Grid )
The UIElement class is used as the type parameter of many properties and methods in the Windows Runtime API. For example, the Child property of Border takes a single UIElement, which represents the element that the Border is drawn around. You can provide any UIElement-derived element for such a property, including custom controls that you define.
The UIElementCollection class provides a strongly typed collection of UIElement items. UIElementCollection is used as a type for properties of objects that contain several child elements, for example for the Children property of any Panel class.
UIElement API and features
UIElement extends DependencyObject, which is another base element, and adds support for various Windows Runtime feature areas.
Input, and events for responding to user interaction
Much of the input behavior for visible elements in a UI is defined in the UIElement class. This includes the events for keyboard, mouse, touch, drag-drop, and focus interactions. For more info, see Handle pointer input, Keyboard interactions, and Custom user interactions.
Prominent API of UIElement that support input and user interaction:
- Pointer events: PointerPressed, PointerReleased, PointerMoved, PointerEntered, PointerExited
- Key handling events: KeyDown, KeyUp
- Focus: GotFocus, LostFocus
- Pointer capture: CapturePointer, PointerCanceled, PointerCaptureLost, ReleasePointerCapture, PointerCaptures
- Drag-drop: DragOver, Drop, DragEnter, DragLeave, AllowDrop
- Properties that influence how basic input is processed: IsHitTestVisible, AllowDrop
Gestures and manipulations
Gestures and manipulations are also a way to handle input and user interaction. The API are listed out separately here because these events represent how the system interacts with device-level input actions and interprets them as a user interaction. Manipulations are a way to handle dynamic multi-touch interactions such as pinching and stretching. Together, the gestures and manipulations provide the touch patterns for touch interaction with UWP app. For more info, see Custom user interactions and Touch interaction design.
Prominent API of UIElement that support gestures and manipulations:
- Gesture events: DoubleTapped, Holding, RightTapped, Tapped
- Manipulation events: ManipulationCompleted, ManipulationDelta, ManipulationInertiaStarting, ManipulationStarted, ManipulationStarting
- Properties that influence how gestures and manipulations are processed: IsHoldingEnabled and other Is*Enabled, ManipulationMode
The Visibility and Opacity properties are frequently used to adjust the appearance of an element in your UI, especially within styles, templates, and visual states. The Clip, RenderTransform, and Transitions properties are each useful for producing interactions and different looks for your UI elements.
The UIElement class provides a starting point for layout characteristics with properties such as DesiredSize and the Arrange and Measure methods. FrameworkElement adds more layout capabilities. For more info, see Define layouts with XAML and FrameworkElement.
Most of the input events of UIElement are routed events. A routed event enables a built-in event handling notification system, so that a parent object can handle input events from child objects in the object tree if the event remains unhandled. This input event behavior is useful for input area grouping, and for control compositing. For more info, see Events and routed events overview.
Other platform support
- OnCreateAutomationPeer enables a class to use a custom AutomationPeer for its Microsoft UI Automation support.
- RenderTransform, TransformToVisual, Projection, CompositeMode, CacheMode and FindSubElementsForTouchTargeting are useful for advanced UI layout scenarios.
UIElement dependency properties
Many of the read-write properties of the UIElement base element class are dependency properties. Dependency properties support some of the basic programming model features for a UWP app using C++, C#, or Visual Basic, 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.
UIElement derived classes
The only Windows Runtime class that derives directly from UIElement is FrameworkElement. For a list of the classes that derive from FrameworkElement, see the "FrameworkElement derived classes" section of the FrameworkElement reference topic.
Gets or sets the access key (mnemonic) for this element.
Identifies for the AccessKey dependency property.
Gets or sets a source element that provides the access key scope for this element, even if it's not in the visual tree of the source element.
Identifies for the AccessKeyScopeOwner dependency property.
Gets the position of this UIElement, relative to its parent, computed during the arrange pass of the layout process.
Gets the size that this UIElement computed during the arrange pass of the layout process.
Gets or sets a value that determines whether this UIElement can be a drop target for purposes of drag-and-drop operations.
Identifies the AllowDrop dependency property.
Gets the identifier for the BringIntoViewRequested routed event.
Gets or sets a value that indicates that rendered content should be cached as a composited bitmap when possible.
Identifies the CacheMode dependency property.
Gets or sets a value that indicates whether the UIElement can be a candidate for scroll anchoring.
Identifies the CanBeScrollAnchor dependency property.
Gets or sets a value that indicates whether the element can be dragged as data in a drag-and-drop operation.
Identifies the CanDrag dependency property.
Gets or sets the center point of the element, which is the point about which rotation or scaling occurs. Affects the rendering position of the element.
Gets the identifier for the CharacterReceived routed event.
Identifies the Clip dependency property.
Gets or sets a property that declares alternate composition and blending modes for the element in its parent layout and window. This is relevant for elements that are involved in a mixed XAML / Microsoft DirectX UI.
Identifies the CompositeMode dependency property.
Gets or sets the flyout associated with this element.
Identifies for the ContextFlyout dependency property.
Gets the identifier for the ContextRequested routed event.
Gets the size that this UIElement computed during the measure pass of the layout process.
Gets the CoreDispatcher that this object is associated with. The CoreDispatcher represents a facility that can access the DependencyObject on the UI thread even if the code is initiated by a non-UI thread.(Inherited from DependencyObject)
Gets the DispatcherQueue that this object is associated with. The DispatcherQueue represents a facility that can access the DependencyObject on the UI thread even if the code is initiated by a non-UI thread.(Inherited from DependencyObject)
Gets the identifier for the DoubleTapped routed event.
Gets the identifier for the DragEnter routed event.
Gets the identifier for the DragLeave routed event.
Gets the identifier for the DragOver routed event.
Gets the identifier for the Drop routed event.
Gets or sets a value that specifies whether the access key display is dismissed when an access key is invoked.
Identifies the ExitDisplayModeOnAccessKeyInvoked dependency property.
Gets the identifier for the GettingFocus routed event.
Gets or sets a value that indicates whether the framework automatically adjusts the element's visual properties when high contrast themes are enabled.
Identifies the HighContrastAdjustment dependency property.
Gets the identifier for the Holding routed event.
Gets or sets a value that indicates whether an element defines its own access key scope.
Identifies for the IsAccessKeyScope dependency property.
Gets or sets a value that determines whether the DoubleTapped event can originate from that element.
Identifies the IsDoubleTapEnabled dependency property.
Gets or sets whether the contained area of this UIElement can return true values for hit testing.
Identifies the IsHitTestVisible dependency property.
Gets or sets a value that determines whether the Holding event can originate from that element.
Identifies the IsHoldingEnabled dependency property.
Gets or sets a value that determines whether the RightTapped event can originate from that element.
Identifies the IsRightTapEnabled dependency property.
Gets or sets a value that determines whether the Tapped event can originate from that element.
Identifies the IsTapEnabled dependency property.
Gets or sets a value that indicates whether the control tooltip displays the key combination for it's associated keyboard accelerator.
Identifies the KeyboardAcceleratorPlacementMode dependency property.
Gets or sets a value that indicates the control tooltip that displays the accelerator key combination.
Identifies the KeyboardAcceleratorPlacementTarget dependency property.
Gets the collection of key combinations that invoke an action using the keyboard.
Accelerators are typically assigned to buttons or menu items.
Gets the identifier for the KeyDown routed event.
Gets or sets a value that indicates how far left or right the Key Tip is placed in relation to the UIElement.
Identifies the KeyTipHorizontalOffset dependency property.
Gets or sets a value that indicates where the access key Key Tip is placed in relation to the boundary of the UIElement.
Identifies the KeyTipPlacementMode dependency property.
Gets or sets a value that indicates the element targeted by the access key Key Tip.
Identifies the KeyTipTarget dependency property.
Gets or sets a value that indicates how far up or down the Key Tip is placed in relation to the UI element.
Identifies the KeyTipVerticalOffset dependency property.
Gets the identifier for the KeyUp routed event.
Gets the collection of XamlLight objects attached to this element.
Identifies the Lights dependency property.
Gets the identifier for the LosingFocus routed event.
Gets the identifier for the ManipulationCompleted routed event.
Gets the identifier for the ManipulationDelta routed event.
Gets the identifier for the ManipulationInertiaStarting routed event.
Identifies the ManipulationMode dependency property.
Gets the identifier for the ManipulationStarted routed event.
Gets the identifier for the ManipulationStarting routed event.
Gets the identifier for the NoFocusCandidateFound routed event.
Gets or sets the degree of the object's opacity.
Identifies the IsHitTestVisible dependency property.
Gets or sets the ScalarTransition that animates changes to the Opacity property.
Gets the identifier for the PointerCanceled routed event.
Gets the identifier for the PointerCaptureLost routed event.
Gets the set of all captured pointers, represented as Pointer values.
Identifies the PointerCaptures dependency property.
Gets the identifier for the PointerEntered routed event.
Gets the identifier for the PointerExited routed event.
Gets the identifier for the PointerMoved routed event.
Gets the identifier for the PointerPressed routed event.
Gets the identifier for the PointerReleased routed event.
Gets the identifier for the PointerWheelChanged routed event.
Gets the identifier for the PreviewKeyDown routed event.
Gets the identifier for the PreviewKeyUp routed event.
Gets or sets the perspective projection (3-D effect) to apply when rendering this element.
Identifies the Projection dependency property.
Gets the final render size of a UIElement. Use is not recommended, see Remarks.
Gets or sets transform information that affects the rendering position of a UIElement.
Identifies the RenderTransformOrigin dependency property.
Identifies the RenderTransform dependency property.
Gets the identifier for the RightTapped routed event.
Gets or sets the angle of clockwise rotation, in degrees. Rotates relative to the RotationAxis and the CenterPoint. Affects the rendering position of the element.
Gets or sets the axis to rotate the element around.
Gets or sets the ScalarTransition that animates changes to the Rotation property.
Gets or sets the scale of the element. Scales relative to the element's CenterPoint. Affects the rendering position of the element.
Gets or sets the Vector3Transition that animates changes to the Scale property.
Gets or sets the shadow effect cast by the element.
Identifies the Shadow dependency property.
Gets or sets a value that modifies how tabbing and TabIndex work for this control.
Identifies the TabFocusNavigation dependency property.
Gets the identifier for the Tapped routed event.
Gets or sets the 3-D transform effect to apply when rendering this element.
Identifies the Transform3D dependency property.
Gets or sets the transformation matrix to apply to the element.
Identifies the Transitions dependency property.
Gets or sets the x, y, and z rendering position of the element.
Gets or sets the Vector3Transition that animates changes to the Translation property.
Gets or sets a value that determines whether rendering for the object and its visual subtree should use rounding behavior that aligns rendering to whole pixels.
Identifies the UseLayoutRounding dependency property.
Identifies the Visibility dependency property.
Gets or sets the XamlRoot in which this element is being viewed.
Gets or sets a value that specifies the strategy used to determine the target element of a down navigation.
Identifies the XYFocusDownNavigationStrategy dependency property.
Gets or sets a value that enables or disables navigation using the keyboard directional arrows.
Identifies the XYFocusKeyboardNavigation dependency property.
Gets or sets a value that specifies the strategy used to determine the target element of a left navigation.
Identifies the XYFocusLeftNavigationStrategy dependency property.
Gets or sets a value that specifies the strategy used to determine the target element of a right navigation.
Identifies the XYFocusRightNavigationStrategy dependency property.
Gets or sets a value that specifies the strategy used to determine the target element of an up navigation.
Identifies the XYFocusUpNavigationStrategy dependency property.
|AddHandler(RoutedEvent, Object, Boolean)||
Adds a routed event handler for a specified routed event, adding the handler to the handler collection on the current element. Specify handledEventsToo as true to have the provided handler be invoked even if the event is handled elsewhere.
Positions child objects and determines a size for a UIElement. Parent objects that implement custom layout for their child elements should call this method from their layout override implementations to form a recursive layout update.
Sets pointer capture to a UIElement. Once captured, only the element that has capture will fire pointer-related events.
Clears the local value of a dependency property.(Inherited from DependencyObject)
Enables a UIElement subclass to expose child elements that assist with resolving touch targeting.
Returns any base value established for a dependency property, which would apply in cases where an animation is not active.(Inherited from DependencyObject)
Enables a UIElement subclass to expose child elements that take part in Tab focus.
Returns the current effective value of a dependency property from a DependencyObject.(Inherited from DependencyObject)
Invalidates the measurement state (layout) for a UIElement.
Updates the DesiredSize of a UIElement. Typically, objects that implement custom layout for their layout children call this method from their own MeasureOverride implementations to form a recursive layout update.
Called before the BringIntoViewRequested event occurs.
When implemented in a derived class, returns class-specific AutomationPeer implementations for the Microsoft UI Automation infrastructure.
Override this method to implement how layout and logic should behave when items are removed from a class-specific content or children property.
Called when a keyboard shortcut (or accelerator) is processed in your app. Override this method to handle how your app responds when a keyboard accelerator is invoked.
Called just before a keyboard shortcut (or accelerator) is processed in your app. Invoked whenever application code or internal processes call ProcessKeyboardAccelerators. Override this method to influence the default accelerator handling.
Defines a property that can be animated.
When overridden in a derived class, defines a property that can be animated.
Returns the local value of a dependency property, if a local value is set.(Inherited from DependencyObject)
Registers an element as representing a scrollable viewport.
Releases pointer captures for capture of one specific pointer by this UIElement.
Releases all pointer captures held by this element.
Sets the local value of a dependency property on a DependencyObject.(Inherited from DependencyObject)
Begins the specified animation on the element.
Initiates a request to the XAML framework to bring the element into view within any scrollable regions it is contained within.
Initiates a request to the XAML framework to bring the element into view using the specified options.
Stops the specified animation on the element.
Returns a transform object that can be used to transform coordinates from the UIElement to the specified object.
Attempts to invoke a keyboard shortcut (or accelerator) by searching the entire visual tree of the UIElement for the shortcut.
Cancels a change notification that was previously registered by calling RegisterPropertyChangedCallback.(Inherited from DependencyObject)
Ensures that all positions of child objects of a UIElement are properly updated for layout.
Occurs when access keys should no longer be displayed.
Occurs when the user requests that access keys be displayed.
Occurs when a user completes an access key sequence.
Occurs when StartBringIntoView is called on this element or one of its descendants.
Occurs when a single, composed character is received by the input queue.
Occurs when a context input gesture continues into a manipulation gesture, to notify the element that the context flyout should not be opened.
Occurs when the user has completed a context input gesture, such as a right-click.
Occurs when an otherwise unhandled DoubleTap interaction occurs over the hit test area of this element.
Occurs when the input system reports an underlying drag event with this element as the target.
Occurs when the input system reports an underlying drag event with this element as the origin.
Occurs when the input system reports an underlying drag event with this element as the potential drop target.
Occurs when a drag operation is initiated.
Occurs when the input system reports an underlying drop event with this element as the drop target.
Occurs when a drag-and-drop operation with this element as the source is ended.
Occurs before a UIElement receives focus. This event is raised synchronously to ensure focus isn't moved while the event is bubbling.
Occurs when a UIElement receives focus. This event is raised asynchronously, so focus can move again before bubbling is complete.
Occurs when an otherwise unhandled Hold interaction occurs over the hit test area of this element.
Occurs when a keyboard key is pressed while the UIElement has focus.
Occurs when a keyboard key is released while the UIElement has focus.
Occurs before a UIElement loses focus. This event is raised synchronously to ensure focus isn't moved while the event is bubbling.
Occurs when a UIElement loses focus. This event is raised asynchronously, so focus can move again before bubbling is complete.
Occurs when a manipulation on the UIElement is complete.
Occurs when the input device changes position during a manipulation.
Occurs when the input device loses contact with the UIElement object during a manipulation and inertia begins.
Occurs when an input device begins a manipulation on the UIElement.
Occurs when the manipulation processor is first created.
Occurs when a user attempts to move focus (via tab or directional arrows), but focus doesn't move because no focus candidate is found in the direction of movement.
Occurs when a pointer that made contact abnormally loses contact.
Occurs when pointer capture previously held by this element moves to another element or elsewhere.
Occurs when a pointer enters the hit test area of this element.
Occurs when a pointer leaves the hit test area of this element.
Occurs when a pointer moves while the pointer remains within the hit test area of this element.
Occurs when the pointer device initiates a Press action within this element.
Occurs when the pointer device that previously initiated a Press action is released, while within this element. Note that the end of a Press action is not guaranteed to fire a PointerReleased event; other events may fire instead. For more info, see Remarks.
Occurs when the delta value of a pointer wheel changes.
Occurs when a keyboard key is pressed while the UIElement has focus.
Occurs when a keyboard key is released while the UIElement has focus.
Occurs when a keyboard shortcut (or accelerator) is pressed.
Occurs when a right-tap input stimulus happens while the pointer is over the element.
Occurs when an otherwise unhandled Tap interaction occurs over the hit test area of this element.