UIElement UIElement UIElement Class
Definition
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 class UIElement : DependencyObject, IUIElement, IUIElement2, IUIElement3, IUIElement4, IUIElement5, IUIElement7, IUIElementOverridespublic class UIElement : DependencyObject, IUIElement, IUIElement2, IUIElement3, IUIElement4, IUIElement5, IUIElement7, IUIElementOverridesPublic Class UIElement Inherits DependencyObject Implements IUIElement, IUIElement2, IUIElement3, IUIElement4, IUIElement5, IUIElement7, IUIElementOverrides
- Inheritance
- Attributes
| Device family |
Windows 10 (introduced v10.0.10240.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v1)
|
Inherited Members
Inherited methods
Inherited properties
Remarks
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 (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 (Control, ContentControl, UserControl )
- Navigation elements (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 Windows Store 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 **IsEnabled, ManipulationMode
Basic appearance
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.
Basic layout
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.
Routed events
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.
Prominent API of UIElement that support routed events: AddHandler, RemoveHandler, **Event* properties.
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 Windows Store 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.
Properties
AccessKey AccessKey AccessKey
Gets or sets the access key (mnemonic) for this element.
public PlatForm::String AccessKey { get; set; }public string AccessKey { get; set; }Public ReadWrite Property AccessKey As string
- Value
- string string string
The access key (mnemonic) for this element.
- Attributes
| Device family |
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v3)
|
Remarks
Setting this property enables the AccessKeyDisplayRequested event to be raised.
If the AutomationProperties.AccessKey attached property is not set, this property is used by the Automation framework instead. The value is used as case-insensitive, using the user language. It is used as text, so if an Input Method Editor (IME) is active the composed text is used.
AccessKeyProperty AccessKeyProperty AccessKeyProperty
Identifies for the AccessKey dependency property.
public static DependencyProperty AccessKeyProperty { get; }public static DependencyProperty AccessKeyProperty { get; }Public Static ReadOnly Property AccessKeyProperty As DependencyProperty
The identifier for the AccessKey dependency property.
- Attributes
| Device family |
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v3)
|
AccessKeyScopeOwner AccessKeyScopeOwner AccessKeyScopeOwner
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.
public DependencyObject AccessKeyScopeOwner { get; set; }public DependencyObject AccessKeyScopeOwner { get; set; }Public ReadWrite Property AccessKeyScopeOwner As DependencyObject
The element that defines the access key scope.
- Attributes
| Device family |
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v3)
|
Remarks
The source element must have it's IsAccessKeyScope property set to true.
AccessKeyScopeOwnerProperty AccessKeyScopeOwnerProperty AccessKeyScopeOwnerProperty
Identifies for the AccessKeyScopeOwner dependency property.
public static DependencyProperty AccessKeyScopeOwnerProperty { get; }public static DependencyProperty AccessKeyScopeOwnerProperty { get; }Public Static ReadOnly Property AccessKeyScopeOwnerProperty As DependencyProperty
The identifier for the AccessKeyScopeOwner dependency property.
- Attributes
| Device family |
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v3)
|
AllowDrop AllowDrop AllowDrop
Gets or sets a value that determines whether this UIElement can be a drop target for purposes of drag-and-drop operations.
public PlatForm::Boolean AllowDrop { get; set; }public bool AllowDrop { get; set; }Public ReadWrite Property AllowDrop As bool
<uiElement AllowDrop="bool"/>
- Value
- bool bool bool
true if this UIElement can be a drop target for purposes of drag-and-drop operations; otherwise, false. The default is false.
- Attributes
Remarks
The value of AllowDrop determines whether various events related to being a drop target or responding to being dragged over can be handled. Such events only can be handled if AllowDrop is true on the UIElement that is a potential drop target. These events are:
- DragEnter
- DragLeave
- DragOver
- Drop Each of the listed events is a routed event. If you want to handle a bubbling drag-drop event, the potential drop target must have AllowDrop set to true, and the object where the event is handled must have AllowDrop set to true. For more info on routed event concepts, see Events and routed events overview.
The Windows Runtime implementation of drag-drop concepts permits only certain controls and input actions to initiate a drag-drop action. There is no generalized DoDragDrop method that would permit any UI element to initiate a drag-drop action. The main source of a drag-drop action in an app is when you drag the items of a list such as GridView. However once the action is initiated, any UIElement in the app can potentially be a drop target so long as AllowDrop is true on that element. Any elements that the drag-drop action passes over can handle DragEnter, DragLeave or DragOver. The initiating list view does not require AllowDrop. Instead, the value of CanDragItems is used to determine whether the items in the list can be used to start a drag-drop action.
A UI element can't be a drop target for any drag-drop action that begins from outside the current Windows Store app. This includes actions that come from another Windows Store app, which is possible for a snapped view.
- See Also
AllowDropProperty AllowDropProperty AllowDropProperty
Identifies the AllowDrop dependency property.
public static DependencyProperty AllowDropProperty { get; }public static DependencyProperty AllowDropProperty { get; }Public Static ReadOnly Property AllowDropProperty As DependencyProperty
The identifier for the AllowDrop dependency property.
- Attributes
CacheMode CacheMode CacheMode
Gets or sets a value that indicates that rendered content should be cached as a composited bitmap when possible.
public CacheMode CacheMode { get; set; }public CacheMode CacheMode { get; set; }Public ReadWrite Property CacheMode As CacheMode
<uiElement CacheMode="BitmapCache" />
A value that indicates that rendered content should be cached as a composited bitmap when possible. If you specify a value of CacheMode, rendering operations from RenderTransform and Opacity execute on the graphics processing unit (GPU), if available. The default is null, which does not enable a cached composition mode.
- Attributes
Remarks
Set this value to enable the caching behavior that offloads RenderTransform and Opacity bitmaps to the graphics processing unit (GPU). Otherwise, leave it as null.
For XAML, the string literal "BitmapCache" is the only enabled value you can use to set CacheMode as an attribute.
Note
BitmapCache is the only existing practical derived classes in the Windows Runtime API that enables this behavior (the CacheMode type is an intermediate type that exists only for infrastructure and legacy reasons).
If setting CacheMode in code, set it to a new value of BitmapCache, like this:
canvas1.CacheMode = new BitmapCache(); //canvas1 is an existing named element in UI
canvas1->CacheMode = ref new BitmapCache(); //canvas1 is an existing named element in UI
Do not generally apply CacheMode values to elements without testing and profiling first. Caching to the graphics processing unit (GPU) is intended only for a minority of possible rendering situations for an app, and it's expected that you will profile various combinations of when and where in your UI to apply a CacheMode setting. Overuse of CacheMode can hurt performance rather than help it. It’s best to profile the app surface area to determine which targeted areas are most expensive to render, and to experiment with caching only certain elements based on those results. For more info on how to profile for rendering, see IsOverdrawHeatMapEnabled and "Cache static content" section of the Optimize your XAML markup topic.
Avoid using CacheMode and storyboarded animations together. Caching content where Opacity or RenderTransform are animated causes the animations to become dependent animations, even if the animation is zero-duration. To even see those animations run you'd have to set EnableDependentAnimation to true, and a dependent animation usually invalidates all the performance gains you might get from caching the composition. Opacity often is animated by visual states in control templates, so this is a consideration even if you aren't declaring any of your own storyboarded animations in XAML pages.
- See Also
CacheModeProperty CacheModeProperty CacheModeProperty
Identifies the CacheMode dependency property.
public static DependencyProperty CacheModeProperty { get; }public static DependencyProperty CacheModeProperty { get; }Public Static ReadOnly Property CacheModeProperty As DependencyProperty
The identifier for the CacheMode dependency property.
- Attributes
CanDrag CanDrag CanDrag
Gets or sets a value that indicates whether the element can be dragged as data in a drag-and-drop operation.
public PlatForm::Boolean CanDrag { get; set; }public bool CanDrag { get; set; }Public ReadWrite Property CanDrag As bool
- Value
- bool bool bool
true if the element can be dragged as data in a drag-and-drop operation; otherwise, false. The default is false.
- Attributes
Remarks
CanDragProperty CanDragProperty CanDragProperty
Clip Clip Clip
Gets or sets the RectangleGeometry used to define the outline of the contents of a UIElement.
public RectangleGeometry Clip { get; set; }public RectangleGeometry Clip { get; set; }Public ReadWrite Property Clip As RectangleGeometry
<uiElement>
<uiElement.Clip>
rectangleGeometry
</uiElement.Clip>
</uiElement>
The rectangle geometry to be used for clipping area sizing. The default value is null (no clipping).
- Attributes
Remarks
The clipping geometry for UIElement.Clip in the Windows Runtime API must be a RectangleGeometry. You can't specify a non-rectangular geometry, as is permitted in some XAML frameworks like Microsoft Silverlight.
The clipped area is the "outside" of the geometry. In other words, the content that is shown (not clipped) is the area of the rectangle that is drawn with Fill if the geometry were used as data for a Path rather than for clipping. The clipped area is any area that falls outside the rectangle. The clipped area isn't hit-testable.
Examples
This example is simple XAML markup that specifies a Clip using an inline RectangleGeometry that specifies its dimensions through an attribute syntax.
<Canvas>
<Image Source="Images/Water_lilies.jpg" Width="200" Height="150">
<Image.Clip>
<RectangleGeometry Rect="100 75 50 50"/>
</Image.Clip>
</Image>
</Canvas>
ClipProperty ClipProperty ClipProperty
CompositeMode CompositeMode CompositeMode
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.
public ElementCompositeMode CompositeMode { get; set; }public ElementCompositeMode CompositeMode { get; set; }Public ReadWrite Property CompositeMode As ElementCompositeMode
<uiElement CompositeMode="elementCompositeModeMemberName" />
A value of the enumeration. The default is Inherit, but see Remarks.
- Attributes
Remarks
If left unset, the default value of CompositeMode is ElementCompositeMode.Inherits. This means that the composite mode inherits from successive parents in the visual tree. However, at the root of a XAML visual tree is a final object representing the hWnd that is not typically represented in user code, and its effective CompositeMode behavior is SourceOver. Therefore, unless some element in the chain is specifically set to MinBlend, the render behavior of XAML elements all inherit to use SourceOver as inherited from the parent window.
Setting CompositeMode to MinBlend is useful for a mixed XAML / Microsoft DirectX UI because it is information used by the Direct Composition layer when it combines the UI sources. The MinBlend behavior can be better for situations such as text overlays.
Setting a value of MinBlend is typically most relevant for a SwapChainPanel element, so that the hosted content gets this behavior. But for some scenarios such as text overlays it can also be set on specific UI elements such as Rectangle, Canvas and so on.
- See Also
CompositeModeProperty CompositeModeProperty CompositeModeProperty
Identifies the CompositeMode dependency property.
public static DependencyProperty CompositeModeProperty { get; }public static DependencyProperty CompositeModeProperty { get; }Public Static ReadOnly Property CompositeModeProperty As DependencyProperty
The identifier for the CompositeMode dependency property.
- Attributes
ContextFlyout ContextFlyout ContextFlyout
Gets or sets the flyout associated with this element.
public FlyoutBase ContextFlyout { get; set; }public FlyoutBase ContextFlyout { get; set; }Public ReadWrite Property ContextFlyout As FlyoutBase
- Value
- FlyoutBase FlyoutBase FlyoutBase
The flyout associated with this element, if any; otherwise, null. The default is null.
- Attributes
| Device family |
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v3)
|
ContextFlyoutProperty ContextFlyoutProperty ContextFlyoutProperty
Identifies for the ContextFlyout dependency property.
public static DependencyProperty ContextFlyoutProperty { get; }public static DependencyProperty ContextFlyoutProperty { get; }Public Static ReadOnly Property ContextFlyoutProperty As DependencyProperty
The identifier for the ContextFlyout dependency property.
- Attributes
| Device family |
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v3)
|
DesiredSize DesiredSize DesiredSize
Gets the size that this UIElement computed during the measure pass of the layout process.
public Size DesiredSize { get; }public Size DesiredSize { get; }Public ReadOnly Property DesiredSize As Size
The size that this UIElement computed during the measure pass of the layout process.
- Attributes
Remarks
DesiredSize is typically checked as one of the measurement factors when you implement layout behavior overrides such as ArrangeOverride or MeasureOverride. Depending on the parent container's layout logic, DesiredSize might be fully respected, constraints on DesiredSize might be applied, and such constraints might also change other characteristics of either the parent element or child element. For example, a control that supports scrollable regions (but chooses not to derive from the controls that already enable scrollable regions) could compare available size to DesiredSize. The control could then set an internal state that enabled scrollbars in the UI for that control. Or, DesiredSize could be ignored and the element always gets a layout that is sized by other considerations such as checking attached property values.
DesiredSize won't contain a useful value unless at least one "Measure" pass of layout has run on the element.
DesiredSize is really only intended for use when you define your own layout override methods. If you're just interested in the size of an element in your app's UI at run time, then you should use the ActualWidth and ActualHeight properties instead. You might be checking size this way if an element is influenced by dynamic layout techniques such as star sizing of Grid cells. Rely on ActualWidth and ActualHeight values only in situations that are sure to be after layout has run: for example, in Loaded events, or triggered by user actions that are only possible after the UI has been rendered initially.
Examples
This example queries DesiredSize as part of the child iteration for an ArrangeOverride implementation.
// Second arrange all children and return final size of panel
protected override Size ArrangeOverride(Size finalSize)
{
// Get the collection of children
UIElementCollection mychildren = Children;
// Get total number of children
int count = mychildren.Count;
// Arrange children
// We're only allowing 9 children in this panel. More children will get a 0x0 layout slot.
int i;
for (i = 0; i < 9; i++)
{
// Get (left, top) origin point for the element in the 3x3 block
Point cellOrigin = GetOrigin(i, 3, new Size(100, 100));
// Arrange child
// Get desired height and width. This will not be larger than 100x100 as set in MeasureOverride.
double dw = mychildren[i].DesiredSize.Width;
double dh = mychildren[i].DesiredSize.Height;
mychildren[i].Arrange(new Rect(cellOrigin.X, cellOrigin.Y, dw, dh));
}
// Give the remaining children a 0x0 layout slot
for (i = 9; i < count; i++)
{
mychildren[i].Arrange(new Rect(0, 0, 0, 0));
}
// Return final size of the panel
return new Size(300, 300);
}
'Second arrange all children and return final size of panel
Protected Overrides Function ArrangeOverride(ByVal finalSize As Size) As Size
'Get the collection of children
Dim mychildren As UIElementCollection = Children
'Get total number of children
Dim count As Integer = mychildren.Count
'Arrange children
'only allowing 9 children in this panel. More children will get a 0x0 layout slot.
Dim i As Integer
For i = 0 To 8
'Get (left, top) origin point for the element in the 3x3 block
Dim cellOrigin As Point = GetOrigin(i, 3, New Size(100, 100))
'Arrange child
'Get desired height and width. This will not be larger than 100x100 as set in MeasureOverride.
Dim dw As Double = mychildren(i).DesiredSize.Width
Dim dh As Double = mychildren(i).DesiredSize.Height
mychildren(i).Arrange(New Rect(cellOrigin.X, cellOrigin.Y, dw, dh))
Next
For i = 9 To count - 1
'Give the remaining children a 0x0 layout slot
mychildren(i).Arrange(New Rect(0, 0, 0, 0))
Next
'Return final size of the panel
Return New Size(300, 300)
End Function
'Calculate point origin of the Block you are in
Protected Function GetOrigin(ByVal blockNum As Integer, ByVal blocksPerRow As Integer, ByVal itemSize As Size) As Point
'Get row number (zero-based)
Dim row As Integer = CInt(Math.Floor(blockNum / blocksPerRow))
'Get column number (zero-based)
Dim column As Integer = blockNum - blocksPerRow * row
'Calculate origin
Dim origin As New Point(itemSize.Width * column, itemSize.Height * row)
Return origin
End Function
DoubleTappedEvent DoubleTappedEvent DoubleTappedEvent
Gets the identifier for the DoubleTapped routed event.
public static RoutedEvent DoubleTappedEvent { get; }public static RoutedEvent DoubleTappedEvent { get; }Public Static ReadOnly Property DoubleTappedEvent As RoutedEvent
The identifier for the DoubleTapped routed event.
- Attributes
- See Also
DragEnterEvent DragEnterEvent DragEnterEvent
DragLeaveEvent DragLeaveEvent DragLeaveEvent
DragOverEvent DragOverEvent DragOverEvent
DropEvent DropEvent DropEvent
ExitDisplayModeOnAccessKeyInvoked ExitDisplayModeOnAccessKeyInvoked ExitDisplayModeOnAccessKeyInvoked
Gets or sets a value that specifies whether the access key display is dismissed when an access key is invoked.
public PlatForm::Boolean ExitDisplayModeOnAccessKeyInvoked { get; set; }public bool ExitDisplayModeOnAccessKeyInvoked { get; set; }Public ReadWrite Property ExitDisplayModeOnAccessKeyInvoked As bool
- Value
- bool bool bool
true to dismiss the access key display when an access key is invoked; otherwise, false.
- Attributes
| Device family |
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v3)
|
ExitDisplayModeOnAccessKeyInvokedProperty ExitDisplayModeOnAccessKeyInvokedProperty ExitDisplayModeOnAccessKeyInvokedProperty
Identifies the ExitDisplayModeOnAccessKeyInvoked dependency property.
public static DependencyProperty ExitDisplayModeOnAccessKeyInvokedProperty { get; }public static DependencyProperty ExitDisplayModeOnAccessKeyInvokedProperty { get; }Public Static ReadOnly Property ExitDisplayModeOnAccessKeyInvokedProperty As DependencyProperty
The identifier for the ExitDisplayModeOnAccessKeyInvoked dependency property.
- Attributes
| Device family |
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v3)
|
GettingFocusEvent GettingFocusEvent GettingFocusEvent
Gets the identifier for the GettingFocus routed event.
public static RoutedEvent GettingFocusEvent { get; }public static RoutedEvent GettingFocusEvent { get; }Public Static ReadOnly Property GettingFocusEvent As RoutedEvent
The identifier for the GettingFocus routed event.
- Attributes
| Device family |
Windows 10 Creators Update (introduced v10.0.15063.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v4)
|
- See Also
HighContrastAdjustment HighContrastAdjustment HighContrastAdjustment
Gets or sets a value that indicates whether the framework automatically adjusts the element's visual properties when high contrast themes are enabled.
public ElementHighContrastAdjustment HighContrastAdjustment { get; set; }public ElementHighContrastAdjustment HighContrastAdjustment { get; set; }Public ReadWrite Property HighContrastAdjustment As ElementHighContrastAdjustment
A value of the enumeration that indicates whether the framework automatically adjusts the element's visual properties when high contrast themes are enabled. The default is Application.
- Attributes
| Device family |
Windows 10 Creators Update (introduced v10.0.15063.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v4)
|
Remarks
The value of the property is inherited. When set to Application the adjustment will mirror what is set for the Application 's HighContrastAdjustment property. Setting the Application 's HighContrastAdjustment property to None will effectively disable it for all UI in the application. It can be selectively enabled for a UIElement by explicitly setting the value to Auto.
When set to Auto, the framework automatically applies the following adjustments to XAML's text elements while a high contrast theme is enabled:
- The foreground color on text is ignored. The text is colored using either the system’s high contrast text color or the disabled color when in a parent Control where IsEnabled = "False".
- An opaque rectangle is rendered immediately behind the text to enforce a high contrast ratio.
- Non-zero values for Opacity are ignored. The element and it's children will appear as if they had an opacity of 1.0.
It is possible to set HighContrastAdjustment = None on a UIElement and then have HighContrastAdjustment = Auto on one of its descendants. However, the framework does not guarantee that the descendent will be fully opaque if an opacity is applied on any of its ancestors.
HighContrastAdjustmentProperty HighContrastAdjustmentProperty HighContrastAdjustmentProperty
Identifies the HighContrastAdjustment dependency property.
public static DependencyProperty HighContrastAdjustmentProperty { get; }public static DependencyProperty HighContrastAdjustmentProperty { get; }Public Static ReadOnly Property HighContrastAdjustmentProperty As DependencyProperty
The identifier for the HighContrastAdjustment dependency property.
- Attributes
| Device family |
Windows 10 Creators Update (introduced v10.0.15063.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v4)
|
HoldingEvent HoldingEvent HoldingEvent
IsAccessKeyScope IsAccessKeyScope IsAccessKeyScope
Gets or sets a value that indicates whether an element defines its own access key scope.
public PlatForm::Boolean IsAccessKeyScope { get; set; }public bool IsAccessKeyScope { get; set; }Public ReadWrite Property IsAccessKeyScope As bool
- Value
- bool bool bool
true if an element defines its own scope; otherwise, false.
- Attributes
| Device family |
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v3)
|
IsAccessKeyScopeProperty IsAccessKeyScopeProperty IsAccessKeyScopeProperty
Identifies for the IsAccessKeyScope dependency property.
public static DependencyProperty IsAccessKeyScopeProperty { get; }public static DependencyProperty IsAccessKeyScopeProperty { get; }Public Static ReadOnly Property IsAccessKeyScopeProperty As DependencyProperty
The identifier for the IsAccessKeyScope dependency property.
- Attributes
| Device family |
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v3)
|
IsDoubleTapEnabled IsDoubleTapEnabled IsDoubleTapEnabled
Gets or sets a value that determines whether the DoubleTapped event can originate from that element.
public PlatForm::Boolean IsDoubleTapEnabled { get; set; }public bool IsDoubleTapEnabled { get; set; }Public ReadWrite Property IsDoubleTapEnabled As bool
<uiElement IsDoubleTapEnabled="bool" />
- Value
- bool bool bool
true if a DoubleTapped event can originate from this element; otherwise, false.
- Attributes
Remarks
The default is true (event enabled). If you set to false, the UIElement will no longer source the DoubleTapped event. This might be desirable if a parent element such as a list control should instead process the action as a manipulation, or if you want to specify that only some child items emit a DoubleTapped event that a parent handles after bubbling.
Another reason to suppress gesture events is if you are handling pointer-level events and don't want gesture recognition logic to impact how the pointer events are fired. For example, if the gesture recognition engine has to test for Tapped, then it must delay firing a PointerMoved event for small movements, because the user might lift the touch point soon and the input event would normally be gesture-recognized as a tap.
- See Also
IsDoubleTapEnabledProperty IsDoubleTapEnabledProperty IsDoubleTapEnabledProperty
Identifies the IsDoubleTapEnabled dependency property.
public static DependencyProperty IsDoubleTapEnabledProperty { get; }public static DependencyProperty IsDoubleTapEnabledProperty { get; }Public Static ReadOnly Property IsDoubleTapEnabledProperty As DependencyProperty
The identifier for the IsDoubleTapEnabled dependency property.
- Attributes
IsHitTestVisible IsHitTestVisible IsHitTestVisible
Gets or sets whether the contained area of this UIElement can return true values for hit testing.
public PlatForm::Boolean IsHitTestVisible { get; set; }public bool IsHitTestVisible { get; set; }Public ReadWrite Property IsHitTestVisible As bool
<uiElement IsHitTestVisible="bool"/>
- Value
- bool bool bool
true if the contained area of this UIElement can be used for hit testing; otherwise, false. The default is true.
- Attributes
IsHitTestVisibleProperty IsHitTestVisibleProperty IsHitTestVisibleProperty
Identifies the IsHitTestVisible dependency property.
public static DependencyProperty IsHitTestVisibleProperty { get; }public static DependencyProperty IsHitTestVisibleProperty { get; }Public Static ReadOnly Property IsHitTestVisibleProperty As DependencyProperty
The identifier for the IsHitTestVisible dependency property.
- Attributes
IsHoldingEnabled IsHoldingEnabled IsHoldingEnabled
Gets or sets a value that determines whether the Holding event can originate from that element.
public PlatForm::Boolean IsHoldingEnabled { get; set; }public bool IsHoldingEnabled { get; set; }Public ReadWrite Property IsHoldingEnabled As bool
<uiElement IsHoldingEnabled="bool" />
- Value
- bool bool bool
true if a Holding event can originate from this element; otherwise, false.
- Attributes
Remarks
The default is true (event enabled). If you set to false, the UIElement will no longer source the Holding event. This might be desirable if a parent element such as a list control should instead process the action as a manipulation, or if you want to specify that only some child items emit a Holding event that a parent handles after bubbling.
Another reason to suppress gesture events is if you are handling pointer-level events and don't want gesture recognition logic to impact how the pointer events are fired. For example, if the gesture recognition engine has to test for Tapped, then it must delay firing a PointerMoved event for small movements, because the user might lift the touch point soon and the input event would normally be gesture-recognized as a tap. Also, Holding states might interfere with other pointer events, or generate theme animations, because of the progression through the Holding states that must be reported by gesture recognition.
- See Also
IsHoldingEnabledProperty IsHoldingEnabledProperty IsHoldingEnabledProperty
Identifies the IsHoldingEnabled dependency property.
public static DependencyProperty IsHoldingEnabledProperty { get; }public static DependencyProperty IsHoldingEnabledProperty { get; }Public Static ReadOnly Property IsHoldingEnabledProperty As DependencyProperty
The identifier for the IsHoldingEnabled dependency property.
- Attributes
IsRightTapEnabled IsRightTapEnabled IsRightTapEnabled
Gets or sets a value that determines whether the RightTapped event can originate from that element.
public PlatForm::Boolean IsRightTapEnabled { get; set; }public bool IsRightTapEnabled { get; set; }Public ReadWrite Property IsRightTapEnabled As bool
<uiElement IsRightTapEnabled="bool" />
- Value
- bool bool bool
true if a RightTapped event can originate from this element; otherwise, false.
- Attributes
Remarks
The default is true (event enabled). If you set to false, the UIElement will no longer source the RightTapped event. This might be desirable if a parent element such as a list control should instead process the action as a manipulation, or if you want to specify that only some child items emit a RightTapped event that a parent handles after bubbling.
Another reason to suppress gesture events is if you are handling pointer-level events and don't want gesture recognition logic to impact how the pointer events are fired. For example, if the gesture recognition engine has to test for Tapped, then it must delay firing a PointerMoved event for small movements, because the user might lift the touch point soon and the input event would normally be gesture-recognized as a tap.
You do not need a mouse device to produce a RightTapped event. A RightTapped event is generated if a touch event becomes a Holding event when the touch position remained in one place. Even though Holding and RightTapped might result from the same user touch action, the design guidance for what that event means to an app is different, as is the timing. For more info, see Quickstart: Touch input.
- See Also
IsRightTapEnabledProperty IsRightTapEnabledProperty IsRightTapEnabledProperty
Identifies the IsRightTapEnabled dependency property.
public static DependencyProperty IsRightTapEnabledProperty { get; }public static DependencyProperty IsRightTapEnabledProperty { get; }Public Static ReadOnly Property IsRightTapEnabledProperty As DependencyProperty
The identifier for the IsRightTapEnabled dependency property.
- Attributes
IsTapEnabled IsTapEnabled IsTapEnabled
Gets or sets a value that determines whether the Tapped event can originate from that element.
public PlatForm::Boolean IsTapEnabled { get; set; }public bool IsTapEnabled { get; set; }Public ReadWrite Property IsTapEnabled As bool
<uiElementIsTapEnabled="bool" />
- Value
- bool bool bool
true if a Tapped event can originate from this element; otherwise, false.
- Attributes
Remarks
The default is true (event enabled). If you set to false, the UIElement will no longer source the Tapped event. This might be desirable if a parent element such as a list control should instead process the action as a manipulation, or if you want to specify that only some child items emit a Tapped event that a parent handles after bubbling.
Another reason to suppress gesture events is if you are handling pointer-level events and don't want gesture recognition logic to impact how the pointer events are fired. For example, if the gesture recognition engine has to test for Tapped, then it must delay firing a PointerMoved event for small movements, because the user might lift the touch point soon and the input event would normally be gesture-recognized as a tap.
- See Also
IsTapEnabledProperty IsTapEnabledProperty IsTapEnabledProperty
Identifies the IsTapEnabled dependency property.
public static DependencyProperty IsTapEnabledProperty { get; }public static DependencyProperty IsTapEnabledProperty { get; }Public Static ReadOnly Property IsTapEnabledProperty As DependencyProperty
The identifier for the IsTapEnabled dependency property.
- Attributes
KeyDownEvent KeyDownEvent KeyDownEvent
KeyTipHorizontalOffset KeyTipHorizontalOffset KeyTipHorizontalOffset
Gets or sets a value that indicates how far left or right the keytip is placed in relation to the UIElement.
public double KeyTipHorizontalOffset { get; set; }public double KeyTipHorizontalOffset { get; set; }Public ReadWrite Property KeyTipHorizontalOffset As double
<uiElement KeyTipHorizontalOffset="double"/>
- Value
- double double double
The number of pixels to move the KeyTip. Positive values move it right. Negative values move it left.
- Attributes
| Device family |
Windows 10 Creators Update (introduced v10.0.15063.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v4)
|
KeyTipHorizontalOffsetProperty KeyTipHorizontalOffsetProperty KeyTipHorizontalOffsetProperty
Identifies the KeyTipHorizontalOffset dependency property.
public static DependencyProperty KeyTipHorizontalOffsetProperty { get; }public static DependencyProperty KeyTipHorizontalOffsetProperty { get; }Public Static ReadOnly Property KeyTipHorizontalOffsetProperty As DependencyProperty
The identifier for the KeyTipHorizontalOffset dependency property.
- Attributes
| Device family |
Windows 10 Creators Update (introduced v10.0.15063.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v4)
|
KeyTipPlacementMode KeyTipPlacementMode KeyTipPlacementMode
Gets or sets a value that indicates where the KeyTip is placed in relation to the UIElement.
public KeyTipPlacementMode KeyTipPlacementMode { get; set; }public KeyTipPlacementMode KeyTipPlacementMode { get; set; }Public ReadWrite Property KeyTipPlacementMode As KeyTipPlacementMode
<uiElement KeyTipPlacementMode="keyTipPlacementModeMemberName"/>
A value of the enumeration. The default is Auto.
- Attributes
| Device family |
Windows 10 Creators Update (introduced v10.0.15063.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v4)
|
KeyTipPlacementModeProperty KeyTipPlacementModeProperty KeyTipPlacementModeProperty
Identifies the KeyTipPlacementMode dependency property.
public static DependencyProperty KeyTipPlacementModeProperty { get; }public static DependencyProperty KeyTipPlacementModeProperty { get; }Public Static ReadOnly Property KeyTipPlacementModeProperty As DependencyProperty
The identifier for the KeyTipPlacementMode dependency property.
- Attributes
| Device family |
Windows 10 Creators Update (introduced v10.0.15063.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v4)
|
KeyTipVerticalOffset KeyTipVerticalOffset KeyTipVerticalOffset
Gets or sets a value that indicates how far up or down the keytip is placed in relation to the UIElement.
public double KeyTipVerticalOffset { get; set; }public double KeyTipVerticalOffset { get; set; }Public ReadWrite Property KeyTipVerticalOffset As double
<uiElement KeyTipVerticalOffset="double"/>
- Value
- double double double
The number of pixels to move the KeyTip. Positive values move it down. Negative values move it up.
- Attributes
| Device family |
Windows 10 Creators Update (introduced v10.0.15063.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v4)
|
KeyTipVerticalOffsetProperty KeyTipVerticalOffsetProperty KeyTipVerticalOffsetProperty
Identifies the KeyTipVerticalOffset dependency property.
public static DependencyProperty KeyTipVerticalOffsetProperty { get; }public static DependencyProperty KeyTipVerticalOffsetProperty { get; }Public Static ReadOnly Property KeyTipVerticalOffsetProperty As DependencyProperty
The identifier for the KeyTipVerticalOffset dependency property.
- Attributes
| Device family |
Windows 10 Creators Update (introduced v10.0.15063.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v4)
|
KeyUpEvent KeyUpEvent KeyUpEvent
Lights Lights Lights
Gets the collection of XamlLight objects attached to this element.
public IVector<XamlLight> Lights { get; }public IVector<XamlLight> Lights { get; }Public ReadOnly Property Lights As IVector<XamlLight>
<uielement>
<uielement.Lights>
oneOrMoreXamlLights
</uielement.Lights>
</uielement>
- Attributes
| Device family |
Windows 10 Creators Update (introduced v10.0.15063.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v4)
|
LightsProperty LightsProperty LightsProperty
Identifies the Lights dependency property.
public static DependencyProperty LightsProperty { get; }public static DependencyProperty LightsProperty { get; }Public Static ReadOnly Property LightsProperty As DependencyProperty
The identifier for the Lights dependency property.
- Attributes
| Device family |
Windows 10 Creators Update (introduced v10.0.15063.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v4)
|
LosingFocusEvent LosingFocusEvent LosingFocusEvent
Gets the identifier for the LosingFocus routed event.
public static RoutedEvent LosingFocusEvent { get; }public static RoutedEvent LosingFocusEvent { get; }Public Static ReadOnly Property LosingFocusEvent As RoutedEvent
The identifier for the LosingFocus routed event.
- Attributes
| Device family |
Windows 10 Creators Update (introduced v10.0.15063.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v4)
|
- See Also
ManipulationCompletedEvent ManipulationCompletedEvent ManipulationCompletedEvent
Gets the identifier for the ManipulationCompleted routed event.
public static RoutedEvent ManipulationCompletedEvent { get; }public static RoutedEvent ManipulationCompletedEvent { get; }Public Static ReadOnly Property ManipulationCompletedEvent As RoutedEvent
The identifier for the ManipulationCompleted routed event.
- Attributes
- See Also
ManipulationDeltaEvent ManipulationDeltaEvent ManipulationDeltaEvent
Gets the identifier for the ManipulationDelta routed event.
public static RoutedEvent ManipulationDeltaEvent { get; }public static RoutedEvent ManipulationDeltaEvent { get; }Public Static ReadOnly Property ManipulationDeltaEvent As RoutedEvent
The identifier for the ManipulationDelta routed event.
- Attributes
- See Also
ManipulationInertiaStartingEvent ManipulationInertiaStartingEvent ManipulationInertiaStartingEvent
Gets the identifier for the ManipulationInertiaStarting routed event.
public static RoutedEvent ManipulationInertiaStartingEvent { get; }public static RoutedEvent ManipulationInertiaStartingEvent { get; }Public Static ReadOnly Property ManipulationInertiaStartingEvent As RoutedEvent
The identifier for the ManipulationInertiaStarting routed event.
- Attributes
- See Also
ManipulationMode ManipulationMode ManipulationMode
Gets or sets the ManipulationModes value used for UIElement behavior and interaction with gestures. Setting this value enables handling the manipulation events from this element in app code.
public ManipulationModes ManipulationMode { get; set; }public ManipulationModes ManipulationMode { get; set; }Public ReadWrite Property ManipulationMode As ManipulationModes
<uiElement ManipulationMode="All"/>
-or-
<uiElement ManipulationMode="None"/>
-or-
<uiElement ManipulationMode="singleManipulationModesMemberName"/>
-or-
<uiElement ManipulationMode="relatedManipulationModesNames"/>
A value or values of the enumeration. The default is typically System, but this can vary on specific controls and elements. See Remarks.
- Attributes
Remarks
You must set the ManipulationMode to a value other than System or None if you want to handle manipulation events such as ManipulationStarted from UI elements in your app code. For more info on manipulations, see Quickstart: Touch input.
The typical default value of ManipulationMode is System rather than None. When the value is System, manipulations that originate from the element can be handled by the Windows Runtime infrastructure, which is based on the Direct Manipulation API. For example, ScrollViewer handles user manipulations in its control logic and processes them as scrolling actions for the control. The System value also enables personality animations that respond to manipulation events.
Slider and ToggleSwitch have default templates that set the ManipulationMode value to None, so None will be the default value you see at design time.
Specifying related manipulation modes
You can specify more than one of the flagwise ManipulationModes values as the value of the ManipulationMode property. This is possible in XAML using the comma syntax shown in the "XAML Values" section. For example, you can combine TranslateX, TranslateY, Rotate, and Scale, or any combination of these. However, not all combinations are valid. Validity is enforced only once ManipulationModes is used by a specific control, so issues with setting an invalid combination of ManipulationModes might not appear until run-time when values are applied.
- Don't combine Translate* values with TranslateRails* values, these are treated as mutually exclusive values.
- Don't combine the inertial values with the non-inertial values.
- The All value isn't the true additive value of all the flags (if values are compared bitwise). A value of All doesn't necessarily indicate that the combination of all the values is valid either, or that any specific value is set.
Windows 8 behavior
On Windows 8, setting ManipulationMode to a value that combines System with any other value will throw an exception, so some of the combinations mentioned above won't work for Windows 8. Starting with Windows 8.1, you can combine System with other values.
Apps that were compiled for Windows 8 but running on Windows 8.1 use the new behavior and permit combining System with other values.
- See Also
ManipulationModeProperty ManipulationModeProperty ManipulationModeProperty
Identifies the ManipulationMode dependency property.
public static DependencyProperty ManipulationModeProperty { get; }public static DependencyProperty ManipulationModeProperty { get; }Public Static ReadOnly Property ManipulationModeProperty As DependencyProperty
The identifier for the ManipulationMode dependency property.
- Attributes
ManipulationStartedEvent ManipulationStartedEvent ManipulationStartedEvent
Gets the identifier for the ManipulationStarted routed event.
public static RoutedEvent ManipulationStartedEvent { get; }public static RoutedEvent ManipulationStartedEvent { get; }Public Static ReadOnly Property ManipulationStartedEvent As RoutedEvent
The identifier for the ManipulationStarted routed event.
- Attributes
- See Also
ManipulationStartingEvent ManipulationStartingEvent ManipulationStartingEvent
Gets the identifier for the ManipulationStarting routed event.
public static RoutedEvent ManipulationStartingEvent { get; }public static RoutedEvent ManipulationStartingEvent { get; }Public Static ReadOnly Property ManipulationStartingEvent As RoutedEvent
The identifier for the ManipulationStarting routed event.
- Attributes
- See Also
NoFocusCandidateFoundEvent NoFocusCandidateFoundEvent NoFocusCandidateFoundEvent
Gets the identifier for the NoFocusCandidateFound routed event.
public static RoutedEvent NoFocusCandidateFoundEvent { get; }public static RoutedEvent NoFocusCandidateFoundEvent { get; }Public Static ReadOnly Property NoFocusCandidateFoundEvent As RoutedEvent
The identifier for the NoFocusCandidateFound routed event.
- Attributes
| Device family |
Windows 10 Creators Update (introduced v10.0.15063.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v4)
|
- See Also
Opacity Opacity Opacity
Gets or sets the degree of the object's opacity.
public double Opacity { get; set; }public double Opacity { get; set; }Public ReadWrite Property Opacity As double
<uiElement Opacity="double" .../>
- Value
- double double double
A value between 0 and 1.0 that declares the opacity factor, with 1.0 meaning full opacity and 0 meaning transparent. The default value is 1.0.
- Attributes
Remarks
When Opacity is set on objects that are nested, the effective opacity for rendering is the product of all applicable opacity factors. For example, if an object that has Opacity=0.5 is contained in a Canvas that is also Opacity=0.5, the effective Opacity value for rendering is 0.25. Opacity values greater than 1.0 are treated as 1.0 when the value is used, although obtaining the property value will still give you the original greater-than-one value. Opacity values set as less than 0 are treated as 0 when the value is used. In the factoring logic, setting an Opacity to 2 to cancel out the effects of being contained by an object with 0.5 Opacity does not work; the 2 value is treated as 1.0 even before the nested-object factoring is calculated.
Opacity is a property that's sometimes animated in visual state storyboards, with zero duration. For example, the focus rectangle for "FocusStates" visual states is set with Opacity="0" in the original control template, because you don't want this rectangle to appear in a default non-focused states. But the visual states define a zero-duration "Focused" state that sets Opacity to 1 when the control using these templates and states has detected that it's keyboard-focused. For more info on this usage of Opacity, see Storyboarded animations for visual states.
Opacity and hit-testing
An Opacity value of 0 does not exclude an object from hit testing. This behavior can be useful for creating imagemap-style overlays that are drawn on top of the rest of the UI. For example, you can use a Canvas that has two children: a Rectangle that has a Height, a Width and an Opacity of 0, and the layout root of the rest of the UI that should draw underneath. By default children of a Canvas draw on top of each other in the same absolute coordinate system. Make sure that the ZIndex value of the Rectangle is higher than the other element's ZIndex (or declare the Rectangle after the other element in XAML element order to get the same result.) Wire your hit-testing logic (combines PointerRoutedEventArgs.GetCurrentPoint and VisualTreeHelper.FindElementsInHostCoordinates ) to the PointerPressed event for the Rectangle.
Alternatively, in order to exclude an object from hit testing, you should set IsHitTestVisible to false, rather than using Opacity.
Examples
This example uses a Storyboard and DoubleAnimation to target Opacity. This animates the Opacity to create an app-specific decorative fade-in animation over a one second duration.
<UserControl x:Class="animation_ovw_intro.Page"
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
Width="400" Height="300">
<StackPanel>
<StackPanel.Resources>
<!-- Animates the rectangle's opacity. -->
<Storyboard x:Name="myStoryboard">
<DoubleAnimation
Storyboard.TargetName="MyAnimatedRectangle"
Storyboard.TargetProperty="Opacity"
From="1.0" To="0.0" Duration="0:0:1"
AutoReverse="True"
RepeatBehavior="Forever"/>
</Storyboard>
</StackPanel.Resources>
<TextBlock Margin="10">Click on the rectangle to start the animation.</TextBlock>
<Rectangle PointerPressed="Item_Clicked"
x:Name="MyAnimatedRectangle"
Width="100" Height="100" Fill="Blue" />
</StackPanel>
</UserControl>
' When the user clicks the Rectangle, the animation
' begins.
Private Sub Pointer_Clicked(ByVal sender As Object, ByVal e As PointerRoutedEventArgs)
myStoryboard.Begin()
End Sub
- See Also
OpacityProperty OpacityProperty OpacityProperty
Identifies the IsHitTestVisible dependency property.
public static DependencyProperty OpacityProperty { get; }public static DependencyProperty OpacityProperty { get; }Public Static ReadOnly Property OpacityProperty As DependencyProperty
The identifier for the IsHitTestVisible dependency property.
- Attributes
PointerCanceledEvent PointerCanceledEvent PointerCanceledEvent
Gets the identifier for the PointerCanceled routed event.
public static RoutedEvent PointerCanceledEvent { get; }public static RoutedEvent PointerCanceledEvent { get; }Public Static ReadOnly Property PointerCanceledEvent As RoutedEvent
The identifier for the PointerCanceled routed event.
- Attributes
- See Also
PointerCaptureLostEvent PointerCaptureLostEvent PointerCaptureLostEvent
Gets the identifier for the PointerCaptureLost routed event.
public static RoutedEvent PointerCaptureLostEvent { get; }public static RoutedEvent PointerCaptureLostEvent { get; }Public Static ReadOnly Property PointerCaptureLostEvent As RoutedEvent
The identifier for the PointerCaptureLost routed event.
- Attributes
- See Also
PointerCaptures PointerCaptures PointerCaptures
Gets the set of all captured pointers, represented as Pointer values.
public IVectorView<Pointer> PointerCaptures { get; }public IVectorView<Pointer> PointerCaptures { get; }Public ReadOnly Property PointerCaptures As IVectorView<Pointer>
- Value
The collection of captured pointers, each represented as a Pointer object.
- Attributes
Remarks
For more info on how to capture a pointer and why you might want to do so, see CapturePointer.
Because there are input scenarios such as manipulations that involve more than one pointer point, the Windows Runtime enables capturing more than one pointer at a time. The PointerCaptures property exposes a view of which pointer points are currently captured by the UIElement.
This property's value is calculated based on the results of other actions. Calling CapturePointer adds to the internal collection that PointerCaptures provides a read-only view of. Calling ReleasePointerCapture removes from the collection. ReleasePointerCaptures clears the collection. User action that invalidates pointer capture such as releasing from a pointer point also changes capture state and thus the collection. For more info, see Mouse interactions and Handle pointer input.
The collection is not necessarily indexed by PointerId. To find a specific PointerId, you must check the items in the collection and reference a specific Pointer.
- See Also
PointerCapturesProperty PointerCapturesProperty PointerCapturesProperty
Identifies the PointerCaptures dependency property.
public static DependencyProperty PointerCapturesProperty { get; }public static DependencyProperty PointerCapturesProperty { get; }Public Static ReadOnly Property PointerCapturesProperty As DependencyProperty
The identifier for the PointerCaptures dependency property.
- Attributes
PointerEnteredEvent PointerEnteredEvent PointerEnteredEvent
Gets the identifier for the PointerEntered routed event.
public static RoutedEvent PointerEnteredEvent { get; }public static RoutedEvent PointerEnteredEvent { get; }Public Static ReadOnly Property PointerEnteredEvent As RoutedEvent
The identifier for the PointerEntered routed event.
- Attributes
- See Also
PointerExitedEvent PointerExitedEvent PointerExitedEvent
Gets the identifier for the PointerExited routed event.
public static RoutedEvent PointerExitedEvent { get; }public static RoutedEvent PointerExitedEvent { get; }Public Static ReadOnly Property PointerExitedEvent As RoutedEvent
The identifier for the PointerExited routed event.
- Attributes
- See Also
PointerMovedEvent PointerMovedEvent PointerMovedEvent
Gets the identifier for the PointerMoved routed event.
public static RoutedEvent PointerMovedEvent { get; }public static RoutedEvent PointerMovedEvent { get; }Public Static ReadOnly Property PointerMovedEvent As RoutedEvent
The identifier for the PointerMoved routed event.
- Attributes
- See Also
PointerPressedEvent PointerPressedEvent PointerPressedEvent
Gets the identifier for the PointerPressed routed event.
public static RoutedEvent PointerPressedEvent { get; }public static RoutedEvent PointerPressedEvent { get; }Public Static ReadOnly Property PointerPressedEvent As RoutedEvent
The identifier for the PointerPressed routed event.
- Attributes
- See Also
PointerReleasedEvent PointerReleasedEvent PointerReleasedEvent
Gets the identifier for the PointerReleased routed event.
public static RoutedEvent PointerReleasedEvent { get; }public static RoutedEvent PointerReleasedEvent { get; }Public Static ReadOnly Property PointerReleasedEvent As RoutedEvent
The identifier for the PointerReleased routed event.
- Attributes
- See Also
PointerWheelChangedEvent PointerWheelChangedEvent PointerWheelChangedEvent
Gets the identifier for the PointerWheelChanged routed event.
public static RoutedEvent PointerWheelChangedEvent { get; }public static RoutedEvent PointerWheelChangedEvent { get; }Public Static ReadOnly Property PointerWheelChangedEvent As RoutedEvent
The identifier for the PointerWheelChanged routed event.
- Attributes
- See Also
PreviewKeyDownEvent PreviewKeyDownEvent PreviewKeyDownEvent
Prerelease. Gets the identifier for the PreviewKeyDown routed event.
public static RoutedEvent PreviewKeyDownEvent { get; }public static RoutedEvent PreviewKeyDownEvent { get; }Public Static ReadOnly Property PreviewKeyDownEvent As RoutedEvent
The identifier for the PreviewKeyDown routed event.
- Attributes
| Device family |
Windows 10 Insider Preview (introduced v10.0.16190.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v5)
|
- See Also
PreviewKeyUpEvent PreviewKeyUpEvent PreviewKeyUpEvent
Prerelease. Gets the identifier for the PreviewKeyUp routed event.
public static RoutedEvent PreviewKeyUpEvent { get; }public static RoutedEvent PreviewKeyUpEvent { get; }Public Static ReadOnly Property PreviewKeyUpEvent As RoutedEvent
The identifier for the PreviewKeyUp routed event.
- Attributes
| Device family |
Windows 10 Insider Preview (introduced v10.0.16190.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v5)
|
- See Also
Projection Projection Projection
Gets or sets the perspective projection (3-D effect) to apply when rendering this element.
public Projection Projection { get; set; }public Projection Projection { get; set; }Public ReadWrite Property Projection As Projection
<uiElement>
<uiElement.Projection>
singleProjection
</uiElement.Projection>
</uiElement>
- Value
- Projection Projection Projection
A 3-D projection effect applied to the element.
- Attributes
Remarks
Projection and RenderTransform with a SkewTransform can achieve similar results, a Projection is probably more versatile, especially if you want a sense of perspective change applied to the element.
Projection is the base class type that this property uses, but Projection does not implement a practical behavior. Use either Matrix3DProjection or PlaneProjection.
The value of Projection is overridden by PointerDownThemeAnimation and PointerUpThemeAnimation.
Examples
This example shows how to apply a basic PlaneProjection in the initial page XAML.
<StackPanel Margin="35" Background="Gray">
<StackPanel.Projection>
<PlaneProjection RotationX="-35" RotationY="-35" RotationZ="15" />
</StackPanel.Projection>
<TextBlock Margin="10">Type Something Below</TextBlock>
<TextBox Margin="10"></TextBox>
<Button Margin="10" Content="Click" Width="100" />
</StackPanel>
- See Also
ProjectionProperty ProjectionProperty ProjectionProperty
Identifies the Projection dependency property.
public static DependencyProperty ProjectionProperty { get; }public static DependencyProperty ProjectionProperty { get; }Public Static ReadOnly Property ProjectionProperty As DependencyProperty
The identifier for the Projection dependency property.
- Attributes
RenderSize RenderSize RenderSize
Gets the final render size of a UIElement. Use is not recommended, see Remarks.
public Size RenderSize { get; }public Size RenderSize { get; }Public ReadOnly Property RenderSize As Size
- Attributes
Remarks
RenderSize is not the property to use to obtain size information about a UI element for most scenarios, because in the current implementation it doesn't have a safe technique for knowing when the value is current. For general UI purposes, use ActualHeight and ActualWidth instead, and do so only at points in object lifetime where object layout is complete. Examples of safe timing for checking ActualHeight or ActualWidth are user input events or the Loaded event. Or you can handle SizeChanged, which has updated size information in its event data. For layout method override purposes (for example MeasureOverride ), use DesiredSize.
RenderTransform RenderTransform RenderTransform
Gets or sets transform information that affects the rendering position of a UIElement.
public Transform RenderTransform { get; set; }public Transform RenderTransform { get; set; }Public ReadWrite Property RenderTransform As Transform
<uiElement>
<uiElement.RenderTransform>
singleTransform
</uiElement.RenderTransform>
</uiElement>
Describes the specifics of the desired render transform. The default value is null.
- Attributes
Remarks
You can animate a transform, if you target sub-properties of the specific transform being used that take Double values. Or you can use ObjectAnimationUsingKeyFrames to cycle through distinct transforms. Classes such as QuarticEase show some example XAML.
If you do animate RenderTransform, make sure there is an existing starting Transform value, even if it is all at default values. You can't animate a RenderTransform value that is initially null.
The value of RenderTransform is overridden by PointerDownThemeAnimation and PointerUpThemeAnimation.
Examples
This XAML defines a Matrix that provides data for a MatrixTransform applied to a rectangular shape as its RenderTransform. In this case, the matrix combines an offset (OffsetX and OffsetY) and a skew (M12). Note that this same effect could have been produced by combining a TranslateTransform and a SkewTransform; whether to use a single Matrix or combinations of discrete transforms (with TransformGroup ) is a matter of coding style; the results are identical.
<Rectangle Width="60" Height="60" Fill="Blue">
<Rectangle.RenderTransform>
<MatrixTransform>
<MatrixTransform.Matrix >
<!-- This matrix transforms the x,y position of the rectangle and skews it. -->
<Matrix OffsetX="30" OffsetY="100" M12="0.5" />
</MatrixTransform.Matrix>
</MatrixTransform>
</Rectangle.RenderTransform>
</Rectangle>
- See Also
RenderTransformOrigin RenderTransformOrigin RenderTransformOrigin
Gets or sets the origin point of any possible render transform declared by RenderTransform, relative to the bounds of the UIElement.
public Point RenderTransformOrigin { get; set; }public Point RenderTransformOrigin { get; set; }Public ReadWrite Property RenderTransformOrigin As Point
<uiElement RenderTransformOrigin="x,y"/>
The origin point of the render transform. The default value is a Point with value 0,0.
- Attributes
Remarks
RenderTransformOrigin enables you to create or change the effect of a transform on a particular element without having to alter the specifics of the RenderTransform transform. The Point value you specify for RenderTransformOrigin is not based on actual pixel measures. Instead, it is a logical point, where a value of 0,0 refers to the top left corner of the overall UIElement render area, and 1,1 refers to the bottom right. The value is then evaluated into an X,Y coordinate by factoring it into the current coordinate space of the UIElement.
For some transforms, the origin doesn't matter. For example the RenderTransformOrigin won't change the behavior of a TranslateTransform applied to the RenderTransform property.
Some transform types have their own properties for specifying the origin of the transform. For example, RotateTransform has CenterX and CenterY. When you're working with a UIElement, visual design tools sometimes hide these other properties so that you only use RenderTransformOrigin for all transform origin changes and leave transform-specific origins as the defaults. Tools might also apply all transform effects to a single CompositeTransform value for RenderTransform, rather than defining XAML elements for the specific transforms and making a TransformGroup. If you're writing your own XAML or defining transforms in code, you might consider following these same practices so that you always use RenderTransformOrigin rather than the transform-specific origin values if you're applying transforms for RenderTransform, otherwise the values will offset each other.
A common technique is to set RenderTransformOrigin to 0.5,0.5, which places the origin at the element center. You could then apply a RotateTransform to rotate the element around the center.
Changing FlowDirection to RightToLeft changes the meaning of the X coordinate of a RenderTransformOrigin for a UIElement; 0 will be the right edge.
Some of the same visual effects that you can produce with RenderTransform and RenderTransformOrigin can also be achieved with Projection and a PlaneProjection. For example, you can rotate a UIElement around its center by changing PlaneProjection.RotationZ.
Examples
This XAML example shows how to set RenderTransformOrigin on the element in the initial XAML. An animation that runs on an initially default CompositeTransform can use the RenderTransformOrigin to modify both the scale and rotate transforms to apply to the circles's center rather than the default 0,0 coordinate origin. This makes it appear as if the circle is spinning around its center and shrinking in place.
Note
To start the animation you'd need to retrieve it from Resources and call Begin; that code is not shown.
<Ellipse x:Name="e1" RenderTransformOrigin=".5,.5" Height="100" Width="100" Loaded="e1_Loaded_1">
<Ellipse.Fill>
<LinearGradientBrush>
<GradientStop Color="Red" Offset="0"/>
<GradientStop Color="Green" Offset="1"/>
</LinearGradientBrush>
</Ellipse.Fill>
<Ellipse.RenderTransform>
<CompositeTransform />
</Ellipse.RenderTransform>
<Ellipse.Resources>
<Storyboard x:Name="esb1" >
<DoubleAnimation RepeatBehavior="3x" Duration="0:0:3" From="0" To="360" Storyboard.TargetName="e1"
Storyboard.TargetProperty="(UIElement.RenderTransform).(CompositeTransform.Rotation)" />
<DoubleAnimation RepeatBehavior="1x" Duration="0:0:7" From="1" To="0" Storyboard.TargetName="e1"
Storyboard.TargetProperty="(UIElement.RenderTransform).(CompositeTransform.ScaleX)" />
<DoubleAnimation RepeatBehavior="1x" Duration="0:0:7" From="1" To="0" Storyboard.TargetName="e1"
Storyboard.TargetProperty="(UIElement.RenderTransform).(CompositeTransform.ScaleY)" />
</Storyboard>
</Ellipse.Resources>
</Ellipse>
- See Also
RenderTransformOriginProperty RenderTransformOriginProperty RenderTransformOriginProperty
Identifies the RenderTransformOrigin dependency property.
public static DependencyProperty RenderTransformOriginProperty { get; }public static DependencyProperty RenderTransformOriginProperty { get; }Public Static ReadOnly Property RenderTransformOriginProperty As DependencyProperty
The identifier for the RenderTransformOrigin dependency property.
- Attributes
RenderTransformProperty RenderTransformProperty RenderTransformProperty
Identifies the RenderTransform dependency property.
public static DependencyProperty RenderTransformProperty { get; }public static DependencyProperty RenderTransformProperty { get; }Public Static ReadOnly Property RenderTransformProperty As DependencyProperty
The identifier for the RenderTransform dependency property.
- Attributes
RightTappedEvent RightTappedEvent RightTappedEvent
Gets the identifier for the RightTapped routed event.
public static RoutedEvent RightTappedEvent { get; }public static RoutedEvent RightTappedEvent { get; }Public Static ReadOnly Property RightTappedEvent As RoutedEvent
The identifier for the RightTapped routed event.
- Attributes
TabFocusNavigation TabFocusNavigation TabFocusNavigation
Gets or sets a value that modifies how tabbing and TabIndex work for this control.
public KeyboardNavigationMode TabFocusNavigation { get; set; }public KeyboardNavigationMode TabFocusNavigation { get; set; }Public ReadWrite Property TabFocusNavigation As KeyboardNavigationMode
<uiElement TabFocusNavigation="keyboardNavigationModeMemberName"/>
A value of the enumeration. The default is Local.
- Attributes
| Device family |
Windows 10 Creators Update (introduced v10.0.15063.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v4)
|
- See Also
TabFocusNavigationProperty TabFocusNavigationProperty TabFocusNavigationProperty
Identifies the TabFocusNavigation dependency property.
public static DependencyProperty TabFocusNavigationProperty { get; }public static DependencyProperty TabFocusNavigationProperty { get; }Public Static ReadOnly Property TabFocusNavigationProperty As DependencyProperty
The identifier for the TabFocusNavigation dependency property.
- Attributes
| Device family |
Windows 10 Creators Update (introduced v10.0.15063.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v4)
|
TappedEvent TappedEvent TappedEvent
Transform3D Transform3D Transform3D
Gets or sets the 3-D transform effect to apply when rendering this element.
public Transform3D Transform3D { get; set; }public Transform3D Transform3D { get; set; }Public ReadWrite Property Transform3D As Transform3D
The 3-D transform effect to apply when rendering this element. The default is null.
- Attributes
Remarks
Use the Transform3D property to apply a 3-D transform matrix to a XAML element. This lets you create effects where two-dimensional UI appears to exist in 3-D space relative to the user. Transform3D behaves much like RenderTransform, but allows transforms in three-dimensional space and not just two dimensions.
PerspectiveTransform3D and CompositeTransform3D
There are two subclasses of Transform3D that you can use to populate the Transform3D property. You should always use these subclasses together to create a 3-D scene. In very simple terms, you apply a PerspectiveTransform3D to the root element of your scene to provide a common viewport for all the elements in it. Then you apply a CompositeTransform3D to individual elements in the scene to rotate, scale, and move them in relation to the common viewport.
PerspectiveTransform3D represents a 3-D perspective transform matrix, and creates a frame of reference and viewport for a 3-D scene. Under a perspective effect, elements further away from the user appear to shrink towards a common vanishing point, as if they were actually viewed in three-dimensional space. Because the perspective effect should apply to all elements in a shared 3-D scene, it is usually applied at the root of 3-D content such as the Page element. The effect is inherited by children of this element. PerspectiveTransform3D preserves coordinates in the Z=0 plane, where UI elements reside by default. Therefore, PerspectiveTransform3D (inherited from the root element) affects the appearance of an element only if the element is also transformed by a CompositeTransform3D, which moves it out of the Z=0 plane.
CompositeTransform3D represents a group of affine 3-D transforms on an element, including rotation, scale and translation. This class is used to position elements in 3-D space.
Here's an example of using the Transform3D subclasses to achieve a 3-D effect for your UI:
<StackPanel Orientation="Horizontal">
<StackPanel.Transform3D>
<PerspectiveTransform3D />
</StackPanel.Transform3D>
<Rectangle Width="300" Height="200" Fill="CornflowerBlue" />
<Rectangle Width="300" Height="200" Fill="CadetBlue" Margin="10">
<Rectangle.Transform3D>
<CompositeTransform3D RotationY="-30" TranslateZ="-75" CenterX="150" />
</Rectangle.Transform3D>
</Rectangle>
<Rectangle Width="300" Height="200" Fill="OrangeRed">
<Rectangle.Transform3D>
<CompositeTransform3D TranslateZ="-150" />
</Rectangle.Transform3D>
</Rectangle>
</StackPanel>
In this example, a PerspectiveTransform3D is attached to the root StackPanel and provides a shared perspective viewport for the panel’s children.
- The Rectangle on the left has no transform, so it appears as normal.
- The Rectangle in the center is rotated -30 degrees about its central axis and translated back 75 pixels, causing its right edge to have a Z-coordinate of -150 pixels.
- The Rectangle on the right is translated back 150 pixels.
The edges of the three rectangles appear to be contiguous because they share a common perspective.
Animating CompositeTransform3D
You can animate each property of a CompositeTransform3D independently. For more info about animations, see Storyboarded animations and Key-frame and easing function animations.
In this example, animations are applied the RotationY and TranslateZ properties to make the middle rectangle appear to drop into place. The end result when the animations have stopped is the same as the previous example.
<StackPanel Orientation="Horizontal" Loaded="StackPanel_Loaded">
<StackPanel.Resources>
<Storyboard x:Name="rect2Storyboard">
<DoubleAnimation
Storyboard.TargetName="rectangle2"
Storyboard.TargetProperty="(UIElement.Transform3D).(CompositeTransform3D.RotationY)"
From="0" To="-30" Duration="0:0:5"/>
<DoubleAnimation
Storyboard.TargetName="rectangle2"
Storyboard.TargetProperty="(UIElement.Transform3D).(CompositeTransform3D.TranslateZ)"
From="175" To="-75" Duration="0:0:10"/>
</Storyboard>
</StackPanel.Resources>
<StackPanel.Transform3D>
<PerspectiveTransform3D />
</StackPanel.Transform3D>
<Rectangle Width="300" Height="200" Fill="CornflowerBlue" />
<Rectangle x:Name="rectangle2" Width="300" Height="200" Fill="CadetBlue" Margin="10">
<Rectangle.Transform3D>
<CompositeTransform3D CenterX="150" />
</Rectangle.Transform3D>
</Rectangle>
<Rectangle Width="300" Height="200" Fill="OrangeRed">
<Rectangle.Transform3D>
<CompositeTransform3D TranslateZ="-150" />
</Rectangle.Transform3D>
</Rectangle>
</StackPanel>
private void StackPanel_Loaded(object sender, RoutedEventArgs e)
{
rect2Storyboard.Begin();
}
Transform3D and PlaneProjection
Prior to Windows 10, the only way to create 3-D effects was to set the Projection property. When using Projection, 3-D transforms are not inherited down the XAML tree. Therefore, Projection is suitable only for applying effects where elements are transformed in local coordinates, not relative to a shared perspective viewport. This same effect can be achieved by setting PerspectiveTransform3D on a local element. For this reason, we recommend that you use Transform3D for all but the most simple 3-D effects, and whenever you need a shared perspective.
Note
Transform3D does not affect the order in which elements are drawn. Elements further away from the viewer along the Z-axis might still be rendered above elements that are closer. You can use the Canvas.ZIndex attached property and the position of elements in the XAML visual tree to manage the drawing order of elements in your UI.
Transform3DProperty Transform3DProperty Transform3DProperty
Identifies the Transform3D dependency property.
public static DependencyProperty Transform3DProperty { get; }public static DependencyProperty Transform3DProperty { get; }Public Static ReadOnly Property Transform3DProperty As DependencyProperty
The identifier for the Transform3D dependency property.
- Attributes
Transitions Transitions Transitions
Gets or sets the collection of Transition style elements that apply to a UIElement.
public TransitionCollection Transitions { get; set; }public TransitionCollection Transitions { get; set; }Public ReadWrite Property Transitions As TransitionCollection
<uielement>
<uielement.Transitions>
<TransitionCollection>
oneOrMoreTransitions
</TransitionCollection>
</uielement.Transitions>
</uielement>
The strongly typed collection of Transition style elements that apply to a UIElement.
- Attributes
Remarks
Important
The XAML syntax for all properties that use a TransitionCollection value is unusual in that you must declare an explicit TransitionCollection object element as the value, and then provide object elements as child elements of TransitionCollection for each of the transition animations you want to use. For most other XAML collection properties you could omit the collection object element because it can be implicit, but properties that use TransitionCollection don't support the implicit collection usage. For more info on implicit collections and XAML, see XAML syntax guide.
This is a short list of some of the possible types for transitions:
- AddDeleteThemeTransition
- ContentThemeTransition
- EdgeUIThemeTransition
- EntranceThemeTransition
- PopupThemeTransition
- ReorderThemeTransition
- RepositionThemeTransition
Specific classes that derive from UIElement sometimes have their own properties that hold other types of transitions for class-specific scenarios. For example, Popup.ChildTransitions and ItemsControl.ItemContainerTransitions.
Transition animations play a particular role in UI design of your app. The basic idea is that when there is a change or transition, the animation draws the attention of the user to the change.
It's not common to set the value of the Transitions property directly on a UIElement that is a direct element of app UI. It's more common to have a transitions collection be a part of a visual state, template or style. In this case you use mechanisms such as Setter of a Style to specify the Transitions property, and set the value using XAML-defined content that is typically stored as a XAML resource.
VisualTransition is not one of the types you put in the UIElement.Transitions collection. VisualTransition is specifically for animations in visual state groups, and is used by the VisualStateGroup.Transitions property.
Examples
This XAML example shows a single EntranceThemeTransition as defined in a Style for a Button. Transition animation properties are typically set in styles and templates rather than as properties directly in a UI definition. Styles are typically stored as a XAML resource.
<Grid Background="{StaticResource ApplicationPageBackgroundBrush}">
<Grid.Resources>
<Style x:Key="DefaultButtonStyle" TargetType="Button">
<Setter Property="Transitions">
<Setter.Value>
<TransitionCollection>
<EntranceThemeTransition/>
</TransitionCollection>
</Setter.Value>
</Setter>
</Style>
</Grid.Resources>
<Button Style="{StaticResource DefaultButtonStyle}"
Content="EntranceThemeTransition style applied" />
</Grid>
- See Also
TransitionsProperty TransitionsProperty TransitionsProperty
Identifies the Transitions dependency property.
public static DependencyProperty TransitionsProperty { get; }public static DependencyProperty TransitionsProperty { get; }Public Static ReadOnly Property TransitionsProperty As DependencyProperty
The identifier for the Transitions dependency property.
- Attributes
UseLayoutRounding UseLayoutRounding UseLayoutRounding
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.
public PlatForm::Boolean UseLayoutRounding { get; set; }public bool UseLayoutRounding { get; set; }Public ReadWrite Property UseLayoutRounding As bool
<uiElement UseLayoutRounding="bool" />
- Value
- bool bool bool
true if rendering and layout should use layout rounding to whole pixels; otherwise, false. The default is true.
- Attributes
Remarks
Various Windows Runtime properties of type Double are used to specify layout desired values or characteristics. The most obvious are Height and Width but there are many others. The default value of true for UseLayoutRounding will cause measurement and layout operations to round potential subpixel values from these layout properties to the nearest integer value, and render objects aligned to pixel boundaries. This behavior is intended to reduce the visual artifacts that can appear when a subpixel value renders and affects pixels on either side of the subpixel boundary. The most prominent example of such an artifact is when you intend to produce a crisp, thin line of a particular color. If your measurement for the line gave a subpixel value, and the layout behavior did not round to whole pixels, then the line can potentially appear blurry as well as appearing as a dimmer color shade than you intended.
Layout rounding affects aliasing as well as positioning.
Possible scenarios for setting UseLayoutRounding to false are not documented here. If you feel that there might be benefit in enabling subpixel rendering for your app, experiment with setting UseLayoutRounding to false, examine the visual results, and make sure that possible rendering artifacts from subpixel rendering do not outweigh the perceived benefits. If you do set UseLayoutRounding to false, it's common to do so on the root of your XAML page or object tree.
- See Also
UseLayoutRoundingProperty UseLayoutRoundingProperty UseLayoutRoundingProperty
Identifies the UseLayoutRounding dependency property.
public static DependencyProperty UseLayoutRoundingProperty { get; }public static DependencyProperty UseLayoutRoundingProperty { get; }Public Static ReadOnly Property UseLayoutRoundingProperty As DependencyProperty
The identifier for the UseLayoutRounding dependency property.
- Attributes
Visibility Visibility Visibility
Gets or sets the visibility of a UIElement. A UIElement that is not visible is not rendered and does not communicate its desired size to layout.
public Visibility Visibility { get; set; }public Visibility Visibility { get; set; }Public ReadWrite Property Visibility As Visibility
<uiElement Visibility="Visible"/>
-or-
<uiElement Visibility="Collapsed"/>
- Value
- Visibility Visibility Visibility
A value of the enumeration. The default value is Visible.
- Attributes
Remarks
A UI element that has Visibility equals Collapsed is still loaded along with the rest of the XAML on a page and exists in the runtime object tree.
An element that has Visibility equals Collapsed has no location in the UI and does not participate in input or hit testing. They are also not in a tab sequence and cannot be focused, not even programmatically. If you still want input, focus or hit testing, rather than set Visibility use a zero Opacity.
BooleanToVisibilityConverter
A common scenario in apps that use data from a data source is to identify a property of the data or the view model for the data that controls whether the data should display. A related scenario is writing a template that can alter the Visibility of a control part based on a Boolean property of the parent control or of another part. To make it easier to define this behavior as part of a Binding, some of the default project templates include a BooleanToVisibilityConverter helper class in the Common folder. For more info on how to use a value converter for a data binding, see IValueConverter.
Examples
Visibility in a visual state As part of defining visual states for a control, you will sometimes want to change the Visibility state of an object to Collapsed. Visual states rely on animations. The property value type of Visibility is Visibility, an enumeration. To animate values that are enumerations, you must use a DiscreteObjectKeyFrame. (You also use this technique for Boolean values). This XAML example shows a visual state that uses DiscreteObjectKeyFrame to change visibility.
<VisualState x:Name="Focused">
<Storyboard>
<ObjectAnimationUsingKeyFrames Storyboard.TargetName="FocusVisualElement" Storyboard.TargetProperty="Visibility" Duration="0">
<DiscreteObjectKeyFrame KeyTime="0" Value="Visible"/>
</ObjectAnimationUsingKeyFrames>
</Storyboard>
</VisualState>
- See Also
VisibilityProperty VisibilityProperty VisibilityProperty
Identifies the Visibility dependency property.
public static DependencyProperty VisibilityProperty { get; }public static DependencyProperty VisibilityProperty { get; }Public Static ReadOnly Property VisibilityProperty As DependencyProperty
The identifier for the Visibility dependency property.
- Attributes
XYFocusDownNavigationStrategy XYFocusDownNavigationStrategy XYFocusDownNavigationStrategy
Gets or sets a value that specifies the strategy used to determine the target element of a down navigation.
public XYFocusNavigationStrategy XYFocusDownNavigationStrategy { get; set; }public XYFocusNavigationStrategy XYFocusDownNavigationStrategy { get; set; }Public ReadWrite Property XYFocusDownNavigationStrategy As XYFocusNavigationStrategy
<uiElement XYFocusDownNavigationStrategy="xyFocusNavigationStrategyMemberName"/>
A value of the enumeration. The default is Auto.
- Attributes
| Device family |
Windows 10 Creators Update (introduced v10.0.15063.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v4)
|
Remarks
When this property is set to Auto, the strategy is inherited from the elements ancestors. If all ancestors have a value of Auto, the fallback strategy is Projection.
XYFocusDownNavigationStrategyProperty XYFocusDownNavigationStrategyProperty XYFocusDownNavigationStrategyProperty
Identifies the XYFocusDownNavigationStrategy dependency property.
public static DependencyProperty XYFocusDownNavigationStrategyProperty { get; }public static DependencyProperty XYFocusDownNavigationStrategyProperty { get; }Public Static ReadOnly Property XYFocusDownNavigationStrategyProperty As DependencyProperty
The identifier for the XYFocusDownNavigationStrategy dependency property.
- Attributes
| Device family |
Windows 10 Creators Update (introduced v10.0.15063.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v4)
|
XYFocusKeyboardNavigation XYFocusKeyboardNavigation XYFocusKeyboardNavigation
Gets or sets a value that enables or disables navigation using the keyboard directional arrows.
public XYFocusKeyboardNavigationMode XYFocusKeyboardNavigation { get; set; }public XYFocusKeyboardNavigationMode XYFocusKeyboardNavigation { get; set; }Public ReadWrite Property XYFocusKeyboardNavigation As XYFocusKeyboardNavigationMode
<uiElement XYFocusKeyboardNavigation="xyFocusKeyboardNavigationModeMemberName"/>
A value of the enumeration. The default is Auto.
- Attributes
| Device family |
Windows 10 Creators Update (introduced v10.0.15063.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v4)
|
Remarks
When this property is set to Auto, the behavior is inherited from the elements ancestors. If all ancestors have a value of Auto, the fallback behavior is Disabled.
XYFocusKeyboardNavigationProperty XYFocusKeyboardNavigationProperty XYFocusKeyboardNavigationProperty
Identifies the XYFocusKeyboardNavigation dependency property.
public static DependencyProperty XYFocusKeyboardNavigationProperty { get; }public static DependencyProperty XYFocusKeyboardNavigationProperty { get; }Public Static ReadOnly Property XYFocusKeyboardNavigationProperty As DependencyProperty
The identifier for the XYFocusKeyboardNavigation dependency property.
- Attributes
| Device family |
Windows 10 Creators Update (introduced v10.0.15063.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v4)
|
XYFocusLeftNavigationStrategy XYFocusLeftNavigationStrategy XYFocusLeftNavigationStrategy
Gets or sets a value that specifies the strategy used to determine the target element of a left navigation.
public XYFocusNavigationStrategy XYFocusLeftNavigationStrategy { get; set; }public XYFocusNavigationStrategy XYFocusLeftNavigationStrategy { get; set; }Public ReadWrite Property XYFocusLeftNavigationStrategy As XYFocusNavigationStrategy
<uiElement XYFocusLeftNavigationStrategy="xyFocusNavigationStrategyMemberName"/>
A value of the enumeration. The default is Auto.
- Attributes
| Device family |
Windows 10 Creators Update (introduced v10.0.15063.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v4)
|
Remarks
When this property is set to Auto, the strategy is inherited from the elements ancestors. If all ancestors have a value of Auto, the fallback strategy is Projection.
XYFocusLeftNavigationStrategyProperty XYFocusLeftNavigationStrategyProperty XYFocusLeftNavigationStrategyProperty
Identifies the XYFocusLeftNavigationStrategy dependency property.
public static DependencyProperty XYFocusLeftNavigationStrategyProperty { get; }public static DependencyProperty XYFocusLeftNavigationStrategyProperty { get; }Public Static ReadOnly Property XYFocusLeftNavigationStrategyProperty As DependencyProperty
The identifier for the XYFocusLeftNavigationStrategy dependency property.
- Attributes
| Device family |
Windows 10 Creators Update (introduced v10.0.15063.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v4)
|
XYFocusRightNavigationStrategy XYFocusRightNavigationStrategy XYFocusRightNavigationStrategy
Gets or sets a value that specifies the strategy used to determine the target element of a right navigation.
public XYFocusNavigationStrategy XYFocusRightNavigationStrategy { get; set; }public XYFocusNavigationStrategy XYFocusRightNavigationStrategy { get; set; }Public ReadWrite Property XYFocusRightNavigationStrategy As XYFocusNavigationStrategy
<uiElement XYFocusRightNavigationStrategy="xyFocusNavigationStrategyMemberName"/>
A value of the enumeration. The default is Auto.
- Attributes
| Device family |
Windows 10 Creators Update (introduced v10.0.15063.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v4)
|
Remarks
When this property is set to Auto, the strategy is inherited from the elements ancestors. If all ancestors have a value of Auto, the fallback strategy is Projection.
XYFocusRightNavigationStrategyProperty XYFocusRightNavigationStrategyProperty XYFocusRightNavigationStrategyProperty
Identifies the XYFocusRightNavigationStrategy dependency property.
public static DependencyProperty XYFocusRightNavigationStrategyProperty { get; }public static DependencyProperty XYFocusRightNavigationStrategyProperty { get; }Public Static ReadOnly Property XYFocusRightNavigationStrategyProperty As DependencyProperty
The identifier for the XYFocusRightNavigationStrategy dependency property.
- Attributes
| Device family |
Windows 10 Creators Update (introduced v10.0.15063.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v4)
|
XYFocusUpNavigationStrategy XYFocusUpNavigationStrategy XYFocusUpNavigationStrategy
Gets or sets a value that specifies the strategy used to determine the target element of an up navigation.
public XYFocusNavigationStrategy XYFocusUpNavigationStrategy { get; set; }public XYFocusNavigationStrategy XYFocusUpNavigationStrategy { get; set; }Public ReadWrite Property XYFocusUpNavigationStrategy As XYFocusNavigationStrategy
<uiElement XYFocusUpNavigationStrategy="xyFocusNavigationStrategyMemberName"/>
A value of the enumeration. The default is Auto.
- Attributes
| Device family |
Windows 10 Creators Update (introduced v10.0.15063.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v4)
|
Remarks
When this property is set to Auto, the strategy is inherited from the elements ancestors. If all ancestors have a value of Auto, the fallback strategy is Projection.
XYFocusUpNavigationStrategyProperty XYFocusUpNavigationStrategyProperty XYFocusUpNavigationStrategyProperty
Identifies the XYFocusUpNavigationStrategy dependency property.
public static DependencyProperty XYFocusUpNavigationStrategyProperty { get; }public static DependencyProperty XYFocusUpNavigationStrategyProperty { get; }Public Static ReadOnly Property XYFocusUpNavigationStrategyProperty As DependencyProperty
The identifier for the XYFocusUpNavigationStrategy dependency property.
- Attributes
| Device family |
Windows 10 Creators Update (introduced v10.0.15063.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v4)
|
Methods
AddHandler(RoutedEvent, Object, Boolean) AddHandler(RoutedEvent, Object, Boolean) 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.
public void AddHandler(RoutedEvent routedEvent, Object handler, Boolean handledEventsToo)public void AddHandler(RoutedEvent routedEvent, Object handler, Boolean handledEventsToo)Public Function AddHandler(routedEvent As RoutedEvent, handler As Object, handledEventsToo As Boolean) As void
- routedEvent
- RoutedEvent RoutedEvent RoutedEvent
An identifier for the routed event to be handled.
- handler
- System.Object System.Object System.Object
A reference to the handler implementation.
- handledEventsToo
- System.Boolean System.Boolean System.Boolean
true to register the handler such that it is invoked even when the routed event is marked handled in its event data.
false to register the handler with the default condition that it will not be invoked if the routed event is already marked handled. The default is false.
Do not routinely ask to rehandle a routed event, because it interferes with the intended design of the Windows Runtime event system for control compositing.
- Attributes
Remarks
Don't try to use AddHandler as a general substitute for the language-specific syntax you normally use for wiring event handlers; it won't work, because not all events have an identifier you can pass as routedEvent. AddHandler is specifically for routed events, and intended mainly for the particular scenario enabled by passing handledEventsToo as true. For more info, see Events and routed events overview.
Routed event identifiers
The routed event identifier is generally a static property member of UIElement. For example, to add a handler for the KeyUp event, pass KeyUpEvent for this parameter. Only a small number of Windows Runtime events have this identifier; only routed events on UIElement have an identifier API available for this usage. These are generally events that are related to input actions at various levels: pointer level, gesture level, manipulation level. Also, the key input events can be handled this way.
Here is a list of routed events that expose a routed event identifier, and thus can be processed by handlers that are registered by an AddHandler call:
- DoubleTapped
- DragEnter
- DragLeave
- DragOver
- Drop
- Holding
- KeyDown
- KeyUp
- ManipulationCompleted
- ManipulationDelta
- ManipulationInertiaStarting
- ManipulationStarted
- ManipulationStarting
- PointerCanceled
- PointerCaptureLost
- PointerEntered
- PointerExited
- PointerMoved
- PointerPressed
- PointerReleased
- PointerWheelChanged
- RightTapped
- Tapped
The handler parameter
The handler parameter is an untyped parameter, but you should provide a new delegate that references a handler method that is specific to the desired event. For example, if handling a KeyUp event, pass a new KeyEventHandler instance that references a method that is based on that KeyEventHandler delegate signature. This requires a dereference, and the dereference syntax varies depending on which language you are using. See the examples in this topic.
When to use handledEventsToo
Processing low-level input events in a practical way is a complex task. Many controls implement behavior where a certain event is marked as handled, and is replaced by another more intuitive event. Generally, a control will mark a routed event as handled only if there is some design intention for doing so. However, in certain scenarios, those design intentions might not be what your particular handling of the input event requires. It is for these scenarios that registering handlers with handledEventsToo as true is appropriate. But you should not do this routinely. Invoking handlers in response to all events even if handled will complicate your own app event-processing logic. You may see a decrease in performance if the handler logic is substantial. You should attach handlers to already-handled events only if you have discovered that certain controls are handling events that you want to handle with app logic.
Another technique for avoiding a control's class-handling behavior is to subclass that control and override its On* methods, which are pre-configured overrides by which the control marks an event as handled. However, this too can be complex. You may have to reproduce a control's handling implementation without calling the base implementation, because the base implementation would mark the event as handled. For more info, see Events and routed events overview.
Examples
This example shows the basic syntax for wiring an event handler with AddHandler and handledEventsToo as true. In this case the event being wired is Tapped. The typical place to wire handlers is either Loaded for a page or OnApplyTemplate for a templated control.
void MainPage::pageRoot_Tapped(Platform::Object^ sender, Windows::UI::Xaml::Input::TappedRoutedEventArgs^ e)
{
//implementation
}
void MainPage::pageRoot_Loaded(Platform::Object^ sender, Windows::UI::Xaml::RoutedEventArgs^ e)
{
this->AddHandler(UIElement::TappedEvent, ref new TappedEventHandler(this, &MainPage::pageRoot_Tapped), true);
}
private void pageRoot_Tapped(object sender, TappedRoutedEventArgs e)
{
//implementation
}
private void pageRoot_Loaded_1(object sender, RoutedEventArgs e)
{
this.AddHandler(UIElement.TappedEvent, new TappedEventHandler(pageRoot_Tapped), true);
}
Private Sub Page_Tapped(sender As Object, e As TappedRoutedEventArgs)
' implementation
End Sub
Private Sub Page_Loaded_1(sender As Object, e As RoutedEventArgs)
Me.AddHandler(UIElement.TappedEvent, New TappedEventHandler(AddressOf Page_Tapped), True)
End Sub
- See Also
Arrange(Rect) Arrange(Rect) Arrange(Rect)
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.
public void Arrange(Rect finalRect)public void Arrange(Rect finalRect)Public Function Arrange(finalRect As Rect) As void
The final size that the parent computes for the child in layout, provided as a Rect value.
- Attributes
Remarks
The Arrange call potentially reaches an ArrangeOverride implementation of that specific class. Otherwise, most FrameworkElement classes have an implicit default layout behavior for Arrange.
Computation of initial layout positioning in a XAML UI consists of a Measure call and an Arrange call, in that order. During the Measure call, the layout system determines an element's size requirements using the availableSize measurement. During the Arrange call, the layout system finalizes the size and position of an element's bounding box.
When a layout is first produced, it always has a Measure call that happens before Arrange. However, after the first layout pass, an Arrange call can happen without a Measure preceding it. This can happen when a property that affects only Arrange is changed (such as alignment), or when the parent receives an Arrange without a Measure.
A Measure call will automatically invalidate any Arrange information. Layout updates generally occur asynchronously (at a time determined by the layout system). An element might not immediately reflect changes to properties that affect element sizing (such as Width ).
Layout updates can be forced by app code rather than relying on the built-in layout system behavior by using the UpdateLayout method. However, that is not recommended. It is usually unnecessary and can cause poor performance if overused. In many situations where calling UpdateLayout from app code might be appropriate because of changes to properties, the layout system will probably already be processing updates. The layout system also has optimizations for dealing with cascades of layout changes through parent-child relationships, and calling UpdateLayout can work against such optimizations. Nevertheless, it's possible that layout situations exist in more complicated scenarios where calling UpdateLayout is the best option for resolving a timing issue or other issue with layout. Just use it deliberately and sparingly.
Examples
This example shows how you would use Arrange within an ArrangeOverride implementation. The basic idea is that you should query DesiredSize on anything you attempt to call Arrange on so that you have a value for finalRect, unless your layout implementation has some specific design that alters or ignores the desired size before passing it as finalRect.
// Second arrange all children and return final size of panel
protected override Size ArrangeOverride(Size finalSize)
{
// Get the collection of children
UIElementCollection mychildren = Children;
// Get total number of children
int count = mychildren.Count;
// Arrange children
// We're only allowing 9 children in this panel. More children will get a 0x0 layout slot.
int i;
for (i = 0; i < 9; i++)
{
// Get (left, top) origin point for the element in the 3x3 block
Point cellOrigin = GetOrigin(i, 3, new Size(100, 100));
// Arrange child
// Get desired height and width. This will not be larger than 100x100 as set in MeasureOverride.
double dw = mychildren[i].DesiredSize.Width;
double dh = mychildren[i].DesiredSize.Height;
mychildren[i].Arrange(new Rect(cellOrigin.X, cellOrigin.Y, dw, dh));
}
// Give the remaining children a 0x0 layout slot
for (i = 9; i < count; i++)
{
mychildren[i].Arrange(new Rect(0, 0, 0, 0));
}
// Return final size of the panel
return new Size(300, 300);
}
'Second arrange all children and return final size of panel
Protected Overrides Function ArrangeOverride(ByVal finalSize As Size) As Size
'Get the collection of children
Dim mychildren As UIElementCollection = Children
'Get total number of children
Dim count As Integer = mychildren.Count
'Arrange children
'only allowing 9 children in this panel. More children will get a 0x0 layout slot.
Dim i As Integer
For i = 0 To 8
'Get (left, top) origin point for the element in the 3x3 block
Dim cellOrigin As Point = GetOrigin(i, 3, New Size(100, 100))
'Arrange child
'Get desired height and width. This will not be larger than 100x100 as set in MeasureOverride.
Dim dw As Double = mychildren(i).DesiredSize.Width
Dim dh As Double = mychildren(i).DesiredSize.Height
mychildren(i).Arrange(New Rect(cellOrigin.X, cellOrigin.Y, dw, dh))
Next
For i = 9 To count - 1
'Give the remaining children a 0x0 layout slot
mychildren(i).Arrange(New Rect(0, 0, 0, 0))
Next
'Return final size of the panel
Return New Size(300, 300)
End Function
'Calculate point origin of the Block you are in
Protected Function GetOrigin(ByVal blockNum As Integer, ByVal blocksPerRow As Integer, ByVal itemSize As Size) As Point
'Get row number (zero-based)
Dim row As Integer = CInt(Math.Floor(blockNum / blocksPerRow))
'Get column number (zero-based)
Dim column As Integer = blockNum - blocksPerRow * row
'Calculate origin
Dim origin As New Point(itemSize.Width * column, itemSize.Height * row)
Return origin
End Function
CancelDirectManipulations() CancelDirectManipulations() CancelDirectManipulations()
Cancels ongoing direct manipulation processing (system-defined panning/zooming) on any ScrollViewer parent that contains the current UIElement.
public PlatForm::Boolean CancelDirectManipulations()public bool CancelDirectManipulations()Public Function CancelDirectManipulations() As bool
true if a ScrollViewer parent exists and setting the value resulted in canceling the panning/zooming action. false if calling the method results in no action.
- Attributes
Remarks
You might call this method if you want the target UIElement to be able to process ongoing manipulations through the lower-level pointer events (PointerPressed, PointerMoved and so on). By default, if the target UIElement is contained in a ScrollViewer, that ScrollViewer parent would handle translation manipulations directly at the system level, treating them as pan or zoom. Manipulation handling by the ScrollViewer parent prevents the contained UIElement from receiving the pointer events (they would be marked as handled). Call CancelDirectManipulations to override this default behavior for an ongoing manipulation, and then you'll be able to handle manipulations at a non-system level for the individual UIElement target.
- See Also
CapturePointer(Pointer) CapturePointer(Pointer) CapturePointer(Pointer)
Sets pointer capture to a UIElement. Once captured, only the element that has capture will fire pointer-related events.
public PlatForm::Boolean CapturePointer(Pointer value)public bool CapturePointer(Pointer value)Public Function CapturePointer(value As Pointer) As bool
true if the object has pointer capture; otherwise, false.
- Attributes
Remarks
You can only successfully capture the pointer if that pointer is in a pressed state (Pointer.IsInContact should be true). What physically constitutes being pressed will vary based on the pointer device type (mouse button pressed, touch point down, stylus in contact). If you attempt to capture a pointer that isn't pressed, or where the pointer was previously pressed but is now released, CapturePointer returns false. Existing captures aren't affected by a CapturePointer call that returned false.
You typically capture the pointer within a PointerPressed event handler. The Pointer instance you get from the PointerRoutedEventArgs event data of your PointerPressed handler is the value you should pass for the value parameter when you call CapturePointer from within your handler's code.
You typically capture the pointer because you want the current pointer action to initiate a behavior in your app. In this case you typically don't want other elements to handle any other events that come from that pointer's actions, until your behavior is either completed or is canceled by releasing the pointer capture. If a pointer is captured, only the element that has capture gets the pointer's input events, and other elements don't fire events even if the pointer moves into their bounds. For example, consider a UI that has two adjacent elements. Normally, if you moved the pointer from one element to the other, you'd first get PointerMoved events from the first element, and then from the second element. But if the first element has captured the pointer, then the first element continues to receive PointerMoved events even if the captured pointer leaves its bounds. Also, the second element doesn't fire PointerEntered events for a captured pointer when the captured pointer enters it.
The pointer capture state and generating the events that are related to pointer capture isn't entirely up to app code. If the user releases the pointer, that generates a PointerReleased event, and pointer captures associated with that pointer are lost. This also fires PointerCaptureLost on the original capturing element.
In most cases the pointer capture will be released automatically when the user completes an input action that releases the previous pointer capture (lifting a touch point, releasing the left mouse button, taking the stylus out of range). Another condition that might release capture is any action that also fires a PointerCanceled event. Your app can typically rely on the capture-release behavior associated with user input actions, without having to specifically cancel a pointer capture with ReleasePointerCapture or ReleasePointerCaptures. For more info, see Mouse interactions.
The CapturePointer method will return false if the pointer was already captured.
A UIElement can capture more than one pointer point at a time. Use the value parameter to indicate the Pointer instance you want to capture.
The input events that represent gestures (such as Tapped or DoubleTapped ) are usually only fired after a pointer is released, so you shouldn't attempt to capture a pointer in event handlers for gesture events. The Pointer reference in event data for gesture events won't be permitted to initiate a pointer capture.
Tip
Don't try to use CapturePointer outside the scope of pointer-relevant input event handlers. Unless you have a Pointer that you're sure is associated with a pointer that's permitted to have pointer capture at that time, your CapturePointer call won't have any effect. There's no practical way to generate a new Pointer and call CapturePointer using that new pointer. You should only use the Pointer references the system is providing to you through the event data of the pointer-related input events.
Examples
This example shows calling CapturePointer based on handling PointerPressed. It also shows a pattern for tracking and counting pointer references.
int _pointerCount;
public Scenario2()
{
this.InitializeComponent();
bEnteredExited.PointerEntered += bEnteredExited_PointerEntered;
bEnteredExited.PointerExited += bEnteredExited_PointerExited;
bEnteredExited.PointerPressed += bEnteredExited_PointerPressed;
bEnteredExited.PointerReleased += bEnteredExited_PointerReleased;
bEnteredExited.PointerMoved += bEnteredExited_PointerMoved;
// To code for multiple Pointers (that is, fingers),
// we track how many entered/exited.
_pointerCount = 0;
}
private void bEnteredExited_PointerMoved(object sender,
PointerRoutedEventArgs e)
{
Scenario2UpdateVisuals(sender as Border, "Moved");
}
private void bEnteredExited_PointerReleased(object sender,
PointerRoutedEventArgs e)
{
((Border)sender).ReleasePointerCapture(e.Pointer);
txtCaptureStatus.Text = string.Empty;
}
//Can only get capture on PointerPressed (i.e. touch down, mouse click, pen press)
private void bEnteredExited_PointerPressed(object sender,
PointerRoutedEventArgs e)
{
if (tbPointerCapture.IsOn)
{
bool _hasCapture = ((Border)sender).CapturePointer(e.Pointer);
txtCaptureStatus.Text = "Got Capture: " + _hasCapture;
}
}
private void bEnteredExited_PointerExited(object sender,
PointerRoutedEventArgs e)
{
_pointerCount--;
Scenario2UpdateVisuals(sender as Border, "Exited");
}
private void bEnteredExited_PointerEntered(object sender,
PointerRoutedEventArgs e)
{
_pointerCount++;
Scenario2UpdateVisuals(sender as Border, "Entered");
}
private void Scenario2UpdateVisuals(Border border,
String eventDescription)
{
switch (eventDescription.ToLower())
{
case "exited":
if (_pointerCount <= 0)
{
border.Background = new SolidColorBrush(Colors.Red);
bEnteredExitedTextBlock.Text = eventDescription;
}
break;
case "moved":
RotateTransform rt =
(RotateTransform)bEnteredExitedTimer.RenderTransform;
rt.Angle += 2;
if (rt.Angle > 360) rt.Angle -= 360;
break;
default:
border.Background = new SolidColorBrush(Colors.Green);
bEnteredExitedTextBlock.Text = eventDescription;
break;
}
}
private void Scenario2Reset(object sender, RoutedEventArgs e)
{
Scenario2Reset();
}
private void Scenario2Reset()
{
bEnteredExited.Background = new SolidColorBrush(Colors.Green);
bEnteredExitedTextBlock.Text = string.Empty;
}
Private _pointerCount As Integer
Public Sub New()
Me.InitializeComponent()
AddHandler bEnteredExited.PointerEntered, AddressOf bEnteredExited_PointerEntered
AddHandler bEnteredExited.PointerExited, AddressOf bEnteredExited_PointerExited
AddHandler bEnteredExited.PointerPressed, AddressOf bEnteredExited_PointerPressed
AddHandler bEnteredExited.PointerReleased, AddressOf bEnteredExited_PointerReleased
AddHandler bEnteredExited.PointerMoved, AddressOf bEnteredExited_PointerMoved
'To code for multiple Pointers (i.e. Fingers) we track how many entered/exited.
_pointerCount = 0
End Sub
''' <summary>
''' Invoked when this page is about to be displayed in a Frame.
''' </summary>
''' <param name="e">Event data that describes how this page was reached. The Parameter
''' property is typically used to configure the page.</param>
Protected Overrides Sub OnNavigatedTo(e As NavigationEventArgs)
End Sub
Private Sub bEnteredExited_PointerMoved(sender As Object, e As PointerRoutedEventArgs)
Scenario2UpdateVisuals(TryCast(sender, Border), "Moved")
End Sub
Private Sub bEnteredExited_PointerReleased(sender As Object, e As PointerRoutedEventArgs)
DirectCast(sender, Border).ReleasePointerCapture(e.Pointer)
txtCaptureStatus.Text = String.Empty
End Sub
'Can only get capture on PointerPressed (i.e. touch down, mouse click, pen press)
Private Sub bEnteredExited_PointerPressed(sender As Object, e As PointerRoutedEventArgs)
If tbPointerCapture.IsOn Then
Dim _hasCapture As Boolean = DirectCast(sender, Border).CapturePointer(e.Pointer)
txtCaptureStatus.Text = "Got Capture: " & _hasCapture
End If
End Sub
Private Sub bEnteredExited_PointerExited(sender As Object, e As PointerRoutedEventArgs)
_pointerCount -= 1
Scenario2UpdateVisuals(TryCast(sender, Border), "Exited")
End Sub
Private Sub bEnteredExited_PointerEntered(sender As Object, e As PointerRoutedEventArgs)
_pointerCount += 1
Scenario2UpdateVisuals(TryCast(sender, Border), "Entered")
End Sub
Private Sub Scenario2UpdateVisuals(border As Border, eventDescription As String)
Select Case eventDescription.ToLower()
Case "exited"
If _pointerCount <= 0 Then
border.Background = New SolidColorBrush(Colors.Red)
bEnteredExitedTextBlock.Text = eventDescription
End If
Exit Select
Case "moved"
Dim rt As RotateTransform = DirectCast(bEnteredExitedTimer.RenderTransform, RotateTransform)
rt.Angle += 2
If rt.Angle > 360 Then
rt.Angle -= 360
End If
Exit Select
Case Else
border.Background = New SolidColorBrush(Colors.Green)
bEnteredExitedTextBlock.Text = eventDescription
Exit Select
End Select
End Sub
Private Sub Scenario2ResetMethod(sender As Object, e As RoutedEventArgs)
Reset()
End Sub
Private Sub Reset()
bEnteredExited.Background = New SolidColorBrush(Colors.Green)
bEnteredExitedTextBlock.Text = String.Empty
End Sub
- See Also
FindSubElementsForTouchTargeting(Point, Rect) FindSubElementsForTouchTargeting(Point, Rect) FindSubElementsForTouchTargeting(Point, Rect)
Enables a UIElement subclass to expose child elements that assist with resolving touch targeting.
protected virtual IIterable<IIterable<Point>> FindSubElementsForTouchTargeting(Point point, Rect boundingRect)protected virtual IIterable<IIterable<Point>> FindSubElementsForTouchTargeting(Point point, Rect boundingRect)Protected Overridable Function FindSubElementsForTouchTargeting(point As Point, boundingRect As Rect) As IIterable( Of IIterablePoint )
A set of point sets. These represent the vertices of sub elements that are intersected by the given touch point (plus tolerance).
- Attributes
Remarks
Points in the list are in descending z-order: topmost in the rendering stack appears first in the list.
FindElementsInHostCoordinates is a similar static-class helper method that is also used for hit testing and general object tree examination. However, FindSubElementsForTouchTargeting adds the refinement of a Rect input to use for touch tolerance.
If you are programming using C# or Microsoft Visual Basic, the return value type of this method is projected as an IEnumerable generic collection that contains UIElement items. If you are programming using Visual C++ component extensions (C++/CX), the return type of this method is IIterable;.
- See Also
InvalidateArrange() InvalidateArrange() InvalidateArrange()
Invalidates the arrange state (layout) for a UIElement. After the invalidation, the UIElement will have its layout updated, which will occur asynchronously.
public void InvalidateArrange()public void InvalidateArrange()Public Function InvalidateArrange() As void
- Attributes
Remarks
Controls that maintain their own orientation property might call InvalidateArrange when that orientation changes, as a way to reconstruct the layout for the new orientation. InvalidateArrange might also be called from within custom layout logic in cases such as when available size isn't adequate and the logic allows for an alternate layout strategy that uses available size differently.
UpdateLayout is basically equivalent to calling InvalidateMeasure and InvalidateArrange in sequence.
Layout updates can be forced by app code rather than relying on the built-in layout system behavior. However, that is not generally recommended. Calling InvalidateArrange, InvalidateMeasure or UpdateLayout is usually unnecessary and can cause poor performance if overused. In many situations where app code might be changing layout properties, the layout system will probably already be processing updates asynchronously. The layout system also has optimizations for dealing with cascades of layout changes through parent-child relationships, and forcing layout with app code can work against such optimizations. Nevertheless, it's possible that layout situations exist in more complicated scenarios where forcing layout is the best option for resolving a timing issue or other issue with layout. Just use it deliberately and sparingly.
- See Also
InvalidateMeasure() InvalidateMeasure() InvalidateMeasure()
Invalidates the measurement state (layout) for a UIElement.
public void InvalidateMeasure()public void InvalidateMeasure()Public Function InvalidateMeasure() As void
- Attributes
Remarks
UpdateLayout is basically equivalent to calling InvalidateMeasure and InvalidateArrange in sequence.
Layout updates can be forced by app code rather than relying on the built-in layout system behavior. However, that is not generally recommended. Calling InvalidateArrange, InvalidateMeasure or UpdateLayout is usually unnecessary and can cause poor performance if overused. In many situations where app code might be changing layout properties, the layout system will probably already be processing updates asynchronously. The layout system also has optimizations for dealing with cascades of layout changes through parent-child relationships, and forcing layout with app code can work against such optimizations. Nevertheless, it's possible that layout situations exist in more complicated scenarios where forcing layout is the best option for resolving a timing issue or other issue with layout. Just use it deliberately and sparingly.
- See Also
Measure(Size) Measure(Size) Measure(Size)
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.
public void Measure(Size availableSize)public void Measure(Size availableSize)Public Function Measure(availableSize As Size) As void
The available space that a parent can allocate to a child object. A child object can request a larger space than what is available; the provided size might be accommodated if scrolling or other resize behavior is possible in that particular container.
- Attributes
Remarks
The Measure call potentially reaches a MeasureOverride implementation of that specific class. Otherwise, most FrameworkElement classes have an implicit default layout behavior for Measure.
availableSize can be any number from zero to infinite. Elements participating in layout should return the minimum Size they require for a given availableSize.
Computation of initial layout positioning in a XAML UI consists of a Measure call and an Arrange call, in that order. During the Measure call, the layout system determines an element's size requirements using the availableSize measurement. During the Arrange call, the layout system finalizes the size and position of an element's bounding box.
When a layout is first produced, it always has a Measure call that happens before Arrange. However, after the first layout pass, an Arrange call can happen without a Measure preceding it. This can happen when a property that affects only Arrange is changed (such as alignment), or when the parent receives an Arrange without a Measure.
A Measure call will automatically invalidate any Arrange information. Layout updates generally occur asynchronously (at a time determined by the layout system). An element might not immediately reflect changes to properties that affect element sizing (such as Width ).
Examples
This example implements MeasureOverride to customize the "Measure" pass logic for a custom panel implementation. Note in particular these aspects of the code:
- Iterates over children.
- For each child, calls Measure, using a Size that makes sense based on how the panel logic treats the number of children and its own known size limit.
- Returns its size (in this case, this simple panel returns a fixed size rather than a size calculated on accumulating the measurements).
// First measure all children and return available size of panel
protected override Size MeasureOverride(Size availableSize)
{
// Measure first 9 children giving them space up to 100x100, remaining children get 0x0
int i = 0;
foreach (FrameworkElement child in Children)
{
if (i < 9)
{
child.Measure(new Size(100, 100));
}
else
{
child.Measure(new Size(0, 0));
}
i++;
}
// return the size available to the whole panel, which is 300x300
return new Size(300, 300);
}
'First measure all children and return available size of panel
Protected Overrides Function MeasureOverride(ByVal availableSize As Size) As Size
'Measure first 9 children giving them space up to 100x100, remaining children get 0x0
Dim i As Integer = 0
For Each child As FrameworkElement In Children
If i < 9 Then
child.Measure(New Size(100, 100))
Else
child.Measure(New Size(0, 0))
End If
i += 1
Next
'return the size available to the whole panel, which is 300x300
Return New Size(300, 300)
End Function
- See Also
OnCreateAutomationPeer() OnCreateAutomationPeer() OnCreateAutomationPeer()
When implemented in a derived class, returns class-specific AutomationPeer implementations for the Microsoft UI Automation infrastructure.
protected virtual AutomationPeer OnCreateAutomationPeer()protected virtual AutomationPeer OnCreateAutomationPeer()Protected Overridable Function OnCreateAutomationPeer() As AutomationPeer
The class-specific AutomationPeer subclass to return.
- Attributes
Remarks
For more info on the purpose of an automation peer and why you might need to define a class-specific AutomationPeer class, see Custom automation peers.
You should override this method in a custom class where you want to supply a custom automation peer for Microsoft UI Automation, rather than the default peer that is referenced by the default OnCreateAutomationPeer implementation. How you define a custom peer for your custom control depends on your control's accessibility requirements , its UI contract, and its behavior. For more info on why you might want to define a new peer, see Custom automation peers. To see a sample that implements OnCreateAutomationPeer and defines the custom peer that OnCreateAutomationPeer returns, see XAML accessibility sample (the peer implementation is part of Scenario 3 in that sample).
We recommend that the OnCreateAutomationPeer implementation should do nothing more than initialize a new instance of your custom automation peer, passing the calling control as owner, and return that instance. Do not attempt additional logic in this method. In particular, any logic that could potentially lead to destruction of the AutomationPeer within the same call may result in unexpected runtime behavior.
Examples
The entirety of a OnCreateAutomationPeer implementation should consist of constructing the custom automation peer class and returning it.
protected override AutomationPeer OnCreateAutomationPeer()
{
return new MediaContainerAP(this, mediaElement);
}
Protected Overrides Function OnCreateAutomationPeer() As AutomationPeer
Return New MediaContainerAP(Me, mediaElement)
End Function
protected:
virtual AutomationPeer^ OnCreateAutomationPeer() override
{
return ref new MediaContainerAP(this, mediaElement);
}
};
- See Also
OnDisconnectVisualChildren() OnDisconnectVisualChildren() OnDisconnectVisualChildren()
Override this method to implement how layout and logic should behave when items are removed from a class-specific content or children property.
protected virtual void OnDisconnectVisualChildren()protected virtual void OnDisconnectVisualChildren()Protected Overridable Function OnDisconnectVisualChildren() As void
- Attributes
Remarks
UIElement does not define any of the content model properties that OnDisconnectVisualChildren might act upon. Such properties are introduced deeper in an inheritance, for example at the ContentControl level.
FrameworkElement uses an OnDisconnectVisualChildren override to clear values from DataContext and Tag. In general, if you override this method you should always call the base implementation so that the framework-intentional behavior that acts on OnDisconnectVisualChildren can be preserved.
VisualTreeHelper.DisconnectChildrenRecursive is a similar static helper API that can be called by app code.
ReleasePointerCapture(Pointer) ReleasePointerCapture(Pointer) ReleasePointerCapture(Pointer)
Releases pointer captures for capture of one specific pointer by this UIElement.
public void ReleasePointerCapture(Pointer value)public void ReleasePointerCapture(Pointer value)Public Function ReleasePointerCapture(value As Pointer) As void
The pointer reference. Use either saved references from previous captures, or pointer event data, to obtain this reference.
- Attributes
Remarks
Programmatically releasing the pointer capture with ReleasePointerCapture is not the only way that an element might lose pointer capture. For example, user-driven events such as releasing the pointer (touch point up, mouse button released) can cause the pointer capture to be canceled.
You can listen for the PointerCaptureLost event to determine when this happens.
Another way that pointer capture might be canceled is if a pointer moves out of one app and into another app while the two apps are side-by-side.
You should only call ReleasePointerCapture if your app code has previously called CapturePointer, and has a reference to the particular Pointer instance where you want to release the pointer capture. You'd typically get that Pointer reference through an event such as PointerReleased or perhaps PointerMoved.
Your app code might call CapturePointer from a different UIElement than the one that has any current pointer capture. If so, that cancels any pointer capture previously made by other elements.
A UIElement can capture multiple pointers to handle multiple touch points such as for manipulations, but only one UIElement in an app can have any pointer captures at any one time. For more info, see Handle pointer input.
Examples
This example shows calling ReleasePointerCapture based on handling PointerReleased.
It also shows code for capturing the pointer initially, and a pattern for tracking and counting pointer references.
int _pointerCount;
public Scenario2()
{
this.InitializeComponent();
bEnteredExited.PointerEntered += bEnteredExited_PointerEntered;
bEnteredExited.PointerExited += bEnteredExited_PointerExited;
bEnteredExited.PointerPressed += bEnteredExited_PointerPressed;
bEnteredExited.PointerReleased += bEnteredExited_PointerReleased;
bEnteredExited.PointerMoved += bEnteredExited_PointerMoved;
// To code for multiple Pointers (that is, fingers),
// we track how many entered/exited.
_pointerCount = 0;
}
private void bEnteredExited_PointerMoved(object sender,
PointerRoutedEventArgs e)
{
Scenario2UpdateVisuals(sender as Border, "Moved");
}
private void bEnteredExited_PointerReleased(object sender,
PointerRoutedEventArgs e)
{
((Border)sender).ReleasePointerCapture(e.Pointer);
txtCaptureStatus.Text = string.Empty;
}
//Can only get capture on PointerPressed (i.e. touch down, mouse click, pen press)
private void bEnteredExited_PointerPressed(object sender,
PointerRoutedEventArgs e)
{
if (tbPointerCapture.IsOn)
{
bool _hasCapture = ((Border)sender).CapturePointer(e.Pointer);
txtCaptureStatus.Text = "Got Capture: " + _hasCapture;
}
}
private void bEnteredExited_PointerExited(object sender,
PointerRoutedEventArgs e)
{
_pointerCount--;
Scenario2UpdateVisuals(sender as Border, "Exited");
}
private void bEnteredExited_PointerEntered(object sender,
PointerRoutedEventArgs e)
{
_pointerCount++;
Scenario2UpdateVisuals(sender as Border, "Entered");
}
private void Scenario2UpdateVisuals(Border border,
String eventDescription)
{
switch (eventDescription.ToLower())
{
case "exited":
if (_pointerCount <= 0)
{
border.Background = new SolidColorBrush(Colors.Red);
bEnteredExitedTextBlock.Text = eventDescription;
}
break;
case "moved":
RotateTransform rt =
(RotateTransform)bEnteredExitedTimer.RenderTransform;
rt.Angle += 2;
if (rt.Angle > 360) rt.Angle -= 360;
break;
default:
border.Background = new SolidColorBrush(Colors.Green);
bEnteredExitedTextBlock.Text = eventDescription;
break;
}
}
private void Scenario2Reset(object sender, RoutedEventArgs e)
{
Scenario2Reset();
}
private void Scenario2Reset()
{
bEnteredExited.Background = new SolidColorBrush(Colors.Green);
bEnteredExitedTextBlock.Text = string.Empty;
}
Private _pointerCount As Integer
Public Sub New()
Me.InitializeComponent()
AddHandler bEnteredExited.PointerEntered, AddressOf bEnteredExited_PointerEntered
AddHandler bEnteredExited.PointerExited, AddressOf bEnteredExited_PointerExited
AddHandler bEnteredExited.PointerPressed, AddressOf bEnteredExited_PointerPressed
AddHandler bEnteredExited.PointerReleased, AddressOf bEnteredExited_PointerReleased
AddHandler bEnteredExited.PointerMoved, AddressOf bEnteredExited_PointerMoved
'To code for multiple Pointers (i.e. Fingers) we track how many entered/exited.
_pointerCount = 0
End Sub
''' <summary>
''' Invoked when this page is about to be displayed in a Frame.
''' </summary>
''' <param name="e">Event data that describes how this page was reached. The Parameter
''' property is typically used to configure the page.</param>
Protected Overrides Sub OnNavigatedTo(e As NavigationEventArgs)
End Sub
Private Sub bEnteredExited_PointerMoved(sender As Object, e As PointerRoutedEventArgs)
Scenario2UpdateVisuals(TryCast(sender, Border), "Moved")
End Sub
Private Sub bEnteredExited_PointerReleased(sender As Object, e As PointerRoutedEventArgs)
DirectCast(sender, Border).ReleasePointerCapture(e.Pointer)
txtCaptureStatus.Text = String.Empty
End Sub
'Can only get capture on PointerPressed (i.e. touch down, mouse click, pen press)
Private Sub bEnteredExited_PointerPressed(sender As Object, e As PointerRoutedEventArgs)
If tbPointerCapture.IsOn Then
Dim _hasCapture As Boolean = DirectCast(sender, Border).CapturePointer(e.Pointer)
txtCaptureStatus.Text = "Got Capture: " & _hasCapture
End If
End Sub
Private Sub bEnteredExited_PointerExited(sender As Object, e As PointerRoutedEventArgs)
_pointerCount -= 1
Scenario2UpdateVisuals(TryCast(sender, Border), "Exited")
End Sub
Private Sub bEnteredExited_PointerEntered(sender As Object, e As PointerRoutedEventArgs)
_pointerCount += 1
Scenario2UpdateVisuals(TryCast(sender, Border), "Entered")
End Sub
Private Sub Scenario2UpdateVisuals(border As Border, eventDescription As String)
Select Case eventDescription.ToLower()
Case "exited"
If _pointerCount <= 0 Then
border.Background = New SolidColorBrush(Colors.Red)
bEnteredExitedTextBlock.Text = eventDescription
End If
Exit Select
Case "moved"
Dim rt As RotateTransform = DirectCast(bEnteredExitedTimer.RenderTransform, RotateTransform)
rt.Angle += 2
If rt.Angle > 360 Then
rt.Angle -= 360
End If
Exit Select
Case Else
border.Background = New SolidColorBrush(Colors.Green)
bEnteredExitedTextBlock.Text = eventDescription
Exit Select
End Select
End Sub
Private Sub Scenario2ResetMethod(sender As Object, e As RoutedEventArgs)
Reset()
End Sub
Private Sub Reset()
bEnteredExited.Background = New SolidColorBrush(Colors.Green)
bEnteredExitedTextBlock.Text = String.Empty
End Sub
- See Also
ReleasePointerCaptures() ReleasePointerCaptures() ReleasePointerCaptures()
Releases all pointer captures held by this element.
public void ReleasePointerCaptures()public void ReleasePointerCaptures()Public Function ReleasePointerCaptures() As void
- Attributes
Remarks
Because there are input scenarios such as manipulations that involve more than one pointer point, the Windows Runtime enables capturing more than one pointer at a time. Calling ReleasePointerCapture removes a specific Pointer from the collection as identified by its ID, whereas ReleasePointerCaptures clears the entire collection.
User action that invalidates pointer capture such as releasing from a pointer point also changes capture state. For more info, see Mouse interactions and Handle pointer input.
The PointerCaptures property exposes a view of which pointer points are currently captured by the UIElement.
RemoveHandler(RoutedEvent, Object) RemoveHandler(RoutedEvent, Object) RemoveHandler(RoutedEvent, Object)
Removes the specified routed event handler from this UIElement. Typically the handler in question was added by AddHandler.
public void RemoveHandler(RoutedEvent routedEvent, Object handler)public void RemoveHandler(RoutedEvent routedEvent, Object handler)Public Function RemoveHandler(routedEvent As RoutedEvent, handler As Object) As void
- routedEvent
- RoutedEvent RoutedEvent RoutedEvent
The identifier of the routed event for which the handler is attached.
- handler
- System.Object System.Object System.Object
The specific handler implementation to remove from the event handler collection on this UIElement.
- Attributes
Remarks
RemoveHandler can only be used for the event handlers of the events that are supported by AddHandler, which is approximately the input-specific events of UIElement. More precisely, the event must have a **Event* property of type RoutedEvent, which is true only of certain events on UIElement. You cannot use RemoveHandler to unhook event handlers for Windows Runtime events on runtime class instances in general. Instead, you should use the specific event handler unhooking syntax:
-=in C#- RemoveHandler in Microsoft Visual Basic
-=in Visual C++ component extensions (C++/CX)
Calling this method has no effect if there were no handlers registered with criteria that match the input parameters for the method call.
This method ignores whether handledEventsToo parameter was true in the AddHandler call that originally attached the handler.
- See Also
StartBringIntoView() StartBringIntoView() StartBringIntoView()
Initiates a request to the XAML framework to bring the element into view within any scrollable regions it is contained within.
public void StartBringIntoView()public void StartBringIntoView()Public Function StartBringIntoView() As void
- Attributes
| Device family |
Windows 10 Creators Update (introduced v10.0.15063.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v4)
|
Remarks
The request is fulfilled asynchronously as the framework initiates changes to the view of ScrollViewer s that contain the element. The HorizontalOffset and VerticalOffset of those ScrollViewers may not be updated immediately upon returning from the call. However, in the process of servicing the request a ScrollViewer’s ViewChanging and ViewChanged events will fire. If you use the signature that does not specify any options, then the entire element size (its RenderSize ) will be made visible and any changes to the viewports will be animated. The StartBringIntoView method does not transmit any information about success or failure. Reasons for failure can include the element settings, such as Visibility being some value other than Visible.
StartBringIntoView(BringIntoViewOptions) StartBringIntoView(BringIntoViewOptions) StartBringIntoView(BringIntoViewOptions)
Initiates a request to the XAML framework to bring the element into view using the specified options.
public void StartBringIntoView(BringIntoViewOptions options)public void StartBringIntoView(BringIntoViewOptions options)Public Function StartBringIntoView(options As BringIntoViewOptions) As void
An instance of BringIntoViewOptions.
- Attributes
| Device family |
Windows 10 Creators Update (introduced v10.0.15063.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v4)
|
StartDragAsync(PointerPoint) StartDragAsync(PointerPoint) StartDragAsync(PointerPoint)
Initiates a drag-and-drop operation.
public IAsyncOperation<DataPackageOperation> StartDragAsync(PointerPoint pointerPoint)public IAsyncOperation<DataPackageOperation> StartDragAsync(PointerPoint pointerPoint)Public Function StartDragAsync(pointerPoint As PointerPoint) As IAsyncOperation( Of DataPackageOperation )
- pointerPoint
- PointerPoint PointerPoint PointerPoint
The coordinates of the pointer where the user interacts with the screen, and where the drag visual is attached.
A DataPackageOperation value that indicates the type of drag-and-drop operation, and whether the operation was successful.
- Attributes
Remarks
If you implement custom gesture detection to initiate a drag operation, you can call the StartDragAsync method to programmatically initiate a drag operation on any UIElement. Calling this method results in the DragStarting event being raised. Handle the DragStarting event to specify other properties of the operation, such as the data package and drag visual.
The pointerPoint parameter is the point at which the user interacts with the screen using an input device (touch, mouse, or pen). The drag visual that is shown during the drag operation is attached to the pointer indicated in the caller-provided PointerPoint.
The DataPackageOperation returned by this method indicates whether the drag operation is a move, copy, or link; and whether or not it's a success. This is the same value that's provided by the DropResult property in the DropCompleted event args.
Examples
This example shows how to handle the PointerPressed event on an Image element to initiate a drag operation.
<Image x:Name="myImage" Source="ms-appx:///Assets/Logo.png"
PointerPressed="myImage_PointerPressed" />
private async void myImage_PointerPressed(object sender, PointerRoutedEventArgs e)
{
var pointerPoint = e.GetCurrentPoint(sender as UIElement);
var dropStatus = await myImage.StartDragAsync(pointerPoint);
if (dropStatus == DataPackageOperation.Move)
{
// App specific code for a "move" operation.
}
}
- See Also
TransformToVisual(UIElement) TransformToVisual(UIElement) TransformToVisual(UIElement)
Returns a transform object that can be used to transform coordinates from the UIElement to the specified object.
public GeneralTransform TransformToVisual(UIElement visual)public GeneralTransform TransformToVisual(UIElement visual)Public Function TransformToVisual(visual As UIElement) As GeneralTransform
The object to compare to the current object for purposes of obtaining the transform.
The transform information as an object. Call methods on this object to get a practical transform.
- Attributes
Remarks
Call TransformToVisual in order to get a coordinate offset between two elements in a UI. The first element being considered is the UIElement where you call TransformToVisual, the second element is the UIElement you pass as the visual parameter. For example, you can use the transform to determine how the bounds of an element are positioned in a coordinate system that is relative to a layout parent element, rather than the app's window.
TransformToVisual gives coordinate results after all considerations that affect rendering and positioning such as RenderTransform have been applied. This is useful if you're processing point values that were obtained during an animation of RenderTransform or other position changes.
The most common scenario for TransformToVisual is if you want to use a local coordinate system relative to the UIElement you call it on, and you aren't handling a real-time input event that has event data methods for converting a Point value into the object's frame of reference. After you call TransformToVisual, you can then call TransformPoint on the returned GeneralTransform.
Note
The GeneralTransform object returned by this method can be cast to a derived type, Transform, but all the methods you need are defined by GeneralTransform. You can't cast to TranslateTransform even though you might expect that the transform result would be a translation.
Examples
This example shows a scenario for calling TransformToVisual in order to interpret the coordinates from a PointerPoint in the coordinate reference frame of an element that's not the event sender. Here, the queryPointer method first accesses coordinates that do relate to the sender (this is the GetCurrentPoint call in the first line of the method) but then later uses TransformToVisual to convert point coordinates into the reference frame for the page layout container that's actually several layers of containment up in the XAML. To see more context for this code (including seeing how queryPointer displays results in UI and when it's called), see the complete code example that is shown in the topic Handle pointer input.
<Page
x:Class="PointerInput.MainPage"
IsTabStop="false"
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
xmlns:local="using:PointerInput"
xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
mc:Ignorable="d"
Name="page">
<Grid Background="{StaticResource ApplicationPageBackgroundThemeBrush}">
<Grid.ColumnDefinitions>
<ColumnDefinition Width="*" />
<ColumnDefinition Width="150" />
</Grid.ColumnDefinitions>
<Grid.RowDefinitions>
<RowDefinition Height="*" />
<RowDefinition Height="320" />
<RowDefinition Height="*"/>
</Grid.RowDefinitions>
<Canvas Name="Container"
Grid.Column="0"
Grid.Row="1"
HorizontalAlignment="Center"
VerticalAlignment="Center"
Margin="0,0,0,0"
Height="320" Width="640">
<Rectangle Name="Target"
Fill="#FF0000"
Stroke="Black"
StrokeThickness="0"
Height="320" Width="640" />
</Canvas>
<TextBox Name="eventLog"
Grid.Column="1"
Grid.Row="0"
Grid.RowSpan="3"
Background="#000000"
TextWrapping="Wrap"
Foreground="#FFFFFF"
ScrollViewer.VerticalScrollBarVisibility="Visible"
BorderThickness="0"/>
</Grid>
</Page>
<Page
x:Class="PointerInput.MainPage"
IsTabStop="false"
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
xmlns:local="using:PointerInput"
xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
mc:Ignorable="d"
Name="page">
<Grid Background="{StaticResource ApplicationForegroundThemeBrush}">
<Grid.ColumnDefinitions>
<ColumnDefinition Width="*" />
<ColumnDefinition Width="69.458" />
<ColumnDefinition Width="80.542"/>
</Grid.ColumnDefinitions>
<Grid.RowDefinitions>
<RowDefinition Height="*" />
<RowDefinition Height="320" />
<RowDefinition Height="*"/>
</Grid.RowDefinitions>
<Canvas Name="Container"
Grid.Column="0"
Grid.Row="1"
HorizontalAlignment="Center"
VerticalAlignment="Center"
Margin="245,0"
Height="320" Width="640">
<Rectangle Name="Target"
Fill="#FF0000"
Stroke="Black"
StrokeThickness="0"
Height="320" Width="640" />
</Canvas>
<Button Name="buttonClear"
Foreground="White"
Width="100"
Height="100">
clear
</Button>
<TextBox Name="eventLog"
Grid.Column="1"
Grid.Row="0"
Grid.RowSpan="3"
Background="#000000"
TextWrapping="Wrap"
Foreground="#FFFFFF"
ScrollViewer.VerticalScrollBarVisibility="Visible"
BorderThickness="0" Grid.ColumnSpan="2"/>
</Grid>
</Page>
String queryPointer(PointerPoint ptrPt)
{
String details = "";
switch (ptrPt.PointerDevice.PointerDeviceType)
{
case Windows.Devices.Input.PointerDeviceType.Mouse:
details += "\nPointer type: mouse";
break;
case Windows.Devices.Input.PointerDeviceType.Pen:
details += "\nPointer type: pen";
if (ptrPt.IsInContact)
{
details += "\nPressure: " + ptrPt.Properties.Pressure;
details += "\nrotation: " + ptrPt.Properties.Orientation;
details += "\nTilt X: " + ptrPt.Properties.XTilt;
details += "\nTilt Y: " + ptrPt.Properties.YTilt;
details += "\nBarrel button pressed: " + ptrPt.Properties.IsBarrelButtonPressed;
}
break;
case Windows.Devices.Input.PointerDeviceType.Touch:
details += "\nPointer type: touch";
details += "\nrotation: " + ptrPt.Properties.Orientation;
details += "\nTilt X: " + ptrPt.Properties.XTilt;
details += "\nTilt Y: " + ptrPt.Properties.YTilt;
break;
default:
details += "\nPointer type: n/a";
break;
}
GeneralTransform gt = Target.TransformToVisual(page);
Point screenPoint;
screenPoint = gt.TransformPoint(new Point(ptrPt.Position.X, ptrPt.Position.Y));
details += "\nPointer Id: " + ptrPt.PointerId.ToString() +
"\nPointer location (parent): " + ptrPt.Position.X + ", " + ptrPt.Position.Y +
"\nPointer location (screen): " + screenPoint.X + ", " + screenPoint.Y;
return details;
}
String queryPointer(PointerPoint ptrPt)
{
String details = "";
switch (ptrPt.PointerDevice.PointerDeviceType)
{
case Windows.Devices.Input.PointerDeviceType.Mouse:
details += "\nPointer type: mouse";
break;
case Windows.Devices.Input.PointerDeviceType.Pen:
details += "\nPointer type: pen";
if (ptrPt.IsInContact)
{
details += "\nPressure: " + ptrPt.Properties.Pressure;
details += "\nrotation: " + ptrPt.Properties.Orientation;
details += "\nTilt X: " + ptrPt.Properties.XTilt;
details += "\nTilt Y: " + ptrPt.Properties.YTilt;
details += "\nBarrel button pressed: " + ptrPt.Properties.IsBarrelButtonPressed;
}
break;
case Windows.Devices.Input.PointerDeviceType.Touch:
details += "\nPointer type: touch";
details += "\nrotation: " + ptrPt.Properties.Orientation;
details += "\nTilt X: " + ptrPt.Properties.XTilt;
details += "\nTilt Y: " + ptrPt.Properties.YTilt;
break;
default:
details += "\nPointer type: n/a";
break;
}
GeneralTransform gt = Target.TransformToVisual(page);
Point screenPoint;
screenPoint = gt.TransformPoint(new Point(ptrPt.Position.X, ptrPt.Position.Y));
details += "\nPointer Id: " + ptrPt.PointerId.ToString() +
"\nPointer location (parent): " + ptrPt.Position.X + ", " + ptrPt.Position.Y +
"\nPointer location (screen): " + screenPoint.X + ", " + screenPoint.Y;
return details;
}
- See Also
TryStartDirectManipulation(Pointer) TryStartDirectManipulation(Pointer) TryStartDirectManipulation(Pointer)
Resumes direct manipulation processing (system-defined panning/zooming) on any ScrollViewer parent that contains the current UIElement.
public static PlatForm::Boolean TryStartDirectManipulation(Pointer value)public static bool TryStartDirectManipulation(Pointer value)Public Static Function TryStartDirectManipulation(value As Pointer) As bool
true if a ScrollViewer parent exists and setting the value resulted in resuming the panning/zooming action. false if calling the method results in no action.
- Attributes
Remarks
By default, touch input interactions in ScrollViewer elements are handled by the Direct Manipulation engine off the UI thread. An app cannot directly process the associated pointer events after Direct Manipulation processing starts. You can call CancelDirectManipulations at the start of a ScrollViewer interaction and handle the pointer events on the UI thread, which gives you the opportunity to do custom input handling in a ScrollViewer.
If you cancel Direct Manipulation processing at the start of a ScrollViewer interaction, you can call TryStartDirectManipulation to resume having Direct Manipulation process the input stream. This lets you to do custom input processing first, and then resume Direct Manipulation handling to make your app more responsive to touch interactions like scrolling and zooming.
Only active touch contacts can be passed to Direct Manipulation. Using non-active or non-touch contacts causes an exception to be thrown.
Specifying a touch contact to pass to Direct Manipulation results in the framework walking up the parent chain and setting the contact on the Direct Manipulation viewport of each ScrollViewer encountered in order, until the walk reaches any element (including the original target element) that does not have a ManipulationMode that contains ManipulationModes.System. A given touch contact can only be associated with a single chain of visuals at a time. Calling TryStartDirectManipulation more than once on the same contact results in any previous chain being released.
- See Also
UpdateLayout() UpdateLayout() UpdateLayout()
Ensures that all positions of child objects of a UIElement are properly updated for layout.
public void UpdateLayout()public void UpdateLayout()Public Function UpdateLayout() As void
- Attributes
Remarks
UpdateLayout is basically equivalent to calling InvalidateMeasure and InvalidateArrange in sequence.
Layout updates can be forced by app code rather than relying on the built-in layout system behavior by using the UpdateLayout method. However, that is not generally recommended. It is usually unnecessary and can cause poor performance if overused. In many situations where calling UpdateLayout from app code might be appropriate because of changes to properties, the layout system will probably already be processing updates. The layout system also has optimizations for dealing with cascades of layout changes through parent-child relationships, and calling UpdateLayout can work against such optimizations. Nevertheless, it's possible that layout situations exist in more complicated scenarios where calling UpdateLayout is the best option for resolving a timing issue or other issue with layout. Just use it deliberately and sparingly. In the cases where you do need to call UpdateLayout you're probably going to call it just after calling Children.Add on some collection of child elements of a common layout parent, then calling UpdateLayout on that parent to make the layout system recognize the new added child.
One scenario for UpdateLayout is when you have linked containers like RichTextBlock and RichTextBlockOverflow, you've made run-time changes to the content, and you want to make sure that operations not specifically tied to displaying the UI have a chance to run the layout and trigger the content rebalance between the linked containers. For example, you might want to do this to prepare a layout for printing. For an example of this scenario, see the #5 scenario in Print sample.
Tip
If you have a scenario where you use data binding to UI and you aren't seeing the layout reflect updates in your data source collections, calling UpdateLayout probably isn't going to help. It's more likely that you have issues with your binding declarations, the data context, or with the INotifyPropertyChanged or INotifyCollectionChanged support in your data source.
- See Also
Events
AccessKeyDisplayDismissed AccessKeyDisplayDismissed AccessKeyDisplayDismissed
Occurs when the access key sequence is complete to notify controls that they should hide access key visuals.
public event TypedEventHandler AccessKeyDisplayDismissedpublic event TypedEventHandler AccessKeyDisplayDismissedPublic Event AccessKeyDisplayDismissed
- Attributes
| Device family |
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v3)
|
AccessKeyDisplayRequested AccessKeyDisplayRequested AccessKeyDisplayRequested
Occurs when the access key sequence is started to notify controls that they should show access key visuals.
public event TypedEventHandler AccessKeyDisplayRequestedpublic event TypedEventHandler AccessKeyDisplayRequestedPublic Event AccessKeyDisplayRequested
- Attributes
| Device family |
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v3)
|
Remarks
This event is not raised if the element is under an element with its Visibility property set to Collapsed.
AccessKeyInvoked AccessKeyInvoked AccessKeyInvoked
Occurs when a user completes an access key sequence to notify the element that the access key action should be invoked.
public event TypedEventHandler AccessKeyInvokedpublic event TypedEventHandler AccessKeyInvokedPublic Event AccessKeyInvoked
- Attributes
| Device family |
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v3)
|
Remarks
This event indicates that an element’s access key action should be invoked. For example, this will be raised if an element’s AccessKey is "A" and the user presses Alt-A.
An access key can have one or several characters. This event occurs only when users type all the characters of an access key. For example, if an AccessKey value is "BC", the event doesn't occur when the user presses "B". The event occurs when the user presses "B", then "C".
This event occurs when the key is pressed, not when it's released.
ContextCanceled ContextCanceled ContextCanceled
Occurs when a context input gesture continues into a manipulation gesture, to notify the element that the context flyout should not be opened.
public event TypedEventHandler ContextCanceledpublic event TypedEventHandler ContextCanceledPublic Event ContextCanceled
- Attributes
| Device family |
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v3)
|
Remarks
You typically handle this event for elements that can be manipulated by drag-and-drop. This event is raised when a ContextRequested event has been raised, but the element has not received a PointerReleased event before a manipulation begins. This indicates that the user intended to invoke a manipulation rather than a context flyout, so the context flyout should not be opened.
ContextRequested ContextRequested ContextRequested
Occurs when the user has completed a context input gesture, such as a right-click.
public event TypedEventHandler ContextRequestedpublic event TypedEventHandler ContextRequestedPublic Event ContextRequested
- Attributes
| Device family |
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v3)
|
Remarks
If the ContextFlyout property is null, this event is marked as handled.
DoubleTapped DoubleTapped DoubleTapped
Occurs when an otherwise unhandled DoubleTap interaction occurs over the hit test area of this element.
public event DoubleTappedEventHandler DoubleTappedpublic event DoubleTappedEventHandler DoubleTappedPublic Event DoubleTapped
<uiElement DoubleTapped="eventhandler"/>
- Attributes
Remarks
A DoubleTap interaction is simply two Tap interactions that occur in quick succession. The exact timing of what the system interprets as a double tap is adjustable by users through system settings.
See Touch interaction design for more info on how to use a DoubleTap interaction in your app design.
If a user interaction also fires DoubleTapped, Tapped will fire first to represent the first tap, but the second tap won't fire an additional Tapped. If you want different logic for Tapped versus DoubleTapped, your Tapped handler may need to use app-specific variables and a timer in order to avoid running on interactions that are eventually interpreted as a DoubleTap action.
A DoubleTapped event represents a gesture, whereas a PointerPressed event is a lower-level input event. DoubleTapped and PointerPressed events can fire as the result of a single user interaction. Even if a control is already handling pointer events in the control logic, or is handling manipulations, that doesn't prevent DoubleTapped from firing.
A DoubleTapped event is potentially the result of more than one pointer point. For the higher-level gesture events like DoubleTapped you no longer have immediate access to PointerPoint details such as individual PointerId values or individual coordinates. You do have access to device type (PointerDeviceType ) and for coordinates you can call GetPosition, which gives an average of the coordinates for a DoubleTap from more than one pointer point.
DoubleTapped is a routed event. Also, an element must have IsDoubleTapEnabled be true to be a DoubleTapped event source (true is the default). It is possible to handle DoubleTapped on parent elements even if IsDoubleTapEnabled is false on the parent element, if the event bubbles to a parent from an event source child element where IsDoubleTapEnabled is false. For more info on the routed event concept, see Events and routed events overview.
For touch actions and also for interaction-specific or manipulation events that are consequences of a touch action, an element must be hit-test visible in order to be the event source and fire the event that is associated with the action. UIElement.Visibility must be Visible. Other properties of derived types also affect hit-test visibility. For more info, see Events and routed events overview.
DoubleTapped supports the ability to attach event handlers to the route that will be invoked even if the event data for the event is marked Handled. See AddHandler.
Specific Windows Runtime controls may have class-based handling for the DoubleTapped input event. If so, the control probably has an override for the method OnDoubleTapped. Typically the event is marked handled by the class handler, and the DoubleTapped event is not raised for handling by any user code handlers on that control. For more info on how class-based handling for events works, see Events and routed events overview.
- See Also
DragEnter DragEnter DragEnter
Occurs when the input system reports an underlying drag event with this element as the target.
public event DragEventHandler DragEnterpublic event DragEventHandler DragEnterPublic Event DragEnter
<uiElement DragEnter="eventhandler"/>
- Attributes
Remarks
For a DragEnter event to occur, the value of AllowDrop on the current UIElement and on the event source must be true. Otherwise, consider using PointerEntered.
You can initiate a drag-drop action on any UIElement by calling the StartDragAsync method. Once the action is initiated, any UIElement in the app can potentially be a drop target so long as AllowDrop is true on that element. Any elements that the drag-drop action passes over can handle DragEnter, DragLeave or DragOver.
DragEnter is a routed event. For more info on the routed event concept, see Events and routed events overview.
For touch actions, drag-drop actions, and also for interaction-specific or manipulation events that are consequences of a touch action, an element must be hit-test visible in order to be the event source and fire the event that is associated with the action. UIElement.Visibility must be Visible. Other properties of derived types also affect hit-test visibility, for example IsEnabled. For more info, see Events and routed events overview.
DragEnter supports the ability to attach event handlers to the route that will be invoked even if the event data for the event is marked Handled. See AddHandler.
Specific Windows Runtime controls may have class-based handling for the DragEnter event. If so, the control probably has an override for the method OnDragEnter. Typically the event is marked handled by the class handler, and the DragEnter event is not raised for handling by any user code handlers on that control. For more info, see Events and routed events overview.
Independent of the event occurrence, some controls may use theme animations such as DragItemThemeAnimation to visually indicate a drag behavior to the user.
Windows 8/Windows 8.1 Prior to Windows 10, the Windows Runtime implementation of drag-drop concepts permits only certain controls and input actions to initiate a drag-drop action. There is no StartDragAsync or generalized DoDragDrop method that would permit any UI element to initiate a drag-drop action. The main source of a drag-drop action in an app is when you drag the items of a list such as GridView.
- See Also
DragLeave DragLeave DragLeave
Occurs when the input system reports an underlying drag event with this element as the origin.
public event DragEventHandler DragLeavepublic event DragEventHandler DragLeavePublic Event DragLeave
<uiElement DragLeave="eventhandler"/>
- Attributes
Remarks
For DragLeave to occur, the value of AllowDrop on the current UIElement and on the event source must be true. Otherwise, consider using PointerExited.
You can initiate a drag-drop action on any UIElement by calling the StartDragAsync method. Once the action is initiated, any UIElement in the app can potentially be a drop target so long as AllowDrop is true on that element. Any elements that the drag-drop action passes over can handle DragEnter, DragLeave or DragOver.
DragLeave is a routed event. For more info on the routed event concept, see Events and routed events overview.
For touch actions, drag-drop actions, and also for interaction-specific or manipulation events that are consequences of a touch action, an element must be hit-test visible in order to be the event source and fire the event that is associated with the action. UIElement.Visibility must be Visible. Other properties of derived types also affect hit-test visibility, for example IsEnabled. For more info, see Events and routed events overview.
DragLeave supports the ability to attach event handlers to the route that will be invoked even if the event data for the event is marked Handled. See AddHandler.
Specific Windows Runtime controls may have class-based handling for the DragLeave event. If so, the control probably has an override for the method OnDragLeave. Typically the event is marked handled by the class handler, and the DragLeave event is not raised for handling by any user code handlers on that control. For more info, see Events and routed events overview.
Independent of the event occurrence, some controls may use theme animations such as DragItemThemeAnimation to visually indicate a drag behavior to the user.
Windows 8/Windows 8.1 Prior to Windows 10, the Windows Runtime implementation of drag-drop concepts permits only certain controls and input actions to initiate a drag-drop action. There is no StartDragAsync or generalized DoDragDrop method that would permit any UI element to initiate a drag-drop action. The main source of a drag-drop action in an app is when you drag the items of a list such as GridView.
- See Also
DragOver DragOver DragOver
Occurs when the input system reports an underlying drag event with this element as the potential drop target.
public event DragEventHandler DragOverpublic event DragEventHandler DragOverPublic Event DragOver
<uiElement DragOver="eventhandler"/>
- Attributes
Remarks
For DragOver to occur, the value of AllowDrop on the current UIElement and on the event source must be true. Otherwise, consider using PointerMoved.
You can initiate a drag-drop action on any UIElement by calling the StartDragAsync method. Once the action is initiated, any UIElement in the app can potentially be a drop target so long as AllowDrop is true on that element. Any elements that the drag-drop action passes over can handle DragEnter, DragLeave or DragOver.
DragOver is a routed event. For more info on the routed event concept, see Events and routed events overview.
For touch actions, drag-drop actions, and also for interaction-specific or manipulation events that are consequences of a touch action, an element must be hit-test visible in order to be the event source and fire the event that is associated with the action. UIElement.Visibility must be Visible. Other properties of derived types also affect hit-test visibility, for example IsEnabled. For more info, see Events and routed events overview.
DragOver supports the ability to attach event handlers to the route that will be invoked even if the event data for the event is marked Handled. See AddHandler.
Specific Windows Runtime controls may have class-based handling for the DragOver event. If so, the control probably has an override for the method OnDragOver. Typically the event is marked handled by the class handler, and the DragOver event is not raised for handling by any user code handlers on that control. For more info, see Events and routed events overview.
Independent of the event occurrence, some controls may use theme animations such as DragItemThemeAnimation to visually indicate a drag behavior to the user.
Windows 8/Windows 8.1 Prior to Windows 10, the Windows Runtime implementation of drag-drop concepts permits only certain controls and input actions to initiate a drag-drop action. There is no StartDragAsync or generalized DoDragDrop method that would permit any UI element to initiate a drag-drop action. The main source of a drag-drop action in an app is when you drag the items of a list such as GridView.
- See Also
DragStarting DragStarting DragStarting
Occurs when a drag operation is initiated.
public event TypedEventHandler DragStartingpublic event TypedEventHandler DragStartingPublic Event DragStarting
- Attributes
- See Also
Drop Drop Drop
Occurs when the input system reports an underlying drop event with this element as the drop target.
public event DragEventHandler Droppublic event DragEventHandler DropPublic Event Drop
<uiElement Drop="eventhandler"/>
- Attributes
Remarks
For Drop to occur and to invoke a handler, the value of AllowDrop on the UIElement that is the drop target and also on the drag-drop action source must be true.
A typical handler will check the Data value from the DragEventArgs event data.
You can initiate a drag-drop action on any UIElement by calling the StartDragAsync method. Once the action is initiated, any UIElement in the app can potentially be a drop target so long as AllowDrop is true on that element, and any elements that the drag-drop action passes over can handle DragEnter, DragLeave or DragOver.
Drop is a routed event. An element must have AllowDrop be true to be a Drop event source. If the event is permitted to bubble up to parent elements because it goes unhandled, then it is possible to handle the event on a parent element if AllowDrop is true on the parent element. Intermediate elements in the route that aren't either the handler object or the drop target don't need AllowDrop to be true. For more info on the routed event concept, see Events and routed events overview.
For touch actions, drag-drop actions, and also for interaction-specific or manipulation events that are consequences of a touch action, an element must be hit-test visible in order to be the event source and fire the event that is associated with the action. UIElement.Visibility must be Visible. Other properties of derived types also affect hit-test visibility, for example IsEnabled. For more info, see Events and routed events overview.
Drop supports the ability to attach event handlers to the route that will be invoked even if the event data for the event is marked Handled. See AddHandler.
Specific Windows Runtime controls may have class-based handling for the Drop event. If so, the control's logic probably has an override for the method OnDrop. Typically the event is marked handled by the class handler, and the Drop event is not raised for handling by any user code handlers on that control. For more info, see Events and routed events overview.
Independent of the event occurrence, some controls may use theme animations such as DragItemThemeAnimation to visually indicate a drag behavior to the user.
Windows 8/Windows 8.1 Prior to Windows 10, the Windows Runtime implementation of drag-drop concepts permits only certain controls and input actions to initiate a drag-drop action. There is no StartDragAsync or generalized DoDragDrop method that would permit any UI element to initiate a drag-drop action. The main source of a drag-drop action in an app is when you drag the items of a list such as GridView.
- See Also
DropCompleted DropCompleted DropCompleted
Occurs when a drag-and-drop operation is ended.
public event TypedEventHandler DropCompletedpublic event TypedEventHandler DropCompletedPublic Event DropCompleted
- Attributes
GettingFocus GettingFocus GettingFocus
Occurs before a UIElement receives focus.
public event TypedEventHandler GettingFocuspublic event TypedEventHandler GettingFocusPublic Event GettingFocus
- Attributes
| Device family |
Windows 10 Creators Update (introduced v10.0.15063.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v4)
|
GotFocus GotFocus GotFocus
Occurs when a UIElement receives focus.
public event RoutedEventHandler GotFocuspublic event RoutedEventHandler GotFocusPublic Event GotFocus
<uiElement GotFocus="eventhandler"/>
- Attributes
Remarks
Only one element at a time in a page of UI can have focus.
If you are using control compositing or UI compositing and handling GotFocus on a container such as a Panel or GridView, then you might want to check the OriginalSource on the event data to determine which element in the composition actually received the focus.
GotFocus doesn't have any specialized event data. For many scenarios where you handle GotFocus, you might want to determine whether it was the user or app code that caused an element to gain focus. To determine this in your handler, cast the sender of the event to be a Control object, and check the FocusState.
Keyboard focus is particularly relevant for keyboard event handling, because only the currently keyboard-focused UIElement can be the source of the key events KeyUp and KeyDown. In some scenarios, apps deliberately call Focus as an initialization action so that the key events in the app as a whole can be used to detect access or accelerator keys. For more info, see Keyboard interactions.
GotFocus is a routed event. For more info on the routed event concept, see Events and routed events overview.
Specific Windows Runtime controls may have class-based handling for the GotFocus event. If so, the control probably has an override for the method OnGotFocus. Typically the event is marked handled by the class handler, and the GotFocus event is not raised for handling by any user code handlers on that control. Controls might handle the event in order to load a visual state that property displays a focus rectangle. A focus rectangle is an important visual component of a control for accessibility purposes, so that users can see where the current focused element is in the UI and where the user is within the tab sequence of the overall app UI. In some cases, the FocusState of the focus action is relevant for whether a visible focus indicator should display. For more info on how class-based handling for events works, see Events and routed events overview. For more info on tab sequences and accessibility, see Keyboard accessibility.
- See Also
Holding Holding Holding
Occurs when an otherwise unhandled Hold interaction occurs over the hit test area of this element.
public event HoldingEventHandler Holdingpublic event HoldingEventHandler HoldingPublic Event Holding
<uiElement Holding="eventhandler"/>
- Attributes
Remarks
Touch can produce a Holding action, but mouse devices generally can't. For more info, see Quickstart: Touch input.
The Tapped, DoubleTapped, and RightTapped events occur only after the touch point is removed. But the initial Holding event occurs while the touch point is still in contact. The event occurs if the touch point remains in approximately the same PointerPoint position for a period of time. The exact timing of what the system interprets as a holding action is adjustable by users through system settings.
Holding is intended for informational UI, but for interactions like displaying a context menu you should use RightTapped instead. You might handle Holding first to display a hint that a menu will appear, but to display the menu itself, use a RightTapped handler. See Touch interaction design or UX guidelines for custom user interactions for more info on how to use a Hold interaction in your app design.
Holding events generally occur in pairs. When the action is first interpreted as a Hold action based on no movement for a period of time, Holding fires, with HoldingState value of Started in the HoldingRoutedEventArgs event data. When the Hold action ends, another Holding event fires, this time with HoldingState of either Completed or Canceled.
- The Hold action ends with HoldingState as Completed if the user doesn't move the pointer during the Hold state and then releases the pointer points that initiated the action. For this case, RightTapped fires just after the second Holding event.
- The Hold action ends with HoldingState as Canceled if the user does move the pointer(s) that initiated the action, or also for uncommon situations such as changing the hit-test status on the element during the action or capturing another pointer. If the Hold action ends with HoldingState as Canceled, RightTapped won't fire.
A Holding event represents a gesture, whereas a PointerPressed event is a lower-level input event. Holding and PointerPressed events can fire as the result of a single user interaction. Even if a control is already handling pointer events in the control logic, or is handling manipulations, that doesn't prevent Holding from firing.
A Holding event is potentially the result of more than one pointer point. For the higher-level gesture events like Holding you no longer have immediate access to PointerPoint details such as individual PointerId values or individual coordinates. You do have access to device type (PointerDeviceType ) and for coordinates you can call GetPosition, which gives an average of the coordinates for a Hold from more than one pointer point.
Holding is a routed event. Also, an element must have IsHoldingEnabled be true to be a Holding event source (true is the default). It is possible to handle Holding on parent elements even if IsHoldingEnabled is false on the parent element, if the event bubbles to a parent from an event source child element where IsHoldingEnabled is false. For more info on the routed event concept, see Events and routed events overview.
For touch actions and also for interaction-specific or manipulation events that are consequences of a touch action, an element must be hit-test visible in order to be the event source and fire the event that is associated with the action. UIElement.Visibility must be Visible. Other properties of derived types also affect hit-test visibility. For more info, see Events and routed events overview.
Holding supports the ability to attach event handlers to the route that will be invoked even if the event data for the event is marked Handled. See AddHandler.
Specific Windows Runtime controls may have class-based handling for the Holding event. If so, the control probably has an override for the method OnHolding. For more info on how class-based handling for events works, see Events and routed events overview.
Tapped and Holding are mutually exclusive. If the action passes the time threshold to be considered a Hold action, it's not considered to be a Tap action also.
Whenever Holding fires initially, so long as the element supports manipulation events through a non-default ManipulationMode value, ManipulationStarting fires too. If the pointer point remains in one place long enough for Holding to be detected, but thereafter the user moves the pointer points associated with the Hold action without releasing them (leading to another Holding event with HoldingState as Canceled), then other manipulation events like ManipulationStarted and ManipulationDelta can fire also.
Holding for mouse and pen/stylus input
Mouse input doesn't produce Holding events by default, no matter how long a mouse button is held down, or which button is held. However, mouse devices and some pen devices can fire RightTapped when a right mouse button or equivalent is pressed and released.
Note
There is a way to treat mouse actions as hold actions if you use your own GestureRecognizer and specify HoldWithMouse in settings.
- See Also
KeyDown KeyDown KeyDown
Occurs when a keyboard key is pressed while the UIElement has focus.
public event KeyEventHandler KeyDownpublic event KeyEventHandler KeyDownPublic Event KeyDown
<uiElement KeyDown="eventhandler"/>
- Attributes
Remarks
Controls in your UI generate keyboard events only when they have input focus. By default, the first focusable element in the visual tree is given focus by the system. An individual control gains focus when the user clicks or taps directly on that control in the layout, or uses the Tab key to step into a tab sequence within the content area. You can also focus controls programmatically by calling Control.Focus.
KeyDown uses KeyRoutedEventArgs event data. The most relevant properties of KeyRoutedEventArgs for most handler scenarios are Key and possibly KeyStatus. For more info on handling keyboard events, including example code for defining a KeyEventHandler method, see Keyboard interactions.
One scenario for handling keyboard events is to support access keys or accelerator keys for an app, or a region or control within an app. For more info about this scenario, see Keyboard accessibility.
KeyDown is a routed event. For more info on the routed event concept, see Events and routed events overview.
Specific Windows Runtime controls may have class-based handling for the KeyDown input event. If so, the control probably has an override for the method OnKeyDown. Typically these class handlers are intended to process a subset of key presses that enable a keyboard-based user interaction with that control, and often this interaction supports a keyboard accessibility feature. If a key press is handled by class-based handling, then the key press is considered to be already handled, and the KeyDown event is not raised for handling by any user code handlers on that control for that key specifically. Usually this is just for a few dedicated keys. For example, ButtonBase has class handling so that the Space key and Enter key are handled as keyboard equivalents for invoking the Button. That provides a built-in keyboard equivalent for tapping the button or clicking on it with a mouse, and enables the accessibility scenario of using the UI and the button using a keyboard only. But any other keys other than Space or Enter will still fire a KeyDown and KeyUp event for a Button. For more info on how class-based handling for events works, see Events and routed events overview.
KeyDown supports the ability to attach event handlers to the route that will be invoked even if the event data for the event is marked Handled. See AddHandler.
- See Also
KeyUp KeyUp KeyUp
Occurs when a keyboard key is released while the UIElement has focus.
public event KeyEventHandler KeyUppublic event KeyEventHandler KeyUpPublic Event KeyUp
<uiElement KeyUp="eventhandler"/>
- Attributes
Remarks
Controls in your UI generate keyboard events only when they have input focus. By default, the first focusable element in the visual tree is given focus by the system. An individual control gains focus when the user clicks or taps directly on that control in the layout, or uses the Tab key to step into a tab sequence within the content area. You can also focus controls programmatically by calling Control.Focus.
KeyUp uses KeyRoutedEventArgs event data. The most relevant properties of KeyRoutedEventArgs for most handler scenarios are Key and possibly KeyStatus. For more info on handling keyboard events, including example code for defining a KeyEventHandler method, see Keyboard interactions.
One scenario for handling keyboard events is to support access keys or accelerator keys for an app, or a region or control within an app. For more info about this scenario, see Keyboard accessibility.
KeyUp is a routed event. For more info on the routed event concept, see Events and routed events overview.
Specific Windows Runtime controls may have class-based handling for the KeyUp input event. If so, the control probably has an override for the method OnKeyUp. Typically these class handlers are intended to process a subset of key presses that enable a keyboard-based user interaction with that control, and often this interaction supports a keyboard accessibility feature. If a keyboard key event is handled by class-based handling, then the key event is considered to be already handled, and the KeyUp event is not raised for handling by any user code handlers on that control. Usually this is just for a few dedicated keys. For example, ButtonBase has class handling so that the Space key and Enter key are handled as keyboard equivalents for invoking the Button. That provides a built-in keyboard equivalent for tapping the button or clicking on it with a mouse, and enables the accessibility scenario of using the UI and the button using a keyboard only. But any other keys other than Space or Enter will still fire a KeyDown and KeyUp event for a Button. For more info on how class-based handling for events works, see Events and routed events overview.
KeyUp supports the ability to attach event handlers to the route that will be invoked even if the event data for the event is marked Handled. See AddHandler.
- See Also
LosingFocus LosingFocus LosingFocus
Occurs before a UIElement loses focus.
public event TypedEventHandler LosingFocuspublic event TypedEventHandler LosingFocusPublic Event LosingFocus
- Attributes
| Device family |
Windows 10 Creators Update (introduced v10.0.15063.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v4)
|
LostFocus LostFocus LostFocus
Occurs when a UIElement loses focus.
public event RoutedEventHandler LostFocuspublic event RoutedEventHandler LostFocusPublic Event LostFocus
<uiElement LostFocus="eventhandler"/>
- Attributes
Remarks
The typical reason that a control loses focus is that another control now has focus. But there are other possible reasons for losing focus, such as switching to another view state or another app, or the user interacting with the system in other ways.
Keyboard focus is particularly relevant for keyboard event handling, because only the currently keyboard-focused UIElement can be the source of the key events KeyUp and KeyDown. In some scenarios, apps deliberately call Focus as an initialization action so that the key events in the app as a whole can be used to detect access or accelerator keys. For more info, see Keyboard interactions.
LostFocus is a routed event. For more info on the routed event concept, see Events and routed events overview.
Specific Windows Runtime controls may have class-based handling for the LostFocus event. If so, the control probably has an override for the method OnLostFocus. Typically the event is marked handled by the class handler, and the LostFocus event is not raised for handling by any user code handlers on that control. Controls might handle the event in order to unload a visual state that displayed a focus rectangle in response to OnGotFocus. A focus rectangle is an important visual component of a control for accessibility purposes, so that users can see where the current focused element is in the UI and where the user is within the tab sequence of the overall app UI. For more info on how class-based handling for events works, see Events and routed events overview. For more info on tab sequences and accessibility, see Keyboard accessibility.
- See Also
ManipulationCompleted ManipulationCompleted ManipulationCompleted
Occurs when a manipulation on the UIElement is complete.
public event ManipulationCompletedEventHandler ManipulationCompletedpublic event ManipulationCompletedEventHandler ManipulationCompletedPublic Event ManipulationCompleted
<uiElement ManipulationCompleted="eventhandler"/>
- Attributes
Remarks
An element must have a ManipulationMode value other than None or System to be a manipulation event source. The default value of ManipulationMode is System, which enables built-in control logic to process manipulations, but doesn't permit app code to handle manipulation events. If you want to handle manipulations, set ManipulationMode to All, or to specific ManipulationModes values. For more info, see ManipulationMode.
ManipulationCompleted is a routed event. If the event is permitted to bubble up to parent elements because it goes unhandled, then it is possible to handle the event on parent elements even if ManipulationMode is None or System on the parent element. For more info on the routed event concept, see Events and routed events overview.
For touch actions and also for interaction-specific or manipulation events that are consequences of a touch action, an element must be hit-test visible in order to be the event source and fire the event that is associated with the action. UIElement.Visibility must be Visible. Other properties of derived types also affect hit-test visibility. For more info, see Events and routed events overview.
ManipulationCompleted supports the ability to attach event handlers to the route that will be invoked even if the event data for the event is marked Handled. See AddHandler.
Windows 8 behavior
Windows 8 doesn't fire ManipulationCompleted in cases where the inertial phase has started (and ManipulationInertiaStarting has fired) but the user has tapped on the item before it's finished scrolling, which cancels the inertial phase visually. The issue is fixed starting with Windows 8.1; ManipulationCompleted is fired as soon as the tap action cancels the inertial phase.
Apps that were compiled for Windows 8 but running on Windows 8.1 continue to use the Windows 8 behavior.
- See Also
ManipulationDelta ManipulationDelta ManipulationDelta
Occurs when the input device changes position during a manipulation.
public event ManipulationDeltaEventHandler ManipulationDeltapublic event ManipulationDeltaEventHandler ManipulationDeltaPublic Event ManipulationDelta
<uiElement ManipulationDelta="eventhandler"/>
- Attributes
Remarks
An element must have a ManipulationMode value other than None or System to be a manipulation event source. The default value of ManipulationMode is System, which enables built-in control logic to process manipulations, but doesn't permit app code to handle manipulation events. If you want to handle manipulations, set ManipulationMode to All, or to specific ManipulationModes values. For more info, see ManipulationMode.
ManipulationDelta is a routed event. If the event is permitted to bubble up to parent elements because it goes unhandled, then it is possible to handle the event on parent elements even if ManipulationMode is None or System on the parent element. For more info on the routed event concept, see Events and routed events overview.
For touch actions and also for interaction-specific or manipulation events that are consequences of a touch action, an element must be hit-test visible in order to be the event source and fire the event that is associated with the action. UIElement.Visibility must be Visible. Other properties of derived types also affect hit-test visibility. For more info, see Events and routed events overview.
ManipulationDelta supports the ability to attach event handlers to the route that will be invoked even if the event data for the event is marked Handled. See AddHandler.
- See Also
ManipulationInertiaStarting ManipulationInertiaStarting ManipulationInertiaStarting
Occurs when the input device loses contact with the UIElement object during a manipulation and inertia begins.
public event ManipulationInertiaStartingEventHandler ManipulationInertiaStartingpublic event ManipulationInertiaStartingEventHandler ManipulationInertiaStartingPublic Event ManipulationInertiaStarting
<uiElement ManipulationInertiaStarting="eventhandler"/>
- Attributes
Remarks
An element must have a ManipulationMode value other than None or System to be a manipulation event source. The default value of ManipulationMode is System, which enables built-in control logic to process manipulations, but doesn't permit app code to handle manipulation events. If you want to handle manipulations, set ManipulationMode to All, or to specific ManipulationModes values. For more info, see ManipulationMode.
ManipulationInertiaStarting is a routed event. If the event is permitted to bubble up to parent elements because it goes unhandled, then it is possible to handle the event on parent elements even if ManipulationMode is None or System on the parent element. For more info on the routed event concept, see Events and routed events overview.
For touch actions and also for interaction-specific or manipulation events that are consequences of a touch action, an element must be hit-test visible in order to be the event source and fire the event that is associated with the action. UIElement.Visibility must be Visible. Other properties of derived types also affect hit-test visibility. For more info, see Events and routed events overview.
ManipulationInertiaStarting supports the ability to attach event handlers to the route that will be invoked even if the event data for the event is marked Handled. See AddHandler.
Windows 8 behavior
Windows 8 doesn't fire ManipulationCompleted in cases where the inertial phase has started (and ManipulationInertiaStarting has fired) but the user has tapped on the item before it's finished scrolling, which cancels the inertial phase visually. The issue is fixed starting with Windows 8.1; ManipulationCompleted is fired as soon as the tap action cancels the inertial phase.
Apps that were compiled for Windows 8 but running on Windows 8.1 continue to use the Windows 8 behavior.
- See Also
ManipulationStarted ManipulationStarted ManipulationStarted
Occurs when an input device begins a manipulation on the UIElement.
public event ManipulationStartedEventHandler ManipulationStartedpublic event ManipulationStartedEventHandler ManipulationStartedPublic Event ManipulationStarted
<uiElement ManipulationStarted="eventhandler"/>
- Attributes
Remarks
ManipulationStarted represents that the manipulation recognition logic has detected pointer movement. In this case it's the second manipulation event to fire in a typical sequence, firing after ManipulationStarting, but before ManipulationDelta or other events such as ManipulationInertiaStarting.
An element must have a ManipulationMode value other than None or System to be a manipulation event source. The default value of ManipulationMode is System, which enables built-in control logic to process manipulations, but doesn't permit app code to handle manipulation events. If you want to handle manipulations, set ManipulationMode to All, or to specific ManipulationModes values. For more info, see ManipulationMode.
ManipulationStarted is a routed event. If the event is permitted to bubble up to parent elements because it goes unhandled, then it is possible to handle the event on parent elements even if ManipulationMode is None or System on the parent element. For more info on the routed event concept, see Events and routed events overview.
For touch actions and also for interaction-specific or manipulation events that are consequences of a touch action, an element must be hit-test visible in order to be the event source and fire the event that is associated with the action. UIElement.Visibility must be Visible. Other properties of derived types also affect hit-test visibility. For more info, see Events and routed events overview.
ManipulationStarted supports the ability to attach event handlers to the route that will be invoked even if the event data for the event is marked Handled. See AddHandler.
- See Also
ManipulationStarting ManipulationStarting ManipulationStarting
Occurs when the manipulation processor is first created.
public event ManipulationStartingEventHandler ManipulationStartingpublic event ManipulationStartingEventHandler ManipulationStartingPublic Event ManipulationStarting
<uiElement ManipulationStarting="eventhandler"/>
- Attributes
Remarks
An element must have a ManipulationMode value other than None or System to be a manipulation event source. The default value of ManipulationMode is System, which enables built-in control logic to process manipulations, but doesn't permit app code to handle manipulation events. If you want