UIElement UIElement UIElement UIElement Class

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

public : PlatForm::String AccessKey { get; set; }public string AccessKey { get; set; }Public ReadWrite Property AccessKey As string// This API is not available in Javascript.

Device family	Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v3)

Remarks

Setting this property enables the AccessKeyDisplayRequested event to be raised.

If the AutomationProperties.AccessKey attached property is not set, this property is used by the Automation framework instead. The value is used as case-insensitive, using the user language. It is used as text, so if an Input Method Editor (IME) is active the composed text is used.

Identifies for the AccessKey dependency property.

public : static DependencyProperty AccessKeyProperty { get; }public static DependencyProperty AccessKeyProperty { get; }Public Static ReadOnly Property AccessKeyProperty As DependencyProperty// This API is not available in Javascript.

Device family	Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v3)

Gets or sets a source element that provides the access key scope for this element, even if it's not in the visual tree of the source element.

public : DependencyObject AccessKeyScopeOwner { get; set; }public DependencyObject AccessKeyScopeOwner { get; set; }Public ReadWrite Property AccessKeyScopeOwner As DependencyObject// This API is not available in Javascript.

Device family	Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v3)

Remarks

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

Identifies for the AccessKeyScopeOwner dependency property.

public : static DependencyProperty AccessKeyScopeOwnerProperty { get; }public static DependencyProperty AccessKeyScopeOwnerProperty { get; }Public Static ReadOnly Property AccessKeyScopeOwnerProperty As DependencyProperty// This API is not available in Javascript.

Device family	Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v3)

Gets or sets a value that determines whether this UIElement can be a drop target for purposes of drag-and-drop operations.

public : PlatForm::Boolean AllowDrop { get; set; }public bool AllowDrop { get; set; }Public ReadWrite Property AllowDrop As bool// This API is not available in Javascript.

<uiElement AllowDrop="bool"/>

Remarks

The value of AllowDrop determines whether various events related to being a drop target or responding to being dragged over can be handled. Such events only can be handled if AllowDrop is true on the UIElement that is a potential drop target. These events are:

• DragEnter
• DragLeave
• DragOver
• Drop Each of the listed events is a routed event. If you want to handle a bubbling drag-drop event, the potential drop target must have AllowDrop set to true, and the object where the event is handled must have AllowDrop set to true. For more info on routed event concepts, see Events and routed events overview.

The Windows Runtime implementation of drag-drop concepts permits only certain controls and input actions to initiate a drag-drop action. There is no generalized DoDragDrop method that would permit any UI element to initiate a drag-drop action. The main source of a drag-drop action in an app is when you drag the items of a list such as GridView. However once the action is initiated, any UIElement in the app can potentially be a drop target so long as AllowDrop is true on that element. Any elements that the drag-drop action passes over can handle DragEnter, DragLeave or DragOver. The initiating list view does not require AllowDrop. Instead, the value of CanDragItems is used to determine whether the items in the list can be used to start a drag-drop action.

A UI element can't be a drop target for any drag-drop action that begins from outside the current Windows Store app. This includes actions that come from another Windows Store app, which is possible for a snapped view.

See Also

Drag and drop sample (Windows 10)

Identifies the AllowDrop dependency property.

public : static DependencyProperty AllowDropProperty { get; }public static DependencyProperty AllowDropProperty { get; }Public Static ReadOnly Property AllowDropProperty As DependencyProperty// This API is not available in Javascript.

Gets or sets a value that indicates that rendered content should be cached as a composited bitmap when possible.

public : CacheMode CacheMode { get; set; }public CacheMode CacheMode { get; set; }Public ReadWrite Property CacheMode As CacheMode// This API is not available in Javascript.

<uiElement CacheMode="BitmapCache" />

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.

If setting CacheMode in code, set it to a new value of BitmapCache, like this:

canvas1.CacheMode = new BitmapCache(); //canvas1 is an existing named element in UI

canvas1->CacheMode = ref new BitmapCache(); //canvas1 is an existing named element in UI

Do not generally apply CacheMode values to elements without testing and profiling first. Caching to the graphics processing unit (GPU) is intended only for a minority of possible rendering situations for an app, and it's expected that you will profile various combinations of when and where in your UI to apply a CacheMode setting. Overuse of CacheMode can hurt performance rather than help it. It’s best to profile the app surface area to determine which targeted areas are most expensive to render, and to experiment with caching only certain elements based on those results. For more info on how to profile for rendering, see IsOverdrawHeatMapEnabled and "Cache static content" section of the Optimize your XAML markup topic.

Avoid using CacheMode and storyboarded animations together. Caching content where Opacity or RenderTransform are animated causes the animations to become dependent animations, even if the animation is zero-duration. To even see those animations run you'd have to set EnableDependentAnimation to true, and a dependent animation usually invalidates all the performance gains you might get from caching the composition. Opacity often is animated by visual states in control templates, so this is a consideration even if you aren't declaring any of your own storyboarded animations in XAML pages.

See Also

Optimize your XAML markup

Storyboarded animations

Identifies the CacheMode dependency property.

public : static DependencyProperty CacheModeProperty { get; }public static DependencyProperty CacheModeProperty { get; }Public Static ReadOnly Property CacheModeProperty As DependencyProperty// This API is not available in Javascript.

Gets or sets a value that indicates whether the element can be dragged as data in a drag-and-drop operation.

public : PlatForm::Boolean CanDrag { get; set; }public bool CanDrag { get; set; }Public ReadWrite Property CanDrag As bool// This API is not available in Javascript.

Remarks

Identifies the CanDrag dependency property.

public : static DependencyProperty CanDragProperty { get; }public static DependencyProperty CanDragProperty { get; }Public Static ReadOnly Property CanDragProperty As DependencyProperty// This API is not available in Javascript.

Gets the identifier for the CharacterReceived routed event.

public : static RoutedEvent CharacterReceivedEvent { get; }public static RoutedEvent CharacterReceivedEvent { get; }Public Static ReadOnly Property CharacterReceivedEvent As RoutedEvent// This API is not available in Javascript.

Device family	Windows 10 Fall Creators Update (introduced v10.0.16299.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v5)

Gets or sets the RectangleGeometry used to define the outline of the contents of a UIElement.

public : RectangleGeometry Clip { get; set; }public RectangleGeometry Clip { get; set; }Public ReadWrite Property Clip As RectangleGeometry// This API is not available in Javascript.

<uiElement>
  <uiElement.Clip>
    rectangleGeometry
  </uiElement.Clip>
</uiElement>

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>

Remarks

The clipping geometry for UIElement.Clip in the Windows Runtime API must be a RectangleGeometry. You can't specify a non-rectangular geometry, as is permitted in some XAML frameworks like Microsoft Silverlight.

The clipped area is the "outside" of the geometry. In other words, the content that is shown (not clipped) is the area of the rectangle that is drawn with Fill if the geometry were used as data for a Path rather than for clipping. The clipped area is any area that falls outside the rectangle. The clipped area isn't hit-testable.

Identifies the Clip dependency property.

public : static DependencyProperty ClipProperty { get; }public static DependencyProperty ClipProperty { get; }Public Static ReadOnly Property ClipProperty As DependencyProperty// This API is not available in Javascript.

Gets or sets a property that declares alternate composition and blending modes for the element in its parent layout and window. This is relevant for elements that are involved in a mixed XAML / Microsoft DirectX UI.

public : ElementCompositeMode CompositeMode { get; set; }public ElementCompositeMode CompositeMode { get; set; }Public ReadWrite Property CompositeMode As ElementCompositeMode// This API is not available in Javascript.

<uiElement CompositeMode="elementCompositeModeMemberName" />

Remarks

If left unset, the default value of CompositeMode is ElementCompositeMode.Inherits. This means that the composite mode inherits from successive parents in the visual tree. However, at the root of a XAML visual tree is a final object representing the hWnd that is not typically represented in user code, and its effective CompositeMode behavior is SourceOver. Therefore, unless some element in the chain is specifically set to MinBlend, the render behavior of XAML elements all inherit to use SourceOver as inherited from the parent window.

Setting CompositeMode to MinBlend is useful for a mixed XAML / Microsoft DirectX UI because it is information used by the Direct Composition layer when it combines the UI sources. The MinBlend behavior can be better for situations such as text overlays.

Setting a value of MinBlend is typically most relevant for a SwapChainPanel element, so that the hosted content gets this behavior. But for some scenarios such as text overlays it can also be set on specific UI elements such as Rectangle, Canvas and so on.

See Also

DirectX and XAML interop

Identifies the CompositeMode dependency property.

public : static DependencyProperty CompositeModeProperty { get; }public static DependencyProperty CompositeModeProperty { get; }Public Static ReadOnly Property CompositeModeProperty As DependencyProperty// This API is not available in Javascript.

Gets or sets the flyout associated with this element.

public : FlyoutBase ContextFlyout { get; set; }public FlyoutBase ContextFlyout { get; set; }Public ReadWrite Property ContextFlyout As FlyoutBase// This API is not available in Javascript.

Device family	Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v3)

Identifies for the ContextFlyout dependency property.

public : static DependencyProperty ContextFlyoutProperty { get; }public static DependencyProperty ContextFlyoutProperty { get; }Public Static ReadOnly Property ContextFlyoutProperty As DependencyProperty// This API is not available in Javascript.

Device family	Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v3)

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

public : Size DesiredSize { get; }public Size DesiredSize { get; }Public ReadOnly Property DesiredSize As Size// This API is not available in Javascript.

Examples

This example queries DesiredSize as part of the child iteration for an ArrangeOverride implementation.

// Second arrange all children and return final size of panel
protected override Size ArrangeOverride(Size finalSize)
{
    // Get the collection of children
    UIElementCollection mychildren = Children;

    // Get total number of children
    int count = mychildren.Count;

    // Arrange children
    // We're only allowing 9 children in this panel.  More children will get a 0x0 layout slot.
    int i;
    for (i = 0; i < 9; i++)
    {

        // Get (left, top) origin point for the element in the 3x3 block
        Point cellOrigin = GetOrigin(i, 3, new Size(100, 100));

        // Arrange child
        // Get desired height and width. This will not be larger than 100x100 as set in MeasureOverride.
        double dw = mychildren[i].DesiredSize.Width;
        double dh = mychildren[i].DesiredSize.Height;

        mychildren[i].Arrange(new Rect(cellOrigin.X, cellOrigin.Y, dw, dh));

    }

    // Give the remaining children a 0x0 layout slot
    for (i = 9; i < count; i++)
    {
        mychildren[i].Arrange(new Rect(0, 0, 0, 0));
    }


    // Return final size of the panel
    return new Size(300, 300);
}

'Second arrange all children and return final size of panel 
Protected Overrides Function ArrangeOverride(ByVal finalSize As Size) As Size
    'Get the collection of children 
    Dim mychildren As UIElementCollection = Children
    'Get total number of children 
    Dim count As Integer = mychildren.Count
    'Arrange children 
    'only allowing 9 children in this panel. More children will get a 0x0 layout slot. 
    Dim i As Integer
    For i = 0 To 8
        'Get (left, top) origin point for the element in the 3x3 block 
        Dim cellOrigin As Point = GetOrigin(i, 3, New Size(100, 100))
        'Arrange child 
        'Get desired height and width. This will not be larger than 100x100 as set in MeasureOverride. 
        Dim dw As Double = mychildren(i).DesiredSize.Width
        Dim dh As Double = mychildren(i).DesiredSize.Height
        mychildren(i).Arrange(New Rect(cellOrigin.X, cellOrigin.Y, dw, dh))
    Next
    For i = 9 To count - 1
        'Give the remaining children a 0x0 layout slot 
        mychildren(i).Arrange(New Rect(0, 0, 0, 0))
    Next
    'Return final size of the panel 
    Return New Size(300, 300)
End Function
'Calculate point origin of the Block you are in 
Protected Function GetOrigin(ByVal blockNum As Integer, ByVal blocksPerRow As Integer, ByVal itemSize As Size) As Point
    'Get row number (zero-based) 
    Dim row As Integer = CInt(Math.Floor(blockNum / blocksPerRow))
    'Get column number (zero-based) 
    Dim column As Integer = blockNum - blocksPerRow * row
    'Calculate origin 
    Dim origin As New Point(itemSize.Width * column, itemSize.Height * row)
    Return origin
End Function

Remarks

DesiredSize is typically checked as one of the measurement factors when you implement layout behavior overrides such as ArrangeOverride or MeasureOverride. Depending on the parent container's layout logic, DesiredSize might be fully respected, constraints on DesiredSize might be applied, and such constraints might also change other characteristics of either the parent element or child element. For example, a control that supports scrollable regions (but chooses not to derive from the controls that already enable scrollable regions) could compare available size to DesiredSize. The control could then set an internal state that enabled scrollbars in the UI for that control. Or, DesiredSize could be ignored and the element always gets a layout that is sized by other considerations such as checking attached property values.

DesiredSize won't contain a useful value unless at least one "Measure" pass of layout has run on the element.

DesiredSize is really only intended for use when you define your own layout override methods. If you're just interested in the size of an element in your app's UI at run time, then you should use the ActualWidth and ActualHeight properties instead. You might be checking size this way if an element is influenced by dynamic layout techniques such as star sizing of Grid cells. Rely on ActualWidth and ActualHeight values only in situations that are sure to be after layout has run: for example, in Loaded events, or triggered by user actions that are only possible after the UI has been rendered initially.

See Also

Arrange(Rect)Arrange(Rect)Arrange(Rect)Arrange(Rect)

Measure(Size)Measure(Size)Measure(Size)Measure(Size)

Gets the identifier for the DoubleTapped routed event.

public : static RoutedEvent DoubleTappedEvent { get; }public static RoutedEvent DoubleTappedEvent { get; }Public Static ReadOnly Property DoubleTappedEvent As RoutedEvent// This API is not available in Javascript.

See Also

AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)

Events and routed events overview

Gets the identifier for the DragEnter routed event.

public : static RoutedEvent DragEnterEvent { get; }public static RoutedEvent DragEnterEvent { get; }Public Static ReadOnly Property DragEnterEvent As RoutedEvent// This API is not available in Javascript.

See Also

AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)

Events and routed events overview

Gets the identifier for the DragLeave routed event.

public : static RoutedEvent DragLeaveEvent { get; }public static RoutedEvent DragLeaveEvent { get; }Public Static ReadOnly Property DragLeaveEvent As RoutedEvent// This API is not available in Javascript.

See Also

AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)

Events and routed events overview

Gets the identifier for the DragOver routed event.

public : static RoutedEvent DragOverEvent { get; }public static RoutedEvent DragOverEvent { get; }Public Static ReadOnly Property DragOverEvent As RoutedEvent// This API is not available in Javascript.

See Also

AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)

Events and routed events overview

Gets the identifier for the Drop routed event.

public : static RoutedEvent DropEvent { get; }public static RoutedEvent DropEvent { get; }Public Static ReadOnly Property DropEvent As RoutedEvent// This API is not available in Javascript.

See Also

AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)

Events and routed events overview

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

public : PlatForm::Boolean ExitDisplayModeOnAccessKeyInvoked { get; set; }public bool ExitDisplayModeOnAccessKeyInvoked { get; set; }Public ReadWrite Property ExitDisplayModeOnAccessKeyInvoked As bool// This API is not available in Javascript.

Device family	Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v3)

Identifies the ExitDisplayModeOnAccessKeyInvoked dependency property.

public : static DependencyProperty ExitDisplayModeOnAccessKeyInvokedProperty { get; }public static DependencyProperty ExitDisplayModeOnAccessKeyInvokedProperty { get; }Public Static ReadOnly Property ExitDisplayModeOnAccessKeyInvokedProperty As DependencyProperty// This API is not available in Javascript.

Device family	Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v3)

Gets the identifier for the GettingFocus routed event.

public : static RoutedEvent GettingFocusEvent { get; }public static RoutedEvent GettingFocusEvent { get; }Public Static ReadOnly Property GettingFocusEvent As RoutedEvent// This API is not available in Javascript.

Device family	Windows 10 Creators Update (introduced v10.0.15063.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v4)

See Also

AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)

Events and routed events overview

Gets or sets a value that indicates whether the framework automatically adjusts the element's visual properties when high contrast themes are enabled.

public : ElementHighContrastAdjustment HighContrastAdjustment { get; set; }public ElementHighContrastAdjustment HighContrastAdjustment { get; set; }Public ReadWrite Property HighContrastAdjustment As ElementHighContrastAdjustment// This API is not available in Javascript.

Device family	Windows 10 Creators Update (introduced v10.0.15063.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v4)

Remarks

The value of the property is inherited. When set to Application the adjustment will mirror what is set for the Application 's HighContrastAdjustment property. Setting the Application 's HighContrastAdjustment property to None will effectively disable it for all UI in the application. It can be selectively enabled for a UIElement by explicitly setting the value to Auto.
When set to Auto, the framework automatically applies the following adjustments to XAML's text elements while a high contrast theme is enabled:

• The foreground color on text is ignored. The text is colored using either the system’s high contrast text color or the disabled color when in a parent Control where IsEnabled = "False".
• An opaque rectangle is rendered immediately behind the text to enforce a high contrast ratio.
• Non-zero values for Opacity are ignored. The element and it's children will appear as if they had an opacity of 1.0.

It is possible to set HighContrastAdjustment = None on a UIElement and then have HighContrastAdjustment = Auto on one of its descendants. However, the framework does not guarantee that the descendent will be fully opaque if an opacity is applied on any of its ancestors.

Identifies the HighContrastAdjustment dependency property.

public : static DependencyProperty HighContrastAdjustmentProperty { get; }public static DependencyProperty HighContrastAdjustmentProperty { get; }Public Static ReadOnly Property HighContrastAdjustmentProperty As DependencyProperty// This API is not available in Javascript.

Device family	Windows 10 Creators Update (introduced v10.0.15063.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v4)

Gets the identifier for the Holding routed event.

public : static RoutedEvent HoldingEvent { get; }public static RoutedEvent HoldingEvent { get; }Public Static ReadOnly Property HoldingEvent As RoutedEvent// This API is not available in Javascript.

See Also

AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)

Events and routed events overview

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

public : PlatForm::Boolean IsAccessKeyScope { get; set; }public bool IsAccessKeyScope { get; set; }Public ReadWrite Property IsAccessKeyScope As bool// This API is not available in Javascript.

Device family	Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v3)

Identifies for the IsAccessKeyScope dependency property.

public : static DependencyProperty IsAccessKeyScopeProperty { get; }public static DependencyProperty IsAccessKeyScopeProperty { get; }Public Static ReadOnly Property IsAccessKeyScopeProperty As DependencyProperty// This API is not available in Javascript.

Device family	Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v3)

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

public : PlatForm::Boolean IsDoubleTapEnabled { get; set; }public bool IsDoubleTapEnabled { get; set; }Public ReadWrite Property IsDoubleTapEnabled As bool// This API is not available in Javascript.

<uiElement IsDoubleTapEnabled="bool" />

Remarks

The default is true (event enabled). If you set to false, the UIElement will no longer source the DoubleTapped event. This might be desirable if a parent element such as a list control should instead process the action as a manipulation, or if you want to specify that only some child items emit a DoubleTapped event that a parent handles after bubbling.

Another reason to suppress gesture events is if you are handling pointer-level events and don't want gesture recognition logic to impact how the pointer events are fired. For example, if the gesture recognition engine has to test for Tapped, then it must delay firing a PointerMoved event for small movements, because the user might lift the touch point soon and the input event would normally be gesture-recognized as a tap.

See Also

DoubleTappedDoubleTappedDoubleTappedDoubleTapped

Quickstart: Touch input

Identifies the IsDoubleTapEnabled dependency property.

public : static DependencyProperty IsDoubleTapEnabledProperty { get; }public static DependencyProperty IsDoubleTapEnabledProperty { get; }Public Static ReadOnly Property IsDoubleTapEnabledProperty As DependencyProperty// This API is not available in Javascript.

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

public : PlatForm::Boolean IsHitTestVisible { get; set; }public bool IsHitTestVisible { get; set; }Public ReadWrite Property IsHitTestVisible As bool// This API is not available in Javascript.

<uiElement IsHitTestVisible="bool"/>

Identifies the IsHitTestVisible dependency property.

public : static DependencyProperty IsHitTestVisibleProperty { get; }public static DependencyProperty IsHitTestVisibleProperty { get; }Public Static ReadOnly Property IsHitTestVisibleProperty As DependencyProperty// This API is not available in Javascript.

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

public : PlatForm::Boolean IsHoldingEnabled { get; set; }public bool IsHoldingEnabled { get; set; }Public ReadWrite Property IsHoldingEnabled As bool// This API is not available in Javascript.

<uiElement IsHoldingEnabled="bool" />

Remarks

The default is true (event enabled). If you set to false, the UIElement will no longer source the Holding event. This might be desirable if a parent element such as a list control should instead process the action as a manipulation, or if you want to specify that only some child items emit a Holding event that a parent handles after bubbling.

Another reason to suppress gesture events is if you are handling pointer-level events and don't want gesture recognition logic to impact how the pointer events are fired. For example, if the gesture recognition engine has to test for Tapped, then it must delay firing a PointerMoved event for small movements, because the user might lift the touch point soon and the input event would normally be gesture-recognized as a tap. Also, Holding states might interfere with other pointer events, or generate theme animations, because of the progression through the Holding states that must be reported by gesture recognition.

See Also

HoldingHoldingHoldingHolding

Quickstart: Touch input

Identifies the IsHoldingEnabled dependency property.

public : static DependencyProperty IsHoldingEnabledProperty { get; }public static DependencyProperty IsHoldingEnabledProperty { get; }Public Static ReadOnly Property IsHoldingEnabledProperty As DependencyProperty// This API is not available in Javascript.

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

public : PlatForm::Boolean IsRightTapEnabled { get; set; }public bool IsRightTapEnabled { get; set; }Public ReadWrite Property IsRightTapEnabled As bool// This API is not available in Javascript.

<uiElement IsRightTapEnabled="bool" />

Remarks

The default is true (event enabled). If you set to false, the UIElement will no longer source the RightTapped event. This might be desirable if a parent element such as a list control should instead process the action as a manipulation, or if you want to specify that only some child items emit a RightTapped event that a parent handles after bubbling.

Another reason to suppress gesture events is if you are handling pointer-level events and don't want gesture recognition logic to impact how the pointer events are fired. For example, if the gesture recognition engine has to test for Tapped, then it must delay firing a PointerMoved event for small movements, because the user might lift the touch point soon and the input event would normally be gesture-recognized as a tap.

You do not need a mouse device to produce a RightTapped event. A RightTapped event is generated if a touch event becomes a Holding event when the touch position remained in one place. Even though Holding and RightTapped might result from the same user touch action, the design guidance for what that event means to an app is different, as is the timing. For more info, see Quickstart: Touch input.

See Also

RightTappedRightTappedRightTappedRightTapped

Quickstart: Touch input

Identifies the IsRightTapEnabled dependency property.

public : static DependencyProperty IsRightTapEnabledProperty { get; }public static DependencyProperty IsRightTapEnabledProperty { get; }Public Static ReadOnly Property IsRightTapEnabledProperty As DependencyProperty// This API is not available in Javascript.

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

public : PlatForm::Boolean IsTapEnabled { get; set; }public bool IsTapEnabled { get; set; }Public ReadWrite Property IsTapEnabled As bool// This API is not available in Javascript.

<uiElementIsTapEnabled="bool" />

Remarks

The default is true (event enabled). If you set to false, the UIElement will no longer source the Tapped event. This might be desirable if a parent element such as a list control should instead process the action as a manipulation, or if you want to specify that only some child items emit a Tapped event that a parent handles after bubbling.

Another reason to suppress gesture events is if you are handling pointer-level events and don't want gesture recognition logic to impact how the pointer events are fired. For example, if the gesture recognition engine has to test for Tapped, then it must delay firing a PointerMoved event for small movements, because the user might lift the touch point soon and the input event would normally be gesture-recognized as a tap.

See Also

TappedTappedTappedTapped

Quickstart: Touch input

Handle pointer input

Identifies the IsTapEnabled dependency property.

public : static DependencyProperty IsTapEnabledProperty { get; }public static DependencyProperty IsTapEnabledProperty { get; }Public Static ReadOnly Property IsTapEnabledProperty As DependencyProperty// This API is not available in Javascript.

Gets the keyboard shortcuts (or accelerators) that lets a user perform an action using the keyboard instead of navigating the app UI (directly or through access keys).

Accelerators are typically assigned to buttons or menu items.

public : IVector<KeyboardAccelerator> KeyboardAccelerators { get; }public IList<KeyboardAccelerator> KeyboardAccelerators { get; }Public ReadOnly Property KeyboardAccelerators As IList<KeyboardAccelerator>// This API is not available in Javascript.

Device family	Windows 10 Fall Creators Update (introduced v10.0.16299.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v5)

Remarks

An accelerator key can be a single key, such as F1 - F12 and Esc, or a combination of keys (Ctrl + Shift + B, or Ctrl C) that invoke a command. They differ from access keys (mnemonics), which are typically modified with the Alt key and simply activate a command or control.

An accelerator can be executed even if the element associated with the accelerator is not visible. For example, an item in the SecondaryCommands collection of the CommandBar can be invoked using an accelerator without expanding the overflow menu and displaying the element.

By default, an accelerator has global scope. However, you can constrain scope using ScopeOwner or disable an accelerator completely using IsEnabled.

Gets the identifier for the KeyDown routed event.

public : static RoutedEvent KeyDownEvent { get; }public static RoutedEvent KeyDownEvent { get; }Public Static ReadOnly Property KeyDownEvent As RoutedEvent// This API is not available in Javascript.

See Also

AddHandler

Events and routed events overview

Gets or sets a value that indicates how far left or right the keytip is placed in relation to the UIElement.

public : double KeyTipHorizontalOffset { get; set; }public double KeyTipHorizontalOffset { get; set; }Public ReadWrite Property KeyTipHorizontalOffset As double// This API is not available in Javascript.

<uiElement KeyTipHorizontalOffset="double"/>

Device family	Windows 10 Creators Update (introduced v10.0.15063.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v4)

Identifies the KeyTipHorizontalOffset dependency property.

public : static DependencyProperty KeyTipHorizontalOffsetProperty { get; }public static DependencyProperty KeyTipHorizontalOffsetProperty { get; }Public Static ReadOnly Property KeyTipHorizontalOffsetProperty As DependencyProperty// This API is not available in Javascript.

Device family	Windows 10 Creators Update (introduced v10.0.15063.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v4)

Gets or sets a value that indicates where the KeyTip is placed in relation to the UIElement.

public : KeyTipPlacementMode KeyTipPlacementMode { get; set; }public KeyTipPlacementMode KeyTipPlacementMode { get; set; }Public ReadWrite Property KeyTipPlacementMode As KeyTipPlacementMode// This API is not available in Javascript.

<uiElement KeyTipPlacementMode="keyTipPlacementModeMemberName"/>

Device family	Windows 10 Creators Update (introduced v10.0.15063.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v4)

Identifies the KeyTipPlacementMode dependency property.

public : static DependencyProperty KeyTipPlacementModeProperty { get; }public static DependencyProperty KeyTipPlacementModeProperty { get; }Public Static ReadOnly Property KeyTipPlacementModeProperty As DependencyProperty// This API is not available in Javascript.

Device family	Windows 10 Creators Update (introduced v10.0.15063.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v4)

Gets or sets a value that indicates how far up or down the keytip is placed in relation to the UIElement.

public : double KeyTipVerticalOffset { get; set; }public double KeyTipVerticalOffset { get; set; }Public ReadWrite Property KeyTipVerticalOffset As double// This API is not available in Javascript.

<uiElement KeyTipVerticalOffset="double"/>

Device family	Windows 10 Creators Update (introduced v10.0.15063.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v4)

Identifies the KeyTipVerticalOffset dependency property.

public : static DependencyProperty KeyTipVerticalOffsetProperty { get; }public static DependencyProperty KeyTipVerticalOffsetProperty { get; }Public Static ReadOnly Property KeyTipVerticalOffsetProperty As DependencyProperty// This API is not available in Javascript.

Device family	Windows 10 Creators Update (introduced v10.0.15063.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v4)

Gets the identifier for the KeyUp routed event.

public : static RoutedEvent KeyUpEvent { get; }public static RoutedEvent KeyUpEvent { get; }Public Static ReadOnly Property KeyUpEvent As RoutedEvent// This API is not available in Javascript.

See Also

AddHandler

Events and routed events overview

Gets the collection of XamlLight objects attached to this element.

public : IVector<XamlLight> Lights { get; }public IList<XamlLight> Lights { get; }Public ReadOnly Property Lights As IList<XamlLight>// This API is not available in Javascript.

<uielement>
  <uielement.Lights>
    oneOrMoreXamlLights
  </uielement.Lights>
</uielement>

Device family	Windows 10 Creators Update (introduced v10.0.15063.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v4)

Identifies the Lights dependency property.

public : static DependencyProperty LightsProperty { get; }public static DependencyProperty LightsProperty { get; }Public Static ReadOnly Property LightsProperty As DependencyProperty// This API is not available in Javascript.

Device family	Windows 10 Creators Update (introduced v10.0.15063.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v4)

Gets the identifier for the LosingFocus routed event.

public : static RoutedEvent LosingFocusEvent { get; }public static RoutedEvent LosingFocusEvent { get; }Public Static ReadOnly Property LosingFocusEvent As RoutedEvent// This API is not available in Javascript.

Device family	Windows 10 Creators Update (introduced v10.0.15063.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v4)

See Also

AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)

Events and routed events overview

Gets the identifier for the ManipulationCompleted routed event.

public : static RoutedEvent ManipulationCompletedEvent { get; }public static RoutedEvent ManipulationCompletedEvent { get; }Public Static ReadOnly Property ManipulationCompletedEvent As RoutedEvent// This API is not available in Javascript.

See Also

AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)

Events and routed events overview

Gets the identifier for the ManipulationDelta routed event.

public : static RoutedEvent ManipulationDeltaEvent { get; }public static RoutedEvent ManipulationDeltaEvent { get; }Public Static ReadOnly Property ManipulationDeltaEvent As RoutedEvent// This API is not available in Javascript.

See Also

AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)

Events and routed events overview

Gets the identifier for the ManipulationInertiaStarting routed event.

public : static RoutedEvent ManipulationInertiaStartingEvent { get; }public static RoutedEvent ManipulationInertiaStartingEvent { get; }Public Static ReadOnly Property ManipulationInertiaStartingEvent As RoutedEvent// This API is not available in Javascript.

See Also

AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)

Events and routed events overview

Gets or sets the ManipulationModes value used for UIElement behavior and interaction with gestures. Setting this value enables handling the manipulation events from this element in app code.

public : ManipulationModes ManipulationMode { get; set; }public ManipulationModes ManipulationMode { get; set; }Public ReadWrite Property ManipulationMode As ManipulationModes// This API is not available in Javascript.

<uiElement ManipulationMode="All"/>
-or-
<uiElement ManipulationMode="None"/>
-or-
<uiElement ManipulationMode="singleManipulationModesMemberName"/>
-or-
<uiElement ManipulationMode="relatedManipulationModesNames"/>

Remarks

You must set the ManipulationMode to a value other than System or None if you want to handle manipulation events such as ManipulationStarted from UI elements in your app code. For more info on manipulations, see Quickstart: Touch input.

The typical default value of ManipulationMode is System rather than None. When the value is System, manipulations that originate from the element can be handled by the Windows Runtime infrastructure, which is based on the Direct Manipulation API. For example, ScrollViewer handles user manipulations in its control logic and processes them as scrolling actions for the control. The System value also enables personality animations that respond to manipulation events.

Slider and ToggleSwitch have default templates that set the ManipulationMode value to None, so None will be the default value you see at design time.

Specifying related manipulation modes

You can specify more than one of the flagwise ManipulationModes values as the value of the ManipulationMode property. This is possible in XAML using the comma syntax shown in the "XAML Values" section. For example, you can combine TranslateX, TranslateY, Rotate, and Scale, or any combination of these. However, not all combinations are valid. Validity is enforced only once ManipulationModes is used by a specific control, so issues with setting an invalid combination of ManipulationModes might not appear until run-time when values are applied.

• Don't combine Translate* values with TranslateRails* values, these are treated as mutually exclusive values.
• Don't combine the inertial values with the non-inertial values.
• The All value isn't the true additive value of all the flags (if values are compared bitwise). A value of All doesn't necessarily indicate that the combination of all the values is valid either, or that any specific value is set.

Windows 8 behavior

On Windows 8, setting ManipulationMode to a value that combines System with any other value will throw an exception, so some of the combinations mentioned above won't work for Windows 8. Starting with Windows 8.1, you can combine System with other values.

Apps that were compiled for Windows 8 but running on Windows 8.1 use the new behavior and permit combining System with other values.

See Also

ManipulationStartedManipulationStartedManipulationStartedManipulationStarted

ManipulationDeltaManipulationDeltaManipulationDeltaManipulationDelta

ManipulationCompletedManipulationCompletedManipulationCompletedManipulationCompleted

ManipulationModesManipulationModesManipulationModesManipulationModes

Quickstart: Touch input

Direct Manipulation Reference

Basic input sample (Windows 10)

Identifies the ManipulationMode dependency property.

public : static DependencyProperty ManipulationModeProperty { get; }public static DependencyProperty ManipulationModeProperty { get; }Public Static ReadOnly Property ManipulationModeProperty As DependencyProperty// This API is not available in Javascript.

Gets the identifier for the ManipulationStarted routed event.

public : static RoutedEvent ManipulationStartedEvent { get; }public static RoutedEvent ManipulationStartedEvent { get; }Public Static ReadOnly Property ManipulationStartedEvent As RoutedEvent// This API is not available in Javascript.

See Also

AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)

Events and routed events overview

Gets the identifier for the ManipulationStarting routed event.

public : static RoutedEvent ManipulationStartingEvent { get; }public static RoutedEvent ManipulationStartingEvent { get; }Public Static ReadOnly Property ManipulationStartingEvent As RoutedEvent// This API is not available in Javascript.

See Also

AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)

Events and routed events overview

Gets the identifier for the NoFocusCandidateFound routed event.

public : static RoutedEvent NoFocusCandidateFoundEvent { get; }public static RoutedEvent NoFocusCandidateFoundEvent { get; }Public Static ReadOnly Property NoFocusCandidateFoundEvent As RoutedEvent// This API is not available in Javascript.

Device family	Windows 10 Creators Update (introduced v10.0.15063.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v4)

See Also

AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)

Events and routed events overview

Gets or sets the degree of the object's opacity.

public : double Opacity { get; set; }public double Opacity { get; set; }Public ReadWrite Property Opacity As double// This API is not available in Javascript.

<uiElement Opacity="double" .../>

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

Remarks

When Opacity is set on objects that are nested, the effective opacity for rendering is the product of all applicable opacity factors. For example, if an object that has Opacity=0.5 is contained in a Canvas that is also Opacity=0.5, the effective Opacity value for rendering is 0.25. Opacity values greater than 1.0 are treated as 1.0 when the value is used, although obtaining the property value will still give you the original greater-than-one value. Opacity values set as less than 0 are treated as 0 when the value is used. In the factoring logic, setting an Opacity to 2 to cancel out the effects of being contained by an object with 0.5 Opacity does not work; the 2 value is treated as 1.0 even before the nested-object factoring is calculated.

Opacity is a property that's sometimes animated in visual state storyboards, with zero duration. For example, the focus rectangle for "FocusStates" visual states is set with Opacity="0" in the original control template, because you don't want this rectangle to appear in a default non-focused states. But the visual states define a zero-duration "Focused" state that sets Opacity to 1 when the control using these templates and states has detected that it's keyboard-focused. For more info on this usage of Opacity, see Storyboarded animations for visual states.

Opacity and hit-testing

An Opacity value of 0 does not exclude an object from hit testing. This behavior can be useful for creating imagemap-style overlays that are drawn on top of the rest of the UI. For example, you can use a Canvas that has two children: a Rectangle that has a Height, a Width and an Opacity of 0, and the layout root of the rest of the UI that should draw underneath. By default children of a Canvas draw on top of each other in the same absolute coordinate system. Make sure that the ZIndex value of the Rectangle is higher than the other element's ZIndex (or declare the Rectangle after the other element in XAML element order to get the same result.) Wire your hit-testing logic (combines PointerRoutedEventArgs.GetCurrentPoint and VisualTreeHelper.FindElementsInHostCoordinates ) to the PointerPressed event for the Rectangle.

Alternatively, in order to exclude an object from hit testing, you should set IsHitTestVisible to false, rather than using Opacity.

See Also

Events and routed events overview

Identifies the IsHitTestVisible dependency property.

public : static DependencyProperty OpacityProperty { get; }public static DependencyProperty OpacityProperty { get; }Public Static ReadOnly Property OpacityProperty As DependencyProperty// This API is not available in Javascript.

Gets the identifier for the PointerCanceled routed event.

public : static RoutedEvent PointerCanceledEvent { get; }public static RoutedEvent PointerCanceledEvent { get; }Public Static ReadOnly Property PointerCanceledEvent As RoutedEvent// This API is not available in Javascript.

See Also

AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)

Events and routed events overview

Gets the identifier for the PointerCaptureLost routed event.

public : static RoutedEvent PointerCaptureLostEvent { get; }public static RoutedEvent PointerCaptureLostEvent { get; }Public Static ReadOnly Property PointerCaptureLostEvent As RoutedEvent// This API is not available in Javascript.

See Also

AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)

Events and routed events overview

Gets the set of all captured pointers, represented as Pointer values.

public : IVectorView<Pointer> PointerCaptures { get; }public IReadOnlyList<Pointer> PointerCaptures { get; }Public ReadOnly Property PointerCaptures As IReadOnlyList<Pointer>// This API is not available in Javascript.

Remarks

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

Because there are input scenarios such as manipulations that involve more than one pointer point, the Windows Runtime enables capturing more than one pointer at a time. The PointerCaptures property exposes a view of which pointer points are currently captured by the UIElement.

This property's value is calculated based on the results of other actions. Calling CapturePointer adds to the internal collection that PointerCaptures provides a read-only view of. Calling ReleasePointerCapture removes from the collection. ReleasePointerCaptures clears the collection. User action that invalidates pointer capture such as releasing from a pointer point also changes capture state and thus the collection. For more info, see Mouse interactions and Handle pointer input.

The collection is not necessarily indexed by PointerId. To find a specific PointerId, you must check the items in the collection and reference a specific Pointer.

See Also

CapturePointer(Pointer)CapturePointer(Pointer)CapturePointer(Pointer)CapturePointer(Pointer)

PointerCapturesPointerCapturesPointerCapturesPointerCaptures

PointerPointerPointerPointer

Handle pointer input

Identifies the PointerCaptures dependency property.

public : static DependencyProperty PointerCapturesProperty { get; }public static DependencyProperty PointerCapturesProperty { get; }Public Static ReadOnly Property PointerCapturesProperty As DependencyProperty// This API is not available in Javascript.

Gets the identifier for the PointerEntered routed event.

public : static RoutedEvent PointerEnteredEvent { get; }public static RoutedEvent PointerEnteredEvent { get; }Public Static ReadOnly Property PointerEnteredEvent As RoutedEvent// This API is not available in Javascript.

See Also

AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)

Events and routed events overview

Gets the identifier for the PointerExited routed event.

public : static RoutedEvent PointerExitedEvent { get; }public static RoutedEvent PointerExitedEvent { get; }Public Static ReadOnly Property PointerExitedEvent As RoutedEvent// This API is not available in Javascript.

See Also

AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)

Events and routed events overview

Gets the identifier for the PointerMoved routed event.

public : static RoutedEvent PointerMovedEvent { get; }public static RoutedEvent PointerMovedEvent { get; }Public Static ReadOnly Property PointerMovedEvent As RoutedEvent// This API is not available in Javascript.

See Also

AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)

Events and routed events overview

Gets the identifier for the PointerPressed routed event.

public : static RoutedEvent PointerPressedEvent { get; }public static RoutedEvent PointerPressedEvent { get; }Public Static ReadOnly Property PointerPressedEvent As RoutedEvent// This API is not available in Javascript.

See Also

AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)

Events and routed events overview

Gets the identifier for the PointerReleased routed event.

public : static RoutedEvent PointerReleasedEvent { get; }public static RoutedEvent PointerReleasedEvent { get; }Public Static ReadOnly Property PointerReleasedEvent As RoutedEvent// This API is not available in Javascript.

See Also

AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)

Events and routed events overview

Gets the identifier for the PointerWheelChanged routed event.

public : static RoutedEvent PointerWheelChangedEvent { get; }public static RoutedEvent PointerWheelChangedEvent { get; }Public Static ReadOnly Property PointerWheelChangedEvent As RoutedEvent// This API is not available in Javascript.

See Also

AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)

Events and routed events overview

Gets the identifier for the PreviewKeyDown routed event.

public : static RoutedEvent PreviewKeyDownEvent { get; }public static RoutedEvent PreviewKeyDownEvent { get; }Public Static ReadOnly Property PreviewKeyDownEvent As RoutedEvent// This API is not available in Javascript.

Device family	Windows 10 Fall Creators Update (introduced v10.0.16299.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v5)

See Also

AddHandler

Events and routed events overview

Gets the identifier for the PreviewKeyUp routed event.

public : static RoutedEvent PreviewKeyUpEvent { get; }public static RoutedEvent PreviewKeyUpEvent { get; }Public Static ReadOnly Property PreviewKeyUpEvent As RoutedEvent// This API is not available in Javascript.

Device family	Windows 10 Fall Creators Update (introduced v10.0.16299.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v5)

See Also

AddHandler

Events and routed events overview

Gets or sets the perspective projection (3-D effect) to apply when rendering this element.

public : Projection Projection { get; set; }public Projection Projection { get; set; }Public ReadWrite Property Projection As Projection// This API is not available in Javascript.

<uiElement>

  <uiElement.Projection>

    singleProjection

  </uiElement.Projection>

</uiElement>

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>

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.

See Also

3-D effects for using XAML

XAML two-dimensional transforms sample

Identifies the Projection dependency property.

public : static DependencyProperty ProjectionProperty { get; }public static DependencyProperty ProjectionProperty { get; }Public Static ReadOnly Property ProjectionProperty As DependencyProperty// This API is not available in Javascript.

Gets the final render size of a UIElement. Use is not recommended, see Remarks.

public : Size RenderSize { get; }public Size RenderSize { get; }Public ReadOnly Property RenderSize As Size// This API is not available in Javascript.

Remarks

RenderSize is not the property to use to obtain size information about a UI element for most scenarios, because in the current implementation it doesn't have a safe technique for knowing when the value is current. For general UI purposes, use ActualHeight and ActualWidth instead, and do so only at points in object lifetime where object layout is complete. Examples of safe timing for checking ActualHeight or ActualWidth are user input events or the Loaded event. Or you can handle SizeChanged, which has updated size information in its event data. For layout method override purposes (for example MeasureOverride ), use DesiredSize.

Gets or sets transform information that affects the rendering position of a UIElement.

public : Transform RenderTransform { get; set; }public Transform RenderTransform { get; set; }Public ReadWrite Property RenderTransform As Transform// This API is not available in Javascript.

<uiElement>
  <uiElement.RenderTransform>
    singleTransform
  </uiElement.RenderTransform>
</uiElement>

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>

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.

See Also

XAML two-dimensional transforms sample

Gets or sets the origin point of any possible render transform declared by RenderTransform, relative to the bounds of the UIElement.

public : Point RenderTransformOrigin { get; set; }public Point RenderTransformOrigin { get; set; }Public ReadWrite Property RenderTransformOrigin As Point// This API is not available in Javascript.

<uiElement RenderTransformOrigin="x,y"/>

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.

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

Remarks

RenderTransformOrigin enables you to create or change the effect of a transform on a particular element without having to alter the specifics of the RenderTransform transform. The Point value you specify for RenderTransformOrigin is not based on actual pixel measures. Instead, it is a logical point, where a value of 0,0 refers to the top left corner of the overall UIElement render area, and 1,1 refers to the bottom right. The value is then evaluated into an X,Y coordinate by factoring it into the current coordinate space of the UIElement.

For some transforms, the origin doesn't matter. For example the RenderTransformOrigin won't change the behavior of a TranslateTransform applied to the RenderTransform property.

Some transform types have their own properties for specifying the origin of the transform. For example, RotateTransform has CenterX and CenterY. When you're working with a UIElement, visual design tools sometimes hide these other properties so that you only use RenderTransformOrigin for all transform origin changes and leave transform-specific origins as the defaults. Tools might also apply all transform effects to a single CompositeTransform value for RenderTransform, rather than defining XAML elements for the specific transforms and making a TransformGroup. If you're writing your own XAML or defining transforms in code, you might consider following these same practices so that you always use RenderTransformOrigin rather than the transform-specific origin values if you're applying transforms for RenderTransform, otherwise the values will offset each other.

A common technique is to set RenderTransformOrigin to 0.5,0.5, which places the origin at the element center. You could then apply a RotateTransform to rotate the element around the center.

Changing FlowDirection to RightToLeft changes the meaning of the X coordinate of a RenderTransformOrigin for a UIElement; 0 will be the right edge.

Some of the same visual effects that you can produce with RenderTransform and RenderTransformOrigin can also be achieved with Projection and a PlaneProjection. For example, you can rotate a UIElement around its center by changing PlaneProjection.RotationZ.

See Also

3-D effects for using XAML

XAML two-dimensional transforms sample

Identifies the RenderTransformOrigin dependency property.

public : static DependencyProperty RenderTransformOriginProperty { get; }public static DependencyProperty RenderTransformOriginProperty { get; }Public Static ReadOnly Property RenderTransformOriginProperty As DependencyProperty// This API is not available in Javascript.

Identifies the RenderTransform dependency property.

public : static DependencyProperty RenderTransformProperty { get; }public static DependencyProperty RenderTransformProperty { get; }Public Static ReadOnly Property RenderTransformProperty As DependencyProperty// This API is not available in Javascript.

Gets the identifier for the RightTapped routed event.

public : static RoutedEvent RightTappedEvent { get; }public static RoutedEvent RightTappedEvent { get; }Public Static ReadOnly Property RightTappedEvent As RoutedEvent// This API is not available in Javascript.

See Also

AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)

Gets or sets a value that modifies how tabbing and TabIndex work for this control.

public : KeyboardNavigationMode TabFocusNavigation { get; set; }public KeyboardNavigationMode TabFocusNavigation { get; set; }Public ReadWrite Property TabFocusNavigation As KeyboardNavigationMode// This API is not available in Javascript.

<uiElement TabFocusNavigation="keyboardNavigationModeMemberName"/>

Device family	Windows 10 Creators Update (introduced v10.0.15063.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v4)

Remarks

Use this property instead of the Control.TabNavigation property for objects that do not use a ControlTemplate to define their appearance.

See Also

Keyboard interactions

Keyboard accessibility

Identifies the TabFocusNavigation dependency property.

public : static DependencyProperty TabFocusNavigationProperty { get; }public static DependencyProperty TabFocusNavigationProperty { get; }Public Static ReadOnly Property TabFocusNavigationProperty As DependencyProperty// This API is not available in Javascript.

Device family	Windows 10 Creators Update (introduced v10.0.15063.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v4)

Gets the identifier for the Tapped routed event.

public : static RoutedEvent TappedEvent { get; }public static RoutedEvent TappedEvent { get; }Public Static ReadOnly Property TappedEvent As RoutedEvent// This API is not available in Javascript.

See Also

AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)

Gets or sets the 3-D transform effect to apply when rendering this element.

public : Transform3D Transform3D { get; set; }public Transform3D Transform3D { get; set; }Public ReadWrite Property Transform3D As Transform3D// This API is not available in Javascript.

Remarks

Use the Transform3D property to apply a 3-D transform matrix to a XAML element. This lets you create effects where two-dimensional UI appears to exist in 3-D space relative to the user. Transform3D behaves much like RenderTransform, but allows transforms in three-dimensional space and not just two dimensions.

PerspectiveTransform3D and CompositeTransform3D

There are two subclasses of Transform3D that you can use to populate the Transform3D property. You should always use these subclasses together to create a 3-D scene. In very simple terms, you apply a PerspectiveTransform3D to the root element of your scene to provide a common viewport for all the elements in it. Then you apply a CompositeTransform3D to individual elements in the scene to rotate, scale, and move them in relation to the common viewport.

PerspectiveTransform3D represents a 3-D perspective transform matrix, and creates a frame of reference and viewport for a 3-D scene. Under a perspective effect, elements further away from the user appear to shrink towards a common vanishing point, as if they were actually viewed in three-dimensional space. Because the perspective effect should apply to all elements in a shared 3-D scene, it is usually applied at the root of 3-D content such as the Page element. The effect is inherited by children of this element. PerspectiveTransform3D preserves coordinates in the Z=0 plane, where UI elements reside by default. Therefore, PerspectiveTransform3D (inherited from the root element) affects the appearance of an element only if the element is also transformed by a CompositeTransform3D, which moves it out of the Z=0 plane.

CompositeTransform3D represents a group of affine 3-D transforms on an element, including rotation, scale and translation. This class is used to position elements in 3-D space.

Here's an example of using the Transform3D subclasses to achieve a 3-D effect for your UI:

<StackPanel Orientation="Horizontal">
    <StackPanel.Transform3D>
        <PerspectiveTransform3D />
    </StackPanel.Transform3D>

    <Rectangle Width="300" Height="200" Fill="CornflowerBlue" />

    <Rectangle Width="300" Height="200" Fill="CadetBlue" Margin="10">
        <Rectangle.Transform3D>
            <CompositeTransform3D RotationY="-30" TranslateZ="-75" CenterX="150" />
        </Rectangle.Transform3D>
    </Rectangle>

    <Rectangle Width="300" Height="200" Fill="OrangeRed">
        <Rectangle.Transform3D>
            <CompositeTransform3D TranslateZ="-150" />
        </Rectangle.Transform3D>
    </Rectangle>
</StackPanel>

In this example, a PerspectiveTransform3D is attached to the root StackPanel and provides a shared perspective viewport for the panel’s children.

• The Rectangle on the left has no transform, so it appears as normal.
• The Rectangle in the center is rotated -30 degrees about its central axis and translated back 75 pixels, causing its right edge to have a Z-coordinate of -150 pixels.
• The Rectangle on the right is translated back 150 pixels.

The edges of the three rectangles appear to be contiguous because they share a common perspective.

Animating CompositeTransform3D

You can animate each property of a CompositeTransform3D independently. For more info about animations, see Storyboarded animations and Key-frame and easing function animations.

In this example, animations are applied the RotationY and TranslateZ properties to make the middle rectangle appear to drop into place. The end result when the animations have stopped is the same as the previous example.

<StackPanel Orientation="Horizontal" Loaded="StackPanel_Loaded">
    <StackPanel.Resources>
        <Storyboard x:Name="rect2Storyboard">
            <DoubleAnimation 
                Storyboard.TargetName="rectangle2"
                Storyboard.TargetProperty="(UIElement.Transform3D).(CompositeTransform3D.RotationY)"
                From="0" To="-30" Duration="0:0:5"/>
            <DoubleAnimation
                Storyboard.TargetName="rectangle2"
                Storyboard.TargetProperty="(UIElement.Transform3D).(CompositeTransform3D.TranslateZ)"
                From="175" To="-75" Duration="0:0:10"/>
        </Storyboard>
    </StackPanel.Resources>
    <StackPanel.Transform3D>
        <PerspectiveTransform3D />
    </StackPanel.Transform3D>

    <Rectangle Width="300" Height="200" Fill="CornflowerBlue" />

    <Rectangle x:Name="rectangle2" Width="300" Height="200" Fill="CadetBlue" Margin="10">
        <Rectangle.Transform3D>
            <CompositeTransform3D CenterX="150" />
        </Rectangle.Transform3D>
    </Rectangle>

    <Rectangle Width="300" Height="200" Fill="OrangeRed">
        <Rectangle.Transform3D>
            <CompositeTransform3D TranslateZ="-150" />
        </Rectangle.Transform3D>
    </Rectangle>
</StackPanel>

private void StackPanel_Loaded(object sender, RoutedEventArgs e)
{
    rect2Storyboard.Begin();
}

Transform3D and PlaneProjection

Prior to Windows 10, the only way to create 3-D effects was to set the Projection property. When using Projection, 3-D transforms are not inherited down the XAML tree. Therefore, Projection is suitable only for applying effects where elements are transformed in local coordinates, not relative to a shared perspective viewport. This same effect can be achieved by setting PerspectiveTransform3D on a local element. For this reason, we recommend that you use Transform3D for all but the most simple 3-D effects, and whenever you need a shared perspective.

Identifies the Transform3D dependency property.

public : static DependencyProperty Transform3DProperty { get; }public static DependencyProperty Transform3DProperty { get; }Public Static ReadOnly Property Transform3DProperty As DependencyProperty// This API is not available in Javascript.

See Also

Transform3DTransform3DTransform3DTransform3D

Gets or sets the collection of Transition style elements that apply to a UIElement.

public : TransitionCollection Transitions { get; set; }public TransitionCollection Transitions { get; set; }Public ReadWrite Property Transitions As TransitionCollection// This API is not available in Javascript.

<uielement>
  <uielement.Transitions>
    <TransitionCollection>
      oneOrMoreTransitions
    </TransitionCollection>
  </uielement.Transitions>
</uielement>

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>

Remarks

This is a short list of some of the possible types for transitions:

• AddDeleteThemeTransition
• ContentThemeTransition
• EdgeUIThemeTransition
• EntranceThemeTransition
• PopupThemeTransition
• ReorderThemeTransition
• RepositionThemeTransition

Specific classes that derive from UIElement sometimes have their own properties that hold other types of transitions for class-specific scenarios. For example, Popup.ChildTransitions and ItemsControl.ItemContainerTransitions.

Transition animations play a particular role in UI design of your app. The basic idea is that when there is a change or transition, the animation draws the attention of the user to the change.

It's not common to set the value of the Transitions property directly on a UIElement that is a direct element of app UI. It's more common to have a transitions collection be a part of a visual state, template or style. In this case you use mechanisms such as Setter of a Style to specify the Transitions property, and set the value using XAML-defined content that is typically stored as a XAML resource.

VisualTransition is not one of the types you put in the UIElement.Transitions collection. VisualTransition is specifically for animations in visual state groups, and is used by the VisualStateGroup.Transitions property.

See Also

Storyboarded animations

TransitionCollectionTransitionCollectionTransitionCollectionTransitionCollection

Identifies the Transitions dependency property.

public : static DependencyProperty TransitionsProperty { get; }public static DependencyProperty TransitionsProperty { get; }Public Static ReadOnly Property TransitionsProperty As DependencyProperty// This API is not available in Javascript.

Gets or sets a value that determines whether rendering for the object and its visual subtree should use rounding behavior that aligns rendering to whole pixels.

public : PlatForm::Boolean UseLayoutRounding { get; set; }public bool UseLayoutRounding { get; set; }Public ReadWrite Property UseLayoutRounding As bool// This API is not available in Javascript.

<uiElement UseLayoutRounding="bool" />

Remarks

Various Windows Runtime properties of type Double are used to specify layout desired values or characteristics. The most obvious are Height and Width but there are many others. The default value of true for UseLayoutRounding will cause measurement and layout operations to round potential subpixel values from these layout properties to the nearest integer value, and render objects aligned to pixel boundaries. This behavior is intended to reduce the visual artifacts that can appear when a subpixel value renders and affects pixels on either side of the subpixel boundary. The most prominent example of such an artifact is when you intend to produce a crisp, thin line of a particular color. If your measurement for the line gave a subpixel value, and the layout behavior did not round to whole pixels, then the line can potentially appear blurry as well as appearing as a dimmer color shade than you intended.

Layout rounding affects aliasing as well as positioning.

Possible scenarios for setting UseLayoutRounding to false are not documented here. If you feel that there might be benefit in enabling subpixel rendering for your app, experiment with setting UseLayoutRounding to false, examine the visual results, and make sure that possible rendering artifacts from subpixel rendering do not outweigh the perceived benefits. If you do set UseLayoutRounding to false, it's common to do so on the root of your XAML page or object tree.

See Also

Define layouts with XAML

Identifies the UseLayoutRounding dependency property.

public : static DependencyProperty UseLayoutRoundingProperty { get; }public static DependencyProperty UseLayoutRoundingProperty { get; }Public Static ReadOnly Property UseLayoutRoundingProperty As DependencyProperty// This API is not available in Javascript.

Gets or sets the visibility of a UIElement. A UIElement that is not visible is not rendered and does not communicate its desired size to layout.

public : Visibility Visibility { get; set; }public Visibility Visibility { get; set; }Public ReadWrite Property Visibility As Visibility// This API is not available in Javascript.

<uiElement Visibility="Visible"/>
-or-
<uiElement Visibility="Collapsed"/>

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>

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.

See Also

Define layouts with XAML

Identifies the Visibility dependency property.

public : static DependencyProperty VisibilityProperty { get; }public static DependencyProperty VisibilityProperty { get; }Public Static ReadOnly Property VisibilityProperty As DependencyProperty// This API is not available in Javascript.

Gets or sets a value that specifies the strategy used to determine the target element of a down navigation.

public : XYFocusNavigationStrategy XYFocusDownNavigationStrategy { get; set; }public XYFocusNavigationStrategy XYFocusDownNavigationStrategy { get; set; }Public ReadWrite Property XYFocusDownNavigationStrategy As XYFocusNavigationStrategy// This API is not available in Javascript.

<uiElement XYFocusDownNavigationStrategy="xyFocusNavigationStrategyMemberName"/>

Device family	Windows 10 Creators Update (introduced v10.0.15063.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v4)

Remarks

When this property is set to Auto, the strategy is inherited from the elements ancestors. If all ancestors have a value of Auto, the fallback strategy is Projection.

See Also

XYFocusNavigationStrategyXYFocusNavigationStrategyXYFocusNavigationStrategyXYFocusNavigationStrategy

Identifies the XYFocusDownNavigationStrategy dependency property.

public : static DependencyProperty XYFocusDownNavigationStrategyProperty { get; }public static DependencyProperty XYFocusDownNavigationStrategyProperty { get; }Public Static ReadOnly Property XYFocusDownNavigationStrategyProperty As DependencyProperty// This API is not available in Javascript.

Device family	Windows 10 Creators Update (introduced v10.0.15063.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v4)

Gets or sets a value that enables or disables navigation using the keyboard directional arrows.

public : XYFocusKeyboardNavigationMode XYFocusKeyboardNavigation { get; set; }public XYFocusKeyboardNavigationMode XYFocusKeyboardNavigation { get; set; }Public ReadWrite Property XYFocusKeyboardNavigation As XYFocusKeyboardNavigationMode// This API is not available in Javascript.

<uiElement XYFocusKeyboardNavigation="xyFocusKeyboardNavigationModeMemberName"/>

Device family	Windows 10 Creators Update (introduced v10.0.15063.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v4)

Remarks

When this property is set to Auto, the behavior is inherited from the elements ancestors. If all ancestors have a value of Auto, the fallback behavior is Disabled.

See Also

XYFocusKeyboardNavigationModeXYFocusKeyboardNavigationModeXYFocusKeyboardNavigationModeXYFocusKeyboardNavigationMode

Identifies the XYFocusKeyboardNavigation dependency property.

public : static DependencyProperty XYFocusKeyboardNavigationProperty { get; }public static DependencyProperty XYFocusKeyboardNavigationProperty { get; }Public Static ReadOnly Property XYFocusKeyboardNavigationProperty As DependencyProperty// This API is not available in Javascript.

Device family	Windows 10 Creators Update (introduced v10.0.15063.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v4)

Gets or sets a value that specifies the strategy used to determine the target element of a left navigation.

public : XYFocusNavigationStrategy XYFocusLeftNavigationStrategy { get; set; }public XYFocusNavigationStrategy XYFocusLeftNavigationStrategy { get; set; }Public ReadWrite Property XYFocusLeftNavigationStrategy As XYFocusNavigationStrategy// This API is not available in Javascript.

<uiElement XYFocusLeftNavigationStrategy="xyFocusNavigationStrategyMemberName"/>

Device family	Windows 10 Creators Update (introduced v10.0.15063.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v4)

Remarks

When this property is set to Auto, the strategy is inherited from the elements ancestors. If all ancestors have a value of Auto, the fallback strategy is Projection.

See Also

XYFocusNavigationStrategyXYFocusNavigationStrategyXYFocusNavigationStrategyXYFocusNavigationStrategy

Identifies the XYFocusLeftNavigationStrategy dependency property.

public : static DependencyProperty XYFocusLeftNavigationStrategyProperty { get; }public static DependencyProperty XYFocusLeftNavigationStrategyProperty { get; }Public Static ReadOnly Property XYFocusLeftNavigationStrategyProperty As DependencyProperty// This API is not available in Javascript.

Device family	Windows 10 Creators Update (introduced v10.0.15063.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v4)

Gets or sets a value that specifies the strategy used to determine the target element of a right navigation.

public : XYFocusNavigationStrategy XYFocusRightNavigationStrategy { get; set; }public XYFocusNavigationStrategy XYFocusRightNavigationStrategy { get; set; }Public ReadWrite Property XYFocusRightNavigationStrategy As XYFocusNavigationStrategy// This API is not available in Javascript.

<uiElement XYFocusRightNavigationStrategy="xyFocusNavigationStrategyMemberName"/>

Device family	Windows 10 Creators Update (introduced v10.0.15063.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v4)

Remarks

When this property is set to Auto, the strategy is inherited from the elements ancestors. If all ancestors have a value of Auto, the fallback strategy is Projection.

See Also

XYFocusNavigationStrategyXYFocusNavigationStrategyXYFocusNavigationStrategyXYFocusNavigationStrategy

Identifies the XYFocusRightNavigationStrategy dependency property.

public : static DependencyProperty XYFocusRightNavigationStrategyProperty { get; }public static DependencyProperty XYFocusRightNavigationStrategyProperty { get; }Public Static ReadOnly Property XYFocusRightNavigationStrategyProperty As DependencyProperty// This API is not available in Javascript.

Device family	Windows 10 Creators Update (introduced v10.0.15063.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v4)

Gets or sets a value that specifies the strategy used to determine the target element of an up navigation.

public : XYFocusNavigationStrategy XYFocusUpNavigationStrategy { get; set; }public XYFocusNavigationStrategy XYFocusUpNavigationStrategy { get; set; }Public ReadWrite Property XYFocusUpNavigationStrategy As XYFocusNavigationStrategy// This API is not available in Javascript.

<uiElement XYFocusUpNavigationStrategy="xyFocusNavigationStrategyMemberName"/>

Device family	Windows 10 Creators Update (introduced v10.0.15063.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v4)

Remarks

When this property is set to Auto, the strategy is inherited from the elements ancestors. If all ancestors have a value of Auto, the fallback strategy is Projection.

See Also

XYFocusNavigationStrategyXYFocusNavigationStrategyXYFocusNavigationStrategyXYFocusNavigationStrategy

Identifies the XYFocusUpNavigationStrategy dependency property.

public : static DependencyProperty XYFocusUpNavigationStrategyProperty { get; }public static DependencyProperty XYFocusUpNavigationStrategyProperty { get; }Public Static ReadOnly Property XYFocusUpNavigationStrategyProperty As DependencyProperty// This API is not available in Javascript.

Device family	Windows 10 Creators Update (introduced v10.0.15063.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v4)

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, PlatForm::Object handler, bool handledEventsToo)public void AddHandler(RoutedEvent routedEvent, Object handler, Boolean handledEventsToo)Public Function AddHandler(routedEvent As RoutedEvent, handler As Object, handledEventsToo As Boolean) As void// This API is not available in Javascript.

Examples

This example shows the basic syntax for wiring an event handler with AddHandler and handledEventsToo as true. In this case the event being wired is Tapped. The typical place to wire handlers is either Loaded for a page or OnApplyTemplate for a templated control.

void MainPage::pageRoot_Tapped(Platform::Object^ sender, Windows::UI::Xaml::Input::TappedRoutedEventArgs^ e)
{
     //implementation
}
void MainPage::pageRoot_Loaded(Platform::Object^ sender, Windows::UI::Xaml::RoutedEventArgs^ e)
{
     this->AddHandler(UIElement::TappedEvent, ref new TappedEventHandler(this, &MainPage::pageRoot_Tapped), true);
}

private void pageRoot_Tapped(object sender, TappedRoutedEventArgs e)
{
    //implementation
}
private void pageRoot_Loaded_1(object sender, RoutedEventArgs e)
{
    this.AddHandler(UIElement.TappedEvent, new TappedEventHandler(pageRoot_Tapped), true);
}

Private Sub Page_Tapped(sender As Object, e As TappedRoutedEventArgs)
    ' implementation
End Sub
Private Sub Page_Loaded_1(sender As Object, e As RoutedEventArgs)
    Me.AddHandler(UIElement.TappedEvent, New TappedEventHandler(AddressOf Page_Tapped), True)
End Sub

Remarks

Don't try to use AddHandler as a general substitute for the language-specific syntax you normally use for wiring event handlers; it won't work, because not all events have an identifier you can pass as routedEvent. AddHandler is specifically for routed events, and intended mainly for the particular scenario enabled by passing handledEventsToo as true. For more info, see Events and routed events overview.

Routed event identifiers

The routed event identifier is generally a static property member of UIElement. For example, to add a handler for the KeyUp event, pass KeyUpEvent for this parameter. Only a small number of Windows Runtime events have this identifier; only routed events on UIElement have an identifier API available for this usage. These are generally events that are related to input actions at various levels: pointer level, gesture level, manipulation level. Also, the key input events can be handled this way.

Here is a list of routed events that expose a routed event identifier, and thus can be processed by handlers that are registered by an AddHandler call:

• DoubleTapped
• DragEnter
• DragLeave
• DragOver
• Drop
• Holding
• KeyDown
• KeyUp
• ManipulationCompleted
• ManipulationDelta
• ManipulationInertiaStarting
• ManipulationStarted
• ManipulationStarting
• PointerCanceled
• PointerCaptureLost
• PointerEntered
• PointerExited
• PointerMoved
• PointerPressed
• PointerReleased
• PointerWheelChanged
• RightTapped
• Tapped

The handler parameter

The handler parameter is an untyped parameter, but you should provide a new delegate that references a handler method that is specific to the desired event. For example, if handling a KeyUp event, pass a new KeyEventHandler instance that references a method that is based on that KeyEventHandler delegate signature. This requires a dereference, and the dereference syntax varies depending on which language you are using. See the examples in this topic.

When to use handledEventsToo

Processing low-level input events in a practical way is a complex task. Many controls implement behavior where a certain event is marked as handled, and is replaced by another more intuitive event. Generally, a control will mark a routed event as handled only if there is some design intention for doing so. However, in certain scenarios, those design intentions might not be what your particular handling of the input event requires. It is for these scenarios that registering handlers with handledEventsToo as true is appropriate. But you should not do this routinely. Invoking handlers in response to all events even if handled will complicate your own app event-processing logic. You may see a decrease in performance if the handler logic is substantial. You should attach handlers to already-handled events only if you have discovered that certain controls are handling events that you want to handle with app logic.

Another technique for avoiding a control's class-handling behavior is to subclass that control and override its On* methods, which are pre-configured overrides by which the control marks an event as handled. However, this too can be complex. You may have to reproduce a control's handling implementation without calling the base implementation, because the base implementation would mark the event as handled. For more info, see Events and routed events overview.

See Also

RemoveHandler(RoutedEvent, Object)RemoveHandler(RoutedEvent, Object)RemoveHandler(RoutedEvent, Object)RemoveHandler(RoutedEvent, Object)

Events and routed events overview

Quickstart: Touch input

Positions child objects and determines a size for a UIElement. Parent objects that implement custom layout for their child elements should call this method from their layout override implementations to form a recursive layout update.

public : void Arrange(Rect finalRect)public void Arrange(Rect finalRect)Public Function Arrange(finalRect As Rect) As void// This API is not available in Javascript.

Examples

This example shows how you would use Arrange within an ArrangeOverride implementation. The basic idea is that you should query DesiredSize on anything you attempt to call Arrange on so that you have a value for finalRect, unless your layout implementation has some specific design that alters or ignores the desired size before passing it as finalRect.

// Second arrange all children and return final size of panel
protected override Size ArrangeOverride(Size finalSize)
{
    // Get the collection of children
    UIElementCollection mychildren = Children;

    // Get total number of children
    int count = mychildren.Count;

    // Arrange children
    // We're only allowing 9 children in this panel.  More children will get a 0x0 layout slot.
    int i;
    for (i = 0; i < 9; i++)
    {

        // Get (left, top) origin point for the element in the 3x3 block
        Point cellOrigin = GetOrigin(i, 3, new Size(100, 100));

        // Arrange child
        // Get desired height and width. This will not be larger than 100x100 as set in MeasureOverride.
        double dw = mychildren[i].DesiredSize.Width;
        double dh = mychildren[i].DesiredSize.Height;

        mychildren[i].Arrange(new Rect(cellOrigin.X, cellOrigin.Y, dw, dh));

    }

    // Give the remaining children a 0x0 layout slot
    for (i = 9; i < count; i++)
    {
        mychildren[i].Arrange(new Rect(0, 0, 0, 0));
    }


    // Return final size of the panel
    return new Size(300, 300);
}

'Second arrange all children and return final size of panel 
Protected Overrides Function ArrangeOverride(ByVal finalSize As Size) As Size
    'Get the collection of children 
    Dim mychildren As UIElementCollection = Children
    'Get total number of children 
    Dim count As Integer = mychildren.Count
    'Arrange children 
    'only allowing 9 children in this panel. More children will get a 0x0 layout slot. 
    Dim i As Integer
    For i = 0 To 8
        'Get (left, top) origin point for the element in the 3x3 block 
        Dim cellOrigin As Point = GetOrigin(i, 3, New Size(100, 100))
        'Arrange child 
        'Get desired height and width. This will not be larger than 100x100 as set in MeasureOverride. 
        Dim dw As Double = mychildren(i).DesiredSize.Width
        Dim dh As Double = mychildren(i).DesiredSize.Height
        mychildren(i).Arrange(New Rect(cellOrigin.X, cellOrigin.Y, dw, dh))
    Next
    For i = 9 To count - 1
        'Give the remaining children a 0x0 layout slot 
        mychildren(i).Arrange(New Rect(0, 0, 0, 0))
    Next
    'Return final size of the panel 
    Return New Size(300, 300)
End Function
'Calculate point origin of the Block you are in 
Protected Function GetOrigin(ByVal blockNum As Integer, ByVal blocksPerRow As Integer, ByVal itemSize As Size) As Point
    'Get row number (zero-based) 
    Dim row As Integer = CInt(Math.Floor(blockNum / blocksPerRow))
    'Get column number (zero-based) 
    Dim column As Integer = blockNum - blocksPerRow * row
    'Calculate origin 
    Dim origin As New Point(itemSize.Width * column, itemSize.Height * row)
    Return origin
End Function

Remarks

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

Computation of initial layout positioning in a XAML UI consists of a Measure call and an Arrange call, in that order. During the Measure call, the layout system determines an element's size requirements using the availableSize measurement. During the Arrange call, the layout system finalizes the size and position of an element's bounding box.

When a layout is first produced, it always has a Measure call that happens before Arrange. However, after the first layout pass, an Arrange call can happen without a Measure preceding it. This can happen when a property that affects only Arrange is changed (such as alignment), or when the parent receives an Arrange without a Measure.

A Measure call will automatically invalidate any Arrange information. Layout updates generally occur asynchronously (at a time determined by the layout system). An element might not immediately reflect changes to properties that affect element sizing (such as Width ).

Layout updates can be forced by app code rather than relying on the built-in layout system behavior by using the UpdateLayout method. However, that is not recommended. It is usually unnecessary and can cause poor performance if overused. In many situations where calling UpdateLayout from app code might be appropriate because of changes to properties, the layout system will probably already be processing updates. The layout system also has optimizations for dealing with cascades of layout changes through parent-child relationships, and calling UpdateLayout can work against such optimizations. Nevertheless, it's possible that layout situations exist in more complicated scenarios where calling UpdateLayout is the best option for resolving a timing issue or other issue with layout. Just use it deliberately and sparingly.

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

public : PlatForm::Boolean CancelDirectManipulations()public bool CancelDirectManipulations()Public Function CancelDirectManipulations() As bool// This API is not available in Javascript.

Remarks

You might call this method if you want the target UIElement to be able to process ongoing manipulations through the lower-level pointer events (PointerPressed, PointerMoved and so on). By default, if the target UIElement is contained in a ScrollViewer, that ScrollViewer parent would handle translation manipulations directly at the system level, treating them as pan or zoom. Manipulation handling by the ScrollViewer parent prevents the contained UIElement from receiving the pointer events (they would be marked as handled). Call CancelDirectManipulations to override this default behavior for an ongoing manipulation, and then you'll be able to handle manipulations at a non-system level for the individual UIElement target.

See Also

ManipulationModeManipulationModeManipulationModeManipulationMode

Gestures, manipulations, and interactions

Sets pointer capture to a UIElement. Once captured, only the element that has capture will fire pointer-related events.

public : PlatForm::Boolean CapturePointer(Pointer value)public bool CapturePointer(Pointer value)Public Function CapturePointer(value As Pointer) As bool// This API is not available in Javascript.

Examples

This example shows calling CapturePointer based on handling PointerPressed. It also shows a pattern for tracking and counting pointer references.

int _pointerCount;

public Scenario2()
{
    this.InitializeComponent();
    bEnteredExited.PointerEntered += bEnteredExited_PointerEntered;
    bEnteredExited.PointerExited += bEnteredExited_PointerExited;
    bEnteredExited.PointerPressed += bEnteredExited_PointerPressed;
    bEnteredExited.PointerReleased += bEnteredExited_PointerReleased;
    bEnteredExited.PointerMoved += bEnteredExited_PointerMoved;

    // To code for multiple Pointers (that is, fingers), 
    // we track how many entered/exited.
    _pointerCount = 0;
}

private void bEnteredExited_PointerMoved(object sender, 
    PointerRoutedEventArgs e)
{
    Scenario2UpdateVisuals(sender as Border, "Moved");
}

private void bEnteredExited_PointerReleased(object sender, 
    PointerRoutedEventArgs e)
{
    ((Border)sender).ReleasePointerCapture(e.Pointer);
    txtCaptureStatus.Text = string.Empty;
}

//Can only get capture on PointerPressed (i.e. touch down, mouse click, pen press)
private void bEnteredExited_PointerPressed(object sender, 
    PointerRoutedEventArgs e)
{
    if (tbPointerCapture.IsOn)
    {
        bool _hasCapture = ((Border)sender).CapturePointer(e.Pointer);
        txtCaptureStatus.Text = "Got Capture: " + _hasCapture;
    }
}

private void bEnteredExited_PointerExited(object sender, 
    PointerRoutedEventArgs e)
{
    _pointerCount--;
    Scenario2UpdateVisuals(sender as Border, "Exited");
}

private void bEnteredExited_PointerEntered(object sender, 
    PointerRoutedEventArgs e)
{
    _pointerCount++;
    Scenario2UpdateVisuals(sender as Border, "Entered");
}

private void Scenario2UpdateVisuals(Border border, 
    String eventDescription)
{
    switch (eventDescription.ToLower())
    {
        case "exited":
            if (_pointerCount <= 0)
            {
                border.Background = new SolidColorBrush(Colors.Red);
                bEnteredExitedTextBlock.Text = eventDescription;
            }
            break;
        case "moved":
            RotateTransform rt = 
                (RotateTransform)bEnteredExitedTimer.RenderTransform;
            rt.Angle += 2;
            if (rt.Angle > 360) rt.Angle -= 360;
            break;
        default:
            border.Background = new SolidColorBrush(Colors.Green);
            bEnteredExitedTextBlock.Text = eventDescription;
            break;
    }
}

private void Scenario2Reset(object sender, RoutedEventArgs e)
{
    Scenario2Reset();
}

private void Scenario2Reset()
{
    bEnteredExited.Background = new SolidColorBrush(Colors.Green);
    bEnteredExitedTextBlock.Text = string.Empty;
}

Private _pointerCount As Integer

Public Sub New()
    Me.InitializeComponent()
    AddHandler bEnteredExited.PointerEntered, AddressOf bEnteredExited_PointerEntered
    AddHandler bEnteredExited.PointerExited, AddressOf bEnteredExited_PointerExited
    AddHandler bEnteredExited.PointerPressed, AddressOf bEnteredExited_PointerPressed
    AddHandler bEnteredExited.PointerReleased, AddressOf bEnteredExited_PointerReleased
    AddHandler bEnteredExited.PointerMoved, AddressOf bEnteredExited_PointerMoved

    'To code for multiple Pointers (i.e. Fingers) we track how many entered/exited.
    _pointerCount = 0
End Sub

''' <summary>
''' Invoked when this page is about to be displayed in a Frame.
''' </summary>
''' <param name="e">Event data that describes how this page was reached.  The Parameter
''' property is typically used to configure the page.</param>
Protected Overrides Sub OnNavigatedTo(e As NavigationEventArgs)
End Sub

Private Sub bEnteredExited_PointerMoved(sender As Object, e As PointerRoutedEventArgs)
    Scenario2UpdateVisuals(TryCast(sender, Border), "Moved")
End Sub

Private Sub bEnteredExited_PointerReleased(sender As Object, e As PointerRoutedEventArgs)
    DirectCast(sender, Border).ReleasePointerCapture(e.Pointer)
    txtCaptureStatus.Text = String.Empty
End Sub

'Can only get capture on PointerPressed (i.e. touch down, mouse click, pen press)
Private Sub bEnteredExited_PointerPressed(sender As Object, e As PointerRoutedEventArgs)
    If tbPointerCapture.IsOn Then
        Dim _hasCapture As Boolean = DirectCast(sender, Border).CapturePointer(e.Pointer)
        txtCaptureStatus.Text = "Got Capture: " & _hasCapture
    End If
End Sub

Private Sub bEnteredExited_PointerExited(sender As Object, e As PointerRoutedEventArgs)
    _pointerCount -= 1
    Scenario2UpdateVisuals(TryCast(sender, Border), "Exited")
End Sub

Private Sub bEnteredExited_PointerEntered(sender As Object, e As PointerRoutedEventArgs)
    _pointerCount += 1
    Scenario2UpdateVisuals(TryCast(sender, Border), "Entered")

End Sub

Private Sub Scenario2UpdateVisuals(border As Border, eventDescription As String)
    Select Case eventDescription.ToLower()
        Case "exited"
            If _pointerCount <= 0 Then
                border.Background = New SolidColorBrush(Colors.Red)
                bEnteredExitedTextBlock.Text = eventDescription
            End If
            Exit Select
        Case "moved"

            Dim rt As RotateTransform = DirectCast(bEnteredExitedTimer.RenderTransform, RotateTransform)
            rt.Angle += 2
            If rt.Angle > 360 Then
                rt.Angle -= 360
            End If
            Exit Select
        Case Else
            border.Background = New SolidColorBrush(Colors.Green)
            bEnteredExitedTextBlock.Text = eventDescription
            Exit Select

    End Select
End Sub

Private Sub Scenario2ResetMethod(sender As Object, e As RoutedEventArgs)
    Reset()
End Sub

Private Sub Reset()
    bEnteredExited.Background = New SolidColorBrush(Colors.Green)
    bEnteredExitedTextBlock.Text = String.Empty
End Sub

Remarks

You can only successfully capture the pointer if that pointer is in a pressed state (Pointer.IsInContact should be true). What physically constitutes being pressed will vary based on the pointer device type (mouse button pressed, touch point down, stylus in contact). If you attempt to capture a pointer that isn't pressed, or where the pointer was previously pressed but is now released, CapturePointer returns false. Existing captures aren't affected by a CapturePointer call that returned false.

You typically capture the pointer within a PointerPressed event handler. The Pointer instance you get from the PointerRoutedEventArgs event data of your PointerPressed handler is the value you should pass for the value parameter when you call CapturePointer from within your handler's code.

You typically capture the pointer because you want the current pointer action to initiate a behavior in your app. In this case you typically don't want other elements to handle any other events that come from that pointer's actions, until your behavior is either completed or is canceled by releasing the pointer capture. If a pointer is captured, only the element that has capture gets the pointer's input events, and other elements don't fire events even if the pointer moves into their bounds. For example, consider a UI that has two adjacent elements. Normally, if you moved the pointer from one element to the other, you'd first get PointerMoved events from the first element, and then from the second element. But if the first element has captured the pointer, then the first element continues to receive PointerMoved events even if the captured pointer leaves its bounds. Also, the second element doesn't fire PointerEntered events for a captured pointer when the captured pointer enters it.

The pointer capture state and generating the events that are related to pointer capture isn't entirely up to app code. If the user releases the pointer, that generates a PointerReleased event, and pointer captures associated with that pointer are lost. This also fires PointerCaptureLost on the original capturing element.

In most cases the pointer capture will be released automatically when the user completes an input action that releases the previous pointer capture (lifting a touch point, releasing the left mouse button, taking the stylus out of range). Another condition that might release capture is any action that also fires a PointerCanceled event. Your app can typically rely on the capture-release behavior associated with user input actions, without having to specifically cancel a pointer capture with ReleasePointerCapture or ReleasePointerCaptures. For more info, see Mouse interactions.

The CapturePointer method will return false if the pointer was already captured.

A UIElement can capture more than one pointer point at a time. Use the value parameter to indicate the Pointer instance you want to capture.

The input events that represent gestures (such as Tapped or DoubleTapped ) are usually only fired after a pointer is released, so you shouldn't attempt to capture a pointer in event handlers for gesture events. The Pointer reference in event data for gesture events won't be permitted to initiate a pointer capture.

See Also

PointerPointerPointerPointer

ReleasePointerCapture(Pointer)ReleasePointerCapture(Pointer)ReleasePointerCapture(Pointer)ReleasePointerCapture(Pointer)

Quickstart: Touch input

Input sample

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 IEnumerable<IEnumerable<Point>> FindSubElementsForTouchTargeting(Point point, Rect boundingRect)Protected Overridable Function FindSubElementsForTouchTargeting(point As Point, boundingRect As Rect) As IEnumerable( Of IEnumerablePoint )// This API is not available in Javascript.

Remarks

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

FindElementsInHostCoordinates is a similar static-class helper method that is also used for hit testing and general object tree examination. However, FindSubElementsForTouchTargeting adds the refinement of a Rect input to use for touch tolerance.

If you are programming using C# or Microsoft Visual Basic, the return value type of this method is projected as an IEnumerable generic collection that contains UIElement items. If you are programming using Visual C++ component extensions (C++/CX), the return type of this method is IIterable;.

See Also

Quickstart: Touch input

Enables a UIElement subclass to expose child elements that take part in Tab focus.

protected : virtual IIterable<DependencyObject> GetChildrenInTabFocusOrder()protected virtual IEnumerable<DependencyObject> GetChildrenInTabFocusOrder()Protected Overridable Function GetChildrenInTabFocusOrder() As IEnumerable( Of DependencyObject )// This API is not available in Javascript.

Device family	Windows 10 Fall Creators Update (introduced v10.0.16299.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v5)

Remarks

The default behavior for this method is to return the UIElement's collection of child elements.

When Tab is processed to move focus, the framework’s focus management calls the GetChildrenInTabFocusOrder override. The resulting list of DependencyObjects is used to process Tab focus instead of the element's default collection of children.

Invalidates the arrange state (layout) for a UIElement. After the invalidation, the UIElement will have its layout updated, which will occur asynchronously.

public : void InvalidateArrange()public void InvalidateArrange()Public Function InvalidateArrange() As void// This API is not available in Javascript.

Remarks

Controls that maintain their own orientation property might call InvalidateArrange when that orientation changes, as a way to reconstruct the layout for the new orientation. InvalidateArrange might also be called from within custom layout logic in cases such as when available size isn't adequate and the logic allows for an alternate layout strategy that uses available size differently.

UpdateLayout is basically equivalent to calling InvalidateMeasure and InvalidateArrange in sequence.

Layout updates can be forced by app code rather than relying on the built-in layout system behavior. However, that is not generally recommended. Calling InvalidateArrange, InvalidateMeasure or UpdateLayout is usually unnecessary and can cause poor performance if overused. In many situations where app code might be changing layout properties, the layout system will probably already be processing updates asynchronously. The layout system also has optimizations for dealing with cascades of layout changes through parent-child relationships, and forcing layout with app code can work against such optimizations. Nevertheless, it's possible that layout situations exist in more complicated scenarios where forcing layout is the best option for resolving a timing issue or other issue with layout. Just use it deliberately and sparingly.

See Also

Arrange(Rect)Arrange(Rect)Arrange(Rect)Arrange(Rect)

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

UpdateLayout()UpdateLayout()UpdateLayout()UpdateLayout()

Define layouts with XAML

Invalidates the measurement state (layout) for a UIElement.

public : void InvalidateMeasure()public void InvalidateMeasure()Public Function InvalidateMeasure() As void// This API is not available in Javascript.

Remarks

UpdateLayout is basically equivalent to calling InvalidateMeasure and InvalidateArrange in sequence.

Layout updates can be forced by app code rather than relying on the built-in layout system behavior. However, that is not generally recommended. Calling InvalidateArrange, InvalidateMeasure or UpdateLayout is usually unnecessary and can cause poor performance if overused. In many situations where app code might be changing layout properties, the layout system will probably already be processing updates asynchronously. The layout system also has optimizations for dealing with cascades of layout changes through parent-child relationships, and forcing layout with app code can work against such optimizations. Nevertheless, it's possible that layout situations exist in more complicated scenarios where forcing layout is the best option for resolving a timing issue or other issue with layout. Just use it deliberately and sparingly.

See Also

Measure(Size)Measure(Size)Measure(Size)Measure(Size)

Define layouts with XAML

Updates the DesiredSize of a UIElement. Typically, objects that implement custom layout for their layout children call this method from their own MeasureOverride implementations to form a recursive layout update.

public : void Measure(Size availableSize)public void Measure(Size availableSize)Public Function Measure(availableSize As Size) As void// This API is not available in Javascript.

Examples

This example implements MeasureOverride to customize the "Measure" pass logic for a custom panel implementation. Note in particular these aspects of the code:

• Iterates over children.
• For each child, calls Measure, using a Size that makes sense based on how the panel logic treats the number of children and its own known size limit.
• Returns its size (in this case, this simple panel returns a fixed size rather than a size calculated on accumulating the measurements).

// First measure all children and return available size of panel
protected override Size MeasureOverride(Size availableSize)
{

    // Measure first 9 children giving them space up to 100x100, remaining children get 0x0 
    int i = 0;
    foreach (FrameworkElement child in Children)
    {
        if (i < 9)
        {
            child.Measure(new Size(100, 100));
        }
        else
        {
            child.Measure(new Size(0, 0));
        }

        i++;
    }


    // return the size available to the whole panel, which is 300x300
    return new Size(300, 300);
}

'First measure all children and return available size of panel 
Protected Overrides Function MeasureOverride(ByVal availableSize As Size) As Size
    'Measure first 9 children giving them space up to 100x100, remaining children get 0x0 
    Dim i As Integer = 0
    For Each child As FrameworkElement In Children
        If i < 9 Then
            child.Measure(New Size(100, 100))
        Else
            child.Measure(New Size(0, 0))
        End If
        i += 1
    Next
    'return the size available to the whole panel, which is 300x300 
    Return New Size(300, 300)
End Function

Remarks

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

availableSize can be any number from zero to infinite. Elements participating in layout should return the minimum Size they require for a given availableSize.

Computation of initial layout positioning in a XAML UI consists of a Measure call and an Arrange call, in that order. During the Measure call, the layout system determines an element's size requirements using the availableSize measurement. During the Arrange call, the layout system finalizes the size and position of an element's bounding box.

When a layout is first produced, it always has a Measure call that happens before Arrange. However, after the first layout pass, an Arrange call can happen without a Measure preceding it. This can happen when a property that affects only Arrange is changed (such as alignment), or when the parent receives an Arrange without a Measure.

A Measure call will automatically invalidate any Arrange information. Layout updates generally occur asynchronously (at a time determined by the layout system). An element might not immediately reflect changes to properties that affect element sizing (such as Width ).

See Also

Define layouts with XAML

When implemented in a derived class, returns class-specific AutomationPeer implementations for the Microsoft UI Automation infrastructure.

protected : virtual AutomationPeer OnCreateAutomationPeer()protected virtual AutomationPeer OnCreateAutomationPeer()Protected Overridable Function OnCreateAutomationPeer() As AutomationPeer// This API is not available in Javascript.

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

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.

See Also

AutomationPeerAutomationPeerAutomationPeerAutomationPeer

XAML accessibility sample

Custom automation peers

Accessibility

Override this method to implement how layout and logic should behave when items are removed from a class-specific content or children property.

protected : virtual void OnDisconnectVisualChildren()protected virtual void OnDisconnectVisualChildren()Protected Overridable Function OnDisconnectVisualChildren() As void// This API is not available in Javascript.

Remarks

UIElement does not define any of the content model properties that OnDisconnectVisualChildren might act upon. Such properties are introduced deeper in an inheritance, for example at the ContentControl level.

FrameworkElement uses an OnDisconnectVisualChildren override to clear values from DataContext and Tag. In general, if you override this method you should always call the base implementation so that the framework-intentional behavior that acts on OnDisconnectVisualChildren can be preserved.

VisualTreeHelper.DisconnectChildrenRecursive is a similar static helper API that can be called by app code.

Called just before a keyboard shortcut (accelerator) is processed in your app. Invoked whenever application code or internal processes call ProcessKeyboardAccelerators. Override this method to influence the default accelerator handling.

protected : virtual void OnProcessKeyboardAccelerators(ProcessKeyboardAcceleratorEventArgs args)protected virtual void OnProcessKeyboardAccelerators(ProcessKeyboardAcceleratorEventArgs args)Protected Overridable Function OnProcessKeyboardAccelerators(args As ProcessKeyboardAcceleratorEventArgs) As void// This API is not available in Javascript.

Device family	Windows 10 Fall Creators Update (introduced v10.0.16299.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v5)

Releases pointer captures for capture of one specific pointer by this UIElement.

public : void ReleasePointerCapture(Pointer value)public void ReleasePointerCapture(Pointer value)Public Function ReleasePointerCapture(value As Pointer) As void// This API is not available in Javascript.

Examples

This example shows calling ReleasePointerCapture based on handling PointerReleased.

It also shows code for capturing the pointer initially, and a pattern for tracking and counting pointer references.

int _pointerCount;

public Scenario2()
{
    this.InitializeComponent();
    bEnteredExited.PointerEntered += bEnteredExited_PointerEntered;
    bEnteredExited.PointerExited += bEnteredExited_PointerExited;
    bEnteredExited.PointerPressed += bEnteredExited_PointerPressed;
    bEnteredExited.PointerReleased += bEnteredExited_PointerReleased;
    bEnteredExited.PointerMoved += bEnteredExited_PointerMoved;

    // To code for multiple Pointers (that is, fingers), 
    // we track how many entered/exited.
    _pointerCount = 0;
}

private void bEnteredExited_PointerMoved(object sender, 
    PointerRoutedEventArgs e)
{
    Scenario2UpdateVisuals(sender as Border, "Moved");
}

private void bEnteredExited_PointerReleased(object sender, 
    PointerRoutedEventArgs e)
{
    ((Border)sender).ReleasePointerCapture(e.Pointer);
    txtCaptureStatus.Text = string.Empty;
}

//Can only get capture on PointerPressed (i.e. touch down, mouse click, pen press)
private void bEnteredExited_PointerPressed(object sender, 
    PointerRoutedEventArgs e)
{
    if (tbPointerCapture.IsOn)
    {
        bool _hasCapture = ((Border)sender).CapturePointer(e.Pointer);
        txtCaptureStatus.Text = "Got Capture: " + _hasCapture;
    }
}

private void bEnteredExited_PointerExited(object sender, 
    PointerRoutedEventArgs e)
{
    _pointerCount--;
    Scenario2UpdateVisuals(sender as Border, "Exited");
}

private void bEnteredExited_PointerEntered(object sender, 
    PointerRoutedEventArgs e)
{
    _pointerCount++;
    Scenario2UpdateVisuals(sender as Border, "Entered");
}

private void Scenario2UpdateVisuals(Border border, 
    String eventDescription)
{
    switch (eventDescription.ToLower())
    {
        case "exited":
            if (_pointerCount <= 0)
            {
                border.Background = new SolidColorBrush(Colors.Red);
                bEnteredExitedTextBlock.Text = eventDescription;
            }
            break;
        case "moved":
            RotateTransform rt = 
                (RotateTransform)bEnteredExitedTimer.RenderTransform;
            rt.Angle += 2;
            if (rt.Angle > 360) rt.Angle -= 360;
            break;
        default:
            border.Background = new SolidColorBrush(Colors.Green);
            bEnteredExitedTextBlock.Text = eventDescription;
            break;
    }
}

private void Scenario2Reset(object sender, RoutedEventArgs e)
{
    Scenario2Reset();
}

private void Scenario2Reset()
{
    bEnteredExited.Background = new SolidColorBrush(Colors.Green);
    bEnteredExitedTextBlock.Text = string.Empty;
}

Private _pointerCount As Integer

Public Sub New()
    Me.InitializeComponent()
    AddHandler bEnteredExited.PointerEntered, AddressOf bEnteredExited_PointerEntered
    AddHandler bEnteredExited.PointerExited, AddressOf bEnteredExited_PointerExited
    AddHandler bEnteredExited.PointerPressed, AddressOf bEnteredExited_PointerPressed
    AddHandler bEnteredExited.PointerReleased, AddressOf bEnteredExited_PointerReleased
    AddHandler bEnteredExited.PointerMoved, AddressOf bEnteredExited_PointerMoved

    'To code for multiple Pointers (i.e. Fingers) we track how many entered/exited.
    _pointerCount = 0
End Sub

''' <summary>
''' Invoked when this page is about to be displayed in a Frame.
''' </summary>
''' <param name="e">Event data that describes how this page was reached.  The Parameter
''' property is typically used to configure the page.</param>
Protected Overrides Sub OnNavigatedTo(e As NavigationEventArgs)
End Sub

Private Sub bEnteredExited_PointerMoved(sender As Object, e As PointerRoutedEventArgs)
    Scenario2UpdateVisuals(TryCast(sender, Border), "Moved")
End Sub

Private Sub bEnteredExited_PointerReleased(sender As Object, e As PointerRoutedEventArgs)
    DirectCast(sender, Border).ReleasePointerCapture(e.Pointer)
    txtCaptureStatus.Text = String.Empty
End Sub

'Can only get capture on PointerPressed (i.e. touch down, mouse click, pen press)
Private Sub bEnteredExited_PointerPressed(sender As Object, e As PointerRoutedEventArgs)
    If tbPointerCapture.IsOn Then
        Dim _hasCapture As Boolean = DirectCast(sender, Border).CapturePointer(e.Pointer)
        txtCaptureStatus.Text = "Got Capture: " & _hasCapture
    End If
End Sub

Private Sub bEnteredExited_PointerExited(sender As Object, e As PointerRoutedEventArgs)
    _pointerCount -= 1
    Scenario2UpdateVisuals(TryCast(sender, Border), "Exited")
End Sub

Private Sub bEnteredExited_PointerEntered(sender As Object, e As PointerRoutedEventArgs)
    _pointerCount += 1
    Scenario2UpdateVisuals(TryCast(sender, Border), "Entered")

End Sub

Private Sub Scenario2UpdateVisuals(border As Border, eventDescription As String)
    Select Case eventDescription.ToLower()
        Case "exited"
            If _pointerCount <= 0 Then
                border.Background = New SolidColorBrush(Colors.Red)
                bEnteredExitedTextBlock.Text = eventDescription
            End If
            Exit Select
        Case "moved"

            Dim rt As RotateTransform = DirectCast(bEnteredExitedTimer.RenderTransform, RotateTransform)
            rt.Angle += 2
            If rt.Angle > 360 Then
                rt.Angle -= 360
            End If
            Exit Select
        Case Else
            border.Background = New SolidColorBrush(Colors.Green)
            bEnteredExitedTextBlock.Text = eventDescription
            Exit Select

    End Select
End Sub

Private Sub Scenario2ResetMethod(sender As Object, e As RoutedEventArgs)
    Reset()
End Sub

Private Sub Reset()
    bEnteredExited.Background = New SolidColorBrush(Colors.Green)
    bEnteredExitedTextBlock.Text = String.Empty
End Sub

Remarks

Programmatically releasing the pointer capture with ReleasePointerCapture is not the only way that an element might lose pointer capture. For example, user-driven events such as releasing the pointer (touch point up, mouse button released) can cause the pointer capture to be canceled.

You can listen for the PointerCaptureLost event to determine when this happens.

Another way that pointer capture might be canceled is if a pointer moves out of one app and into another app while the two apps are side-by-side.

You should only call ReleasePointerCapture if your app code has previously called CapturePointer, and has a reference to the particular Pointer instance where you want to release the pointer capture. You'd typically get that Pointer reference through an event such as PointerReleased or perhaps PointerMoved.

Your app code might call CapturePointer from a different UIElement than the one that has any current pointer capture. If so, that cancels any pointer capture previously made by other elements.

A UIElement can capture multiple pointers to handle multiple touch points such as for manipulations, but only one UIElement in an app can have any pointer captures at any one time. For more info, see Handle pointer input.

See Also

CapturePointer(Pointer)CapturePointer(Pointer)CapturePointer(Pointer)CapturePointer(Pointer)

PointerReleasedPointerReleasedPointerReleasedPointerReleased

PointerCaptureLostPointerCaptureLostPointerCaptureLostPointerCaptureLost

Input sample

Releases all pointer captures held by this element.

public : void ReleasePointerCaptures()public void ReleasePointerCaptures()Public Function ReleasePointerCaptures() As void// This API is not available in Javascript.

Remarks

Because there are input scenarios such as manipulations that involve more than one pointer point, the Windows Runtime enables capturing more than one pointer at a time. Calling ReleasePointerCapture removes a specific Pointer from the collection as identified by its ID, whereas ReleasePointerCaptures clears the entire collection.

User action that invalidates pointer capture such as releasing from a pointer point also changes capture state. For more info, see Mouse interactions and Handle pointer input.

The PointerCaptures property exposes a view of which pointer points are currently captured by the UIElement.

See Also

ReleasePointerCapture(Pointer)ReleasePointerCapture(Pointer)ReleasePointerCapture(Pointer)ReleasePointerCapture(Pointer)

Removes the specified routed event handler from this UIElement. Typically the handler in question was added by AddHandler.

public : void RemoveHandler(RoutedEvent routedEvent, PlatForm::Object handler)public void RemoveHandler(RoutedEvent routedEvent, Object handler)Public Function RemoveHandler(routedEvent As RoutedEvent, handler As Object) As void// This API is not available in Javascript.

Remarks

RemoveHandler can only be used for the event handlers of the events that are supported by AddHandler, which is approximately the input-specific events of UIElement. More precisely, the event must have a **Event* property of type RoutedEvent, which is true only of certain events on UIElement. You cannot use RemoveHandler to unhook event handlers for Windows Runtime events on runtime class instances in general. Instead, you should use the specific event handler unhooking syntax:

• -= in C#
• RemoveHandler in Microsoft Visual Basic
• -= in Visual C++ component extensions (C++/CX)

Calling this method has no effect if there were no handlers registered with criteria that match the input parameters for the method call.

This method ignores whether handledEventsToo parameter was true in the AddHandler call that originally attached the handler.

See Also

AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)AddHandler(RoutedEvent, Object, Boolean)

Events and routed events overview

RoutedEventRoutedEventRoutedEventRoutedEvent

Initiates a request to the XAML framework to bring the element into view within any scrollable regions it is contained within.

public : void StartBringIntoView()public void StartBringIntoView()Public Function StartBringIntoView() As void// This API is not available in Javascript.

Device family	Windows 10 Creators Update (introduced v10.0.15063.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v4)

Remarks

The request is fulfilled asynchronously as the framework initiates changes to the view of ScrollViewer s that contain the element. The HorizontalOffset and VerticalOffset of those ScrollViewers may not be updated immediately upon returning from the call. However, in the process of servicing the request a ScrollViewer’s ViewChanging and ViewChanged events will fire. If you use the signature that does not specify any options, then the entire element size (its RenderSize ) will be made visible and any changes to the viewports will be animated. The StartBringIntoView method does not transmit any information about success or failure. Reasons for failure can include the element settings, such as Visibility being some value other than Visible.

Initiates a request to the XAML framework to bring the element into view using the specified options.

public : void StartBringIntoView(BringIntoViewOptions options)public void StartBringIntoView(BringIntoViewOptions options)Public Function StartBringIntoView(options As BringIntoViewOptions) As void// This API is not available in Javascript.

Device family	Windows 10 Creators Update (introduced v10.0.15063.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v4)

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 )// This API is not available in Javascript.

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

Remarks

If you implement custom gesture detection to initiate a drag operation, you can call the StartDragAsync method to programmatically initiate a drag operation on any UIElement. Calling this method results in the DragStarting event being raised. Handle the DragStarting event to specify other properties of the operation, such as the data package and drag visual.

The pointerPoint parameter is the point at which the user interacts with the screen using an input device (touch, mouse, or pen). The drag visual that is shown during the drag operation is attached to the pointer indicated in the caller-provided PointerPoint.

The DataPackageOperation returned by this method indicates whether the drag operation is a move, copy, or link; and whether or not it's a success. This is the same value that's provided by the DropResult property in the DropCompleted event args.

See Also

DragStartingDragStartingDragStartingDragStarting

CanDragCanDragCanDragCanDrag

Drag and drop sample (Windows 10)

Returns a transform object that can be used to transform coordinates from the UIElement to the specified object.

public : GeneralTransform TransformToVisual(UIElement visual)public GeneralTransform TransformToVisual(UIElement visual)Public Function TransformToVisual(visual As UIElement) As GeneralTransform// This API is not available in Javascript.

Examples

This example shows a scenario for calling TransformToVisual in order to interpret the coordinates from a PointerPoint in the coordinate reference frame of an element that's not the event sender. Here, the queryPointer method first accesses coordinates that do relate to the sender (this is the GetCurrentPoint call in the first line of the method) but then later uses TransformToVisual to convert point coordinates into the reference frame for the page layout container that's actually several layers of containment up in the XAML. To see more context for this code (including seeing how queryPointer displays results in UI and when it's called), see the complete code example that is shown in the topic Handle pointer input.

    <Page
    x:Class="PointerInput.MainPage"
    IsTabStop="false"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:PointerInput"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d"
    Name="page">

    <Grid Background="{StaticResource ApplicationPageBackgroundThemeBrush}">
        <Grid.ColumnDefinitions>
            <ColumnDefinition Width="*" />
            <ColumnDefinition Width="150" />
        </Grid.ColumnDefinitions>
        <Grid.RowDefinitions>
            <RowDefinition Height="*" />
            <RowDefinition Height="320" />
            <RowDefinition Height="*"/>
        </Grid.RowDefinitions>
        <Canvas Name="Container" 
                Grid.Column="0"
                Grid.Row="1"
                HorizontalAlignment="Center" 
                VerticalAlignment="Center" 
                Margin="0,0,0,0" 
                Height="320"  Width="640">
            <Rectangle Name="Target" 
                       Fill="#FF0000" 
                       Stroke="Black" 
                       StrokeThickness="0"
                       Height="320" Width="640" />
        </Canvas>
        <TextBox Name="eventLog" 
                 Grid.Column="1"
                 Grid.Row="0"
                 Grid.RowSpan="3" 
                 Background="#000000" 
                 TextWrapping="Wrap" 
                 Foreground="#FFFFFF" 
                 ScrollViewer.VerticalScrollBarVisibility="Visible" 
                 BorderThickness="0"/>
    </Grid>
</Page>

<Page
    x:Class="PointerInput.MainPage"
    IsTabStop="false"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:PointerInput"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d"
    Name="page">

    <Grid Background="{StaticResource ApplicationForegroundThemeBrush}">
        <Grid.ColumnDefinitions>
            <ColumnDefinition Width="*" />
            <ColumnDefinition Width="69.458" />
            <ColumnDefinition Width="80.542"/>
        </Grid.ColumnDefinitions>
        <Grid.RowDefinitions>
            <RowDefinition Height="*" />
            <RowDefinition Height="320" />
            <RowDefinition Height="*"/>
        </Grid.RowDefinitions>
        <Canvas Name="Container" 
                Grid.Column="0"
                Grid.Row="1"
                HorizontalAlignment="Center" 
                VerticalAlignment="Center" 
                Margin="245,0" 
                Height="320"  Width="640">
            <Rectangle Name="Target" 
                       Fill="#FF0000" 
                       Stroke="Black" 
                       StrokeThickness="0"
                       Height="320" Width="640" />
        </Canvas>
        <Button Name="buttonClear"
                Foreground="White"
                Width="100"
                Height="100">
            clear
        </Button>
        <TextBox Name="eventLog" 
                 Grid.Column="1"
                 Grid.Row="0"
                 Grid.RowSpan="3" 
                 Background="#000000" 
                 TextWrapping="Wrap" 
                 Foreground="#FFFFFF" 
                 ScrollViewer.VerticalScrollBarVisibility="Visible" 
                 BorderThickness="0" Grid.ColumnSpan="2"/>
    </Grid>
</Page>

String queryPointer(PointerPoint ptrPt)
{
    String details = "";

    switch (ptrPt.PointerDevice.PointerDeviceType)
    {
        case Windows.Devices.Input.PointerDeviceType.Mouse:
            details += "
Pointer type: mouse";
            break;
        case Windows.Devices.Input.PointerDeviceType.Pen:
            details += "
Pointer type: pen";
            if (ptrPt.IsInContact)
            {
                details += "
Pressure: " + ptrPt.Properties.Pressure;
                details += "
rotation: " + ptrPt.Properties.Orientation;
                details += "
Tilt X: " + ptrPt.Properties.XTilt;
                details += "
Tilt Y: " + ptrPt.Properties.YTilt;
                details += "
Barrel button pressed: " + ptrPt.Properties.IsBarrelButtonPressed;
            }
            break;
        case Windows.Devices.Input.PointerDeviceType.Touch:
            details += "
Pointer type: touch";
            details += "
rotation: " + ptrPt.Properties.Orientation;
            details += "
Tilt X: " + ptrPt.Properties.XTilt;
            details += "
Tilt Y: " + ptrPt.Properties.YTilt;
            break;
        default:
            details += "
Pointer type: n/a";
            break;
    }

    GeneralTransform gt = Target.TransformToVisual(page);
    Point screenPoint;

    screenPoint = gt.TransformPoint(new Point(ptrPt.Position.X, ptrPt.Position.Y));
    details += "
Pointer Id: " + ptrPt.PointerId.ToString() +
        "
Pointer location (parent): " + ptrPt.Position.X + ", " + ptrPt.Position.Y +
        "
Pointer 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 += "
Pointer type: mouse";
            break;
        case Windows.Devices.Input.PointerDeviceType.Pen:
            details += "
Pointer type: pen";
            if (ptrPt.IsInContact)
            {
                details += "
Pressure: " + ptrPt.Properties.Pressure;
                details += "
rotation: " + ptrPt.Properties.Orientation;
                details += "
Tilt X: " + ptrPt.Properties.XTilt;
                details += "
Tilt Y: " + ptrPt.Properties.YTilt;
                details += "
Barrel button pressed: " + ptrPt.Properties.IsBarrelButtonPressed;
            }
            break;
        case Windows.Devices.Input.PointerDeviceType.Touch:
            details += "
Pointer type: touch";
            details += "
rotation: " + ptrPt.Properties.Orientation;
            details += "
Tilt X: " + ptrPt.Properties.XTilt;
            details += "
Tilt Y: " + ptrPt.Properties.YTilt;
            break;
        default:
            details += "
Pointer type: n/a";
            break;
    }

    GeneralTransform gt = Target.TransformToVisual(page);
    Point screenPoint;

    screenPoint = gt.TransformPoint(new Point(ptrPt.Position.X, ptrPt.Position.Y));
    details += "
Pointer Id: " + ptrPt.PointerId.ToString() +
        "
Pointer location (parent): " + ptrPt.Position.X + ", " + ptrPt.Position.Y +
        "
Pointer location (screen): " + screenPoint.X + ", " + screenPoint.Y;
    return details;
}

Remarks

Call TransformToVisual in order to get a coordinate offset between two elements in a UI. The first element being considered is the UIElement where you call TransformToVisual, the second element is the UIElement you pass as the visual parameter. For example, you can use the transform to determine how the bounds of an element are positioned in a coordinate system that is relative to a layout parent element, rather than the app's window.

TransformToVisual gives coordinate results after all considerations that affect rendering and positioning such as RenderTransform have been applied. This is useful if you're processing point values that were obtained during an animation of RenderTransform or other position changes.

The most common scenario for TransformToVisual is if you want to use a local coordinate system relative to the UIElement you call it on, and you aren't handling a real-time input event that has event data methods for converting a Point value into the object's frame of reference. After you call TransformToVisual, you can then call TransformPoint on the returned GeneralTransform.

See Also

GeneralTransformGeneralTransformGeneralTransformGeneralTransform

Define layouts with XAML

XAML two-dimensional transforms sample](http://go.microsoft.com/fwlink/p/?linkid=226868) transforms sample

Attempts to invoke a keyboard shortcut (accelerator).

public : void TryInvokeKeyboardAccelerator(ProcessKeyboardAcceleratorEventArgs args)public void TryInvokeKeyboardAccelerator(ProcessKeyboardAcceleratorEventArgs args)Public Function TryInvokeKeyboardAccelerator(args As ProcessKeyboardAcceleratorEventArgs) As void// This API is not available in Javascript.

Device family	Windows 10 Fall Creators Update (introduced v10.0.16299.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v5)

Remarks

Call this method in the OnProcessKeyboardAccelerators override when an accelerator is invoked and you want to influence the default accelerator handling.

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

public : static PlatForm::Boolean TryStartDirectManipulation(Pointer value)public static bool TryStartDirectManipulation(Pointer value)Public Static Function TryStartDirectManipulation(value As Pointer) As bool// This API is not available in Javascript.

Remarks

By default, touch input interactions in ScrollViewer elements are handled by the Direct Manipulation engine off the UI thread. An app cannot directly process the associated pointer events after Direct Manipulation processing starts. You can call CancelDirectManipulations at the start of a ScrollViewer interaction and handle the pointer events on the UI thread, which gives you the opportunity to do custom input handling in a ScrollViewer.

If you cancel Direct Manipulation processing at the start of a ScrollViewer interaction, you can call TryStartDirectManipulation to resume having Direct Manipulation process the input stream. This lets you do custom input processing first, and then resume Direct Manipulation handling to make your app more responsive to touch interactions like scrolling and zooming.

Only active touch contacts can be passed to Direct Manipulation. Using non-active or non-touch contacts causes an exception to be thrown.

Specifying a touch contact to pass to Direct Manipulation results in the framework walking up the parent chain and setting the contact on the Direct Manipulation viewport of each ScrollViewer encountered in order, until the walk reaches any element (including the original target element) that does not have a ManipulationMode that contains ManipulationModes.System. A given touch contact can only be associated with a single chain of visuals at a time. Calling TryStartDirectManipulation more than once on the same contact results in any previous chain being released.

See Also

CancelDirectManipulations()CancelDirectManipulations()CancelDirectManipulations()CancelDirectManipulations()

ManipulationStartedManipulationStartedManipulationStartedManipulationStarted

ManipulationModesManipulationModesManipulationModesManipulationModes

Gestures, manipulations, and interactions

Direct Manipulation

Ensures that all positions of child objects of a UIElement are properly updated for layout.

public : void UpdateLayout()public void UpdateLayout()Public Function UpdateLayout() As void// This API is not available in Javascript.

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.

See Also

Arrange(Rect)Arrange(Rect)Arrange(Rect)Arrange(Rect)

InvalidateArrange()InvalidateArrange()InvalidateArrange()InvalidateArrange()

Define layouts with XAML

Occurs when the access key sequence is complete to notify controls that they should hide access key visuals.

public : event TypedEventHandler AccessKeyDisplayDismissed<UIElement,  AccessKeyDisplayDismissedEventArgs>public event TypedEventHandler AccessKeyDisplayDismissed<UIElement,  AccessKeyDisplayDismissedEventArgs>Public Event AccessKeyDisplayDismissed<UIElement,  AccessKeyDisplayDismissedEventArgs>// This API is not available in Javascript.

<uiElement AccessKeyDisplayDismissed="eventhandler"/>

Device family	Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v3)

Occurs when the access key sequence is started to notify controls that they should show access key visuals.

public : event TypedEventHandler AccessKeyDisplayRequested<UIElement,  AccessKeyDisplayRequestedEventArgs>public event TypedEventHandler AccessKeyDisplayRequested<UIElement,  AccessKeyDisplayRequestedEventArgs>Public Event AccessKeyDisplayRequested<UIElement,  AccessKeyDisplayRequestedEventArgs>// This API is not available in Javascript.

<uiElement AccessKeyDisplayRequested="eventhandler"/>

Device family	Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v3)

Remarks

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

Occurs when a user completes an access key sequence to notify the element that the access key action should be invoked.

public : event TypedEventHandler AccessKeyInvoked<UIElement,  AccessKeyInvokedEventArgs>public event TypedEventHandler AccessKeyInvoked<UIElement,  AccessKeyInvokedEventArgs>Public Event AccessKeyInvoked<UIElement,  AccessKeyInvokedEventArgs>// This API is not available in Javascript.

<uiElement AccessKeyInvoked="eventhandler"/>

Device family	Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v3)

Remarks

This event indicates that an element’s access key action should be invoked. For example, this will be raised if an element’s AccessKey is "A" and the user presses Alt-A.

An access key can have one or several characters. This event occurs only when users type all the characters of an access key. For example, if an AccessKey value is "BC", the event doesn't occur when the user presses "B". The event occurs when the user presses "B", then "C".

This event occurs when the key is pressed, not when it's released.

Occurs when a single, composed character is received by the input queue.

public : event TypedEventHandler CharacterReceived<UIElement,  CharacterReceivedRoutedEventArgs>public event TypedEventHandler CharacterReceived<UIElement,  CharacterReceivedRoutedEventArgs>Public Event CharacterReceived<UIElement,  CharacterReceivedRoutedEventArgs>// This API is not available in Javascript.

<uiElement CharacterReceived="eventhandler"/>

Device family	Windows 10 Fall Creators Update (introduced v10.0.16299.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v5)

Remarks

Apps do not receive this event when an Input Method Editor (IME) is enabled. The Input Method Editor (IME) handles all keyboard input and sets Handled to true.

This event is useful for text input scenarios such as "typeahead find or search" (also known as incremental search, incremental find, or real-time suggestions) where, as the user types, the control progressively searches for and filters text based on the characters in the input queue.

The CharacterReceived event can occur at different times depending on the character entered, as the event is not fired until the composed character is registered in the input queue.

• User presses the W key (the character 'w' is received):

  • PreviewKeyDown for W

  • KeyDown for W

  • CharacterReceived

  • PreviewKeyUp for W

  • KeyUp for W

• User presses the Shift+W keys (the character 'W' is received):

  • PreviewKeyDown for Shift

  • KeyDown for Shift

  • PreviewKeyDown for W

  • KeyDown for W

  • CharacterReceived

  • PreviewKeyUp for W

  • KeyUp for W

  • PreviewKeyUp for Shift

  • KeyUp for Shift

• User presses Alt+164 using the NumPad (the character ‘ñ’ is received):

  • PreviewKeyDown for Alt

  • KeyDown for Alt

  • PreviewKeyDown for 1

  • KeyDown for 1

  • PreviewKeyUp for 1

  • KeyUp for 1

  • PreviewKeyDown for 6

  • KeyDown for 6

  • PreviewKeyUp for 6

  • KeyUp for 6

  • PreviewKeyDown for 4

  • KeyDown for 4

  • PreviewKeyUp for 4

  • KeyUp for 4

  • CharacterReceived

  • PreviewKeyUp for Alt

  • KeyUp for Alt

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 ContextCanceled<UIElement,  RoutedEventArgs>public event TypedEventHandler ContextCanceled<UIElement,  RoutedEventArgs>Public Event ContextCanceled<UIElement,  RoutedEventArgs>// This API is not available in Javascript.

<uiElement ContextCanceled="eventhandler"/>

Device family	Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v3)

Remarks

You typically handle this event for elements that can be manipulated by drag-and-drop. This event is raised when a ContextRequested event has been raised, but the element has not received a PointerReleased event before a manipulation begins. This indicates that the user intended to invoke a manipulation rather than a context flyout, so the context flyout should not be opened.

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

public : event TypedEventHandler ContextRequested<UIElement,  ContextRequestedEventArgs>public event TypedEventHandler ContextRequested<UIElement,  ContextRequestedEventArgs>Public Event ContextRequested<UIElement,  ContextRequestedEventArgs>// This API is not available in Javascript.

<uiElement ContextRequested="eventhandler"/>

Device family	Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract	Windows.Foundation.UniversalApiContract (introduced v3)

Remarks

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

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

public : event DoubleTappedEventHandler DoubleTappedpublic event DoubleTappedEventHandler DoubleTappedPublic Event DoubleTapped// This API is not available in Javascript.

<uiElement DoubleTapped="eventhandler"/>

Remarks

A DoubleTap interaction is simply two Tap interactions that occur in quick succession. The exact timing of what the system interprets as a double tap is adjustable by users through system settings.

See Touch interaction design for more info on how to use a DoubleTap interaction in your app design.

If a user interaction also fires DoubleTapped, Tapped will fire first to represent the first tap, but the second tap won't fire an additional Tapped. If you want different logic for Tapped versus DoubleTapped, your Tapped handler may need to use app-specific variables and a timer in order to avoid running on interactions that are eventually interpreted as a DoubleTap action.

A DoubleTapped event represents a gesture, whereas a PointerPressed event is a lower-level input event. DoubleTapped and PointerPressed events can fire as the result of a single user interaction. Even if a control is already handling pointer events in the control logic, or is handling manipulations, that doesn't prevent DoubleTapped from firing.

A DoubleTapped event is potentially the result of more than one pointer point. For the higher-level gesture events like DoubleTapped you no longer have immediate access to PointerPoint details such as individual PointerId values or individual coordinates. You do have access to device type (PointerDeviceType ) and for coordinates you can call GetPosition, which gives an average of the coordinates for a DoubleTap from more than one pointer point.

DoubleTapped is a routed event. Also, an element must have IsDoubleTapEnabled be true to be a DoubleTapped event source (true is the default). It is possible to handle DoubleTapped on parent elements even if IsDoubleTapEnabled is false on the parent element, if the event bubbles to a parent from an event source child element where IsDoubleTapEnabled is false. For more info on the routed event concept, see Events and routed events overview.

For touch actions and also for interaction-specific or manipulation events that are consequences of a touch action, an element must be hit-test visible in order to be the event source and fire the event that is associated with the action. UIElement.Visibility must be Visible. Other properties of derived types also affect hit-test visibility. For more info, see Events and routed events overview.

DoubleTapped supports the ability to attach event handlers to the route that will be invoked even if the event data for the event is marked Handled. See AddHandler.

Specific Windows Runtime controls may have class-based handling for the DoubleTapped input event. If so, the control probably has an override for the method OnDoubleTapped. Typically the event is marked handled by the class handler, and the DoubleTapped event is not raised for handling by any user code handlers on that control. For more info on how class-based handling for events works, see Events and routed events overview.

See Also

Quickstart: Touch input

XAML user input events sample

Occurs when the input system reports an underlying drag event with this element as the target.

public : event DragEventHandler DragEnterpublic event DragEventHandler DragEnterPublic Event DragEnter// This API is not available in Javascript.

<uiElement DragEnter="eventhandler"/>

Remarks

For a DragEnter event to occur, the value of AllowDrop on the current UIElement and on the event source must be true. Otherwise, consider using PointerEntered.

You can initiate a drag-drop action on any UIElement by calling the StartDragAsync method. Once the action is initiated, any UIElement in the app can potentially be a drop target so long as AllowDrop is true on that element. Any elements that the drag-drop action passes over can handle DragEnter, DragLeave or DragOver.

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

For touch actions, drag-drop actions, and also for interaction-specific or manipulation events that are consequences of a touch action, an element must be hit-test visible in order to be the event source and fire the event that is associated with the action. UIElement.Visibility must be Visible. Other properties of derived types also affect hit-test visibility, for example IsEnabled. For more info, see Events and routed events overview.

DragEnter supports the ability to attach event handlers to the route that will be invoked even if the event data for the event is marked Handled. See AddHandler.

Specific Windows Runtime controls may have class-based handling for the DragEnter event. If so, the control probably has an override for the method OnDragEnter. Typically the event is marked handled by the class handler, and the DragEnter event is not raised for handling by any user code handlers on that control. For more info, see Events and routed events overview.

Independent of the event occurrence, some controls may use theme animations such as DragItemThemeAnimation to visually indicate a drag behavior to the user.

Windows 8/Windows 8.1 Prior to Windows 10, the Windows Runtime implementation of drag-drop concepts permits only certain controls and input actions to initiate a drag-drop action. There is no StartDragAsync or generalized DoDragDrop method that would permit any UI element to initiate a drag-drop action. The main source of a drag-drop action in an app is when you drag the items of a list such as GridView.

See Also

DragOverDragOverDragOverDragOver

AllowDropAllowDropAllowDropAllowDrop

Events and routed events overview

Drag and drop sample (Windows 10)

Occurs when the input system reports an underlying drag event with this element as the origin.

public : event DragEventHandler DragLeavepublic event DragEventHandler DragLeavePublic Event DragLeave// This API is not available in Javascript.

<uiElement DragLeave="eventhandler"/>

Remarks

For DragLeave to occur, the value of AllowDrop on the current UIElement and on the event source must be true. Otherwise, consider using PointerExited.

You can initiate a drag-drop action on any UIElement by calling the StartDragAsync method. Once the action is initiated, any UIElement in the app can potentially be a drop target so long as AllowDrop is true on that element. Any elements that the drag-drop action passes over can handle DragEnter, DragLeave or DragOver.

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

For touch actions, drag-drop actions, and also for interaction-specific or manipulation events that are consequences of a touch action, an element must be hit-test visible in order to be the event source and fire the event that is associated with the action. UIElement.Visibility must be Visible. Other properties of derived types also affect hit-test visibility, for example IsEnabled. For more info, see Events and routed events overview.

DragLeave supports the ability to attach event handlers to the route that will be invoked even if the event data for the event is marked Handled. See AddHandler.

Specific Windows Runtime controls may have class-based handling for the DragLeave event. If so, the control probably has an override for the method OnDragLeave. Typically the event is marked handled by the class handler, and the DragLeave event is not raised for handling by any user code handlers on that control. For more info, see Events and routed events overview.

Independent of the event occurrence, some controls may use theme animations such as DragItemThemeAnimation to visually indicate a drag behavior to the user.

Windows 8/Windows 8.1 Prior to Windows 10, the Windows Runtime implementation of drag-drop concepts permits only certain controls and input actions to initiate a drag-drop action. There is no StartDragAsync or generalized DoDragDrop method that would permit any UI element to initiate a drag-drop action. The main source of a drag-drop action in an app is when you drag the items of a list such as GridView.

See Also

DragEnterDragEnterDragEnterDragEnter

AllowDropAllowDropAllowDropAllowDrop

Events and routed events overview

Drag and drop sample (Windows 10)