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 UIElementpublic class UIElementPublic Class UIElement
Inheritance
Attributes
Windows 10 requirements
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:

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:

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:

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(Rect) and Measure(Size) 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(RoutedEvent, Object, Boolean), RemoveHandler(RoutedEvent, Object), **Event* properties.

Other platform support

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 AccessKey

Gets or sets the access key (mnemonic) for this element.

public string AccessKey { get; set; }public string AccessKey { get; set; }Public ReadWrite Property AccessKey As stringpublic string AccessKey { get; set; }
Value
string string string

The access key (mnemonic) for this element.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

Setting this property enables the AccessKeyDisplayRequested event to be raised.

If the AccessKeyProperty 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 AccessKeyProperty

Identifies for the AccessKey dependency property.

public static DependencyProperty AccessKeyProperty { get; }public static DependencyProperty AccessKeyProperty { get; }Public Static ReadOnly Property AccessKeyProperty As DependencyPropertypublic static DependencyProperty AccessKeyProperty { get; }
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the AccessKey dependency property.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

AccessKeyScopeOwner 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 DependencyObjectpublic DependencyObject AccessKeyScopeOwner { get; set; }
Value
DependencyObject DependencyObject DependencyObject

The element that defines the access key scope.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

The source element must have it's IsAccessKeyScope property set to true.

AccessKeyScopeOwnerProperty 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 DependencyPropertypublic static DependencyProperty AccessKeyScopeOwnerProperty { get; }
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the AccessKeyScopeOwner dependency property.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

AllowDrop 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 bool AllowDrop { get; set; }public bool AllowDrop { get; set; }Public ReadWrite Property AllowDrop As boolpublic bool AllowDrop { get; set; }
<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
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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:

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.

AllowDropProperty AllowDropProperty AllowDropProperty AllowDropProperty

Identifies the AllowDrop dependency property.

public static DependencyProperty AllowDropProperty { get; }public static DependencyProperty AllowDropProperty { get; }Public Static ReadOnly Property AllowDropProperty As DependencyPropertypublic static DependencyProperty AllowDropProperty { get; }
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the AllowDrop dependency property.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

CacheMode 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 CacheModepublic CacheMode CacheMode { get; set; }
<uiElement CacheMode="BitmapCache" />
Value
CacheMode CacheMode CacheMode

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
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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.

CacheModeProperty CacheModeProperty CacheModeProperty CacheModeProperty

Identifies the CacheMode dependency property.

public static DependencyProperty CacheModeProperty { get; }public static DependencyProperty CacheModeProperty { get; }Public Static ReadOnly Property CacheModeProperty As DependencyPropertypublic static DependencyProperty CacheModeProperty { get; }
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the CacheMode dependency property.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

CanDrag 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 bool CanDrag { get; set; }public bool CanDrag { get; set; }Public ReadWrite Property CanDrag As boolpublic bool CanDrag { get; set; }
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
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

CanDragProperty CanDragProperty CanDragProperty CanDragProperty

Identifies the CanDrag dependency property.

public static DependencyProperty CanDragProperty { get; }public static DependencyProperty CanDragProperty { get; }Public Static ReadOnly Property CanDragProperty As DependencyPropertypublic static DependencyProperty CanDragProperty { get; }
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the CanDrag dependency property.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Clip 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 RectangleGeometrypublic RectangleGeometry Clip { get; set; }
<uiElement>
  <uiElement.Clip>
    rectangleGeometry
  </uiElement.Clip>
</uiElement>
Value
RectangleGeometry RectangleGeometry RectangleGeometry

The rectangle geometry to be used for clipping area sizing. The default value is null (no clipping).

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

The clipping geometry for 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 ClipProperty

Identifies the Clip dependency property.

public static DependencyProperty ClipProperty { get; }public static DependencyProperty ClipProperty { get; }Public Static ReadOnly Property ClipProperty As DependencyPropertypublic static DependencyProperty ClipProperty { get; }
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the Clip dependency property.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

CompositeMode 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 ElementCompositeModepublic ElementCompositeMode CompositeMode { get; set; }
<uiElement CompositeMode="elementCompositeModeMemberName" />
Value
ElementCompositeMode ElementCompositeMode ElementCompositeMode

A value of the enumeration. The default is Inherit, but see Remarks.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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 SwapChainBackgroundPanel 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.

CompositeModeProperty CompositeModeProperty CompositeModeProperty CompositeModeProperty

Identifies the CompositeMode dependency property.

public static DependencyProperty CompositeModeProperty { get; }public static DependencyProperty CompositeModeProperty { get; }Public Static ReadOnly Property CompositeModeProperty As DependencyPropertypublic static DependencyProperty CompositeModeProperty { get; }
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the CompositeMode dependency property.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

ContextFlyout 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 FlyoutBasepublic FlyoutBase ContextFlyout { get; set; }
Value
FlyoutBase FlyoutBase FlyoutBase

The flyout associated with this element, if any; otherwise, null. The default is null.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

ContextFlyoutProperty 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 DependencyPropertypublic static DependencyProperty ContextFlyoutProperty { get; }
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the ContextFlyout dependency property.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

DesiredSize 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 Sizepublic Size DesiredSize { get; }
Value
Size Size Size

The size that this UIElement computed during the measure pass of the layout process.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

DesiredSize is typically checked as one of the measurement factors when you implement layout behavior overrides such as ArrangeOverride(Size) or MeasureOverride(Size). 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(Size) 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 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 RoutedEventpublic static RoutedEvent DoubleTappedEvent { get; }
Value
RoutedEvent RoutedEvent RoutedEvent

The identifier for the DoubleTapped routed event.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

DragEnterEvent DragEnterEvent DragEnterEvent DragEnterEvent

Gets the identifier for the DragEnter routed event.

public static RoutedEvent DragEnterEvent { get; }public static RoutedEvent DragEnterEvent { get; }Public Static ReadOnly Property DragEnterEvent As RoutedEventpublic static RoutedEvent DragEnterEvent { get; }
Value
RoutedEvent RoutedEvent RoutedEvent

The identifier for the DragEnter routed event.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

DragLeaveEvent DragLeaveEvent DragLeaveEvent DragLeaveEvent

Gets the identifier for the DragLeave routed event.

public static RoutedEvent DragLeaveEvent { get; }public static RoutedEvent DragLeaveEvent { get; }Public Static ReadOnly Property DragLeaveEvent As RoutedEventpublic static RoutedEvent DragLeaveEvent { get; }
Value
RoutedEvent RoutedEvent RoutedEvent

The identifier for the DragLeave routed event.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

DragOverEvent DragOverEvent DragOverEvent DragOverEvent

Gets the identifier for the DragOver routed event.

public static RoutedEvent DragOverEvent { get; }public static RoutedEvent DragOverEvent { get; }Public Static ReadOnly Property DragOverEvent As RoutedEventpublic static RoutedEvent DragOverEvent { get; }
Value
RoutedEvent RoutedEvent RoutedEvent

The identifier for the DragOver routed event.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

DropEvent DropEvent DropEvent DropEvent

Gets the identifier for the Drop routed event.

public static RoutedEvent DropEvent { get; }public static RoutedEvent DropEvent { get; }Public Static ReadOnly Property DropEvent As RoutedEventpublic static RoutedEvent DropEvent { get; }
Value
RoutedEvent RoutedEvent RoutedEvent

The identifier for the Drop routed event.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

ExitDisplayModeOnAccessKeyInvoked ExitDisplayModeOnAccessKeyInvoked ExitDisplayModeOnAccessKeyInvoked ExitDisplayModeOnAccessKeyInvoked

Gets or sets a value that specifies whether the access key display is dismissed when an access key is invoked.

public bool ExitDisplayModeOnAccessKeyInvoked { get; set; }public bool ExitDisplayModeOnAccessKeyInvoked { get; set; }Public ReadWrite Property ExitDisplayModeOnAccessKeyInvoked As boolpublic bool ExitDisplayModeOnAccessKeyInvoked { get; set; }
Value
bool bool bool

true to dismiss the access key display when an access key is invoked; otherwise, false.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

ExitDisplayModeOnAccessKeyInvokedProperty ExitDisplayModeOnAccessKeyInvokedProperty ExitDisplayModeOnAccessKeyInvokedProperty ExitDisplayModeOnAccessKeyInvokedProperty

Identifies the ExitDisplayModeOnAccessKeyInvoked dependency property.

public static DependencyProperty ExitDisplayModeOnAccessKeyInvokedProperty { get; }public static DependencyProperty ExitDisplayModeOnAccessKeyInvokedProperty { get; }Public Static ReadOnly Property ExitDisplayModeOnAccessKeyInvokedProperty As DependencyPropertypublic static DependencyProperty ExitDisplayModeOnAccessKeyInvokedProperty { get; }
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

GettingFocusEvent GettingFocusEvent GettingFocusEvent GettingFocusEvent

Prerelease. Gets the identifier for the GettingFocus routed event.

public static RoutedEvent GettingFocusEvent { get; }public static RoutedEvent GettingFocusEvent { get; }Public Static ReadOnly Property GettingFocusEvent As RoutedEventpublic static RoutedEvent GettingFocusEvent { get; }
Value
RoutedEvent RoutedEvent RoutedEvent

The identifier for the GettingFocus routed event.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

HighContrastAdjustment HighContrastAdjustment HighContrastAdjustment HighContrastAdjustment

Prerelease. 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 ElementHighContrastAdjustmentpublic ElementHighContrastAdjustment HighContrastAdjustment { get; set; }
Value
ElementHighContrastAdjustment ElementHighContrastAdjustment 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
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

HighContrastAdjustmentProperty HighContrastAdjustmentProperty HighContrastAdjustmentProperty HighContrastAdjustmentProperty

Prerelease. Identifies the HighContrastAdjustment dependency property.

public static DependencyProperty HighContrastAdjustmentProperty { get; }public static DependencyProperty HighContrastAdjustmentProperty { get; }Public Static ReadOnly Property HighContrastAdjustmentProperty As DependencyPropertypublic static DependencyProperty HighContrastAdjustmentProperty { get; }
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the HighContrastAdjustment dependency property.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

HoldingEvent HoldingEvent HoldingEvent HoldingEvent

Gets the identifier for the Holding routed event.

public static RoutedEvent HoldingEvent { get; }public static RoutedEvent HoldingEvent { get; }Public Static ReadOnly Property HoldingEvent As RoutedEventpublic static RoutedEvent HoldingEvent { get; }
Value
RoutedEvent RoutedEvent RoutedEvent

The identifier for the Holding routed event.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

IsAccessKeyScope IsAccessKeyScope IsAccessKeyScope IsAccessKeyScope

Gets or sets a value that indicates whether an element defines its own access key scope.

public bool IsAccessKeyScope { get; set; }public bool IsAccessKeyScope { get; set; }Public ReadWrite Property IsAccessKeyScope As boolpublic bool IsAccessKeyScope { get; set; }
Value
bool bool bool

true if an element defines its own scope; otherwise, false.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

IsAccessKeyScopeProperty 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 DependencyPropertypublic static DependencyProperty IsAccessKeyScopeProperty { get; }
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the IsAccessKeyScope dependency property.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

IsDoubleTapEnabled IsDoubleTapEnabled IsDoubleTapEnabled IsDoubleTapEnabled

Gets or sets a value that determines whether the DoubleTapped event can originate from that element.

public bool IsDoubleTapEnabled { get; set; }public bool IsDoubleTapEnabled { get; set; }Public ReadWrite Property IsDoubleTapEnabled As boolpublic bool IsDoubleTapEnabled { get; set; }
<uiElement IsDoubleTapEnabled="bool" />
Value
bool bool bool

true if a DoubleTapped event can originate from this element; otherwise, false.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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.

IsDoubleTapEnabledProperty IsDoubleTapEnabledProperty IsDoubleTapEnabledProperty IsDoubleTapEnabledProperty

Identifies the IsDoubleTapEnabled dependency property.

public static DependencyProperty IsDoubleTapEnabledProperty { get; }public static DependencyProperty IsDoubleTapEnabledProperty { get; }Public Static ReadOnly Property IsDoubleTapEnabledProperty As DependencyPropertypublic static DependencyProperty IsDoubleTapEnabledProperty { get; }
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the IsDoubleTapEnabled dependency property.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

IsHitTestVisible IsHitTestVisible IsHitTestVisible IsHitTestVisible

Gets or sets whether the contained area of this UIElement can return true values for hit testing.

public bool IsHitTestVisible { get; set; }public bool IsHitTestVisible { get; set; }Public ReadWrite Property IsHitTestVisible As boolpublic bool IsHitTestVisible { get; set; }
<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
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

IsHitTestVisibleProperty IsHitTestVisibleProperty IsHitTestVisibleProperty IsHitTestVisibleProperty

Identifies the IsHitTestVisible dependency property.

public static DependencyProperty IsHitTestVisibleProperty { get; }public static DependencyProperty IsHitTestVisibleProperty { get; }Public Static ReadOnly Property IsHitTestVisibleProperty As DependencyPropertypublic static DependencyProperty IsHitTestVisibleProperty { get; }
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the IsHitTestVisible dependency property.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

IsHoldingEnabled IsHoldingEnabled IsHoldingEnabled IsHoldingEnabled

Gets or sets a value that determines whether the Holding event can originate from that element.

public bool IsHoldingEnabled { get; set; }public bool IsHoldingEnabled { get; set; }Public ReadWrite Property IsHoldingEnabled As boolpublic bool IsHoldingEnabled { get; set; }
<uiElement IsHoldingEnabled="bool" />
Value
bool bool bool

true if a Holding event can originate from this element; otherwise, false.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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.

IsHoldingEnabledProperty IsHoldingEnabledProperty IsHoldingEnabledProperty IsHoldingEnabledProperty

Identifies the IsHoldingEnabled dependency property.

public static DependencyProperty IsHoldingEnabledProperty { get; }public static DependencyProperty IsHoldingEnabledProperty { get; }Public Static ReadOnly Property IsHoldingEnabledProperty As DependencyPropertypublic static DependencyProperty IsHoldingEnabledProperty { get; }
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the IsHoldingEnabled dependency property.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

IsRightTapEnabled IsRightTapEnabled IsRightTapEnabled IsRightTapEnabled

Gets or sets a value that determines whether the RightTapped event can originate from that element.

public bool IsRightTapEnabled { get; set; }public bool IsRightTapEnabled { get; set; }Public ReadWrite Property IsRightTapEnabled As boolpublic bool IsRightTapEnabled { get; set; }
<uiElement IsRightTapEnabled="bool" />
Value
bool bool bool

true if a RightTapped event can originate from this element; otherwise, false.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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.

IsRightTapEnabledProperty IsRightTapEnabledProperty IsRightTapEnabledProperty IsRightTapEnabledProperty

Identifies the IsRightTapEnabled dependency property.

public static DependencyProperty IsRightTapEnabledProperty { get; }public static DependencyProperty IsRightTapEnabledProperty { get; }Public Static ReadOnly Property IsRightTapEnabledProperty As DependencyPropertypublic static DependencyProperty IsRightTapEnabledProperty { get; }
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the IsRightTapEnabled dependency property.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

IsTapEnabled IsTapEnabled IsTapEnabled IsTapEnabled

Gets or sets a value that determines whether the Tapped event can originate from that element.

public bool IsTapEnabled { get; set; }public bool IsTapEnabled { get; set; }Public ReadWrite Property IsTapEnabled As boolpublic bool IsTapEnabled { get; set; }
<uiElementIsTapEnabled="bool" />
Value
bool bool bool

true if a Tapped event can originate from this element; otherwise, false.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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.

IsTapEnabledProperty IsTapEnabledProperty IsTapEnabledProperty IsTapEnabledProperty

Identifies the IsTapEnabled dependency property.

public static DependencyProperty IsTapEnabledProperty { get; }public static DependencyProperty IsTapEnabledProperty { get; }Public Static ReadOnly Property IsTapEnabledProperty As DependencyPropertypublic static DependencyProperty IsTapEnabledProperty { get; }
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the IsTapEnabled dependency property.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

KeyDownEvent KeyDownEvent KeyDownEvent KeyDownEvent

Gets the identifier for the KeyDown routed event.

public static RoutedEvent KeyDownEvent { get; }public static RoutedEvent KeyDownEvent { get; }Public Static ReadOnly Property KeyDownEvent As RoutedEventpublic static RoutedEvent KeyDownEvent { get; }
Value
RoutedEvent RoutedEvent RoutedEvent

The identifier for the KeyDown routed event.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

KeyTipHorizontalOffset KeyTipHorizontalOffset KeyTipHorizontalOffset KeyTipHorizontalOffset

Prerelease. 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 doublepublic double KeyTipHorizontalOffset { get; set; }
<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
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

KeyTipHorizontalOffsetProperty KeyTipHorizontalOffsetProperty KeyTipHorizontalOffsetProperty KeyTipHorizontalOffsetProperty

Prerelease. Identifies the KeyTipHorizontalOffset dependency property.

public static DependencyProperty KeyTipHorizontalOffsetProperty { get; }public static DependencyProperty KeyTipHorizontalOffsetProperty { get; }Public Static ReadOnly Property KeyTipHorizontalOffsetProperty As DependencyPropertypublic static DependencyProperty KeyTipHorizontalOffsetProperty { get; }
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the KeyTipHorizontalOffset dependency property.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

KeyTipPlacementMode KeyTipPlacementMode KeyTipPlacementMode KeyTipPlacementMode

Prerelease. 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 KeyTipPlacementModepublic KeyTipPlacementMode KeyTipPlacementMode { get; set; }
<uiElement KeyTipPlacementMode="keyTipPlacementModeMemberName"/>
Value
KeyTipPlacementMode KeyTipPlacementMode KeyTipPlacementMode

A value of the enumeration. The default is Auto.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

KeyTipPlacementModeProperty KeyTipPlacementModeProperty KeyTipPlacementModeProperty KeyTipPlacementModeProperty

Prerelease. Identifies the KeyTipPlacementMode dependency property.

public static DependencyProperty KeyTipPlacementModeProperty { get; }public static DependencyProperty KeyTipPlacementModeProperty { get; }Public Static ReadOnly Property KeyTipPlacementModeProperty As DependencyPropertypublic static DependencyProperty KeyTipPlacementModeProperty { get; }
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the KeyTipPlacementMode dependency property.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

KeyTipVerticalOffset KeyTipVerticalOffset KeyTipVerticalOffset KeyTipVerticalOffset

Prerelease. 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 doublepublic double KeyTipVerticalOffset { get; set; }
<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
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

KeyTipVerticalOffsetProperty KeyTipVerticalOffsetProperty KeyTipVerticalOffsetProperty KeyTipVerticalOffsetProperty

Prerelease. Identifies the KeyTipVerticalOffset dependency property.

public static DependencyProperty KeyTipVerticalOffsetProperty { get; }public static DependencyProperty KeyTipVerticalOffsetProperty { get; }Public Static ReadOnly Property KeyTipVerticalOffsetProperty As DependencyPropertypublic static DependencyProperty KeyTipVerticalOffsetProperty { get; }
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the KeyTipVerticalOffset dependency property.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

KeyUpEvent KeyUpEvent KeyUpEvent KeyUpEvent

Gets the identifier for the KeyUp routed event.

public static RoutedEvent KeyUpEvent { get; }public static RoutedEvent KeyUpEvent { get; }Public Static ReadOnly Property KeyUpEvent As RoutedEventpublic static RoutedEvent KeyUpEvent { get; }
Value
RoutedEvent RoutedEvent RoutedEvent

The identifier for the KeyUp routed event.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Lights Lights Lights Lights

Prerelease. 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>public IVector<XamlLight> Lights { get; }
<uielement>
  <uielement.Lights>
    oneOrMoreXamlLights
  </uielement.Lights>
</uielement>
Value

The collection of XamlLight elements that apply to a UIElement.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

LightsProperty LightsProperty LightsProperty LightsProperty

Prerelease. Identifies the Lights dependency property.

public static DependencyProperty LightsProperty { get; }public static DependencyProperty LightsProperty { get; }Public Static ReadOnly Property LightsProperty As DependencyPropertypublic static DependencyProperty LightsProperty { get; }
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the Lights dependency property.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

LosingFocusEvent LosingFocusEvent LosingFocusEvent LosingFocusEvent

Prerelease. Gets the identifier for the LosingFocus routed event.

public static RoutedEvent LosingFocusEvent { get; }public static RoutedEvent LosingFocusEvent { get; }Public Static ReadOnly Property LosingFocusEvent As RoutedEventpublic static RoutedEvent LosingFocusEvent { get; }
Value
RoutedEvent RoutedEvent RoutedEvent

The identifier for the LosingFocus routed event.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

ManipulationCompletedEvent 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 RoutedEventpublic static RoutedEvent ManipulationCompletedEvent { get; }
Value
RoutedEvent RoutedEvent RoutedEvent

The identifier for the ManipulationCompleted routed event.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

ManipulationDeltaEvent 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 RoutedEventpublic static RoutedEvent ManipulationDeltaEvent { get; }
Value
RoutedEvent RoutedEvent RoutedEvent

The identifier for the ManipulationDelta routed event.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

ManipulationInertiaStartingEvent 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 RoutedEventpublic static RoutedEvent ManipulationInertiaStartingEvent { get; }
Value
RoutedEvent RoutedEvent RoutedEvent

The identifier for the ManipulationInertiaStarting routed event.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

ManipulationMode 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 ManipulationModespublic ManipulationModes ManipulationMode { get; set; }
<uiElement ManipulationMode="All"/>
-or-
<uiElement ManipulationMode="None"/>
-or-
<uiElement ManipulationMode="singleManipulationModesMemberName"/>
-or-
<uiElement ManipulationMode="relatedManipulationModesNames"/>

Value
ManipulationModes ManipulationModes ManipulationModes

A value or values of the enumeration. The default is typically System, but this can vary on specific controls and elements. See Remarks.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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.

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.

ManipulationModeProperty ManipulationModeProperty ManipulationModeProperty ManipulationModeProperty

Identifies the ManipulationMode dependency property.

public static DependencyProperty ManipulationModeProperty { get; }public static DependencyProperty ManipulationModeProperty { get; }Public Static ReadOnly Property ManipulationModeProperty As DependencyPropertypublic static DependencyProperty ManipulationModeProperty { get; }
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the ManipulationMode dependency property.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

ManipulationStartedEvent 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 RoutedEventpublic static RoutedEvent ManipulationStartedEvent { get; }
Value
RoutedEvent RoutedEvent RoutedEvent

The identifier for the ManipulationStarted routed event.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

ManipulationStartingEvent 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 RoutedEventpublic static RoutedEvent ManipulationStartingEvent { get; }
Value
RoutedEvent RoutedEvent RoutedEvent

The identifier for the ManipulationStarting routed event.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

NoFocusCandidateFoundEvent NoFocusCandidateFoundEvent NoFocusCandidateFoundEvent NoFocusCandidateFoundEvent

Prerelease. Gets the identifier for the NoFocusCandidateFound routed event.

public static RoutedEvent NoFocusCandidateFoundEvent { get; }public static RoutedEvent NoFocusCandidateFoundEvent { get; }Public Static ReadOnly Property NoFocusCandidateFoundEvent As RoutedEventpublic static RoutedEvent NoFocusCandidateFoundEvent { get; }
Value
RoutedEvent RoutedEvent RoutedEvent

The identifier for the NoFocusCandidateFound routed event.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Opacity 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 doublepublic double Opacity { get; set; }
<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
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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 ZIndexProperty value of the Rectangle is higher than the other element's ZIndexProperty (or declare the Rectangle after the other element in XAML element order to get the same result.) Wire your hit-testing logic (combines GetCurrentPoint(UInt32) and FindElementsInHostCoordinates(Point, UIElement) ) 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

OpacityProperty OpacityProperty OpacityProperty OpacityProperty

Identifies the IsHitTestVisible dependency property.

public static DependencyProperty OpacityProperty { get; }public static DependencyProperty OpacityProperty { get; }Public Static ReadOnly Property OpacityProperty As DependencyPropertypublic static DependencyProperty OpacityProperty { get; }
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the IsHitTestVisible dependency property.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

PointerCanceledEvent 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 RoutedEventpublic static RoutedEvent PointerCanceledEvent { get; }
Value
RoutedEvent RoutedEvent RoutedEvent

The identifier for the PointerCanceled routed event.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

PointerCaptureLostEvent 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 RoutedEventpublic static RoutedEvent PointerCaptureLostEvent { get; }
Value
RoutedEvent RoutedEvent RoutedEvent

The identifier for the PointerCaptureLost routed event.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

PointerCaptures 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>public IVectorView<Pointer> PointerCaptures { get; }
Value

The collection of captured pointers, each represented as a Pointer object.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

For more info on how to capture a pointer and why you might want to do so, see CapturePointer(Pointer).

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(Pointer) adds to the internal collection that PointerCaptures provides a read-only view of. Calling ReleasePointerCapture(Pointer) 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.

PointerCapturesProperty PointerCapturesProperty PointerCapturesProperty PointerCapturesProperty

Identifies the PointerCaptures dependency property.

public static DependencyProperty PointerCapturesProperty { get; }public static DependencyProperty PointerCapturesProperty { get; }Public Static ReadOnly Property PointerCapturesProperty As DependencyPropertypublic static DependencyProperty PointerCapturesProperty { get; }
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the PointerCaptures dependency property.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

PointerEnteredEvent 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 RoutedEventpublic static RoutedEvent PointerEnteredEvent { get; }
Value
RoutedEvent RoutedEvent RoutedEvent

The identifier for the PointerEntered routed event.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

PointerExitedEvent 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 RoutedEventpublic static RoutedEvent PointerExitedEvent { get; }
Value
RoutedEvent RoutedEvent RoutedEvent

The identifier for the PointerExited routed event.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

PointerMovedEvent 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 RoutedEventpublic static RoutedEvent PointerMovedEvent { get; }
Value
RoutedEvent RoutedEvent RoutedEvent

The identifier for the PointerMoved routed event.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

PointerPressedEvent 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 RoutedEventpublic static RoutedEvent PointerPressedEvent { get; }
Value
RoutedEvent RoutedEvent RoutedEvent

The identifier for the PointerPressed routed event.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

PointerReleasedEvent 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 RoutedEventpublic static RoutedEvent PointerReleasedEvent { get; }
Value
RoutedEvent RoutedEvent RoutedEvent

The identifier for the PointerReleased routed event.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

PointerWheelChangedEvent 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 RoutedEventpublic static RoutedEvent PointerWheelChangedEvent { get; }
Value
RoutedEvent RoutedEvent RoutedEvent

The identifier for the PointerWheelChanged routed event.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Projection 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 Projectionpublic Projection Projection { get; set; }
<uiElement>

  <uiElement.Projection>

    singleProjection

  </uiElement.Projection>

</uiElement>

Value
Projection Projection Projection

A 3-D projection effect applied to the element.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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>

ProjectionProperty ProjectionProperty ProjectionProperty ProjectionProperty

Identifies the Projection dependency property.

public static DependencyProperty ProjectionProperty { get; }public static DependencyProperty ProjectionProperty { get; }Public Static ReadOnly Property ProjectionProperty As DependencyPropertypublic static DependencyProperty ProjectionProperty { get; }
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the Projection dependency property.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

RenderSize 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 Sizepublic Size RenderSize { get; }
Value
Size Size Size

The rendered size for this object. There is no default value.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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(Size) ), use DesiredSize.

RenderTransform 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 Transformpublic Transform RenderTransform { get; set; }
<uiElement>
  <uiElement.RenderTransform>
    singleTransform
  </uiElement.RenderTransform>
</uiElement>
Value
Transform Transform Transform

Describes the specifics of the desired render transform. The default value is null.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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>

RenderTransformOrigin 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 Pointpublic Point RenderTransformOrigin { get; set; }
<uiElement RenderTransformOrigin="x,y"/>

Value
Point Point Point

The origin point of the render transform. The default value is a Point with value 0,0.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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 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>

RenderTransformOriginProperty RenderTransformOriginProperty RenderTransformOriginProperty RenderTransformOriginProperty

Identifies the RenderTransformOrigin dependency property.

public static DependencyProperty RenderTransformOriginProperty { get; }public static DependencyProperty RenderTransformOriginProperty { get; }Public Static ReadOnly Property RenderTransformOriginProperty As DependencyPropertypublic static DependencyProperty RenderTransformOriginProperty { get; }
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the RenderTransformOrigin dependency property.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

RenderTransformProperty RenderTransformProperty RenderTransformProperty RenderTransformProperty

Identifies the RenderTransform dependency property.

public static DependencyProperty RenderTransformProperty { get; }public static DependencyProperty RenderTransformProperty { get; }Public Static ReadOnly Property RenderTransformProperty As DependencyPropertypublic static DependencyProperty RenderTransformProperty { get; }
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the RenderTransform dependency property.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

RightTappedEvent 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 RoutedEventpublic static RoutedEvent RightTappedEvent { get; }
Value
RoutedEvent RoutedEvent RoutedEvent

The identifier for the RightTapped routed event.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

TabFocusNavigation TabFocusNavigation TabFocusNavigation TabFocusNavigation

Prerelease. 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 KeyboardNavigationModepublic KeyboardNavigationMode TabFocusNavigation { get; set; }
<uiElement TabFocusNavigation="keyboardNavigationModeMemberName"/>
Value
KeyboardNavigationMode KeyboardNavigationMode KeyboardNavigationMode

A value of the enumeration. The default is Local.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

TabFocusNavigationProperty TabFocusNavigationProperty TabFocusNavigationProperty TabFocusNavigationProperty

Prerelease. Identifies the TabFocusNavigation dependency property.

public static DependencyProperty TabFocusNavigationProperty { get; }public static DependencyProperty TabFocusNavigationProperty { get; }Public Static ReadOnly Property TabFocusNavigationProperty As DependencyPropertypublic static DependencyProperty TabFocusNavigationProperty { get; }
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the TabFocusNavigation dependency property.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

TappedEvent TappedEvent TappedEvent TappedEvent

Gets the identifier for the Tapped routed event.

public static RoutedEvent TappedEvent { get; }public static RoutedEvent TappedEvent { get; }Public Static ReadOnly Property TappedEvent As RoutedEventpublic static RoutedEvent TappedEvent { get; }
Value
RoutedEvent RoutedEvent RoutedEvent

The identifier for the Tapped routed event.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Transform3D 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 Transform3Dpublic Transform3D Transform3D { get; set; }
Value
Transform3D Transform3D Transform3D

The 3-D transform effect to apply when rendering this element. The default is null.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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>

Rectangles with 3-D transforms 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 ZIndexProperty 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 Transform3DProperty

Identifies the Transform3D dependency property.

public static DependencyProperty Transform3DProperty { get; }public static DependencyProperty Transform3DProperty { get; }Public Static ReadOnly Property Transform3DProperty As DependencyPropertypublic static DependencyProperty Transform3DProperty { get; }
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the Transform3D dependency property.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Transitions 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 TransitionCollectionpublic TransitionCollection Transitions { get; set; }
<uielement>
  <uielement.Transitions>
    <TransitionCollection>
      oneOrMoreTransitions
    </TransitionCollection>
  </uielement.Transitions>
</uielement>
Value
TransitionCollection TransitionCollection TransitionCollection

The strongly typed collection of Transition style elements that apply to a UIElement.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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:

Specific classes that derive from UIElement sometimes have their own properties that hold other types of transitions for class-specific scenarios. For example, ChildTransitions and 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 Transitions collection. VisualTransition is specifically for animations in visual state groups, and is used by the 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>

TransitionsProperty TransitionsProperty TransitionsProperty TransitionsProperty

Identifies the Transitions dependency property.

public static DependencyProperty TransitionsProperty { get; }public static DependencyProperty TransitionsProperty { get; }Public Static ReadOnly Property TransitionsProperty As DependencyPropertypublic static DependencyProperty TransitionsProperty { get; }
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the Transitions dependency property.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

UseLayoutRounding 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 bool UseLayoutRounding { get; set; }public bool UseLayoutRounding { get; set; }Public ReadWrite Property UseLayoutRounding As boolpublic bool UseLayoutRounding { get; set; }
<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
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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.

UseLayoutRoundingProperty UseLayoutRoundingProperty UseLayoutRoundingProperty UseLayoutRoundingProperty

Identifies the UseLayoutRounding dependency property.

public static DependencyProperty UseLayoutRoundingProperty { get; }public static DependencyProperty UseLayoutRoundingProperty { get; }Public Static ReadOnly Property UseLayoutRoundingProperty As DependencyPropertypublic static DependencyProperty UseLayoutRoundingProperty { get; }
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the UseLayoutRounding dependency property.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Visibility 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 Visibilitypublic Visibility Visibility { get; set; }
<uiElement Visibility="Visible"/>
-or-
<uiElement Visibility="Collapsed"/>
Value
Visibility Visibility Visibility

A value of the enumeration. The default value is Visible.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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>

VisibilityProperty VisibilityProperty VisibilityProperty VisibilityProperty

Identifies the Visibility dependency property.

public static DependencyProperty VisibilityProperty { get; }public static DependencyProperty VisibilityProperty { get; }Public Static ReadOnly Property VisibilityProperty As DependencyPropertypublic static DependencyProperty VisibilityProperty { get; }
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the Visibility dependency property.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

XYFocusDownNavigationStrategy XYFocusDownNavigationStrategy XYFocusDownNavigationStrategy XYFocusDownNavigationStrategy

Prerelease. 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 XYFocusNavigationStrategypublic XYFocusNavigationStrategy XYFocusDownNavigationStrategy { get; set; }
<uiElement XYFocusDownNavigationStrategy="xyFocusNavigationStrategyMemberName"/>
Value
XYFocusNavigationStrategy XYFocusNavigationStrategy XYFocusNavigationStrategy

A value of the enumeration. The default is Auto.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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 XYFocusDownNavigationStrategyProperty

Prerelease. Identifies the XYFocusDownNavigationStrategy dependency property.

public static DependencyProperty XYFocusDownNavigationStrategyProperty { get; }public static DependencyProperty XYFocusDownNavigationStrategyProperty { get; }Public Static ReadOnly Property XYFocusDownNavigationStrategyProperty As DependencyPropertypublic static DependencyProperty XYFocusDownNavigationStrategyProperty { get; }
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

XYFocusKeyboardNavigation XYFocusKeyboardNavigation XYFocusKeyboardNavigation XYFocusKeyboardNavigation

Prerelease. 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 XYFocusKeyboardNavigationModepublic XYFocusKeyboardNavigationMode XYFocusKeyboardNavigation { get; set; }
<uiElement XYFocusKeyboardNavigation="xyFocusKeyboardNavigationModeMemberName"/>
Value
XYFocusKeyboardNavigationMode XYFocusKeyboardNavigationMode XYFocusKeyboardNavigationMode

A value of the enumeration. The default is Auto.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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 XYFocusKeyboardNavigationProperty

Prerelease. Identifies the XYFocusKeyboardNavigation dependency property.

public static DependencyProperty XYFocusKeyboardNavigationProperty { get; }public static DependencyProperty XYFocusKeyboardNavigationProperty { get; }Public Static ReadOnly Property XYFocusKeyboardNavigationProperty As DependencyPropertypublic static DependencyProperty XYFocusKeyboardNavigationProperty { get; }
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the XYFocusKeyboardNavigation dependency property.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

XYFocusLeftNavigationStrategy XYFocusLeftNavigationStrategy XYFocusLeftNavigationStrategy XYFocusLeftNavigationStrategy

Prerelease. 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 XYFocusNavigationStrategypublic XYFocusNavigationStrategy XYFocusLeftNavigationStrategy { get; set; }
<uiElement XYFocusLeftNavigationStrategy="xyFocusNavigationStrategyMemberName"/>
Value
XYFocusNavigationStrategy XYFocusNavigationStrategy XYFocusNavigationStrategy

A value of the enumeration. The default is Auto.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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 XYFocusLeftNavigationStrategyProperty

Prerelease. Identifies the XYFocusLeftNavigationStrategy dependency property.

public static DependencyProperty XYFocusLeftNavigationStrategyProperty { get; }public static DependencyProperty XYFocusLeftNavigationStrategyProperty { get; }Public Static ReadOnly Property XYFocusLeftNavigationStrategyProperty As DependencyPropertypublic static DependencyProperty XYFocusLeftNavigationStrategyProperty { get; }
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

XYFocusRightNavigationStrategy XYFocusRightNavigationStrategy XYFocusRightNavigationStrategy XYFocusRightNavigationStrategy

Prerelease. 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 XYFocusNavigationStrategypublic XYFocusNavigationStrategy XYFocusRightNavigationStrategy { get; set; }
<uiElement XYFocusRightNavigationStrategy="xyFocusNavigationStrategyMemberName"/>
Value
XYFocusNavigationStrategy XYFocusNavigationStrategy XYFocusNavigationStrategy

A value of the enumeration. The default is Auto.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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 XYFocusRightNavigationStrategyProperty

Prerelease. Identifies the XYFocusRightNavigationStrategy dependency property.

public static DependencyProperty XYFocusRightNavigationStrategyProperty { get; }public static DependencyProperty XYFocusRightNavigationStrategyProperty { get; }Public Static ReadOnly Property XYFocusRightNavigationStrategyProperty As DependencyPropertypublic static DependencyProperty XYFocusRightNavigationStrategyProperty { get; }
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

XYFocusUpNavigationStrategy XYFocusUpNavigationStrategy XYFocusUpNavigationStrategy XYFocusUpNavigationStrategy

Prerelease. 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 XYFocusNavigationStrategypublic XYFocusNavigationStrategy XYFocusUpNavigationStrategy { get; set; }
<uiElement XYFocusUpNavigationStrategy="xyFocusNavigationStrategyMemberName"/>
Value
XYFocusNavigationStrategy XYFocusNavigationStrategy XYFocusNavigationStrategy

A value of the enumeration. The default is Auto.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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 XYFocusUpNavigationStrategyProperty

Prerelease. Identifies the XYFocusUpNavigationStrategy dependency property.

public static DependencyProperty XYFocusUpNavigationStrategyProperty { get; }public static DependencyProperty XYFocusUpNavigationStrategyProperty { get; }Public Static ReadOnly Property XYFocusUpNavigationStrategyProperty As DependencyPropertypublic static DependencyProperty XYFocusUpNavigationStrategyProperty { get; }
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the XYFocusUpNavigationStrategy dependency property.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Methods

AddHandler(RoutedEvent, Object, Boolean) 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 voidpublic void AddHandler(RoutedEvent routedEvent, Object handler, Boolean handledEventsToo)
Parameters
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
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

Don't try to use AddHandler(RoutedEvent, Object, Boolean) 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(RoutedEvent, Object, Boolean) 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(RoutedEvent, Object, Boolean) call:

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(RoutedEvent, Object, Boolean) 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

Arrange(Rect) 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 voidpublic void Arrange(Rect finalRect)
Parameters
finalRect
Rect Rect Rect

The final size that the parent computes for the child in layout, provided as a Rect value.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

The Arrange(Rect) call potentially reaches an ArrangeOverride(Size) implementation of that specific class. Otherwise, most FrameworkElement classes have an implicit default layout behavior for Arrange(Rect).

Computation of initial layout positioning in a XAML UI consists of a Measure(Size) call and an Arrange(Rect) call, in that order. During the Measure(Size) call, the layout system determines an element's size requirements using the availableSize measurement. During the Arrange(Rect) 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(Size) call that happens before Arrange(Rect). However, after the first layout pass, an Arrange(Rect) call can happen without a Measure(Size) preceding it. This can happen when a property that affects only Arrange(Rect) is changed (such as alignment), or when the parent receives an Arrange(Rect) without a Measure(Size).

A Measure(Size) call will automatically invalidate any Arrange(Rect) 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 ActualWidth ).

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(Rect) within an ArrangeOverride(Size) implementation. The basic idea is that you should query DesiredSize on anything you attempt to call Arrange(Rect) 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() CancelDirectManipulations()

Cancels ongoing direct manipulation processing (system-defined panning/zooming) on any ScrollViewer parent that contains the current UIElement.

public bool CancelDirectManipulations()public bool CancelDirectManipulations()Public Function CancelDirectManipulations() As boolpublic bool CancelDirectManipulations()
Returns
bool bool 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
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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.

CapturePointer(Pointer) 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 bool CapturePointer(Pointer value)public bool CapturePointer(Pointer value)Public Function CapturePointer(value As Pointer) As boolpublic bool CapturePointer(Pointer value)
Parameters
value
Pointer Pointer Pointer

The pointer object reference.

Returns
bool bool bool

true if the object has pointer capture; otherwise, false.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

You can only successfully capture the pointer if that pointer is in a pressed state (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(Pointer) returns false. Existing captures aren't affected by a CapturePointer(Pointer) 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(Pointer) 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(Pointer) or ReleasePointerCaptures(). For more info, see Mouse interactions.

The CapturePointer(Pointer) 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(Pointer) 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(Pointer) call won't have any effect. There's no practical way to generate a new Pointer and call CapturePointer(Pointer) 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(Pointer) 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

FindSubElementsForTouchTargeting(Point, Rect) 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 )protected virtual IIterable<IIterable<Point>> FindSubElementsForTouchTargeting(Point point, Rect boundingRect)
Parameters
point
Point Point Point

The point being touched.

boundingRect
Rect Rect Rect

The bounds used for touch tolerance.

Returns

A set of point sets. These represent the vertices of sub elements that are intersected by the given touch point (plus tolerance).

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

Points in the list are in descending z-order: topmost in the rendering stack appears first in the list.

FindElementsInHostCoordinates(Point, UIElement) is a similar static-class helper method that is also used for hit testing and general object tree examination. However, FindSubElementsForTouchTargeting(Point, Rect) 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<T>.

InvalidateArrange() 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 voidpublic void InvalidateArrange()
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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.

InvalidateMeasure() InvalidateMeasure() InvalidateMeasure() InvalidateMeasure()

Invalidates the measurement state (layout) for a UIElement.

public void InvalidateMeasure()public void InvalidateMeasure()Public Function InvalidateMeasure() As voidpublic void InvalidateMeasure()
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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.

Measure(Size) 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(Size) implementations to form a recursive layout update.

public void Measure(Size availableSize)public void Measure(Size availableSize)Public Function Measure(availableSize As Size) As voidpublic void Measure(Size availableSize)
Parameters
availableSize
Size Size Size

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
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

The Measure(Size) call potentially reaches a MeasureOverride(Size) implementation of that specific class. Otherwise, most FrameworkElement classes have an implicit default layout behavior for Measure(Size).

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(Size) call and an Arrange(Rect) call, in that order. During the Measure(Size) call, the layout system determines an element's size requirements using the availableSize measurement. During the Arrange(Rect) 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(Size) call that happens before Arrange(Rect). However, after the first layout pass, an Arrange(Rect) call can happen without a Measure(Size) preceding it. This can happen when a property that affects only Arrange(Rect) is changed (such as alignment), or when the parent receives an Arrange(Rect) without a Measure(Size).

A Measure(Size) call will automatically invalidate any Arrange(Rect) 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 ActualWidth ).

Examples

This example implements MeasureOverride(Size) 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(Size), 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

OnCreateAutomationPeer() 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 AutomationPeerprotected virtual AutomationPeer OnCreateAutomationPeer()
Returns

The class-specific AutomationPeer subclass to return.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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);
            }
        };

OnDisconnectVisualChildren() 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 voidprotected virtual void OnDisconnectVisualChildren()
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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.

DisconnectChildrenRecursive(UIElement) is a similar static helper API that can be called by app code.

ReleasePointerCapture(Pointer) 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 voidpublic void ReleasePointerCapture(Pointer value)
Parameters
value
Pointer Pointer Pointer

The pointer reference. Use either saved references from previous captures, or pointer event data, to obtain this reference.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

Programmatically releasing the pointer capture with ReleasePointerCapture(Pointer) 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(Pointer) if your app code has previously called CapturePointer(Pointer), 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(Pointer) 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(Pointer) 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

ReleasePointerCaptures() ReleasePointerCaptures() ReleasePointerCaptures() ReleasePointerCaptures()

Releases all pointer captures held by this element.

public void ReleasePointerCaptures()public void ReleasePointerCaptures()Public Function ReleasePointerCaptures() As voidpublic void ReleasePointerCaptures()
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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(Pointer) 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) RemoveHandler(RoutedEvent, Object)

Removes the specified routed event handler from this UIElement. Typically the handler in question was added by AddHandler(RoutedEvent, Object, Boolean).

public void RemoveHandler(RoutedEvent routedEvent, Object handler)public void RemoveHandler(RoutedEvent routedEvent, Object handler)Public Function RemoveHandler(routedEvent As RoutedEvent, handler As Object) As voidpublic void RemoveHandler(RoutedEvent routedEvent, Object handler)
Parameters
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
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

RemoveHandler(RoutedEvent, Object) can only be used for the event handlers of the events that are supported by AddHandler(RoutedEvent, Object, Boolean), 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(RoutedEvent, Object) 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(RoutedEvent, Object, Boolean) call that originally attached the handler.

StartBringIntoView() StartBringIntoView() StartBringIntoView() StartBringIntoView()

Prerelease. Initiates a request to the XAML framework to bring the element into view.

public void StartBringIntoView()public void StartBringIntoView()Public Function StartBringIntoView() As voidpublic void StartBringIntoView()
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

StartBringIntoView(BringIntoViewOptions) StartBringIntoView(BringIntoViewOptions) StartBringIntoView(BringIntoViewOptions) StartBringIntoView(BringIntoViewOptions)

Prerelease. 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 voidpublic void StartBringIntoView(BringIntoViewOptions options)
Parameters
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

StartDragAsync(PointerPoint) 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 )public IAsyncOperation<DataPackageOperation> StartDragAsync(PointerPoint pointerPoint)
Parameters
pointerPoint
PointerPoint PointerPoint PointerPoint

The coordinates of the pointer where the user interacts with the screen, and where the drag visual is attached.

Returns

A DataPackageOperation value that indicates the type of drag-and-drop operation, and whether the operation was successful.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

If you implement custom gesture detection to initiate a drag operation, you can call the StartDragAsync(PointerPoint) 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.
    }
}

TransformToVisual(UIElement) 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 GeneralTransformpublic GeneralTransform TransformToVisual(UIElement visual)
Parameters
visual
UIElement UIElement UIElement

The object to compare to the current object for purposes of obtaining the transform.

Returns

The transform information as an object. Call methods on this object to get a practical transform.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

Call TransformToVisual(UIElement) 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(UIElement), 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(UIElement) 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(UIElement) 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(UIElement), you can then call TransformPoint(Point) 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(UIElement) 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(UInt32) call in the first line of the method) but then later uses TransformToVisual(UIElement) 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;
}

TryStartDirectManipulation(Pointer) 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 bool TryStartDirectManipulation(Pointer value)public static bool TryStartDirectManipulation(Pointer value)Public Static Function TryStartDirectManipulation(value As Pointer) As boolpublic static bool TryStartDirectManipulation(Pointer value)
Parameters
value
Pointer Pointer Pointer

The active touch point that initiated the manipulation.

Returns
bool bool 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
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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(Pointer) 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. A given touch contact can only be associated with a single chain of visuals at a time. Calling TryStartDirectManipulation(Pointer) more than once on the same contact results in any previous chain being released.

UpdateLayout() 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 voidpublic void UpdateLayout()
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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.

Events

AccessKeyDisplayDismissed 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 AccessKeyDisplayDismissedpublic event TypedEventHandler AccessKeyDisplayDismissed
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

AccessKeyDisplayRequested 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 AccessKeyDisplayRequestedpublic event TypedEventHandler AccessKeyDisplayRequested
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

This event is not raised if the element is under an element with its Visibility property set to Collapsed.

AccessKeyInvoked 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 AccessKeyInvokedpublic event TypedEventHandler AccessKeyInvoked
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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 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 ContextCanceledpublic event TypedEventHandler ContextCanceled
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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 ContextRequested

Occurs when the user has completed a context input gesture, such as a right-click.

public event TypedEventHandler ContextRequestedpublic event TypedEventHandler ContextRequestedPublic Event ContextRequestedpublic event TypedEventHandler ContextRequested
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

If the ContextFlyout property is null, this event is marked as handled.

DoubleTapped 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 DoubleTappedpublic event DoubleTappedEventHandler DoubleTapped
<uiElement DoubleTapped="eventhandler"/>
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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 DoubleTapped. 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(UIElement), 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. Visibility must be Visibility. 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(RoutedEvent, Object, Boolean).

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(DoubleTappedRoutedEventArgs). 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.

DragEnter 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 DragEnterpublic event DragEventHandler DragEnter
<uiElement DragEnter="eventhandler"/>
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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(PointerPoint) 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. Visibility must be Visibility. 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(RoutedEvent, Object, Boolean).

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(DragEventArgs). 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(PointerPoint) 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.

DragLeave 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 DragLeavepublic event DragEventHandler DragLeave
<uiElement DragLeave="eventhandler"/>
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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(PointerPoint) 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. Visibility must be Visibility. 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(RoutedEvent, Object, Boolean).

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(DragEventArgs). 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(PointerPoint) 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.

DragOver 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 DragOverpublic event DragEventHandler DragOver
<uiElement DragOver="eventhandler"/>
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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(PointerPoint) 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. Visibility must be Visibility. 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(RoutedEvent, Object, Boolean).

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(DragEventArgs). 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(PointerPoint) 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.

DragStarting DragStarting DragStarting DragStarting

Occurs when a drag operation is initiated.

public event TypedEventHandler DragStartingpublic event TypedEventHandler DragStartingPublic Event DragStartingpublic event TypedEventHandler DragStarting
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Drop 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 Droppublic event DragEventHandler Drop
<uiElement Drop="eventhandler"/>
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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(PointerPoint) 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. Visibility must be Visibility. 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(RoutedEvent, Object, Boolean).

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(DragEventArgs). 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(PointerPoint) 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.

DropCompleted DropCompleted DropCompleted DropCompleted

Occurs when a drag-and-drop operation is ended.

public event TypedEventHandler DropCompletedpublic event TypedEventHandler DropCompletedPublic Event DropCompletedpublic event TypedEventHandler DropCompleted
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

GettingFocus GettingFocus GettingFocus GettingFocus

Prerelease. Occurs before a UIElement receives focus.

public event TypedEventHandler GettingFocuspublic event TypedEventHandler GettingFocusPublic Event GettingFocuspublic event TypedEventHandler GettingFocus
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

GotFocus GotFocus GotFocus GotFocus

Occurs when a UIElement receives focus.

public event RoutedEventHandler GotFocuspublic event RoutedEventHandler GotFocusPublic Event GotFocuspublic event RoutedEventHandler GotFocus
<uiElement GotFocus="eventhandler"/>
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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(FocusState) 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(RoutedEventArgs). 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.

Holding 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 Holdingpublic event HoldingEventHandler Holding
<uiElement Holding="eventhandler"/>
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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(UIElement), 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. Visibility must be Visibility. 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(RoutedEvent, Object, Boolean).

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(HoldingRoutedEventArgs). 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.

KeyDown KeyDown KeyDown KeyDown

Occurs when a keyboard key is pressed while the UIElement has focus.

public event KeyEventHandler KeyDownpublic event KeyEventHandler KeyDownPublic Event KeyDownpublic event KeyEventHandler KeyDown
<uiElement KeyDown="eventhandler"/>
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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 Focus(FocusState).

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(KeyRoutedEventArgs). 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(RoutedEvent, Object, Boolean).

KeyUp KeyUp KeyUp KeyUp

Occurs when a keyboard key is released while the UIElement has focus.

public event KeyEventHandler KeyUppublic event KeyEventHandler KeyUpPublic Event KeyUppublic event KeyEventHandler KeyUp
<uiElement KeyUp="eventhandler"/>
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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 Focus(FocusState).

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(KeyRoutedEventArgs). 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(RoutedEvent, Object, Boolean).

LosingFocus LosingFocus LosingFocus LosingFocus

Prerelease. Occurs before a UIElement loses focus.

public event TypedEventHandler LosingFocuspublic event TypedEventHandler LosingFocusPublic Event LosingFocuspublic event TypedEventHandler LosingFocus
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

LostFocus LostFocus LostFocus LostFocus

Occurs when a UIElement loses focus.

public event RoutedEventHandler LostFocuspublic event RoutedEventHandler LostFocusPublic Event LostFocuspublic event RoutedEventHandler LostFocus
<uiElement LostFocus="eventhandler"/>
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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(FocusState) 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(RoutedEventArgs). 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(RoutedEventArgs). 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.

ManipulationCompleted ManipulationCompleted ManipulationCompleted ManipulationCompleted

Occurs when a manipulation on the UIElement is complete.

public event ManipulationCompletedEventHandler ManipulationCompletedpublic event ManipulationCompletedEventHandler ManipulationCompletedPublic Event ManipulationCompletedpublic event ManipulationCompletedEventHandler ManipulationCompleted
<uiElement ManipulationCompleted="eventhandler"/>
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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. Visibility must be Visibility. 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(RoutedEvent, Object, Boolean).

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.

ManipulationDelta ManipulationDelta ManipulationDelta ManipulationDelta

Occurs when the input device changes position during a manipulation.

public event ManipulationDeltaEventHandler ManipulationDeltapublic event ManipulationDeltaEventHandler ManipulationDeltaPublic Event ManipulationDeltapublic event ManipulationDeltaEventHandler ManipulationDelta
<uiElement ManipulationDelta="eventhandler"/>
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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. Visibility must be Visibility. 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(RoutedEvent, Object, Boolean).

ManipulationInertiaStarting 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 ManipulationInertiaStartingpublic event ManipulationInertiaStartingEventHandler ManipulationInertiaStarting
<uiElement ManipulationInertiaStarting="eventhandler"/>
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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. Visibility must be Visibility. 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(RoutedEvent, Object, Boolean).

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.

ManipulationStarted ManipulationStarted ManipulationStarted ManipulationStarted

Occurs when an input device begins a manipulation on the UIElement.

public event ManipulationStartedEventHandler ManipulationStartedpublic event ManipulationStartedEventHandler ManipulationStartedPublic Event ManipulationStartedpublic event ManipulationStartedEventHandler ManipulationStarted
<uiElement ManipulationStarted="eventhandler"/>
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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. Visibility must be Visibility. 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(RoutedEvent, Object, Boolean).

ManipulationStarting ManipulationStarting ManipulationStarting ManipulationStarting

Occurs when the manipulation processor is first created.

public event ManipulationStartingEventHandler ManipulationStartingpublic event ManipulationStartingEventHandler ManipulationStartingPublic Event ManipulationStartingpublic event ManipulationStartingEventHandler ManipulationStarting
<uiElement ManipulationStarting="eventhandler"/>
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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.

ManipulationStarting fires basically any time that a pointer interacts with an element where the element enables manipulation. This includes cases where the manipulation is interpreted as a gesture and the pointers never move, for example a Tapped or Holding gesture. If the pointers do move, ManipulationStarted typically fires thereafter.

ManipulationStarting 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. Visibility must be Visibility. Other properties of derived types also affect hit-test visibility. For more info, see Events and routed events overview.

ManipulationStarting 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(RoutedEvent, Object, Boolean).

Windows 8 behavior

Windows 8 had an issue with firing this event if multiple gestures happened in a short period of time. For example, Windows 8 might only fire ManipulationStarting for the first gesture and not the second. The issue is fixed starting with Windows 8.1; multiple starting gestures processed by the input system each fire a distinct ManipulationStarting event.

Apps that were compiled for Windows 8 but running on Windows 8.1 continue to use the Windows 8 behavior.

NoFocusCandidateFound NoFocusCandidateFound NoFocusCandidateFound NoFocusCandidateFound

Prerelease. Occurs when a user attempts to move focus (via tab or directional arrows), but focus doesn't move because no focus candidate is found in the direction of movement.

public event TypedEventHandler NoFocusCandidateFoundpublic event TypedEventHandler NoFocusCandidateFoundPublic Event NoFocusCandidateFoundpublic event TypedEventHandler NoFocusCandidateFound
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

PointerCanceled PointerCanceled PointerCanceled PointerCanceled

Occurs when a pointer that made contact abnormally loses contact.

public event PointerEventHandler PointerCanceledpublic event PointerEventHandler PointerCanceledPublic Event PointerCanceledpublic event PointerEventHandler PointerCanceled
<uiElement PointerCanceled="eventhandler"/>
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

Some of the reasons why you might get a PointerCanceled occurrence are:

  • User actions that change the relationship of the display area, such as changing resolution or monitor settings
  • Input interactions such as a stylus touching the same surface as a previous touch action
  • The user logs off or similar interruptions that aren't app-specific
  • The number of simultaneous contacts exceeded the number supported by the device
Important

PointerCanceled might fire instead of PointerReleased. Don't rely on PointerPressed and PointerReleased events always occurring in pairs. To function properly, your app must listen for and handle all events that represent the possible conclusions to a Press action, and that includes PointerCanceled.

If PointerCanceled fires, any pointer captures by that pointer are released. For more info on pointer capture, see CapturePointer(Pointer).

When handling a PointerCanceled event, anticipate that some of the event data normally available for a pointer event won't be meaningful in the PointerRoutedEventArgs object you get through your handler. For example, the Position of the pointer is invalid because the pointer no longer exists.

PointerCanceled is a routed event. For more info on the routed event concept, see Events and routed events overview.

PointerCanceled 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(RoutedEvent, Object, Boolean).

PointerCaptureLost PointerCaptureLost PointerCaptureLost PointerCaptureLost

Occurs when pointer capture previously held by this element moves to another element or elsewhere.

public event PointerEventHandler PointerCaptureLostpublic event PointerEventHandler PointerCaptureLostPublic Event PointerCaptureLostpublic event PointerEventHandler PointerCaptureLost
<uiElement PointerCaptureLost="eventhandler"/>
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

Important

PointerCaptureLost might fire instead of PointerReleased. Don't rely on PointerPressed and PointerReleased events always occurring in pairs. To function properly, your app must listen for and handle all events that represent likely conclusions to the Press action, and that includes PointerCaptureLost. A pointer can lose capture either because of user interactions or because you programmatically captured another pointer or released the current pointer capture deliberately.

There is no event that fires when a pointer is successfully captured. To capture a pointer, you call the CapturePointer(Pointer) method, and this is usually done within the context of an event handler for other pointer events. For more info on how to capture a pointer and why you might want to do so, see CapturePointer(Pointer) or Mouse interactions.

PointerCaptureLost is a routed event. For more info on the routed event concept, see Events and routed events overview.

PointerCaptureLost 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(RoutedEvent, Object, Boolean).

PointerEntered PointerEntered PointerEntered PointerEntered

Occurs when a pointer enters the hit test area of this element.

public event PointerEventHandler PointerEnteredpublic event PointerEventHandler PointerEnteredPublic Event PointerEnteredpublic event PointerEventHandler PointerEntered
<uiElement PointerEntered="eventhandler"/>
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

The PointerEntered event fires in response to a pointer moving into the element's bounding area. Touch, mouse, and pen/stylus interactions are received, processed, and managed as pointer input in Windows Store app. Any of these devices and their interactions can produce a PointerEntered event. For more info, see Handle pointer input and also the other remarks in this topic.

Use a handler based on PointerEventHandler to handle this event.

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. Visibility must be Visibility. Other properties of derived types also affect hit-test visibility. For more info, see Events and routed events overview.

PointerEntered 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(RoutedEvent, Object, Boolean).

Specific Windows Runtime controls may have class-based handling for the PointerEntered input event. If so, the control probably has an override for the method OnPointerEntered(PointerRoutedEventArgs). Typically the event is not marked handled by the class handler, so the PointerEntered event can still be handled by your user code for the control in your UI. For more info on how class-based handling for events works, see Events and routed events overview.

PointerEntered for mouse and pen/stylus input

A mouse input device has an onscreen cursor that is visible whenever the mouse moves, even if no mouse button is pressed at the time. A PointerEntered event will precede the first PointerEntered event fired by the element. Similar behavior is available for pen device input, where the input devices can detect that the stylus is hovering just over the input device surface (IsInRange ) but not touching it. Mouse and pen device input will thus fire PointerEntered events in slightly different cases than touch events do. For more info, see Mouse interactions.

PointerEntered for touch input

A touch point is only detectable if a finger is touching the surface. Whenever a touch action results in a PointerPressed event, that event is immediately preceded by a PointerEntered event, with all the event data being the same information for the two events (same pointer ID, same position, and so on.) In other words the pointer is considered to enter the element at the moment and position that the element is touched by a touch point.

Alternatively, a touch point will generate PointerEntered if a pointer remains in constant contact with the surface as it moves, and enters the hit testing bounds of an element. For these kinds of touch actions it's also possible that the action could be processed as a manipulation, or as a gesture, rather than a pointer event. For more info, see Quickstart: Touch input.

Routed event behavior for PointerEntered

PointerEntered is a routed event. For more info on the routed event concept, see Events and routed events overview. You can define multiple PointerEntered events for elements in a XAML UI, including for elements that are in a parent-child relationship. In a typical UI composition, the child elements are somewhere within a parent element's bounds, so the PointerEntered event will first occur for the parent when the pointer moves into the parent, and then for the child when the pointer moves there. The PointerEntered event doesn't typically bubble to the parent when the child element fires it, because conceptually the pointer is already within the parent bounds and it would be confusing for the input system to route the PointerEntered event occurrence to the parent too. Typically you don't want PointerEntered events to route anyways, you only want to process them from the sender. You can explicitly prevent event routing by setting Handled to true in your handler.

In rare cases it's possible to see a PointerEntered event bubble to the parent. For example, if you've used a RenderTransform to offset a child element outside the bounds of its parent, the event bubbles to the parent when the child element is entered, and gives the event info as reported by how the child element fired the event.

Pointer capture

If another element has captured the pointer, PointerEntered won't fire even if the captured pointer enters an element's bounds. However, if pointer capture is released while the pointer is over the element, PointerEntered will then fire, even thought the pointer might have remained stationary in this case. The value of GetCurrentPoint(UIElement) from event data might be a point somewhere in the middle of an element rather than a point along its edges because the pointer was already over the element when capture was released. For more info on pointer capture, see CapturePointer(Pointer) or Mouse interactions.

PointerOver visual states for controls

Controls that have control templates can apply visual states that are active only when a pointer is over the bounds of the control. You don't always need to handle PointerEntered or PointerExited to get or change this behavior. You may need to retemplate the control. If you are deriving from an existing control that already has the low-level input handling that invokes visual states, you should provide a visual state named "PointerOver" in the "CommonStates" VisualStateGroup, and the built-in control logic will load that visual state whenever a pointer is over the control. A visual state for pointer-over is often present on controls that can be invoked or selected, like a Button or ListViewItem. If you're deriving from a base class like Control that doesn't have built-in input event handling that invokes visual states, you may need to override OnPointerEntered(PointerRoutedEventArgs) and OnPointerExited(PointerRoutedEventArgs) yourself to get this behavior. For more info, see Storyboarded animations for visual states.

Windows 8 behavior

For Windows 8, generally the PointerEntered event won't fire if the onscreen cursor (or stylus or touchpoint) did not actually move. For example, PointerEntered doesn't fire if the mouse and its onscreen cursor remains stationary, and an object with a PointerEntered handler has its position translated or otherwise adjusted to move underneath the onscreen cursor. Or, PointerEntered doesn't fire if an element like a popup or flyout disappears and the pointer is now over a new element (but pointer hasn't moved yet). Related to this is the PointerExited behavior. For example, if a popup is dismissed programmatically, it won't fire PointerExited if the pointer didn't move as the cause of dismissing it. You would still get a PointerEntered event if the pointer moves while over the newly revealed element, but that's up to the user whether that will happen, and it happens at the time of movement, not the moment of dismissal. In short, trying to use the last element that fired PointerEntered for pointer state determination in the app UI isn't comprehensive in Windows 8, and there are many scenarios where PointerEntered and PointerExited won't pair up. This impacts the visual states for controls that use PointerEntered and PointerExited as triggers also.

Starting with Windows 8.1, PointerExited is fired for any case where the pointer had at one time fired a PointerEntered event, but some UI state change happens where the pointer is no longer within that element. This includes cases where the whole element disappears. And if the pointer is now over a different element because a previous element disappeared, that element fires PointerEntered, even if the pointer never moves. Elements that set their Visibility to Collapsed programmatically is one way that elements might disappear from UI, and the Windows 8.1 behavior accounts for this and will fire PointerExited for the **Collapsed ** element and PointerEntered for the newly revealed element.

If you migrate your app code from Windows 8 to Windows 8.1 you may want to account for this behavior change, because it results in PointerExited and PointerEntered being fired in cases where they wouldn't have fired before.

Apps that were compiled for Windows 8 but running on Windows 8.1 continue to use the Windows 8 behavior.

PointerExited PointerExited PointerExited PointerExited

Occurs when a pointer leaves the hit test area of this element.

public event PointerEventHandler PointerExitedpublic event PointerEventHandler PointerExitedPublic Event PointerExitedpublic event PointerEventHandler PointerExited
<uiElement PointerExited="eventhandler"/>
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

The PointerExited event fires in response to a pointer that was initially in the element's bounding area leaving that bounding area. Touch, mouse, and pen/stylus interactions are received, processed, and managed as pointer input in Windows Store app. Any of these devices and their interactions can produce a PointerExited event. For more info, see Handle pointer input and the other remarks in this topic.

Use a handler based on PointerEventHandler to handle this event.

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. Visibility must be Visibility. Other properties of derived types also affect hit-test visibility. For more info, see Events and routed events overview.

PointerExited 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(RoutedEvent, Object, Boolean).

Specific Windows Runtime controls may have class-based handling for the PointerExited input event. If so, the control probably has an override for the method OnPointerExited(PointerRoutedEventArgs). Typically the event is not marked handled by the class handler, so the PointerExited event can still be handled by your user code for the control in your UI. For more info on how class-based handling for events works, see Events and routed events overview.

If another element has captured the pointer, PointerExited won't fire even if the captured pointer leaves an element's bounds. For more info on pointer capture, see CapturePointer(Pointer) or Mouse interactions.

PointerExited for mouse and pen/stylus input

A mouse input device has an onscreen cursor that is visible whenever the mouse moves, even if no mouse button is pressed at the time. Similar behavior is available for pen device input, where the input devices can detect that the stylus is hovering just over the input device surface (IsInRange ) but not touching it. Mouse and pen device input will thus fire PointerExited events in slightly different cases than touch events do. For more info, see Mouse interactions. A PointerExited event fires after the last PointerEntered event for the element fires.

PointerExited for touch input

A touch point is only detectable if a finger is touching the surface. Whenever a touch action results in a PointerReleased event, that event is immediately followed by a PointerExited event, with all the event data being the same information for the two events (same pointer ID, same position, and so on.) In other words the pointer is considered to enter the element at the moment and position that the element is touched by a touch point.

Alternatively, a touch point will generate PointerExited if that pointer remains in constant contact with the surface as it moves, was over the element initially, and then exits the hit testing bounds of an element. For these kinds of touch actions it's also possible that the action could be processed as a manipulation, or as a gesture, rather than a pointer event. For more info, see Quickstart: Touch input.

Routed event behavior for PointerExited

PointerExited is a routed event. For more info on the routed event concept, see Events and routed events overview. You can define multiple PointerExited events for elements in a XAML UI, including for elements that are in a parent-child relationship. In a typical UI composition, the child elements are somewhere within a parent element's bounds, so the PointerExited event will first occur for the child when the pointer moves out of the child, and then for the parent when the pointer moves completely out of that parent. The PointerExited event doesn't typically bubble to the parent when the child element fires it, because it would be confusing for the input system to route the PointerExited event occurrence to the parent too. Typically you don't want PointerExited events to route anyways, you only want to process them from the sender. You can explicitly prevent event routing by setting Handled to true in your handler.

In rare cases it's possible to see a PointerExited event bubble to the parent. For example, if you've used a RenderTransform to offset a child element outside the bounds of its parent, the event bubbles to the parent when the child element is exited, and gives the event info as reported by how the child element fired the event.

PointerOver visual states for controls

Controls that have control templates can apply visual states that are active only when a pointer is over the bounds of the control. You don't always need to handle PointerEntered or PointerExited to get or change this behavior. You may need to retemplate the control. If you are deriving from an existing control that already has the low-level input handling that invokes visual states, you should provide a visual state named "PointerOver" in the "CommonStates" VisualStateGroup, and the built-in control logic will load that visual state whenever a pointer is over the control. A visual state for pointer-over is often present on controls that can be invoked or selected, like a Button or ListViewItem. If you're deriving from a base class like Control that doesn't have built-in input event handling that invokes visual states, you may need to override OnPointerEntered(PointerRoutedEventArgs) and OnPointerExited(PointerRoutedEventArgs) yourself to get this behavior. Use OnPointerExited(PointerRoutedEventArgs) to call GoToState(Control, String, Boolean) to load a state other than the "PointerOver" state, for example "Normal". For more info, see Storyboarded animations for visual states.

Windows 8 behavior

For Windows 8, generally the PointerEntered event won't fire if the onscreen cursor (or stylus or touchpoint) did not actually move. For example, PointerEntered doesn't fire if the mouse and its onscreen cursor remains stationary, and an object with a PointerEntered handler has its position translated or otherwise adjusted to move underneath the onscreen cursor. Or, PointerEntered doesn't fire if an element like a popup or flyout disappears and the pointer is now over a new element (but pointer hasn't moved yet). Related to this is the PointerExited behavior. For example, if a popup is dismissed programmatically, it won't fire PointerExited if the pointer didn't move as the cause of dismissing it. You would still get a PointerEntered event if the pointer moves while over the newly revealed element, but that's up to the user whether that will happen, and it happens at the time of movement, not the moment of dismissal. In short, trying to use the last element that fired PointerEntered for pointer state determination in the app UI isn't comprehensive in Windows 8, and there are many scenarios where PointerEntered and PointerExited won't pair up. This impacts the visual states for controls that use PointerEntered and PointerExited as triggers also.

Starting with Windows 8.1, PointerExited is fired for any case where the pointer had at one time fired a PointerEntered event, but some UI state change happens where the pointer is no longer within that element. This includes cases where the whole element disappears. And if the pointer is now over a different element because a previous element disappeared, that element fires PointerEntered, even if the pointer never moves. Elements that set their Visibility to Collapsed programmatically is one way that elements might disappear from UI, and the Windows 8.1 behavior accounts for this and will fire PointerExited for the **Collapsed ** element and PointerEntered for the newly revealed element.

If you migrate your app code from Windows 8 to Windows 8.1 you may want to account for this behavior change, because it results in PointerExited and PointerEntered being fired in cases where they wouldn't have fired before.

Apps that were compiled for Windows 8 but running on Windows 8.1 continue to use the Windows 8 behavior.

PointerMoved PointerMoved PointerMoved PointerMoved

Occurs when a pointer moves while the pointer remains within the hit test area of this element.

public event PointerEventHandler PointerMovedpublic event PointerEventHandler PointerMovedPublic Event PointerMovedpublic event PointerEventHandler PointerMoved
<uiElement PointerMoved="eventhandler"/>

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

Touch, mouse, and pen/stylus interactions are received, processed, and managed as pointer input in Windows Store app. Any of these interactions can produce a PointerMoved event. For more info, see Handle pointer input and the "PointerMoved for mouse and stylus input" section of this topic.

In some UI scenarios, particularly if the user is using a mouse, this event will fire a lot. Be aware of the performance profile for code you put into this handler, and consider ways to use your own flags or tolerances that can throttle how many times the logic actually needs to run.

This event is a routed event. 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. Visibility must be Visibility. Other properties of derived types also affect hit-test visibility. For more info, see Events and routed events overview.

This event also 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(RoutedEvent, Object, Boolean).

PointerMoved for mouse and stylus input

A mouse input device has an onscreen cursor that is visible whenever the mouse moves over an element's bounds, even if no mouse button is pressed at the time. Similar behavior is available for pen device input, where the input devices can detect that the pen is hovering just over the input device surface but not touching it. Mouse and pen input will thus fire PointerMoved events more often than touch input. For more info, see Mouse interactions.

In contrast, a touch point is only detectable if a finger is touching the surface. A touch point will generate PointerMoved only while that touch point remains in constant contact with the surface as it moves. For these kinds of touch actions that are generating PointerMoved it's also likely that the action will be processed as a manipulation, or as a gesture. For more info, see Quickstart: Touch input.

Mouse input is associated with a single pointer assigned when mouse input is first detected, and all mouse-initiated interactions have the same PointerId. Clicking a mouse button (left, wheel, or right) creates a secondary association between the pointer and that button through the PointerPressed event. The PointerReleased event is fired only when that same mouse button is released (no other button can be associated with the pointer until this event is complete). Because of this exclusive association, other mouse button clicks are routed through the PointerMoved event. You can test the mouse button state when handling this event, as shown in this example:

private void Target_PointerMoved(object sender, PointerRoutedEventArgs e)
{
    Windows.UI.Xaml.Input.Pointer ptr = e.Pointer;

    // Multiple, simultaneous mouse button inputs are processed here.
    // Mouse input is associated with a single pointer assigned when 
    // mouse input is first detected. 
    // Clicking additional mouse buttons (left, wheel, or right) during 
    // the interaction creates secondary associations between those buttons 
    // and the pointer through the pointer pressed event. 
    // The pointer released event is fired only when the last mouse button 
    // associated with the interaction (not necessarily the initial button) 
    // is released. 
    // Because of this exclusive association, other mouse button clicks are 
    // routed through the pointer move event.          
    if (ptr.PointerDeviceType == Windows.Devices.Input.PointerDeviceType.Mouse)
    {
        // To get mouse state, we need extended pointer details.
        // We get the pointer info through the getCurrentPoint method
        // of the event argument. 
        Windows.UI.Input.PointerPoint ptrPt = e.GetCurrentPoint(Target);
        if (ptrPt.Properties.IsLeftButtonPressed)
        {
            eventLog.Text += "\nLeft button: " + ptrPt.PointerId;
        }
        if (ptrPt.Properties.IsMiddleButtonPressed)
        {
            eventLog.Text += "\nWheel button: " + ptrPt.PointerId;
        }
        if (ptrPt.Properties.IsRightButtonPressed)
        {
            eventLog.Text += "\nRight button: " + ptrPt.PointerId;
        }
    }

    // Prevent most handlers along the event route from handling the same event again.
    e.Handled = true;

    // Display pointer details.
    updateInfoPop(e);
}
private void Target_PointerMoved(object sender, PointerRoutedEventArgs e)
{
    Windows.UI.Xaml.Input.Pointer ptr = e.Pointer;

    // Multiple, simultaneous mouse button inputs are processed here.
    // Mouse input is associated with a single pointer assigned when 
    // mouse input is first detected. 
    // Clicking additional mouse buttons (left, wheel, or right) during 
    // the interaction creates secondary associations between those buttons 
    // and the pointer through the pointer pressed event. 
    // The pointer released event is fired only when the last mouse button 
    // associated with the interaction (not necessarily the initial button) 
    // is released. 
    // Because of this exclusive association, other mouse button clicks are 
    // routed through the pointer move event.          
    if (ptr.PointerDeviceType == Windows.Devices.Input.PointerDeviceType.Mouse)
    {
        // To get mouse state, we need extended pointer details.
        // We get the pointer info through the getCurrentPoint method
        // of the event argument. 
        Windows.UI.Input.PointerPoint ptrPt = e.GetCurrentPoint(Target);
        if (ptrPt.Properties.IsLeftButtonPressed)
        {
            eventLog.Text += "\nLeft button: " + ptrPt.PointerId;
        }
        if (ptrPt.Properties.IsMiddleButtonPressed)
        {
            eventLog.Text += "\nWheel button: " + ptrPt.PointerId;
        }
        if (ptrPt.Properties.IsRightButtonPressed)
        {
            eventLog.Text += "\nRight button: " + ptrPt.PointerId;
        }
    }

    // Prevent most handlers along the event route from handling the same event again.
    e.Handled = true;

    // Display pointer details.
    updateInfoPop(e);
}

PointerPressed PointerPressed PointerPressed PointerPressed

Occurs when the pointer device initiates a Press action within this element.

public event PointerEventHandler PointerPressedpublic event PointerEventHandler PointerPressedPublic Event PointerPressedpublic event PointerEventHandler PointerPressed
<uiElement PointerPressed="eventhandler"/>

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

Touch, mouse, and pen/stylus interactions are received, processed, and managed as pointer input in Windows Store app. Any of these interactions can produce a PointerPressed event. For more info, see Handle pointer input. Pointer events are intended for scenarios where you're interested in multiple pointers and their relationships, or when you are examining specifics of each pointer such as exact coordinate position. Otherwise, you might consider handling gesture events such as Tapped.

Use a handler based on PointerEventHandler to handle this event.

Mouse input is associated with a single pointer assigned when mouse input is first detected. Clicking a mouse button (left, wheel, or right) creates a secondary association between the pointer and that button through the PointerPressed event. The PointerReleased event is fired only when that same mouse button is released (no other button can be associated with the pointer until this event is complete). Because of this exclusive association, other mouse button clicks are routed through the PointerMoved event. You can test the mouse button state when handling this event, as shown in the following example.

private void Target_PointerMoved(object sender, PointerRoutedEventArgs e)
{
    Windows.UI.Xaml.Input.Pointer ptr = e.Pointer;

    // Multiple, simultaneous mouse button inputs are processed here.
    // Mouse input is associated with a single pointer assigned when 
    // mouse input is first detected. 
    // Clicking additional mouse buttons (left, wheel, or right) during 
    // the interaction creates secondary associations between those buttons 
    // and the pointer through the pointer pressed event. 
    // The pointer released event is fired only when the last mouse button 
    // associated with the interaction (not necessarily the initial button) 
    // is released. 
    // Because of this exclusive association, other mouse button clicks are 
    // routed through the pointer move event.          
    if (ptr.PointerDeviceType == Windows.Devices.Input.PointerDeviceType.Mouse)
    {
        // To get mouse state, we need extended pointer details.
        // We get the pointer info through the getCurrentPoint method
        // of the event argument. 
        Windows.UI.Input.PointerPoint ptrPt = e.GetCurrentPoint(Target);
        if (ptrPt.Properties.IsLeftButtonPressed)
        {
            eventLog.Text += "\nLeft button: " + ptrPt.PointerId;
        }
        if (ptrPt.Properties.IsMiddleButtonPressed)
        {
            eventLog.Text += "\nWheel button: " + ptrPt.PointerId;
        }
        if (ptrPt.Properties.IsRightButtonPressed)
        {
            eventLog.Text += "\nRight button: " + ptrPt.PointerId;
        }
    }

    // Prevent most handlers along the event route from handling the same event again.
    e.Handled = true;

    // Display pointer details.
    updateInfoPop(e);
}
private void Target_PointerMoved(object sender, PointerRoutedEventArgs e)
{
    Windows.UI.Xaml.Input.Pointer ptr = e.Pointer;

    // Multiple, simultaneous mouse button inputs are processed here.
    // Mouse input is associated with a single pointer assigned when 
    // mouse input is first detected. 
    // Clicking additional mouse buttons (left, wheel, or right) during 
    // the interaction creates secondary associations between those buttons 
    // and the pointer through the pointer pressed event. 
    // The pointer released event is fired only when the last mouse button 
    // associated with the interaction (not necessarily the initial button) 
    // is released. 
    // Because of this exclusive association, other mouse button clicks are 
    // routed through the pointer move event.          
    if (ptr.PointerDeviceType == Windows.Devices.Input.PointerDeviceType.Mouse)
    {
        // To get mouse state, we need extended pointer details.
        // We get the pointer info through the getCurrentPoint method
        // of the event argument. 
        Windows.UI.Input.PointerPoint ptrPt = e.GetCurrentPoint(Target);
        if (ptrPt.Properties.IsLeftButtonPressed)
        {
            eventLog.Text += "\nLeft button: " + ptrPt.PointerId;
        }
        if (ptrPt.Properties.IsMiddleButtonPressed)
        {
            eventLog.Text += "\nWheel button: " + ptrPt.PointerId;
        }
        if (ptrPt.Properties.IsRightButtonPressed)
        {
            eventLog.Text += "\nRight button: " + ptrPt.PointerId;
        }
    }

    // Prevent most handlers along the event route from handling the same event again.
    e.Handled = true;

    // Display pointer details.
    updateInfoPop(e);
}

Pointer events from a mouse input device generally have the same PointerId in the event details for the lifetime of the app.

PointerPressed is a routed event. 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. Visibility must be Visibility. Other properties of derived types also affect hit-test visibility. For more info, see Events and routed events overview.

PointerPressed 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(RoutedEvent, Object, Boolean).

Specific Windows Runtime controls may have class-based handling for the PointerPressed input event. If so, the control probably has an override for the method OnPointerPressed(PointerRoutedEventArgs). Typically the event is marked handled by the class handler, and the PointerPressed event is not raised for handling by any user code handlers on that control. For example, ButtonBase has class handling that handles PointerPressed and instead fires Click. For more info on how class-based handling for events works, see Events and routed events overview.

Controls may also have a PointerDownThemeAnimation personality animation that run independently of the event.

Pointer capture

PointerPressed is sometimes used as the initiating event when capturing the pointer, so that further pointer-related events are all captured by a particular element so long as the pointer remains down. To capture a pointer, you call the CapturePointer(Pointer) method on a specific UI element that should maintain the capture. This is usually done within a PointerPressed event handler, and you call CapturePointer(Pointer) on the event's sender. For more info on how to capture a pointer and why you might want to do so, see CapturePointer(Pointer).

PointerPressed and gesture events, or manipulation events

The user action that fires a PointerPressed event initially can eventually result in the Holding event representing a Hold gesture, unless the input device is a mouse. If the element where PointerPressed occurs has a non-default ManipulationMode value, then the action might also result in various manipulation events like ManipulationStarted. For more info, see "Using manipulation events" section in Quickstart: Touch input.

When PointerPressed fires, gesture events such as Tapped won't fire yet because the gesture events other than Holding are waiting for the pointer to be released before firing an event.

As a general design rule for your app's user interactions, you should examine whether there are control-specific events you can handle for an interaction, or appropriate gesture events. For example, if your control is a Button, that control has a Click event that's specifically intended for when the user invokes the button's action. Or if your element isn't a button but you're handling and event for an element's primary action, you would handle Tapped.

Gesture events can be specifically disabled on individual elements by setting properties such as IsTapEnabled. You might disable the gesture events if you are processing manipulations, but you typically don't need to disable gesture events if you're handling pointer events. Pointer events can't be specifically disabled, but you can choose to not handle them.

PointerPressed and PointerReleased

Other events instead of PointerReleased may fire at the end of the action— for example, PointerCanceled or PointerCaptureLost. Don't rely on PointerPressed and PointerReleased events always occurring in pairs. To function properly, your app must listen for and handle all events that represent likely conclusions to the Press action. Some of the reasons why you might not get a PointerReleased occurrence are:

  • Differences in how specific hardware handles touch actions and Press actions
  • A programmatic pointer capture from a different pointer
  • User actions that change the relationship of the display area, such as changing resolution or monitor settings
  • Input interactions such as a stylus touching the same surface as a previous touch action

PointerReleased PointerReleased PointerReleased PointerReleased

Occurs when the pointer device that previously initiated a Press action is released, while within this element. Note that the end of a Press action is not guaranteed to fire a PointerReleased event; other events may fire instead. For more info, see Remarks.

public event PointerEventHandler PointerReleasedpublic event PointerEventHandler PointerReleasedPublic Event PointerReleasedpublic event PointerEventHandler PointerReleased
<uiElement PointerReleased="eventhandler"/>

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

Touch, mouse, and pen/stylus interactions are received, processed, and managed as pointer input in Windows Store app. Any of these interactions can produce a PointerReleased event. For more info, see Handle pointer input.

Other events instead of PointerReleased may fire at the end of the action— for example, PointerCanceled or PointerCaptureLost. Don't rely on PointerPressed and PointerReleased events always occurring in pairs. To function properly, your app must listen for and handle all events that represent likely conclusions to the Press action. Some of the reasons why you might not get a PointerReleased occurrence are:

  • Differences in how specific hardware handles touch actions and Press actions
  • A programmatic pointer capture from a different pointer
  • User actions that change the relationship of the display area, such as changing resolution or monitor settings
  • Input interactions such as a stylus touching the same surface as a previous touch action

The user action that fires a PointerReleased event initially can result in the Tapped event, or can also result in RightTapped under conditions that vary per device. For more info, see Tapped and RightTapped.

Mouse input is associated with a single pointer assigned when mouse input is first detected. Clicking a mouse button (left, wheel, or right) creates a secondary association between the pointer and that button through the PointerPressed event. The PointerReleased event is fired only when that same mouse button is released (no other button can be associated with the pointer until this event is complete). Because of this exclusive association, other mouse button clicks are routed through the PointerMoved event. You can test the mouse button state when handling this event, as shown in the following example.

private void Target_PointerMoved(object sender, PointerRoutedEventArgs e)
{
    Windows.UI.Xaml.Input.Pointer ptr = e.Pointer;

    // Multiple, simultaneous mouse button inputs are processed here.
    // Mouse input is associated with a single pointer assigned when 
    // mouse input is first detected. 
    // Clicking additional mouse buttons (left, wheel, or right) during 
    // the interaction creates secondary associations between those buttons 
    // and the pointer through the pointer pressed event. 
    // The pointer released event is fired only when the last mouse button 
    // associated with the interaction (not necessarily the initial button) 
    // is released. 
    // Because of this exclusive association, other mouse button clicks are 
    // routed through the pointer move event.          
    if (ptr.PointerDeviceType == Windows.Devices.Input.PointerDeviceType.Mouse)
    {
        // To get mouse state, we need extended pointer details.
        // We get the pointer info through the getCurrentPoint method
        // of the event argument. 
        Windows.UI.Input.PointerPoint ptrPt = e.GetCurrentPoint(Target);
        if (ptrPt.Properties.IsLeftButtonPressed)
        {
            eventLog.Text += "\nLeft button: " + ptrPt.PointerId;
        }
        if (ptrPt.Properties.IsMiddleButtonPressed)
        {
            eventLog.Text += "\nWheel button: " + ptrPt.PointerId;
        }
        if (ptrPt.Properties.IsRightButtonPressed)
        {
            eventLog.Text += "\nRight button: " + ptrPt.PointerId;
        }
    }

    // Prevent most handlers along the event route from handling the same event again.
    e.Handled = true;

    // Display pointer details.
    updateInfoPop(e);
}
private void Target_PointerMoved(object sender, PointerRoutedEventArgs e)
{
    Windows.UI.Xaml.Input.Pointer ptr = e.Pointer;

    // Multiple, simultaneous mouse button inputs are processed here.
    // Mouse input is associated with a single pointer assigned when 
    // mouse input is first detected. 
    // Clicking additional mouse buttons (left, wheel, or right) during 
    // the interaction creates secondary associations between those buttons 
    // and the pointer through the pointer pressed event. 
    // The pointer released event is fired only when the last mouse button 
    // associated with the interaction (not necessarily the initial button) 
    // is released. 
    // Because of this exclusive association, other mouse button clicks are 
    // routed through the pointer move event.          
    if (ptr.PointerDeviceType == Windows.Devices.Input.PointerDeviceType.Mouse)
    {
        // To get mouse state, we need extended pointer details.
        // We get the pointer info through the getCurrentPoint method
        // of the event argument. 
        Windows.UI.Input.PointerPoint ptrPt = e.GetCurrentPoint(Target);
        if (ptrPt.Properties.IsLeftButtonPressed)
        {
            eventLog.Text += "\nLeft button: " + ptrPt.PointerId;
        }
        if (ptrPt.Properties.IsMiddleButtonPressed)
        {
            eventLog.Text += "\nWheel button: " + ptrPt.PointerId;
        }
        if (ptrPt.Properties.IsRightButtonPressed)
        {
            eventLog.Text += "\nRight button: " + ptrPt.PointerId;
        }
    }

    // Prevent most handlers along the event route from handling the same event again.
    e.Handled = true;

    // Display pointer details.
    updateInfoPop(e);
}

PointerReleased is a routed event. 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. Visibility must be Visibility. Other properties of derived types also affect hit-test visibility. For more info, see Events and routed events overview.

PointerReleased 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(RoutedEvent, Object, Boolean).

Specific Windows Runtime controls may have class-based handling for the PointerReleased input event. If so, the control probably has an override for the method OnPointerReleased(PointerRoutedEventArgs). Typically the event is marked handled by the class handler, and the PointerReleased 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.

Controls may also have a PointerUpThemeAnimation personality animation that run independently of the event.

PointerWheelChanged PointerWheelChanged PointerWheelChanged PointerWheelChanged

Occurs when the delta value of a pointer wheel changes.

public event PointerEventHandler PointerWheelChangedpublic event PointerEventHandler PointerWheelChangedPublic Event PointerWheelChangedpublic event PointerEventHandler PointerWheelChanged
<uielement PointerWheelChanged = "eventhandler" .../>
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

When you handle PointerWheelChanged, you are usually interested in the MouseWheelDelta property value:

  1. Call GetCurrentPoint(UIElement) from the PointerRoutedEventArgs available to your handler. This returns a PointerPoint.
  2. Get the Properties of the PointerPoint. It contains a PointerPointProperties object.
  3. Get the MouseWheelDelta property value from the PointerPointProperties object. A positive value indicates that the wheel was rotated forward (away from the user) or tilted to the right; a negative value indicates that the wheel was rotated backward (toward the user) or tilted to the left.

If the element where pointer events occur has a non-default ManipulationMode value, then the action might also result in various manipulation events like ManipulationStarted. In addition, mouse wheel input can be handled as a built-in manipulation behavior by controls, even with no ManipulationMode value set. For example, certain controls like GridView and ListView can process mouse wheel input to initiate a scroll/pan action.

PointerWheelChanged is a routed event. 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. Visibility must be Visibility. Other properties of derived types also affect hit-test visibility. For more info, see Events and routed events overview.

PointerWheelChanged 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(RoutedEvent, Object, Boolean).

Specific Windows Runtime controls may have class-based handling for the PointerWheelChanged input event. If so, the control probably has an override for the method OnPointerWheelChanged(PointerRoutedEventArgs). Typically the event is marked handled by the class handler, and the PointerWheelChanged event is not raised for handling by any user code handlers on that control. A control might do this in order to support traversal of its child elements by using a pointer wheel action. For more info on how class-based handling for events works, see Events and routed events overview.

Windows 8 behavior

For Windows 8, track pad device gestures that were input-handled by a ScrollViewer control part were interpreted as mouse wheel input, and thus would fire a PointerWheelChanged event. Starting with Windows 8.1, ScrollViewer uses an underlying manipulation logic that interprets track pad gestures as actions that the ScrollViewer responds to, and thus the gesture is considered handled by the control and the PointerWheelChanged event is not fired anymore.

If you migrate your app code from Windows 8 to Windows 8.1 you may want to account for this behavior change, because it results in PointerWheelChanged being fired in fewer cases. Also, the behavior that's now built-in to ScrollViewer may be duplicating what your handler would have done.

Apps that were compiled for Windows 8 but running on Windows 8.1 continue to use the Windows 8 behavior.

RightTapped RightTapped RightTapped RightTapped

Occurs when a right-tap input stimulus happens while the pointer is over the element.

public event RightTappedEventHandler RightTappedpublic event RightTappedEventHandler RightTappedPublic Event RightTappedpublic event RightTappedEventHandler RightTapped
<uielement RightTapped = "eventhandler" .../>
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

RightTapped for a touch action results from processing an action that remains in one place for a certain amount of time. If it's a touch action, a Holding event from the same element always precedes this, but RightTapped won't fire until the touch point is released. If the time the pointer is pressed is too short and Tapped fires instead of Holding, or if the Hold action ends with HoldingState as Canceled, RightTapped won't fire.

RightTapped is the event to handle for displaying context menus. See Touch interaction design and UX guidelines for custom user interactions for more info on how to use a right-tap interaction in your app design.

A RightTapped event represents a gesture, whereas a PointerReleased event is a lower-level input event. RightTapped and PointerReleased 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 RightTapped from firing.

A RightTapped event is potentially the result of more than one pointer point. For the higher-level gesture events like RightTapped 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(UIElement), which gives an average of the coordinates for a RightTap from more than one pointer point.

RightTapped is a routed event. Also, an element must have IsRightTapEnabled be true to be a RightTapped event source (true is the default). It is possible to handle RightTapped on parent elements even if IsRightTapEnabled is false on the parent element, if the event bubbles to a parent from an event source child element where IsRightTapEnabled 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. Visibility must be Visibility. Other properties of derived types also affect hit-test visibility. For more info, see Events and routed events overview.

RightTapped 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(RoutedEvent, Object, Boolean).

Specific Windows Runtime controls may have class-based handling for the RightTapped event. If so, the control probably has an override for the method OnRightTapped(RightTappedRoutedEventArgs). A right-tap action might be associated with displaying a context menu or secondary window. For more info on how class-based handling for events works, see Events and routed events overview.

RightTapped for mouse and pen/stylus input

The input system processes an action where the user clicks the right mouse button while over the element as a RightTapped action. The event doesn't fire until the right mouse button is released. Mouse input doesn't produce Holding events by default, no matter how long a mouse button is held down, or which button is held.

Some pen devices have multiple buttons, one of which can be used the same way that the right button on a mouse device is used. This depends on the device and its settings, but if a right-click equivalent is enabled by the pen device, the input system can fire RightTapped for these actions also.

Windows 8 behavior

Windows 8 had an issue with the data for the RightTapped event, where the X and Y values for the point you'd get from GetPosition(UIElement) were reversed (X was really Y; Y was really X). This issue has been fixed starting with Windows 8.1. But if you're retargeting a Windows 8 app for Windows 8.1, you might have had code that worked around this issue by swapping the X and Y back. If so, remove that code when you retarget because the issue is now fixed.

Apps that were compiled for Windows 8 but running on Windows 8.1 continue to use this Windows 8 behavior.

Also, Windows 8 didn't include default key handling for Shift+F10 that would fire this event and then display context menus. Shift+F10 is typically a secondary key combination for the VK_APP virtual key value (the Properties key), and thus Shift+F10 might be expected to fire RightTapped too. This issue has been fixed starting with Windows 8.1; Shift+F10 now fires RightTapped. You can see this change as default event handling on some controls that have default context menus for text, such as TextBox, or when invoking custom menus and flyouts.

Apps that were compiled for Windows 8 but running on Windows 8.1 do not use this Windows 8 behavior, they use the corrected Windows 8.1 behavior.

Tapped Tapped Tapped Tapped

Occurs when an otherwise unhandled Tap interaction occurs over the hit test area of this element.

public event TappedEventHandler Tappedpublic event TappedEventHandler TappedPublic Event Tappedpublic event TappedEventHandler Tapped
<uiElement Tapped="eventhandler"/>
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

Touch, mouse devices and pen devices can all produce a Tap action. For more info, see Quickstart: Touch input.

See Touch interaction design for more info on how to use a Tap interaction in your app design. The general idea is that a Tap interaction on an element invokes the element's primary action in your app.

A Tapped event represents a gesture, whereas a PointerPressed event is a lower-level input event. Tapped and PointerPressed events can be raised as the result of a single user interaction. If the event source has a nondefault ManipulationMode, ManipulationStarting can be raised too. Even if a control is already handling PointerPressed in the control logic, or is handling manipulations, that doesn't prevent Tapped from being raised.

A Tapped event is potentially the result of more than one pointer point. For the higher-level gesture events such as Tapped 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(UIElement), which gives an average of the coordinates for a Tap from more than one pointer point.

Tapped is a routed event. Also, an element must have IsTapEnabled be true to be a Tapped event source (true is the default). It is possible to handle Tapped on parent elements even if IsTapEnabled is false on the parent element, if the event bubbles to a parent from an event source child element where IsTapEnabled 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. Visibility must be Visibility. Other properties of derived types also affect hit-test visibility. For more info, see Events and routed events overview.

Tapped 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(RoutedEvent, Object, Boolean).

Specific Windows Runtime controls may also have class-based handling for the Tapped event. If so, the control probably has an override for the method OnTapped(TappedRoutedEventArgs). For more info on how class-based handling for events works, see Events and routed events overview.

Tapped and Holding are mutually exclusive. The input system must wait until the pointer point is released in order to determine whether the action should be Tapped, Holding or some other gesture, so you don't get Tapped at the very instant that a user touches the screen. If you really need instant feedback you may want to use PointerPressed instead.

If a user interaction also raises DoubleTapped, Tapped will be raised first to represent the first tap, but the second tap won't raise 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.

Tapped for mouse and pen/stylus input

The input system processes an action where the user clicks the left mouse button while over the element as a Tapped action. The event doesn't fire until the left mouse button is released. Mouse input doesn't produce Holding events by default, no matter how long a mouse button is held down, or which button is held.

For pen devices, touching the pen device to the surface and remaining in one place produces a Hold action.

Controls that do not raise the Tapped event

These controls do not raise the Tapped event: