UIElement UIElement UIElement Class

UIElement is a base class for most of the Windows Runtime UI objects that have visual appearance and can process basic input as part of your app's user interface.

Syntax

Declaration

public class UIElementpublic class UIElementPublic Class UIElement

Inheritance Hierarchy

Remarks

UIElement is a base element: it's a class that many other Windows Runtime classes inherit from in order to support the XAML UI element model. Properties, methods and events that UIElement defines are inherited by hundreds of other Windows Runtime classes.

Although UIElement defines the events for focus reporting (GotFocus, LostFocus ), UIElement does not define an API for programmatically setting the focus. This capability is defined by the Control class.

UIElement does not expose a public constructor. Typically, you don't derive classes from either UIElement or FrameworkElement directly. More typically used base classes for derived custom classes are these classes:

The UIElement class is used as the type parameter of many properties and methods in the Windows Runtime API. For example, the Child property of Border takes a single UIElement, which represents the element that the Border is drawn around. You can provide any UIElement -derived element for such a property, including custom controls that you define.

The UIElementCollection class provides a strongly typed collection of UIElement items. UIElementCollection is used as a type for properties of objects that contain several child elements, for example for the Children property of any Panel class.

UIElement API and features

UIElement extends DependencyObject, which is another base element, and adds support for various Windows Runtime feature areas.

Input, and events for responding to user interaction

Much of the input behavior for visible elements in a UI is defined in the UIElement class. This includes the events for keyboard, mouse, touch, drag-drop, and focus interactions. For more info, see Handle pointer input, Keyboard interactions, and Custom user interactions.

Prominent API of UIElement that support input and user interaction:

Gestures and manipulations

Gestures and manipulations are also a way to handle input and user interaction. The API are listed out separately here because these events represent how the system interacts with device-level input actions and interprets them as a user interaction. Manipulations are a way to handle dynamic multi-touch interactions such as pinching and stretching. Together, the gestures and manipulations provide the touch patterns for touch interaction with Windows Store app. For more info, see Custom user interactions and Touch interaction design.

Prominent API of UIElement that support gestures and manipulations:

Basic appearance

The Visibility and Opacity properties are frequently used to adjust the appearance of an element in your UI, especially within styles, templates, and visual states. The Clip, RenderTransform, and Transitions properties are each useful for producing interactions and different looks for your UI elements.

Basic layout

The UIElement class provides a starting point for layout characteristics with properties such as DesiredSize and the Arrange(Windows.Foundation.Rect) and Measure(Windows.Foundation.Size) methods. FrameworkElement adds more layout capabilities. For more info, see Define layouts with XAML and FrameworkElement.

Routed events

Most of the input events of UIElement are routed events. A routed event enables a built-in event handling notification system, so that a parent object can handle input events from child objects in the object tree if the event remains unhandled. This input event behavior is useful for input area grouping, and for control compositing. For more info, see Events and routed events overview.

Prominent API of UIElement that support routed events: AddHandler(Windows.UI.Xaml.RoutedEvent,System.Object,System.Boolean), RemoveHandler(Windows.UI.Xaml.RoutedEvent,System.Object), **Event* properties.

Other platform support

UIElement dependency properties

Many of the read-write properties of the UIElement base element class are dependency properties. Dependency properties support some of the basic programming model features for a Windows Store app using C++, C#, or Visual Basic, such as styles and templates, data binding, XAML resource references, and property-changed logic. For more info on dependency properties and the features they support, see Dependency properties overview.

UIElement derived classes

The only Windows Runtime class that derives directly from UIElement is FrameworkElement. For a list of the classes that derive from FrameworkElement, see the "FrameworkElement derived classes" section of the FrameworkElement reference topic.

Properties summary

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

Identifies for the AccessKey dependency property.

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

Identifies for the AccessKeyScopeOwner dependency property.

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

Identifies the AllowDrop dependency property.

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

Identifies the CacheMode dependency property.

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

Identifies the CanDrag dependency property.

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

Identifies the Clip dependency property.

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

Identifies the CompositeMode dependency property.

Gets or sets the flyout associated with this element.

Identifies for the ContextFlyout dependency property.

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

Gets the identifier for the DoubleTapped routed event.

Gets the identifier for the DragEnter routed event.

Gets the identifier for the DragLeave routed event.

Gets the identifier for the DragOver routed event.

Gets the identifier for the Drop routed event.

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

Identifies the ExitDisplayModeOnAccessKeyInvoked dependency property.

Gets the identifier for the Holding routed event.

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

Identifies for the IsAccessKeyScope dependency property.

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

Identifies the IsDoubleTapEnabled dependency property.

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

Identifies the IsHitTestVisible dependency property.

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

Identifies the IsHoldingEnabled dependency property.

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

Identifies the IsRightTapEnabled dependency property.

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

Identifies the IsTapEnabled dependency property.

Gets the identifier for the KeyDown routed event.

Gets the identifier for the KeyUp routed event.

Gets the identifier for the ManipulationCompleted routed event.

Gets the identifier for the ManipulationDelta routed event.

Gets the identifier for the ManipulationInertiaStarting routed event.

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.

Identifies the ManipulationMode dependency property.

Gets the identifier for the ManipulationStarted routed event.

Gets the identifier for the ManipulationStarting routed event.

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

Identifies the IsHitTestVisible dependency property.

Gets the identifier for the PointerCanceled routed event.

Gets the identifier for the PointerCaptureLost routed event.

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

Identifies the PointerCaptures dependency property.

Gets the identifier for the PointerEntered routed event.

Gets the identifier for the PointerExited routed event.

Gets the identifier for the PointerMoved routed event.

Gets the identifier for the PointerPressed routed event.

Gets the identifier for the PointerReleased routed event.

Gets the identifier for the PointerWheelChanged routed event.

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

Identifies the Projection dependency property.

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

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

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

Identifies the RenderTransformOrigin dependency property.

Identifies the RenderTransform dependency property.

Gets the identifier for the RightTapped routed event.

Gets the identifier for the Tapped routed event.

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

Identifies the Transform3D dependency property.

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

Identifies the Transitions dependency property.

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

Identifies the UseLayoutRounding dependency property.

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.

Identifies the Visibility dependency property.

Methods summary

Adds a routed event handler for a specified routed event, adding the handler to the handler collection on the current element. Specify handledEventsToo as true to have the provided handler be invoked even if the event is handled elsewhere.

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

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

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

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

Invalidates the measurement state (layout) for a UIElement.

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

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

Releases all pointer captures held by this element.

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

Initiates a drag-and-drop operation.

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

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

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

Events summary

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

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

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

Occurs when a context input gesture continues into a manipulation gesture, to notify the element that the context flyout should not be opened.

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

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

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

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

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

Occurs when a drag operation is initiated.

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

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

Occurs when a UIElement receives focus.

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

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

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

Occurs when a UIElement loses focus.

Occurs when a manipulation on the UIElement is complete.

Occurs when the input device changes position during a manipulation.

Occurs when the input device loses contact with the UIElement object during a manipulation and inertia begins.

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

Occurs when the manipulation processor is first created.

Occurs when a pointer that made contact abnormally loses contact.

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

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

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

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

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

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

Occurs when the delta value of a pointer wheel changes.

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

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

Properties

  • AccessKey
    AccessKey
    AccessKey
    AccessKey

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

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

    Property Value

    • string
      string
      string

      The access key (mnemonic) for this element.

    Remarks

    Setting this property enables the AccessKeyDisplayRequested event to be raised.

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

  • AccessKeyProperty
    AccessKeyProperty
    AccessKeyProperty
    AccessKeyProperty

    Identifies for the AccessKey dependency property.

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

    Property Value

  • AccessKeyScopeOwner
    AccessKeyScopeOwner
    AccessKeyScopeOwner
    AccessKeyScopeOwner

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

    public DependencyObject AccessKeyScopeOwner { get; set; }public DependencyObject AccessKeyScopeOwner { get; set; }Public ReadWrite Property AccessKeyScopeOwner As DependencyObject

    Property Value

    Remarks

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

  • AccessKeyScopeOwnerProperty
    AccessKeyScopeOwnerProperty
    AccessKeyScopeOwnerProperty
    AccessKeyScopeOwnerProperty

    Identifies for the AccessKeyScopeOwner dependency property.

    public static DependencyProperty AccessKeyScopeOwnerProperty { get; }public static DependencyProperty AccessKeyScopeOwnerProperty { get; }Public Static ReadOnly Property AccessKeyScopeOwnerProperty As DependencyProperty

    Property Value

  • AllowDrop
    AllowDrop
    AllowDrop
    AllowDrop

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

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

    Property Value

    • bool
      bool
      bool

      true if this UIElement can be a drop target for purposes of drag-and-drop operations; otherwise, false. The default is false.

    Remarks

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

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

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

  • AllowDropProperty
    AllowDropProperty
    AllowDropProperty
    AllowDropProperty

    Identifies the AllowDrop dependency property.

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

    Property Value

  • CacheMode
    CacheMode
    CacheMode
    CacheMode

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

    public CacheMode CacheMode { get; set; }public CacheMode CacheMode { get; set; }Public ReadWrite Property CacheMode As CacheMode
    <uiElement CacheMode="BitmapCache" />
    

    Property Value

    • A value that indicates that rendered content should be cached as a composited bitmap when possible. If you specify a value of CacheMode, rendering operations from RenderTransform and Opacity execute on the graphics processing unit (GPU), if available. The default is null, which does not enable a cached composition mode.

    Remarks

    Set this value to enable the caching behavior that offloads RenderTransform and Opacity bitmaps to the graphics processing unit (GPU). Otherwise, leave it as null.

    For XAML, the string literal "BitmapCache" is the only enabled value you can use to set CacheMode as an attribute.

    Note

    BitmapCache is the only existing practical derived classes in the Windows Runtime API that enables this behavior (the CacheMode type is an intermediate type that exists only for infrastructure and legacy reasons).

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

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

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

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

  • CacheModeProperty
    CacheModeProperty
    CacheModeProperty
    CacheModeProperty

    Identifies the CacheMode dependency property.

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

    Property Value

  • CanDrag
    CanDrag
    CanDrag
    CanDrag

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

    public bool CanDrag { get; set; }public bool CanDrag { get; set; }Public ReadWrite Property CanDrag As bool

    Property Value

    • bool
      bool
      bool

      true if the element can be dragged as data in a drag-and-drop operation; otherwise, false. The default is false.

    Remarks

  • CanDragProperty
    CanDragProperty
    CanDragProperty
    CanDragProperty

    Identifies the CanDrag dependency property.

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

    Property Value

  • Clip
    Clip
    Clip
    Clip

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

    public RectangleGeometry Clip { get; set; }public RectangleGeometry Clip { get; set; }Public ReadWrite Property Clip As RectangleGeometry
    <uiElement>
      <uiElement.Clip>
        rectangleGeometry
      </uiElement.Clip>
    </uiElement>
    

    Property Value

    Remarks

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

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

    Examples

    This example is simple XAML markup that specifies a Clip using an inline RectangleGeometry that specifies its dimensions through an attribute syntax.

    <Canvas>
        <Image Source="Images/Water_lilies.jpg" Width="200" Height="150">
            <Image.Clip>
                <RectangleGeometry Rect="100 75 50 50"/>
            </Image.Clip>
        </Image>
    </Canvas>
    
  • ClipProperty
    ClipProperty
    ClipProperty
    ClipProperty

    Identifies the Clip dependency property.

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

    Property Value

  • CompositeMode
    CompositeMode
    CompositeMode
    CompositeMode

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

    public ElementCompositeMode CompositeMode { get; set; }public ElementCompositeMode CompositeMode { get; set; }Public ReadWrite Property CompositeMode As ElementCompositeMode
    <uiElement CompositeMode="elementCompositeModeMemberName" />
    

    Property Value

    Remarks

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

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

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

  • CompositeModeProperty
    CompositeModeProperty
    CompositeModeProperty
    CompositeModeProperty

    Identifies the CompositeMode dependency property.

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

    Property Value

  • ContextFlyout
    ContextFlyout
    ContextFlyout
    ContextFlyout

    Gets or sets the flyout associated with this element.

    public FlyoutBase ContextFlyout { get; set; }public FlyoutBase ContextFlyout { get; set; }Public ReadWrite Property ContextFlyout As FlyoutBase

    Property Value

  • ContextFlyoutProperty
    ContextFlyoutProperty
    ContextFlyoutProperty
    ContextFlyoutProperty

    Identifies for the ContextFlyout dependency property.

    public static DependencyProperty ContextFlyoutProperty { get; }public static DependencyProperty ContextFlyoutProperty { get; }Public Static ReadOnly Property ContextFlyoutProperty As DependencyProperty

    Property Value

  • DesiredSize
    DesiredSize
    DesiredSize
    DesiredSize

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

    public Size DesiredSize { get; }public Size DesiredSize { get; }Public ReadOnly Property DesiredSize As Size

    Property Value

    Remarks

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

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

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

    Examples

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

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

    Gets the identifier for the DoubleTapped routed event.

    public static RoutedEvent DoubleTappedEvent { get; }public static RoutedEvent DoubleTappedEvent { get; }Public Static ReadOnly Property DoubleTappedEvent As RoutedEvent

    Property Value

  • DragEnterEvent
    DragEnterEvent
    DragEnterEvent
    DragEnterEvent

    Gets the identifier for the DragEnter routed event.

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

    Property Value

  • DragLeaveEvent
    DragLeaveEvent
    DragLeaveEvent
    DragLeaveEvent

    Gets the identifier for the DragLeave routed event.

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

    Property Value

  • DragOverEvent
    DragOverEvent
    DragOverEvent
    DragOverEvent

    Gets the identifier for the DragOver routed event.

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

    Property Value

  • DropEvent
    DropEvent
    DropEvent
    DropEvent

    Gets the identifier for the Drop routed event.

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

    Property Value

  • ExitDisplayModeOnAccessKeyInvoked
    ExitDisplayModeOnAccessKeyInvoked
    ExitDisplayModeOnAccessKeyInvoked
    ExitDisplayModeOnAccessKeyInvoked

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

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

    Property Value

    • bool
      bool
      bool

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

  • ExitDisplayModeOnAccessKeyInvokedProperty
    ExitDisplayModeOnAccessKeyInvokedProperty
    ExitDisplayModeOnAccessKeyInvokedProperty
    ExitDisplayModeOnAccessKeyInvokedProperty

    Identifies the ExitDisplayModeOnAccessKeyInvoked dependency property.

    public static DependencyProperty ExitDisplayModeOnAccessKeyInvokedProperty { get; }public static DependencyProperty ExitDisplayModeOnAccessKeyInvokedProperty { get; }Public Static ReadOnly Property ExitDisplayModeOnAccessKeyInvokedProperty As DependencyProperty

    Property Value

  • HoldingEvent
    HoldingEvent
    HoldingEvent
    HoldingEvent

    Gets the identifier for the Holding routed event.

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

    Property Value

  • IsAccessKeyScope
    IsAccessKeyScope
    IsAccessKeyScope
    IsAccessKeyScope

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

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

    Property Value

    • bool
      bool
      bool

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

  • IsAccessKeyScopeProperty
    IsAccessKeyScopeProperty
    IsAccessKeyScopeProperty
    IsAccessKeyScopeProperty

    Identifies for the IsAccessKeyScope dependency property.

    public static DependencyProperty IsAccessKeyScopeProperty { get; }public static DependencyProperty IsAccessKeyScopeProperty { get; }Public Static ReadOnly Property IsAccessKeyScopeProperty As DependencyProperty

    Property Value

  • IsDoubleTapEnabled
    IsDoubleTapEnabled
    IsDoubleTapEnabled
    IsDoubleTapEnabled

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

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

    Property Value

    • bool
      bool
      bool

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

    Remarks

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

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

  • IsDoubleTapEnabledProperty
    IsDoubleTapEnabledProperty
    IsDoubleTapEnabledProperty
    IsDoubleTapEnabledProperty

    Identifies the IsDoubleTapEnabled dependency property.

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

    Property Value

  • IsHitTestVisible
    IsHitTestVisible
    IsHitTestVisible
    IsHitTestVisible

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

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

    Property Value

    • bool
      bool
      bool

      true if the contained area of this UIElement can be used for hit testing; otherwise, false. The default is true.

  • IsHitTestVisibleProperty
    IsHitTestVisibleProperty
    IsHitTestVisibleProperty
    IsHitTestVisibleProperty

    Identifies the IsHitTestVisible dependency property.

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

    Property Value

  • IsHoldingEnabled
    IsHoldingEnabled
    IsHoldingEnabled
    IsHoldingEnabled

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

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

    Property Value

    • bool
      bool
      bool

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

    Remarks

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

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

  • IsHoldingEnabledProperty
    IsHoldingEnabledProperty
    IsHoldingEnabledProperty
    IsHoldingEnabledProperty

    Identifies the IsHoldingEnabled dependency property.

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

    Property Value

  • IsRightTapEnabled
    IsRightTapEnabled
    IsRightTapEnabled
    IsRightTapEnabled

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

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

    Property Value

    • bool
      bool
      bool

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

    Remarks

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

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

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

  • IsRightTapEnabledProperty
    IsRightTapEnabledProperty
    IsRightTapEnabledProperty
    IsRightTapEnabledProperty

    Identifies the IsRightTapEnabled dependency property.

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

    Property Value

  • IsTapEnabled
    IsTapEnabled
    IsTapEnabled
    IsTapEnabled

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

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

    Property Value

    • bool
      bool
      bool

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

    Remarks

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

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

  • IsTapEnabledProperty
    IsTapEnabledProperty
    IsTapEnabledProperty
    IsTapEnabledProperty

    Identifies the IsTapEnabled dependency property.

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

    Property Value

  • KeyDownEvent
    KeyDownEvent
    KeyDownEvent
    KeyDownEvent

    Gets the identifier for the KeyDown routed event.

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

    Property Value

  • KeyUpEvent
    KeyUpEvent
    KeyUpEvent
    KeyUpEvent

    Gets the identifier for the KeyUp routed event.

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

    Property Value

  • ManipulationCompletedEvent
    ManipulationCompletedEvent
    ManipulationCompletedEvent
    ManipulationCompletedEvent

    Gets the identifier for the ManipulationCompleted routed event.

    public static RoutedEvent ManipulationCompletedEvent { get; }public static RoutedEvent ManipulationCompletedEvent { get; }Public Static ReadOnly Property ManipulationCompletedEvent As RoutedEvent

    Property Value

  • ManipulationDeltaEvent
    ManipulationDeltaEvent
    ManipulationDeltaEvent
    ManipulationDeltaEvent

    Gets the identifier for the ManipulationDelta routed event.

    public static RoutedEvent ManipulationDeltaEvent { get; }public static RoutedEvent ManipulationDeltaEvent { get; }Public Static ReadOnly Property ManipulationDeltaEvent As RoutedEvent

    Property Value

  • ManipulationInertiaStartingEvent
    ManipulationInertiaStartingEvent
    ManipulationInertiaStartingEvent
    ManipulationInertiaStartingEvent

    Gets the identifier for the ManipulationInertiaStarting routed event.

    public static RoutedEvent ManipulationInertiaStartingEvent { get; }public static RoutedEvent ManipulationInertiaStartingEvent { get; }Public Static ReadOnly Property ManipulationInertiaStartingEvent As RoutedEvent

    Property Value

  • ManipulationMode
    ManipulationMode
    ManipulationMode
    ManipulationMode

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

    public ManipulationModes ManipulationMode { get; set; }public ManipulationModes ManipulationMode { get; set; }Public ReadWrite Property ManipulationMode As ManipulationModes
    <uiElement ManipulationMode="All"/>
    -or-
    <uiElement ManipulationMode="None"/>
    -or-
    <uiElement ManipulationMode="singleManipulationModesMemberName"/>
    -or-
    <uiElement ManipulationMode="relatedManipulationModesNames"/>
    
    

    Property Value

    Remarks

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

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

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

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

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

    Windows 8 behavior

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

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

  • ManipulationModeProperty
    ManipulationModeProperty
    ManipulationModeProperty
    ManipulationModeProperty

    Identifies the ManipulationMode dependency property.

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

    Property Value

  • ManipulationStartedEvent
    ManipulationStartedEvent
    ManipulationStartedEvent
    ManipulationStartedEvent

    Gets the identifier for the ManipulationStarted routed event.

    public static RoutedEvent ManipulationStartedEvent { get; }public static RoutedEvent ManipulationStartedEvent { get; }Public Static ReadOnly Property ManipulationStartedEvent As RoutedEvent

    Property Value

  • ManipulationStartingEvent
    ManipulationStartingEvent
    ManipulationStartingEvent
    ManipulationStartingEvent

    Gets the identifier for the ManipulationStarting routed event.

    public static RoutedEvent ManipulationStartingEvent { get; }public static RoutedEvent ManipulationStartingEvent { get; }Public Static ReadOnly Property ManipulationStartingEvent As RoutedEvent

    Property Value

  • Opacity
    Opacity
    Opacity
    Opacity

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

    public double Opacity { get; set; }public double Opacity { get; set; }Public ReadWrite Property Opacity As double
    <uiElement Opacity="double" .../>
    

    Property Value

    • double
      double
      double

      A value between 0 and 1.0 that declares the opacity factor, with 1.0 meaning full opacity and 0 meaning transparent. The default value is 1.0.

    Remarks

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

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

    Opacity and hit-testing

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

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

    Examples

    This example uses a Storyboard and DoubleAnimation to target Opacity. This animates the Opacity to create an app-specific decorative fade-in animation over a one second duration.

      <UserControl x:Class="animation_ovw_intro.Page"
      xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
      xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 
      Width="400" Height="300">
    
      <StackPanel>
        <StackPanel.Resources>
          <!-- Animates the rectangle's opacity. -->
          <Storyboard x:Name="myStoryboard">
            <DoubleAnimation
              Storyboard.TargetName="MyAnimatedRectangle"
              Storyboard.TargetProperty="Opacity"
              From="1.0" To="0.0" Duration="0:0:1" 
              AutoReverse="True" 
              RepeatBehavior="Forever"/>
           </Storyboard>
        </StackPanel.Resources>
        <TextBlock Margin="10">Click on the rectangle to start the animation.</TextBlock>
    
        <Rectangle PointerPressed="Item_Clicked"
          x:Name="MyAnimatedRectangle"
          Width="100" Height="100" Fill="Blue" />
    
      </StackPanel>
    </UserControl>
    
    ' When the user clicks the Rectangle, the animation
    ' begins.
    Private Sub Pointer_Clicked(ByVal sender As Object, ByVal e As PointerRoutedEventArgs)
        myStoryboard.Begin()
    End Sub
    
  • OpacityProperty
    OpacityProperty
    OpacityProperty
    OpacityProperty

    Identifies the IsHitTestVisible dependency property.

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

    Property Value

  • PointerCanceledEvent
    PointerCanceledEvent
    PointerCanceledEvent
    PointerCanceledEvent

    Gets the identifier for the PointerCanceled routed event.

    public static RoutedEvent PointerCanceledEvent { get; }public static RoutedEvent PointerCanceledEvent { get; }Public Static ReadOnly Property PointerCanceledEvent As RoutedEvent

    Property Value

  • PointerCaptureLostEvent
    PointerCaptureLostEvent
    PointerCaptureLostEvent
    PointerCaptureLostEvent

    Gets the identifier for the PointerCaptureLost routed event.

    public static RoutedEvent PointerCaptureLostEvent { get; }public static RoutedEvent PointerCaptureLostEvent { get; }Public Static ReadOnly Property PointerCaptureLostEvent As RoutedEvent

    Property Value

  • PointerCaptures
    PointerCaptures
    PointerCaptures
    PointerCaptures

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

    public IVectorView<Pointer> PointerCaptures { get; }public IVectorView<Pointer> PointerCaptures { get; }Public ReadOnly Property PointerCaptures As IVectorView<Pointer>

    Property Value

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

    Remarks

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

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

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

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

  • PointerCapturesProperty
    PointerCapturesProperty
    PointerCapturesProperty
    PointerCapturesProperty

    Identifies the PointerCaptures dependency property.

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

    Property Value

  • PointerEnteredEvent
    PointerEnteredEvent
    PointerEnteredEvent
    PointerEnteredEvent

    Gets the identifier for the PointerEntered routed event.

    public static RoutedEvent PointerEnteredEvent { get; }public static RoutedEvent PointerEnteredEvent { get; }Public Static ReadOnly Property PointerEnteredEvent As RoutedEvent

    Property Value

  • PointerExitedEvent
    PointerExitedEvent
    PointerExitedEvent
    PointerExitedEvent

    Gets the identifier for the PointerExited routed event.

    public static RoutedEvent PointerExitedEvent { get; }public static RoutedEvent PointerExitedEvent { get; }Public Static ReadOnly Property PointerExitedEvent As RoutedEvent

    Property Value

  • PointerMovedEvent
    PointerMovedEvent
    PointerMovedEvent
    PointerMovedEvent

    Gets the identifier for the PointerMoved routed event.

    public static RoutedEvent PointerMovedEvent { get; }public static RoutedEvent PointerMovedEvent { get; }Public Static ReadOnly Property PointerMovedEvent As RoutedEvent

    Property Value

  • PointerPressedEvent
    PointerPressedEvent
    PointerPressedEvent
    PointerPressedEvent

    Gets the identifier for the PointerPressed routed event.

    public static RoutedEvent PointerPressedEvent { get; }public static RoutedEvent PointerPressedEvent { get; }Public Static ReadOnly Property PointerPressedEvent As RoutedEvent

    Property Value

  • PointerReleasedEvent
    PointerReleasedEvent
    PointerReleasedEvent
    PointerReleasedEvent

    Gets the identifier for the PointerReleased routed event.

    public static RoutedEvent PointerReleasedEvent { get; }public static RoutedEvent PointerReleasedEvent { get; }Public Static ReadOnly Property PointerReleasedEvent As RoutedEvent

    Property Value

  • PointerWheelChangedEvent
    PointerWheelChangedEvent
    PointerWheelChangedEvent
    PointerWheelChangedEvent

    Gets the identifier for the PointerWheelChanged routed event.

    public static RoutedEvent PointerWheelChangedEvent { get; }public static RoutedEvent PointerWheelChangedEvent { get; }Public Static ReadOnly Property PointerWheelChangedEvent As RoutedEvent

    Property Value

  • Projection
    Projection
    Projection
    Projection

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

    public Projection Projection { get; set; }public Projection Projection { get; set; }Public ReadWrite Property Projection As Projection
    <uiElement>
      <uiElement.Projection>
        singleProjection
      </uiElement.Projection>
    </uiElement>
    

    Property Value

    Remarks

    Projection and RenderTransform with a SkewTransform can achieve similar results, a Projection is probably more versatile, especially if you want a sense of perspective change applied to the element.

    Projection is the base class type that this property uses, but Projection does not implement a practical behavior. Use either Matrix3DProjection or PlaneProjection.

    The value of Projection is overridden by PointerDownThemeAnimation and PointerUpThemeAnimation.

    Examples

    This example shows how to apply a basic PlaneProjection in the initial page XAML.

    <StackPanel Margin="35" Background="Gray">
        <StackPanel.Projection>
            <PlaneProjection RotationX="-35" RotationY="-35" RotationZ="15"  />
        </StackPanel.Projection>
        <TextBlock Margin="10">Type Something Below</TextBlock>
        <TextBox Margin="10"></TextBox>
        <Button Margin="10" Content="Click" Width="100" />
    </StackPanel>
    
  • ProjectionProperty
    ProjectionProperty
    ProjectionProperty
    ProjectionProperty

    Identifies the Projection dependency property.

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

    Property Value

  • RenderSize
    RenderSize
    RenderSize
    RenderSize

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

    public Size RenderSize { get; }public Size RenderSize { get; }Public ReadOnly Property RenderSize As Size

    Property Value

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

    Remarks

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

  • RenderTransform
    RenderTransform
    RenderTransform
    RenderTransform

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

    public Transform RenderTransform { get; set; }public Transform RenderTransform { get; set; }Public ReadWrite Property RenderTransform As Transform
    <uiElement>
      <uiElement.RenderTransform>
        singleTransform
      </uiElement.RenderTransform>
    </uiElement>
    

    Property Value

    Remarks

    You can animate a transform, if you target sub-properties of the specific transform being used that take Double values. Or you can use ObjectAnimationUsingKeyFrames to cycle through distinct transforms. Classes such as QuarticEase show some example XAML.

    If you do animate RenderTransform, make sure there is an existing starting Transform value, even if it is all at default values. You can't animate a RenderTransform value that is initially null.

    The value of RenderTransform is overridden by PointerDownThemeAnimation and PointerUpThemeAnimation.

    Examples

    This XAML defines a Matrix that provides data for a MatrixTransform applied to a rectangular shape as its RenderTransform. In this case, the matrix combines an offset (OffsetX and OffsetY) and a skew (M12). Note that this same effect could have been produced by combining a TranslateTransform and a SkewTransform; whether to use a single Matrix or combinations of discrete transforms (with TransformGroup ) is a matter of coding style; the results are identical.

    <Rectangle Width="60" Height="60" Fill="Blue">
      <Rectangle.RenderTransform>
        <MatrixTransform>
          <MatrixTransform.Matrix >
            <!-- This matrix transforms the x,y position of the rectangle and skews it. -->
            <Matrix OffsetX="30" OffsetY="100" M12="0.5" />
          </MatrixTransform.Matrix>
        </MatrixTransform>
      </Rectangle.RenderTransform>
    </Rectangle>
    
  • RenderTransformOrigin
    RenderTransformOrigin
    RenderTransformOrigin
    RenderTransformOrigin

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

    public Point RenderTransformOrigin { get; set; }public Point RenderTransformOrigin { get; set; }Public ReadWrite Property RenderTransformOrigin As Point
    <uiElement RenderTransformOrigin="x,y"/>
    

    Property Value

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

    Remarks

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

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

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

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

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

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

    Examples

    This XAML example shows how to set RenderTransformOrigin on the element in the initial XAML. An animation that runs on an initially default CompositeTransform can use the RenderTransformOrigin to modify both the scale and rotate transforms to apply to the circles's center rather than the default 0,0 coordinate origin. This makes it appear as if the circle is spinning around its center and shrinking in place.

    Note

    To start the animation you'd need to retrieve it from Resources and call Begin(); that code is not shown.

            <Ellipse x:Name="e1" RenderTransformOrigin=".5,.5" Height="100" Width="100" Loaded="e1_Loaded_1">
                <Ellipse.Fill>
                    <LinearGradientBrush>
                        <GradientStop Color="Red" Offset="0"/>
                        <GradientStop Color="Green" Offset="1"/>
                    </LinearGradientBrush>
                </Ellipse.Fill>
                <Ellipse.RenderTransform>
                    <CompositeTransform />
                </Ellipse.RenderTransform>
                <Ellipse.Resources>
                    <Storyboard x:Name="esb1" >
                        <DoubleAnimation RepeatBehavior="3x" Duration="0:0:3" From="0" To="360" Storyboard.TargetName="e1" 
                          Storyboard.TargetProperty="(UIElement.RenderTransform).(CompositeTransform.Rotation)" />
                        <DoubleAnimation RepeatBehavior="1x" Duration="0:0:7" From="1" To="0" Storyboard.TargetName="e1" 
                          Storyboard.TargetProperty="(UIElement.RenderTransform).(CompositeTransform.ScaleX)" />
                        <DoubleAnimation RepeatBehavior="1x" Duration="0:0:7" From="1" To="0" Storyboard.TargetName="e1" 
                          Storyboard.TargetProperty="(UIElement.RenderTransform).(CompositeTransform.ScaleY)" />
                    </Storyboard>
                </Ellipse.Resources>
            </Ellipse>
    
  • RenderTransformOriginProperty
    RenderTransformOriginProperty
    RenderTransformOriginProperty
    RenderTransformOriginProperty

    Identifies the RenderTransformOrigin dependency property.

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

    Property Value

  • RenderTransformProperty
    RenderTransformProperty
    RenderTransformProperty
    RenderTransformProperty

    Identifies the RenderTransform dependency property.

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

    Property Value

  • RightTappedEvent
    RightTappedEvent
    RightTappedEvent
    RightTappedEvent

    Gets the identifier for the RightTapped routed event.

    public static RoutedEvent RightTappedEvent { get; }public static RoutedEvent RightTappedEvent { get; }Public Static ReadOnly Property RightTappedEvent As RoutedEvent

    Property Value

  • TappedEvent
    TappedEvent
    TappedEvent
    TappedEvent

    Gets the identifier for the Tapped routed event.

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

    Property Value

  • Transform3D
    Transform3D
    Transform3D
    Transform3D

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

    public Transform3D Transform3D { get; set; }public Transform3D Transform3D { get; set; }Public ReadWrite Property Transform3D As Transform3D

    Property Value

    Remarks

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

    PerspectiveTransform3D and CompositeTransform3D

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

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

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

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

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

    Rectangles with 3-D transforms In this example, a PerspectiveTransform3D is attached to the root StackPanel and provides a shared perspective viewport for the panel’s children.

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

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

    Animating CompositeTransform3D

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

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

    <StackPanel Orientation="Horizontal" Loaded="StackPanel_Loaded">
        <StackPanel.Resources>
            <Storyboard x:Name="rect2Storyboard">
                <DoubleAnimation 
                    Storyboard.TargetName="rectangle2"
                    Storyboard.TargetProperty="(UIElement.Transform3D).(CompositeTransform3D.RotationY)"
                    From="0" To="-30" Duration="0:0:5"/>
                <DoubleAnimation
                    Storyboard.TargetName="rectangle2"
                    Storyboard.TargetProperty="(UIElement.Transform3D).(CompositeTransform3D.TranslateZ)"
                    From="175" To="-75" Duration="0:0:10"/>
            </Storyboard>
        </StackPanel.Resources>
        <StackPanel.Transform3D>
            <PerspectiveTransform3D />
        </StackPanel.Transform3D>
    
        <Rectangle Width="300" Height="200" Fill="CornflowerBlue" />
    
        <Rectangle x:Name="rectangle2" Width="300" Height="200" Fill="CadetBlue" Margin="10">
            <Rectangle.Transform3D>
                <CompositeTransform3D CenterX="150" />
            </Rectangle.Transform3D>
        </Rectangle>
    
        <Rectangle Width="300" Height="200" Fill="OrangeRed">
            <Rectangle.Transform3D>
                <CompositeTransform3D TranslateZ="-150" />
            </Rectangle.Transform3D>
        </Rectangle>
    </StackPanel>
    
    private void StackPanel_Loaded(object sender, RoutedEventArgs e)
    {
        rect2Storyboard.Begin();
    }
    

    Transform3D and PlaneProjection

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

    Note

    Transform3D does not affect the order in which elements are drawn. Elements further away from the viewer along the Z-axis might still be rendered above elements that are closer. You can use the ZIndexProperty attached property and the position of elements in the XAML visual tree to manage the drawing order of elements in your UI.

  • Transform3DProperty
    Transform3DProperty
    Transform3DProperty
    Transform3DProperty

    Identifies the Transform3D dependency property.

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

    Property Value

  • Transitions
    Transitions
    Transitions
    Transitions

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

    public TransitionCollection Transitions { get; set; }public TransitionCollection Transitions { get; set; }Public ReadWrite Property Transitions As TransitionCollection
    <uielement>
      <uielement.Transitions>
        <TransitionCollection>
          oneOrMoreTransitions
        </TransitionCollection>
      </uielement.Transitions>
    </uielement>
    

    Property Value

    Remarks

    Important

    The XAML syntax for all properties that use a TransitionCollection value is unusual in that you must declare an explicit TransitionCollection object element as the value, and then provide object elements as child elements of TransitionCollection for each of the transition animations you want to use. For most other XAML collection properties you could omit the collection object element because it can be implicit, but properties that use TransitionCollection don't support the implicit collection usage. For more info on implicit collections and XAML, see XAML syntax guide.

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

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

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

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

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

    Examples

    This XAML example shows a single EntranceThemeTransition as defined in a Style for a Button. Transition animation properties are typically set in styles and templates rather than as properties directly in a UI definition. Styles are typically stored as a XAML resource.

    <Grid Background="{StaticResource ApplicationPageBackgroundBrush}">
        <Grid.Resources>
            <Style x:Key="DefaultButtonStyle" TargetType="Button">
                <Setter Property="Transitions">
                    <Setter.Value>
                        <TransitionCollection>
                            <EntranceThemeTransition/>
                        </TransitionCollection>
                    </Setter.Value>
                </Setter>
            </Style>
        </Grid.Resources>
    
        <Button Style="{StaticResource DefaultButtonStyle}" 
                Content="EntranceThemeTransition style applied" />
    
    </Grid>
    
  • TransitionsProperty
    TransitionsProperty
    TransitionsProperty
    TransitionsProperty

    Identifies the Transitions dependency property.

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

    Property Value

  • UseLayoutRounding
    UseLayoutRounding
    UseLayoutRounding
    UseLayoutRounding

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

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

    Property Value

    • bool
      bool
      bool

      true if rendering and layout should use layout rounding to whole pixels; otherwise, false. The default is true.

    Remarks

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

    Layout rounding affects aliasing as well as positioning.

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

  • UseLayoutRoundingProperty
    UseLayoutRoundingProperty
    UseLayoutRoundingProperty
    UseLayoutRoundingProperty

    Identifies the UseLayoutRounding dependency property.

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

    Property Value

  • Visibility
    Visibility
    Visibility
    Visibility

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

    public Visibility Visibility { get; set; }public Visibility Visibility { get; set; }Public ReadWrite Property Visibility As Visibility
    <uiElement Visibility="Visible"/>
    -or-
    <uiElement Visibility="Collapsed"/>
    

    Property Value

    Remarks

    A UI element that has Visibility equals Collapsed is still loaded along with the rest of the XAML on a page and exists in the runtime object tree.

    An element that has Visibility equals Collapsed has no location in the UI and does not participate in input or hit testing. They are also not in a tab sequence and cannot be focused, not even programmatically. If you still want input, focus or hit testing, rather than set Visibility use a zero Opacity.

    BooleanToVisibilityConverter

    A common scenario in apps that use data from a data source is to identify a property of the data or the view model for the data that controls whether the data should display. A related scenario is writing a template that can alter the Visibility of a control part based on a Boolean property of the parent control or of another part. To make it easier to define this behavior as part of a Binding, some of the default project templates include a BooleanToVisibilityConverter helper class in the Common folder. For more info on how to use a value converter for a data binding, see IValueConverter.

    Examples

    Visibility in a visual state As part of defining visual states for a control, you will sometimes want to change the Visibility state of an object to** Collapsed**. Visual states rely on animations. The property value type of Visibility is Visibility, an enumeration. To animate values that are enumerations, you must use a DiscreteObjectKeyFrame. (You also use this technique for Boolean values). This XAML example shows a visual state that uses DiscreteObjectKeyFrame to change visibility.

    <VisualState x:Name="Focused">
      <Storyboard>
        <ObjectAnimationUsingKeyFrames Storyboard.TargetName="FocusVisualElement" Storyboard.TargetProperty="Visibility" Duration="0">
          <DiscreteObjectKeyFrame KeyTime="0" Value="Visible"/>
        </ObjectAnimationUsingKeyFrames>
      </Storyboard>
    </VisualState>
    
  • VisibilityProperty
    VisibilityProperty
    VisibilityProperty
    VisibilityProperty

    Identifies the Visibility dependency property.

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

    Property Value

Methods

  • AddHandler(Windows.UI.Xaml.RoutedEvent,System.Object,System.Boolean)
    AddHandler(Windows.UI.Xaml.RoutedEvent,System.Object,System.Boolean)
    AddHandler(Windows.UI.Xaml.RoutedEvent,System.Object,System.Boolean)
    AddHandler(Windows.UI.Xaml.RoutedEvent,System.Object,System.Boolean)

    Adds a routed event handler for a specified routed event, adding the handler to the handler collection on the current element. Specify handledEventsToo as true to have the provided handler be invoked even if the event is handled elsewhere.

    public void AddHandler(Windows.UI.Xaml.RoutedEvent routedEvent,System.Object handler,System.Boolean handledEventsToo)public void AddHandler(Windows.UI.Xaml.RoutedEvent routedEvent,System.Object handler,System.Boolean handledEventsToo)Public Function AddHandler(routedEvent As Windows.UI.Xaml.RoutedEvent,handler As System.Object,handledEventsToo As System.Boolean) As void

    Parameters

    • routedEvent

      An identifier for the routed event to be handled.

    • handler
      System.Object
      System.Object
      System.Object

      A reference to the handler implementation.

    • handledEventsToo
      System.Boolean
      System.Boolean
      System.Boolean

      true to register the handler such that it is invoked even when the routed event is marked handled in its event data.

      false to register the handler with the default condition that it will not be invoked if the routed event is already marked handled. The default is false.

      Do not routinely ask to rehandle a routed event, because it interferes with the intended design of the Windows Runtime event system for control compositing.

    Remarks

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

    Routed event identifiers

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

    Here is a list of routed events that expose a routed event identifier, and thus can be processed by handlers that are registered by an AddHandler(Windows.UI.Xaml.RoutedEvent,System.Object,System.Boolean) call:

    The handler parameter

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

    When to use handledEventsToo

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

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

    Examples

    This example shows the basic syntax for wiring an event handler with AddHandler(Windows.UI.Xaml.RoutedEvent,System.Object,System.Boolean) and handledEventsToo as true. In this case the event being wired is Tapped. The typical place to wire handlers is either Loaded for a page or OnApplyTemplate for a templated control.

    void MainPage::pageRoot_Tapped(Platform::Object^ sender, Windows::UI::Xaml::Input::TappedRoutedEventArgs^ e)
    {
         //implementation
    }
    void MainPage::pageRoot_Loaded(Platform::Object^ sender, Windows::UI::Xaml::RoutedEventArgs^ e)
    {
         this->AddHandler(UIElement::TappedEvent, ref new TappedEventHandler(this, &MainPage::pageRoot_Tapped), true);
    }
    
    private void pageRoot_Tapped(object sender, TappedRoutedEventArgs e)
    {
        //implementation
    }
    private void pageRoot_Loaded_1(object sender, RoutedEventArgs e)
    {
        this.AddHandler(UIElement.TappedEvent, new TappedEventHandler(pageRoot_Tapped), true);
    }
    
    Private Sub Page_Tapped(sender As Object, e As TappedRoutedEventArgs)
        ' implementation
    End Sub
    Private Sub Page_Loaded_1(sender As Object, e As RoutedEventArgs)
        Me.AddHandler(UIElement.TappedEvent, New TappedEventHandler(AddressOf Page_Tapped), True)
    End Sub
    
  • Arrange(Windows.Foundation.Rect)
    Arrange(Windows.Foundation.Rect)
    Arrange(Windows.Foundation.Rect)
    Arrange(Windows.Foundation.Rect)

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

    public void Arrange(Windows.Foundation.Rect finalRect)public void Arrange(Windows.Foundation.Rect finalRect)Public Function Arrange(finalRect As Windows.Foundation.Rect) As void

    Parameters

    • finalRect

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

    Remarks

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

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

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

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

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

    Examples

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

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

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

    public bool CancelDirectManipulations()public bool CancelDirectManipulations()Public Function CancelDirectManipulations() As bool

    Returns

    • bool
      bool
      bool

      true if a ScrollViewer parent exists and setting the value resulted in canceling the panning/zooming action. false if calling the method results in no action.

    Remarks

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

  • CapturePointer(Windows.UI.Xaml.Input.Pointer)
    CapturePointer(Windows.UI.Xaml.Input.Pointer)
    CapturePointer(Windows.UI.Xaml.Input.Pointer)
    CapturePointer(Windows.UI.Xaml.Input.Pointer)

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

    public bool CapturePointer(Windows.UI.Xaml.Input.Pointer value)public bool CapturePointer(Windows.UI.Xaml.Input.Pointer value)Public Function CapturePointer(value As Windows.UI.Xaml.Input.Pointer) As bool

    Parameters

    Returns

    • bool
      bool
      bool

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

    Remarks

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

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

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

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

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

    The CapturePointer(Windows.UI.Xaml.Input.Pointer) method will return false if the pointer was already captured.

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

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

    Tip

    Don't try to use CapturePointer(Windows.UI.Xaml.Input.Pointer) outside the scope of pointer-relevant input event handlers. Unless you have a Pointer that you're sure is associated with a pointer that's permitted to have pointer capture at that time, your CapturePointer(Windows.UI.Xaml.Input.Pointer) call won't have any effect. There's no practical way to generate a new Pointer and call CapturePointer(Windows.UI.Xaml.Input.Pointer) using that new pointer. You should only use the Pointer references the system is providing to you through the event data of the pointer-related input events.

    Examples

    This example shows calling CapturePointer(Windows.UI.Xaml.Input.Pointer) based on handling PointerPressed. It also shows a pattern for tracking and counting pointer references.

    int _pointerCount;
    
    public Scenario2()
    {
        this.InitializeComponent();
        bEnteredExited.PointerEntered += bEnteredExited_PointerEntered;
        bEnteredExited.PointerExited += bEnteredExited_PointerExited;
        bEnteredExited.PointerPressed += bEnteredExited_PointerPressed;
        bEnteredExited.PointerReleased += bEnteredExited_PointerReleased;
        bEnteredExited.PointerMoved += bEnteredExited_PointerMoved;
    
        // To code for multiple Pointers (that is, fingers), 
        // we track how many entered/exited.
        _pointerCount = 0;
    }
    
    private void bEnteredExited_PointerMoved(object sender, 
        PointerRoutedEventArgs e)
    {
        Scenario2UpdateVisuals(sender as Border, "Moved");
    }
    
    private void bEnteredExited_PointerReleased(object sender, 
        PointerRoutedEventArgs e)
    {
        ((Border)sender).ReleasePointerCapture(e.Pointer);
        txtCaptureStatus.Text = string.Empty;
    }
    
    //Can only get capture on PointerPressed (i.e. touch down, mouse click, pen press)
    private void bEnteredExited_PointerPressed(object sender, 
        PointerRoutedEventArgs e)
    {
        if (tbPointerCapture.IsOn)
        {
            bool _hasCapture = ((Border)sender).CapturePointer(e.Pointer);
            txtCaptureStatus.Text = "Got Capture: " + _hasCapture;
        }
    }
    
    private void bEnteredExited_PointerExited(object sender, 
        PointerRoutedEventArgs e)
    {
        _pointerCount--;
        Scenario2UpdateVisuals(sender as Border, "Exited");
    }
    
    private void bEnteredExited_PointerEntered(object sender, 
        PointerRoutedEventArgs e)
    {
        _pointerCount++;
        Scenario2UpdateVisuals(sender as Border, "Entered");
    }
    
    private void Scenario2UpdateVisuals(Border border, 
        String eventDescription)
    {
        switch (eventDescription.ToLower())
        {
            case "exited":
                if (_pointerCount <= 0)
                {
                    border.Background = new SolidColorBrush(Colors.Red);
                    bEnteredExitedTextBlock.Text = eventDescription;
                }
                break;
            case "moved":
                RotateTransform rt = 
                    (RotateTransform)bEnteredExitedTimer.RenderTransform;
                rt.Angle += 2;
                if (rt.Angle > 360) rt.Angle -= 360;
                break;
            default:
                border.Background = new SolidColorBrush(Colors.Green);
                bEnteredExitedTextBlock.Text = eventDescription;
                break;
        }
    }
    
    private void Scenario2Reset(object sender, RoutedEventArgs e)
    {
        Scenario2Reset();
    }
    
    private void Scenario2Reset()
    {
        bEnteredExited.Background = new SolidColorBrush(Colors.Green);
        bEnteredExitedTextBlock.Text = string.Empty;
    }
    
    Private _pointerCount As Integer
    
    Public Sub New()
        Me.InitializeComponent()
        AddHandler bEnteredExited.PointerEntered, AddressOf bEnteredExited_PointerEntered
        AddHandler bEnteredExited.PointerExited, AddressOf bEnteredExited_PointerExited
        AddHandler bEnteredExited.PointerPressed, AddressOf bEnteredExited_PointerPressed
        AddHandler bEnteredExited.PointerReleased, AddressOf bEnteredExited_PointerReleased
        AddHandler bEnteredExited.PointerMoved, AddressOf bEnteredExited_PointerMoved
    
        'To code for multiple Pointers (i.e. Fingers) we track how many entered/exited.
        _pointerCount = 0
    End Sub
    
    ''' <summary>
    ''' Invoked when this page is about to be displayed in a Frame.
    ''' </summary>
    ''' <param name="e">Event data that describes how this page was reached.  The Parameter
    ''' property is typically used to configure the page.</param>
    Protected Overrides Sub OnNavigatedTo(e As NavigationEventArgs)
    End Sub
    
    Private Sub bEnteredExited_PointerMoved(sender As Object, e As PointerRoutedEventArgs)
        Scenario2UpdateVisuals(TryCast(sender, Border), "Moved")
    End Sub
    
    Private Sub bEnteredExited_PointerReleased(sender As Object, e As PointerRoutedEventArgs)
        DirectCast(sender, Border).ReleasePointerCapture(e.Pointer)
        txtCaptureStatus.Text = String.Empty
    End Sub
    
    'Can only get capture on PointerPressed (i.e. touch down, mouse click, pen press)
    Private Sub bEnteredExited_PointerPressed(sender As Object, e As PointerRoutedEventArgs)
        If tbPointerCapture.IsOn Then
            Dim _hasCapture As Boolean = DirectCast(sender, Border).CapturePointer(e.Pointer)
            txtCaptureStatus.Text = "Got Capture: " & _hasCapture
        End If
    End Sub
    
    Private Sub bEnteredExited_PointerExited(sender As Object, e As PointerRoutedEventArgs)
        _pointerCount -= 1
        Scenario2UpdateVisuals(TryCast(sender, Border), "Exited")
    End Sub
    
    Private Sub bEnteredExited_PointerEntered(sender As Object, e As PointerRoutedEventArgs)
        _pointerCount += 1
        Scenario2UpdateVisuals(TryCast(sender, Border), "Entered")
    
    End Sub
    
    Private Sub Scenario2UpdateVisuals(border As Border, eventDescription As String)
        Select Case eventDescription.ToLower()
            Case "exited"
                If _pointerCount <= 0 Then
                    border.Background = New SolidColorBrush(Colors.Red)
                    bEnteredExitedTextBlock.Text = eventDescription
                End If
                Exit Select
            Case "moved"
    
                Dim rt As RotateTransform = DirectCast(bEnteredExitedTimer.RenderTransform, RotateTransform)
                rt.Angle += 2
                If rt.Angle > 360 Then
                    rt.Angle -= 360
                End If
                Exit Select
            Case Else
                border.Background = New SolidColorBrush(Colors.Green)
                bEnteredExitedTextBlock.Text = eventDescription
                Exit Select
    
        End Select
    End Sub
    
    Private Sub Scenario2ResetMethod(sender As Object, e As RoutedEventArgs)
        Reset()
    End Sub
    
    Private Sub Reset()
        bEnteredExited.Background = New SolidColorBrush(Colors.Green)
        bEnteredExitedTextBlock.Text = String.Empty
    End Sub
    
  • InvalidateArrange()
    InvalidateArrange()
    InvalidateArrange()
    InvalidateArrange()

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

    public void InvalidateArrange()public void InvalidateArrange()Public Function InvalidateArrange() As void

    Remarks

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

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

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

  • InvalidateMeasure()
    InvalidateMeasure()
    InvalidateMeasure()
    InvalidateMeasure()

    Invalidates the measurement state (layout) for a UIElement.

    public void InvalidateMeasure()public void InvalidateMeasure()Public Function InvalidateMeasure() As void

    Remarks

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

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

  • Measure(Windows.Foundation.Size)
    Measure(Windows.Foundation.Size)
    Measure(Windows.Foundation.Size)
    Measure(Windows.Foundation.Size)

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

    public void Measure(Windows.Foundation.Size availableSize)public void Measure(Windows.Foundation.Size availableSize)Public Function Measure(availableSize As Windows.Foundation.Size) As void

    Parameters

    • availableSize

      The available space that a parent can allocate to a child object. A child object can request a larger space than what is available; the provided size might be accommodated if scrolling or other resize behavior is possible in that particular container.

    Remarks

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

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

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

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

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

    Examples

    This example implements MeasureOverride 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(Windows.Foundation.Size), using a Size that makes sense based on how the panel logic treats the number of children and its own known size limit.
    • Returns its size (in this case, this simple panel returns a fixed size rather than a size calculated on accumulating the measurements).
    // First measure all children and return available size of panel
    protected override Size MeasureOverride(Size availableSize)
    {
    
        // Measure first 9 children giving them space up to 100x100, remaining children get 0x0 
        int i = 0;
        foreach (FrameworkElement child in Children)
        {
            if (i < 9)
            {
                child.Measure(new Size(100, 100));
            }
            else
            {
                child.Measure(new Size(0, 0));
            }
    
            i++;
        }
    
    
        // return the size available to the whole panel, which is 300x300
        return new Size(300, 300);
    }
    
    'First measure all children and return available size of panel 
    Protected Overrides Function MeasureOverride(ByVal availableSize As Size) As Size
        'Measure first 9 children giving them space up to 100x100, remaining children get 0x0 
        Dim i As Integer = 0
        For Each child As FrameworkElement In Children
            If i < 9 Then
                child.Measure(New Size(100, 100))
            Else
                child.Measure(New Size(0, 0))
            End If
            i += 1
        Next
        'return the size available to the whole panel, which is 300x300 
        Return New Size(300, 300)
    End Function
    
  • ReleasePointerCapture(Windows.UI.Xaml.Input.Pointer)
    ReleasePointerCapture(Windows.UI.Xaml.Input.Pointer)
    ReleasePointerCapture(Windows.UI.Xaml.Input.Pointer)
    ReleasePointerCapture(Windows.UI.Xaml.Input.Pointer)

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

    public void ReleasePointerCapture(Windows.UI.Xaml.Input.Pointer value)public void ReleasePointerCapture(Windows.UI.Xaml.Input.Pointer value)Public Function ReleasePointerCapture(value As Windows.UI.Xaml.Input.Pointer) As void

    Parameters

    • value

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

    Remarks

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

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

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

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

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

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

    Examples

    This example shows calling ReleasePointerCapture(Windows.UI.Xaml.Input.Pointer) based on handling PointerReleased.

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

    int _pointerCount;
    
    public Scenario2()
    {
        this.InitializeComponent();
        bEnteredExited.PointerEntered += bEnteredExited_PointerEntered;
        bEnteredExited.PointerExited += bEnteredExited_PointerExited;
        bEnteredExited.PointerPressed += bEnteredExited_PointerPressed;
        bEnteredExited.PointerReleased += bEnteredExited_PointerReleased;
        bEnteredExited.PointerMoved += bEnteredExited_PointerMoved;
    
        // To code for multiple Pointers (that is, fingers), 
        // we track how many entered/exited.
        _pointerCount = 0;
    }
    
    private void bEnteredExited_PointerMoved(object sender, 
        PointerRoutedEventArgs e)
    {
        Scenario2UpdateVisuals(sender as Border, "Moved");
    }
    
    private void bEnteredExited_PointerReleased(object sender, 
        PointerRoutedEventArgs e)
    {
        ((Border)sender).ReleasePointerCapture(e.Pointer);
        txtCaptureStatus.Text = string.Empty;
    }
    
    //Can only get capture on PointerPressed (i.e. touch down, mouse click, pen press)
    private void bEnteredExited_PointerPressed(object sender, 
        PointerRoutedEventArgs e)
    {
        if (tbPointerCapture.IsOn)
        {
            bool _hasCapture = ((Border)sender).CapturePointer(e.Pointer);
            txtCaptureStatus.Text = "Got Capture: " + _hasCapture;
        }
    }
    
    private void bEnteredExited_PointerExited(object sender, 
        PointerRoutedEventArgs e)
    {
        _pointerCount--;
        Scenario2UpdateVisuals(sender as Border, "Exited");
    }
    
    private void bEnteredExited_PointerEntered(object sender, 
        PointerRoutedEventArgs e)
    {
        _pointerCount++;
        Scenario2UpdateVisuals(sender as Border, "Entered");
    }
    
    private void Scenario2UpdateVisuals(Border border, 
        String eventDescription)
    {
        switch (eventDescription.ToLower())
        {
            case "exited":
                if (_pointerCount <= 0)
                {
                    border.Background = new SolidColorBrush(Colors.Red);
                    bEnteredExitedTextBlock.Text = eventDescription;
                }
                break;
            case "moved":
                RotateTransform rt = 
                    (RotateTransform)bEnteredExitedTimer.RenderTransform;
                rt.Angle += 2;
                if (rt.Angle > 360) rt.Angle -= 360;
                break;
            default:
                border.Background = new SolidColorBrush(Colors.Green);
                bEnteredExitedTextBlock.Text = eventDescription;
                break;
        }
    }
    
    private void Scenario2Reset(object sender, RoutedEventArgs e)
    {
        Scenario2Reset();
    }
    
    private void Scenario2Reset()
    {
        bEnteredExited.Background = new SolidColorBrush(Colors.Green);
        bEnteredExitedTextBlock.Text = string.Empty;
    }
    
    Private _pointerCount As Integer
    
    Public Sub New()
        Me.InitializeComponent()
        AddHandler bEnteredExited.PointerEntered, AddressOf bEnteredExited_PointerEntered
        AddHandler bEnteredExited.PointerExited, AddressOf bEnteredExited_PointerExited
        AddHandler bEnteredExited.PointerPressed, AddressOf bEnteredExited_PointerPressed
        AddHandler bEnteredExited.PointerReleased, AddressOf bEnteredExited_PointerReleased
        AddHandler bEnteredExited.PointerMoved, AddressOf bEnteredExited_PointerMoved
    
        'To code for multiple Pointers (i.e. Fingers) we track how many entered/exited.
        _pointerCount = 0
    End Sub
    
    ''' <summary>
    ''' Invoked when this page is about to be displayed in a Frame.
    ''' </summary>
    ''' <param name="e">Event data that describes how this page was reached.  The Parameter
    ''' property is typically used to configure the page.</param>
    Protected Overrides Sub OnNavigatedTo(e As NavigationEventArgs)
    End Sub
    
    Private Sub bEnteredExited_PointerMoved(sender As Object, e As PointerRoutedEventArgs)
        Scenario2UpdateVisuals(TryCast(sender, Border), "Moved")
    End Sub
    
    Private Sub bEnteredExited_PointerReleased(sender As Object, e As PointerRoutedEventArgs)
        DirectCast(sender, Border).ReleasePointerCapture(e.Pointer)
        txtCaptureStatus.Text = String.Empty
    End Sub
    
    'Can only get capture on PointerPressed (i.e. touch down, mouse click, pen press)
    Private Sub bEnteredExited_PointerPressed(sender As Object, e As PointerRoutedEventArgs)
        If tbPointerCapture.IsOn Then
            Dim _hasCapture As Boolean = DirectCast(sender, Border).CapturePointer(e.Pointer)
            txtCaptureStatus.Text = "Got Capture: " & _hasCapture
        End If
    End Sub
    
    Private Sub bEnteredExited_PointerExited(sender As Object, e As PointerRoutedEventArgs)
        _pointerCount -= 1
        Scenario2UpdateVisuals(TryCast(sender, Border), "Exited")
    End Sub
    
    Private Sub bEnteredExited_PointerEntered(sender As Object, e As PointerRoutedEventArgs)
        _pointerCount += 1
        Scenario2UpdateVisuals(TryCast(sender, Border), "Entered")
    
    End Sub
    
    Private Sub Scenario2UpdateVisuals(border As Border, eventDescription As String)
        Select Case eventDescription.ToLower()
            Case "exited"
                If _pointerCount <= 0 Then
                    border.Background = New SolidColorBrush(Colors.Red)
                    bEnteredExitedTextBlock.Text = eventDescription
                End If
                Exit Select
            Case "moved"
    
                Dim rt As RotateTransform = DirectCast(bEnteredExitedTimer.RenderTransform, RotateTransform)
                rt.Angle += 2
                If rt.Angle > 360 Then
                    rt.Angle -= 360
                End If
                Exit Select
            Case Else
                border.Background = New SolidColorBrush(Colors.Green)
                bEnteredExitedTextBlock.Text = eventDescription
                Exit Select
    
        End Select
    End Sub
    
    Private Sub Scenario2ResetMethod(sender As Object, e As RoutedEventArgs)
        Reset()
    End Sub
    
    Private Sub Reset()
        bEnteredExited.Background = New SolidColorBrush(Colors.Green)
        bEnteredExitedTextBlock.Text = String.Empty
    End Sub
    
  • ReleasePointerCaptures()
    ReleasePointerCaptures()
    ReleasePointerCaptures()
    ReleasePointerCaptures()

    Releases all pointer captures held by this element.

    public void ReleasePointerCaptures()public void ReleasePointerCaptures()Public Function ReleasePointerCaptures() As void

    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(Windows.UI.Xaml.Input.Pointer) removes a specific Pointer from the collection as identified by its ID, whereas ReleasePointerCaptures() clears the entire collection.

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

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

  • RemoveHandler(Windows.UI.Xaml.RoutedEvent,System.Object)
    RemoveHandler(Windows.UI.Xaml.RoutedEvent,System.Object)
    RemoveHandler(Windows.UI.Xaml.RoutedEvent,System.Object)
    RemoveHandler(Windows.UI.Xaml.RoutedEvent,System.Object)

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

    public void RemoveHandler(Windows.UI.Xaml.RoutedEvent routedEvent,System.Object handler)public void RemoveHandler(Windows.UI.Xaml.RoutedEvent routedEvent,System.Object handler)Public Function RemoveHandler(routedEvent As Windows.UI.Xaml.RoutedEvent,handler As System.Object) As void

    Parameters

    • routedEvent

      The identifier of the routed event for which the handler is attached.

    • handler
      System.Object
      System.Object
      System.Object

      The specific handler implementation to remove from the event handler collection on this UIElement.

    Remarks

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

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

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

    This method ignores whether handledEventsToo parameter was true in the AddHandler(Windows.UI.Xaml.RoutedEvent,System.Object,System.Boolean) call that originally attached the handler.

  • StartDragAsync(Windows.UI.Input.PointerPoint)
    StartDragAsync(Windows.UI.Input.PointerPoint)
    StartDragAsync(Windows.UI.Input.PointerPoint)
    StartDragAsync(Windows.UI.Input.PointerPoint)

    Initiates a drag-and-drop operation.

    public IAsyncOperation<DataPackageOperation> StartDragAsync(Windows.UI.Input.PointerPoint pointerPoint)public IAsyncOperation<DataPackageOperation> StartDragAsync(Windows.UI.Input.PointerPoint pointerPoint)Public Function StartDragAsync(pointerPoint As Windows.UI.Input.PointerPoint) As IAsyncOperation( Of DataPackageOperation )

    Parameters

    Returns

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

    Remarks

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

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

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

    Examples

    This example shows how to handle the PointerPressed event on an Image element to initiate a drag operation.

    <Image x:Name="myImage" Source="ms-appx:///Assets/Logo.png" 
           PointerPressed="myImage_PointerPressed" />
    
    private async void myImage_PointerPressed(object sender, PointerRoutedEventArgs e)
    {
        var pointerPoint = e.GetCurrentPoint(sender as UIElement);
        var dropStatus = await myImage.StartDragAsync(pointerPoint);
        if (dropStatus == DataPackageOperation.Move)
        {
            // App specific code for a "move" operation.
        }
    }
    
  • TransformToVisual(Windows.UI.Xaml.UIElement)
    TransformToVisual(Windows.UI.Xaml.UIElement)
    TransformToVisual(Windows.UI.Xaml.UIElement)
    TransformToVisual(Windows.UI.Xaml.UIElement)

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

    public GeneralTransform TransformToVisual(Windows.UI.Xaml.UIElement visual)public GeneralTransform TransformToVisual(Windows.UI.Xaml.UIElement visual)Public Function TransformToVisual(visual As Windows.UI.Xaml.UIElement) As GeneralTransform

    Parameters

    Returns

    Remarks

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

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

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

    Note

    The GeneralTransform object returned by this method can be cast to a derived type, Transform, but all the methods you need are defined by GeneralTransform. You can't cast to TranslateTransform even though you might expect that the transform result would be a translation.

    Examples

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

        <Page
        x:Class="PointerInput.MainPage"
        IsTabStop="false"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:local="using:PointerInput"
        xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
        xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
        mc:Ignorable="d"
        Name="page">
    
        <Grid Background="{StaticResource ApplicationPageBackgroundThemeBrush}">
            <Grid.ColumnDefinitions>
                <ColumnDefinition Width="*" />
                <ColumnDefinition Width="150" />
            </Grid.ColumnDefinitions>
            <Grid.RowDefinitions>
                <RowDefinition Height="*" />
                <RowDefinition Height="320" />
                <RowDefinition Height="*"/>
            </Grid.RowDefinitions>
            <Canvas Name="Container" 
                    Grid.Column="0"
                    Grid.Row="1"
                    HorizontalAlignment="Center" 
                    VerticalAlignment="Center" 
                    Margin="0,0,0,0" 
                    Height="320"  Width="640">
                <Rectangle Name="Target" 
                           Fill="#FF0000" 
                           Stroke="Black" 
                           StrokeThickness="0"
                           Height="320" Width="640" />
            </Canvas>
            <TextBox Name="eventLog" 
                     Grid.Column="1"
                     Grid.Row="0"
                     Grid.RowSpan="3" 
                     Background="#000000" 
                     TextWrapping="Wrap" 
                     Foreground="#FFFFFF" 
                     ScrollViewer.VerticalScrollBarVisibility="Visible" 
                     BorderThickness="0"/>
        </Grid>
    </Page>
    
    <Page
        x:Class="PointerInput.MainPage"
        IsTabStop="false"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:local="using:PointerInput"
        xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
        xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
        mc:Ignorable="d"
        Name="page">
    
        <Grid Background="{StaticResource ApplicationForegroundThemeBrush}">
            <Grid.ColumnDefinitions>
                <ColumnDefinition Width="*" />
                <ColumnDefinition Width="69.458" />
                <ColumnDefinition Width="80.542"/>
            </Grid.ColumnDefinitions>
            <Grid.RowDefinitions>
                <RowDefinition Height="*" />
                <RowDefinition Height="320" />
                <RowDefinition Height="*"/>
            </Grid.RowDefinitions>
            <Canvas Name="Container" 
                    Grid.Column="0"
                    Grid.Row="1"
                    HorizontalAlignment="Center" 
                    VerticalAlignment="Center" 
                    Margin="245,0" 
                    Height="320"  Width="640">
                <Rectangle Name="Target" 
                           Fill="#FF0000" 
                           Stroke="Black" 
                           StrokeThickness="0"
                           Height="320" Width="640" />
            </Canvas>
            <Button Name="buttonClear"
                    Foreground="White"
                    Width="100"
                    Height="100">
                clear
            </Button>
            <TextBox Name="eventLog" 
                     Grid.Column="1"
                     Grid.Row="0"
                     Grid.RowSpan="3" 
                     Background="#000000" 
                     TextWrapping="Wrap" 
                     Foreground="#FFFFFF" 
                     ScrollViewer.VerticalScrollBarVisibility="Visible" 
                     BorderThickness="0" Grid.ColumnSpan="2"/>
        </Grid>
    </Page>
    
    String queryPointer(PointerPoint ptrPt)
    {
        String details = "";
    
        switch (ptrPt.PointerDevice.PointerDeviceType)
        {
            case Windows.Devices.Input.PointerDeviceType.Mouse:
                details += "\nPointer type: mouse";
                break;
            case Windows.Devices.Input.PointerDeviceType.Pen:
                details += "\nPointer type: pen";
                if (ptrPt.IsInContact)
                {
                    details += "\nPressure: " + ptrPt.Properties.Pressure;
                    details += "\nrotation: " + ptrPt.Properties.Orientation;
                    details += "\nTilt X: " + ptrPt.Properties.XTilt;
                    details += "\nTilt Y: " + ptrPt.Properties.YTilt;
                    details += "\nBarrel button pressed: " + ptrPt.Properties.IsBarrelButtonPressed;
                }
                break;
            case Windows.Devices.Input.PointerDeviceType.Touch:
                details += "\nPointer type: touch";
                details += "\nrotation: " + ptrPt.Properties.Orientation;
                details += "\nTilt X: " + ptrPt.Properties.XTilt;
                details += "\nTilt Y: " + ptrPt.Properties.YTilt;
                break;
            default:
                details += "\nPointer type: n/a";
                break;
        }
    
        GeneralTransform gt = Target.TransformToVisual(page);
        Point screenPoint;
    
        screenPoint = gt.TransformPoint(new Point(ptrPt.Position.X, ptrPt.Position.Y));
        details += "\nPointer Id: " + ptrPt.PointerId.ToString() +
            "\nPointer location (parent): " + ptrPt.Position.X + ", " + ptrPt.Position.Y +
            "\nPointer location (screen): " + screenPoint.X + ", " + screenPoint.Y;
        return details;
    }
    
    String queryPointer(PointerPoint ptrPt)
    {
        String details = "";
    
        switch (ptrPt.PointerDevice.PointerDeviceType)
        {
            case Windows.Devices.Input.PointerDeviceType.Mouse:
                details += "\nPointer type: mouse";
                break;
            case Windows.Devices.Input.PointerDeviceType.Pen:
                details += "\nPointer type: pen";
                if (ptrPt.IsInContact)
                {
                    details += "\nPressure: " + ptrPt.Properties.Pressure;
                    details += "\nrotation: " + ptrPt.Properties.Orientation;
                    details += "\nTilt X: " + ptrPt.Properties.XTilt;
                    details += "\nTilt Y: " + ptrPt.Properties.YTilt;
                    details += "\nBarrel button pressed: " + ptrPt.Properties.IsBarrelButtonPressed;
                }
                break;
            case Windows.Devices.Input.PointerDeviceType.Touch:
                details += "\nPointer type: touch";
                details += "\nrotation: " + ptrPt.Properties.Orientation;
                details += "\nTilt X: " + ptrPt.Properties.XTilt;
                details += "\nTilt Y: " + ptrPt.Properties.YTilt;
                break;
            default:
                details += "\nPointer type: n/a";
                break;
        }
    
        GeneralTransform gt = Target.TransformToVisual(page);
        Point screenPoint;
    
        screenPoint = gt.TransformPoint(new Point(ptrPt.Position.X, ptrPt.Position.Y));
        details += "\nPointer Id: " + ptrPt.PointerId.ToString() +
            "\nPointer location (parent): " + ptrPt.Position.X + ", " + ptrPt.Position.Y +
            "\nPointer location (screen): " + screenPoint.X + ", " + screenPoint.Y;
        return details;
    }
    
  • TryStartDirectManipulation(Windows.UI.Xaml.Input.Pointer)
    TryStartDirectManipulation(Windows.UI.Xaml.Input.Pointer)
    TryStartDirectManipulation(Windows.UI.Xaml.Input.Pointer)
    TryStartDirectManipulation(Windows.UI.Xaml.Input.Pointer)

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

    public static bool TryStartDirectManipulation(Windows.UI.Xaml.Input.Pointer value)public static bool TryStartDirectManipulation(Windows.UI.Xaml.Input.Pointer value)Public Static Function TryStartDirectManipulation(value As Windows.UI.Xaml.Input.Pointer) As bool

    Parameters

    Returns

    • bool
      bool
      bool

      true if a ScrollViewer parent exists and setting the value resulted in resuming the panning/zooming action. false if calling the method results in no action.

    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(Windows.UI.Xaml.Input.Pointer) to resume having Direct Manipulation process the input stream. This lets you to do custom input processing first, and then resume Direct Manipulation handling to make your app more responsive to touch interactions like scrolling and zooming.

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

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

  • UpdateLayout()
    UpdateLayout()
    UpdateLayout()
    UpdateLayout()

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

    public void UpdateLayout()public void UpdateLayout()Public Function UpdateLayout() As void

    Remarks

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

    Layout updates can be forced by app code rather than relying on the built-in layout system behavior by using the UpdateLayout() method. However, that is not generally recommended. It is usually unnecessary and can cause poor performance if overused. In many situations where calling UpdateLayout() from app code might be appropriate because of changes to properties, the layout system will probably already be processing updates. The layout system also has optimizations for dealing with cascades of layout changes through parent-child relationships, and calling UpdateLayout() can work against such optimizations. Nevertheless, it's possible that layout situations exist in more complicated scenarios where calling UpdateLayout() is the best option for resolving a timing issue or other issue with layout. Just use it deliberately and sparingly. In the cases where you do need to call UpdateLayout() you're probably going to call it just after calling Children.Add on some collection of child elements of a common layout parent, then calling UpdateLayout() on that parent to make the layout system recognize the new added child.

    One scenario for UpdateLayout() is when you have linked containers like RichTextBlock and RichTextBlockOverflow, you've made run-time changes to the content, and you want to make sure that operations not specifically tied to displaying the UI have a chance to run the layout and trigger the content rebalance between the linked containers. For example, you might want to do this to prepare a layout for printing. For an example of this scenario, see the #5 scenario in Print sample.

    Tip

    If you have a scenario where you use data binding to UI and you aren't seeing the layout reflect updates in your data source collections, calling UpdateLayout() probably isn't going to help. It's more likely that you have issues with your binding declarations, the data context, or with the INotifyPropertyChanged or INotifyCollectionChanged support in your data source.

Events

  • AccessKeyDisplayDismissed
    AccessKeyDisplayDismissed
    AccessKeyDisplayDismissed
    AccessKeyDisplayDismissed

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

    public event TypedEventHandler AccessKeyDisplayDismissedpublic event TypedEventHandler AccessKeyDisplayDismissedPublic Event AccessKeyDisplayDismissed
  • AccessKeyDisplayRequested
    AccessKeyDisplayRequested
    AccessKeyDisplayRequested
    AccessKeyDisplayRequested

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

    public event TypedEventHandler AccessKeyDisplayRequestedpublic event TypedEventHandler AccessKeyDisplayRequestedPublic Event AccessKeyDisplayRequested

    Remarks

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

  • AccessKeyInvoked
    AccessKeyInvoked
    AccessKeyInvoked
    AccessKeyInvoked

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

    public event TypedEventHandler AccessKeyInvokedpublic event TypedEventHandler AccessKeyInvokedPublic Event AccessKeyInvoked

    Remarks

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

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

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

  • ContextCanceled
    ContextCanceled
    ContextCanceled
    ContextCanceled

    Occurs when a context input gesture continues into a manipulation gesture, to notify the element that the context flyout should not be opened.

    public event TypedEventHandler ContextCanceledpublic event TypedEventHandler ContextCanceledPublic Event ContextCanceled

    Remarks

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

  • ContextRequested
    ContextRequested
    ContextRequested
    ContextRequested

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

    public event TypedEventHandler ContextRequestedpublic event TypedEventHandler ContextRequestedPublic Event ContextRequested

    Remarks

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

  • DoubleTapped
    DoubleTapped
    DoubleTapped
    DoubleTapped

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

    public event DoubleTappedEventHandler DoubleTappedpublic event DoubleTappedEventHandler DoubleTappedPublic Event DoubleTapped
    <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 DoubleTapped. If you want different logic for Tapped versus DoubleTapped, your Tapped handler may need to use app-specific variables and a timer in order to avoid running on interactions that are eventually interpreted as a DoubleTap action.

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

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

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

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

    DoubleTapped supports the ability to attach event handlers to the route that will be invoked even if the event data for the event is marked Handled. See AddHandler(Windows.UI.Xaml.RoutedEvent,System.Object,System.Boolean).

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

  • DragEnter
    DragEnter
    DragEnter
    DragEnter

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

    public event DragEventHandler DragEnterpublic event DragEventHandler DragEnterPublic Event DragEnter
    <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(Windows.UI.Input.PointerPoint) method. Once the action is initiated, any UIElement in the app can potentially be a drop target so long as AllowDrop is true on that element. Any elements that the drag-drop action passes over can handle DragEnter, DragLeave or DragOver.

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

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

    DragEnter supports the ability to attach event handlers to the route that will be invoked even if the event data for the event is marked Handled. See AddHandler(Windows.UI.Xaml.RoutedEvent,System.Object,System.Boolean).

    Specific Windows Runtime controls may have class-based handling for the DragEnter event. If so, the control probably has an override for the method OnDragEnter. 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(Windows.UI.Input.PointerPoint) or generalized DoDragDrop method that would permit any UI element to initiate a drag-drop action. The main source of a drag-drop action in an app is when you drag the items of a list such as GridView.

  • DragLeave
    DragLeave
    DragLeave
    DragLeave

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

    public event DragEventHandler DragLeavepublic event DragEventHandler DragLeavePublic Event DragLeave
    <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(Windows.UI.Input.PointerPoint) method. Once the action is initiated, any UIElement in the app can potentially be a drop target so long as AllowDrop is true on that element. Any elements that the drag-drop action passes over can handle DragEnter, DragLeave or DragOver.

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

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

    DragLeave supports the ability to attach event handlers to the route that will be invoked even if the event data for the event is marked Handled. See AddHandler(Windows.UI.Xaml.RoutedEvent,System.Object,System.Boolean).

    Specific Windows Runtime controls may have class-based handling for the DragLeave event. If so, the control probably has an override for the method OnDragLeave. 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(Windows.UI.Input.PointerPoint) or generalized DoDragDrop method that would permit any UI element to initiate a drag-drop action. The main source of a drag-drop action in an app is when you drag the items of a list such as GridView.

  • DragOver
    DragOver
    DragOver
    DragOver

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

    public event DragEventHandler DragOverpublic event DragEventHandler DragOverPublic Event DragOver
    <uiElement DragOver="eventhandler"/>
    

    Remarks

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

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

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

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

    DragOver supports the ability to attach event handlers to the route that will be invoked even if the event data for the event is marked Handled. See AddHandler(Windows.UI.Xaml.RoutedEvent,System.Object,System.Boolean).

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

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

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

  • DragStarting
    DragStarting
    DragStarting
    DragStarting

    Occurs when a drag operation is initiated.

    public event TypedEventHandler DragStartingpublic event TypedEventHandler DragStartingPublic Event DragStarting
  • Drop
    Drop
    Drop
    Drop

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

    public event DragEventHandler Droppublic event DragEventHandler DropPublic Event Drop
    <uiElement Drop="eventhandler"/>
    

    Remarks

    For Drop to occur and to invoke a handler, the value of AllowDrop on the UIElement that is the drop target and also on the drag-drop action source must be true.

    A typical handler will check the Data value from the DragEventArgs event data.

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

    Drop is a routed event. An element must have AllowDrop be true to be a Drop event source. If the event is permitted to bubble up to parent elements because it goes unhandled, then it is possible to handle the event on a parent element if AllowDrop is true on the parent element. Intermediate elements in the route that aren't either the handler object or the drop target don't need AllowDrop to be true. For more info on the routed event concept, see Events and routed events overview.

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

    Drop supports the ability to attach event handlers to the route that will be invoked even if the event data for the event is marked Handled. See AddHandler(Windows.UI.Xaml.RoutedEvent,System.Object,System.Boolean).

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

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

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

  • DropCompleted
    DropCompleted
    DropCompleted
    DropCompleted

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

    public event TypedEventHandler DropCompletedpublic event TypedEventHandler DropCompletedPublic Event DropCompleted
  • GotFocus
    GotFocus
    GotFocus
    GotFocus

    Occurs when a UIElement receives focus.

    public event RoutedEventHandler GotFocuspublic event RoutedEventHandler GotFocusPublic Event GotFocus
    <uiElement GotFocus="eventhandler"/>
    

    Remarks

    Only one element at a time in a page of UI can have focus.

    If you are using control compositing or UI compositing and handling GotFocus on a container such as a Panel or GridView, then you might want to check the OriginalSource on the event data to determine which element in the composition actually received the focus.

    GotFocus doesn't have any specialized event data. For many scenarios where you handle GotFocus, you might want to determine whether it was the user or app code that caused an element to gain focus. To determine this in your handler, cast the sender of the event to be a Control object, and check the FocusState.

    Keyboard focus is particularly relevant for keyboard event handling, because only the currently keyboard-focused UIElement can be the source of the key events KeyUp and KeyDown. In some scenarios, apps deliberately call Focus(Windows.UI.Xaml.FocusState) as an initialization action so that the key events in the app as a whole can be used to detect access or accelerator keys. For more info, see Keyboard interactions.

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

    Specific Windows Runtime controls may have class-based handling for the GotFocus event. If so, the control probably has an override for the method OnGotFocus. Typically the event is marked handled by the class handler, and the GotFocus event is not raised for handling by any user code handlers on that control. Controls might handle the event in order to load a visual state that property displays a focus rectangle. A focus rectangle is an important visual component of a control for accessibility purposes, so that users can see where the current focused element is in the UI and where the user is within the tab sequence of the overall app UI. In some cases, the FocusState of the focus action is relevant for whether a visible focus indicator should display. For more info on how class-based handling for events works, see Events and routed events overview. For more info on tab sequences and accessibility, see Keyboard accessibility.

  • Holding
    Holding
    Holding
    Holding

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

    public event HoldingEventHandler Holdingpublic event HoldingEventHandler HoldingPublic Event Holding
    <uiElement Holding="eventhandler"/>
    

    Remarks

    Touch can produce a Holding action, but mouse devices generally can't. For more info, see Quickstart: Touch input.

    The Tapped, DoubleTapped, and RightTapped events occur only after the touch point is removed. But the initial Holding event occurs while the touch point is still in contact. The event occurs if the touch point remains in approximately the same PointerPoint position for a period of time. The exact timing of what the system interprets as a holding action is adjustable by users through system settings.

    Holding is intended for informational UI, but for interactions like displaying a context menu you should use RightTapped instead. You might handle Holding first to display a hint that a menu will appear, but to display the menu itself, use a RightTapped handler. See Touch interaction design or UX guidelines for custom user interactions for more info on how to use a Hold interaction in your app design.

    Holding events generally occur in pairs. When the action is first interpreted as a Hold action based on no movement for a period of time, Holding fires, with HoldingState value of Started in the HoldingRoutedEventArgs event data. When the Hold action ends, another Holding event fires, this time with HoldingState of either Completed or Canceled.

    • The Hold action ends with HoldingState as Completed if the user doesn't move the pointer during the Hold state and then releases the pointer points that initiated the action. For this case, RightTapped fires just after the second Holding event.
    • The Hold action ends with HoldingState as Canceled if the user does move the pointer(s) that initiated the action, or also for uncommon situations such as changing the hit-test status on the element during the action or capturing another pointer. If the Hold action ends with HoldingState as Canceled, RightTapped won't fire.

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

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

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

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

    Holding supports the ability to attach event handlers to the route that will be invoked even if the event data for the event is marked Handled. See AddHandler(Windows.UI.Xaml.RoutedEvent,System.Object,System.Boolean).

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

    Tapped and Holding are mutually exclusive. If the action passes the time threshold to be considered a Hold action, it's not considered to be a Tap action also.

    Whenever Holding fires initially, so long as the element supports manipulation events through a non-default ManipulationMode value, ManipulationStarting fires too. If the pointer point remains in one place long enough for Holding to be detected, but thereafter the user moves the pointer points associated with the Hold action without releasing them (leading to another Holding event with HoldingState as Canceled), then other manipulation events like ManipulationStarted and ManipulationDelta can fire also.

    Holding for mouse and pen/stylus input

    Mouse input doesn't produce Holding events by default, no matter how long a mouse button is held down, or which button is held. However, mouse devices and some pen devices can fire RightTapped when a right mouse button or equivalent is pressed and released.

    Note

    There is a way to treat mouse actions as hold actions if you use your own GestureRecognizer and specify HoldWithMouse in settings.

  • KeyDown
    KeyDown
    KeyDown
    KeyDown

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

    public event KeyEventHandler KeyDownpublic event KeyEventHandler KeyDownPublic Event KeyDown
    <uiElement KeyDown="eventhandler"/>
    

    Remarks

    Controls in your UI generate keyboard events only when they have input focus. By default, the first focusable element in the visual tree is given focus by the system. An individual control gains focus when the user clicks or taps directly on that control in the layout, or uses the Tab key to step into a tab sequence within the content area. You can also focus controls programmatically by calling Focus(Windows.UI.Xaml.FocusState).

    KeyDown uses KeyRoutedEventArgs event data. The most relevant properties of KeyRoutedEventArgs for most handler scenarios are Key and possibly KeyStatus. For more info on handling keyboard events, including example code for defining a KeyEventHandler method, see Keyboard interactions.

    One scenario for handling keyboard events is to support access keys or accelerator keys for an app, or a region or control within an app. For more info about this scenario, see Keyboard accessibility.

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

    Specific Windows Runtime controls may have class-based handling for the KeyDown input event. If so, the control probably has an override for the method OnKeyDown. Typically these class handlers are intended to process a subset of key presses that enable a keyboard-based user interaction with that control, and often this interaction supports a keyboard accessibility feature. If a key press is handled by class-based handling, then the key press is considered to be already handled, and the KeyDown event is not raised for handling by any user code handlers on that control for that key specifically. Usually this is just for a few dedicated keys. For example, ButtonBase has class handling so that the Space key and Enter key are handled as keyboard equivalents for invoking the Button. That provides a built-in keyboard equivalent for tapping the button or clicking on it with a mouse, and enables the accessibility scenario of using the UI and the button using a keyboard only. But any other keys other than Space or Enter will still fire a KeyDown and KeyUp event for a Button. For more info on how class-based handling for events works, see Events and routed events overview.

    KeyDown supports the ability to attach event handlers to the route that will be invoked even if the event data for the event is marked Handled. See AddHandler(Windows.UI.Xaml.RoutedEvent,System.Object,System.Boolean).

  • KeyUp
    KeyUp
    KeyUp
    KeyUp

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

    public event KeyEventHandler KeyUppublic event KeyEventHandler KeyUpPublic Event KeyUp
    <uiElement KeyUp="eventhandler"/>
    

    Remarks

    Controls in your UI generate keyboard events only when they have input focus. By default, the first focusable element in the visual tree is given focus by the system. An individual control gains focus when the user clicks or taps directly on that control in the layout, or uses the Tab key to step into a tab sequence within the content area. You can also focus controls programmatically by calling Focus(Windows.UI.Xaml.FocusState).

    KeyUp uses KeyRoutedEventArgs event data. The most relevant properties of KeyRoutedEventArgs for most handler scenarios are Key and possibly KeyStatus. For more info on handling keyboard events, including example code for defining a KeyEventHandler method, see Keyboard interactions.

    One scenario for handling keyboard events is to support access keys or accelerator keys for an app, or a region or control within an app. For more info about this scenario, see Keyboard accessibility.

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

    Specific Windows Runtime controls may have class-based handling for the KeyUp input event. If so, the control probably has an override for the method OnKeyUp. Typically these class handlers are intended to process a subset of key presses that enable a keyboard-based user interaction with that control, and often this interaction supports a keyboard accessibility feature. If a keyboard key event is handled by class-based handling, then the key event is considered to be already handled, and the KeyUp event is not raised for handling by any user code handlers on that control. Usually this is just for a few dedicated keys. For example, ButtonBase has class handling so that the Space key and Enter key are handled as keyboard equivalents for invoking the Button. That provides a built-in keyboard equivalent for tapping the button or clicking on it with a mouse, and enables the accessibility scenario of using the UI and the button using a keyboard only. But any other keys other than Space or Enter will still fire a KeyDown and KeyUp event for a Button. For more info on how class-based handling for events works, see Events and routed events overview.

    KeyUp supports the ability to attach event handlers to the route that will be invoked even if the event data for the event is marked Handled. See AddHandler(Windows.UI.Xaml.RoutedEvent,System.Object,System.Boolean).

  • LostFocus
    LostFocus
    LostFocus
    LostFocus

    Occurs when a UIElement loses focus.

    public event RoutedEventHandler LostFocuspublic event RoutedEventHandler LostFocusPublic Event LostFocus
    <uiElement LostFocus="eventhandler"/>
    

    Remarks

    The typical reason that a control loses focus is that another control now has focus. But there are other possible reasons for losing focus, such as switching to another view state or another app, or the user interacting with the system in other ways.

    Keyboard focus is particularly relevant for keyboard event handling, because only the currently keyboard-focused UIElement can be the source of the key events KeyUp and KeyDown. In some scenarios, apps deliberately call Focus(Windows.UI.Xaml.FocusState) as an initialization action so that the key events in the app as a whole can be used to detect access or accelerator keys. For more info, see Keyboard interactions.

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

    Specific Windows Runtime controls may have class-based handling for the LostFocus event. If so, the control probably has an override for the method OnLostFocus. Typically the event is marked handled by the class handler, and the LostFocus event is not raised for handling by any user code handlers on that control. Controls might handle the event in order to unload a visual state that displayed a focus rectangle in response to OnGotFocus. A focus rectangle is an important visual component of a control for accessibility purposes, so that users can see where the current focused element is in the UI and where the user is within the tab sequence of the overall app UI. For more info on how class-based handling for events works, see Events and routed events overview. For more info on tab sequences and accessibility, see Keyboard accessibility.

  • ManipulationCompleted
    ManipulationCompleted
    ManipulationCompleted
    ManipulationCompleted

    Occurs when a manipulation on the UIElement is complete.

    public event ManipulationCompletedEventHandler ManipulationCompletedpublic event ManipulationCompletedEventHandler ManipulationCompletedPublic Event ManipulationCompleted
    <uiElement ManipulationCompleted="eventhandler"/>
    

    Remarks

    An element must have a ManipulationMode value other than None or System to be a manipulation event source. The default value of ManipulationMode is System, which enables built-in control logic to process manipulations, but doesn't permit app code to handle manipulation events. If you want to handle manipulations, set ManipulationMode to All, or to specific ManipulationModes values. For more info, see ManipulationMode.

    ManipulationCompleted is a routed event. If the event is permitted to bubble up to parent elements because it goes unhandled, then it is possible to handle the event on parent elements even if ManipulationMode is None or System on the parent element. For more info on the routed event concept, see Events and routed events overview.

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

    ManipulationCompleted supports the ability to attach event handlers to the route that will be invoked even if the event data for the event is marked Handled. See AddHandler(Windows.UI.Xaml.RoutedEvent,System.Object,System.Boolean).

    Windows 8 behavior

    Windows 8 doesn't fire ManipulationCompleted in cases where the inertial phase has started (and ManipulationInertiaStarting has fired) but the user has tapped on the item before it's finished scrolling, which cancels the inertial phase visually. The issue is fixed starting with Windows 8.1; ManipulationCompleted is fired as soon as the tap action cancels the inertial phase.

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

  • ManipulationDelta
    ManipulationDelta
    ManipulationDelta
    ManipulationDelta

    Occurs when the input device changes position during a manipulation.

    public event ManipulationDeltaEventHandler ManipulationDeltapublic event ManipulationDeltaEventHandler ManipulationDeltaPublic Event ManipulationDelta
    <uiElement ManipulationDelta="eventhandler"/>
    

    Remarks

    An element must have a ManipulationMode value other than None or System to be a manipulation event source. The default value of ManipulationMode is System, which enables built-in control logic to process manipulations, but doesn't permit app code to handle manipulation events. If you want to handle manipulations, set ManipulationMode to All, or to specific ManipulationModes values. For more info, see ManipulationMode.

    ManipulationDelta is a routed event. If the event is permitted to bubble up to parent elements because it goes unhandled, then it is possible to handle the event on parent elements even if ManipulationMode is None or System on the parent element. For more info on the routed event concept, see Events and routed events overview.

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

    ManipulationDelta supports the ability to attach event handlers to the route that will be invoked even if the event data for the event is marked Handled. See AddHandler(Windows.UI.Xaml.RoutedEvent,System.Object,System.Boolean).

  • ManipulationInertiaStarting
    ManipulationInertiaStarting
    ManipulationInertiaStarting
    ManipulationInertiaStarting

    Occurs when the input device loses contact with the UIElement object during a manipulation and inertia begins.

    public event ManipulationInertiaStartingEventHandler ManipulationInertiaStartingpublic event ManipulationInertiaStartingEventHandler ManipulationInertiaStartingPublic Event ManipulationInertiaStarting
    <uiElement ManipulationInertiaStarting="eventhandler"/>
    

    Remarks

    An element must have a ManipulationMode value other than None or System to be a manipulation event source. The default value of ManipulationMode is System, which enables built-in control logic to process manipulations, but doesn't permit app code to handle manipulation events. If you want to handle manipulations, set ManipulationMode to All, or to specific ManipulationModes values. For more info, see ManipulationMode.

    ManipulationInertiaStarting is a routed event. If the event is permitted to bubble up to parent elements because it goes unhandled, then it is possible to handle the event on parent elements even if ManipulationMode is None or System on the parent element. For more info on the routed event concept, see Events and routed events overview.

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

    ManipulationInertiaStarting supports the ability to attach event handlers to the route that will be invoked even if the event data for the event is marked Handled. See AddHandler(Windows.UI.Xaml.RoutedEvent,System.Object,System.Boolean).

    Windows 8 behavior

    Windows 8 doesn't fire ManipulationCompleted in cases where the inertial phase has started (and ManipulationInertiaStarting has fired) but the user has tapped on the item before it's finished scrolling, which cancels the inertial phase visually. The issue is fixed starting with Windows 8.1; ManipulationCompleted is fired as soon as the tap action cancels the inertial phase.

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

  • ManipulationStarted
    ManipulationStarted
    ManipulationStarted
    ManipulationStarted

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

    public event ManipulationStartedEventHandler ManipulationStartedpublic event ManipulationStartedEventHandler ManipulationStartedPublic Event ManipulationStarted
    <uiElement ManipulationStarted="eventhandler"/>
    

    Remarks

    ManipulationStarted represents that the manipulation recognition logic has detected pointer movement. In this case it's the second manipulation event to fire in a typical sequence, firing after ManipulationStarting, but before ManipulationDelta or other events such as ManipulationInertiaStarting.

    An element must have a ManipulationMode value other than None or System to be a manipulation event source. The default value of ManipulationMode is System, which enables built-in control logic to process manipulations, but doesn't permit app code to handle manipulation events. If you want to handle manipulations, set ManipulationMode to All, or to specific ManipulationModes values. For more info, see ManipulationMode.

    ManipulationStarted is a routed event. If the event is permitted to bubble up to parent elements because it goes unhandled, then it is possible to handle the event on parent elements even if ManipulationMode is None or System on the parent element. For more info on the routed event concept, see Events and routed events overview.

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

    ManipulationStarted supports the ability to attach event handlers to the route that will be invoked even if the event data for the event is marked Handled. See AddHandler(Windows.UI.Xaml.RoutedEvent,System.Object,System.Boolean).

  • ManipulationStarting
    ManipulationStarting
    ManipulationStarting
    ManipulationStarting

    Occurs when the manipulation processor is first created.

    public event ManipulationStartingEventHandler ManipulationStartingpublic event ManipulationStartingEventHandler ManipulationStartingPublic Event ManipulationStarting
    <uiElement ManipulationStarting="eventhandler"/>
    

    Remarks

    An element must have a ManipulationMode value other than None or System to be a manipulation event source. The default value of ManipulationMode is System, which enables built-in control logic to process manipulations, but doesn't permit app code to handle manipulation events. If you want to handle manipulations, set ManipulationMode to All, or to specific ManipulationModes values. For more info, see ManipulationMode.

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

    ManipulationStarting is a routed event. If the event is permitted to bubble up to parent elements because it goes unhandled, then it is possible to handle the event on parent elements even if ManipulationMode is None or System on the parent element. For more info on the routed event concept, see Events and routed events overview.

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

    ManipulationStarting supports the ability to attach event handlers to the route that will be invoked even if the event data for the event is marked Handled. See AddHandler(Windows.UI.Xaml.RoutedEvent,System.Object,System.Boolean).

    Windows 8 behavior

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

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

  • PointerCanceled
    PointerCanceled
    PointerCanceled
    PointerCanceled

    Occurs when a pointer that made contact abnormally loses contact.

    public event PointerEventHandler PointerCanceledpublic event PointerEventHandler PointerCanceledPublic Event PointerCanceled
    <uiElement PointerCanceled="eventhandler"/>
    

    Remarks

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

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

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

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

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

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

    PointerCanceled supports the ability to attach event handlers to the route that will be invoked even if the event data for the event is marked Handled. See AddHandler(Windows.UI.Xaml.RoutedEvent,System.Object,System.Boolean).

  • PointerCaptureLost
    PointerCaptureLost
    PointerCaptureLost
    PointerCaptureLost

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

    public event PointerEventHandler PointerCaptureLostpublic event PointerEventHandler PointerCaptureLostPublic Event PointerCaptureLost
    <uiElement PointerCaptureLost="eventhandler"/>
    

    Remarks

    Important

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

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

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

    PointerCaptureLost supports the ability to attach event handlers to the route that will be invoked even if the event data for the event is marked Handled. See AddHandler(Windows.UI.Xaml.RoutedEvent,System.Object,System.Boolean).

  • PointerEntered
    PointerEntered
    PointerEntered
    PointerEntered

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

    public event PointerEventHandler PointerEnteredpublic event PointerEventHandler PointerEnteredPublic Event PointerEntered
    <uiElement PointerEntered="eventhandler"/>
    

    Remarks

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

    Use a handler based on PointerEventHandler to handle this event.

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

    PointerEntered supports the ability to attach event handlers to the route that will be invoked even if the event data for the event is marked Handled. See AddHandler(Windows.UI.Xaml.RoutedEvent,System.Object,System.Boolean).

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

    PointerEntered for mouse and pen/stylus input

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

    PointerEntered for touch input

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

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

    Routed event behavior for PointerEntered

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

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

    Pointer capture

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

    PointerOver visual states for controls

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

    Windows 8 behavior

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

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

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

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

  • PointerExited
    PointerExited
    PointerExited
    PointerExited

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

    public event PointerEventHandler PointerExitedpublic event PointerEventHandler PointerExitedPublic Event PointerExited
    <uiElement PointerExited="eventhandler"/>
    

    Remarks

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

    Use a handler based on PointerEventHandler to handle this event.

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

    PointerExited supports the ability to attach event handlers to the route that will be invoked even if the event data for the event is marked Handled. See AddHandler(Windows.UI.Xaml.RoutedEvent,System.Object,System.Boolean).

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

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

    PointerExited for mouse and pen/stylus input

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

    PointerExited for touch input

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

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

    Routed event behavior for PointerExited

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

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

    PointerOver visual states for controls

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

    Windows 8 behavior

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

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

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

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

  • PointerMoved
    PointerMoved
    PointerMoved
    PointerMoved

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

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

    Remarks

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

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

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

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

    This event also supports the ability to attach event handlers to the route that will be invoked even if the event data for the event is marked Handled. See AddHandler(Windows.UI.Xaml.RoutedEvent,System.Object,System.Boolean).

    PointerMoved for mouse and stylus input

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

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

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

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

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

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

    Remarks

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

    Use a handler based on PointerEventHandler to handle this event.

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

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

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

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

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

    PointerPressed supports the ability to attach event handlers to the route that will be invoked even if the event data for the event is marked Handled. See AddHandler(Windows.UI.Xaml.RoutedEvent,System.Object,System.Boolean).

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

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

    Pointer capture

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

    PointerPressed and gesture events, or manipulation events

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

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

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

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

    PointerPressed and PointerReleased

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

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

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

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

    Remarks

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

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

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

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

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

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

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

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

    PointerReleased supports the ability to attach event handlers to the route that will be invoked even if the event data for the event is marked Handled. See AddHandler(Windows.UI.Xaml.RoutedEvent,System.Object,System.Boolean).

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

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

  • PointerWheelChanged
    PointerWheelChanged
    PointerWheelChanged
    PointerWheelChanged

    Occurs when the delta value of a pointer wheel changes.

    public event PointerEventHandler PointerWheelChangedpublic event PointerEventHandler PointerWheelChangedPublic Event PointerWheelChanged
    <uielement PointerWheelChanged = "eventhandler" .../>
    

    Remarks

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

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

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

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

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

    PointerWheelChanged supports the ability to attach event handlers to the route that will be invoked even if the event data for the event is marked Handled. See AddHandler(Windows.UI.Xaml.RoutedEvent,System.Object,System.Boolean).

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

    Windows 8 behavior

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

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

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

  • RightTapped
    RightTapped
    RightTapped
    RightTapped

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

    public event RightTappedEventHandler RightTappedpublic event RightTappedEventHandler RightTappedPublic Event RightTapped
    <uielement RightTapped = "eventhandler" .../>
    

    Remarks

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

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

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

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

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

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

    RightTapped supports the ability to attach event handlers to the route that will be invoked even if the event data for the event is marked Handled. See AddHandler(Windows.UI.Xaml.RoutedEvent,System.Object,System.Boolean).

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

    RightTapped for mouse and pen/stylus input

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

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

    Windows 8 behavior

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

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

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

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

  • Tapped
    Tapped
    Tapped
    Tapped

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

    public event TappedEventHandler Tappedpublic event TappedEventHandler TappedPublic Event Tapped
    <uiElement Tapped="eventhandler"/>
    

    Remarks

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

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

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

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

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

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

    Tapped supports the ability to attach event handlers to the route that will be invoked even if the event data for the event is marked Handled. See AddHandler(Windows.UI.Xaml.RoutedEvent,System.Object,System.Boolean).

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

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

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

    Tapped for mouse and pen/stylus input

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

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

    Controls that do not raise the Tapped event

    These controls do not raise the Tapped event:

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.WebHostHiddenAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.ComposableAttribute
Windows.Foundation.Metadata.ThreadingAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute

Details

Assembly

Windows.UI.Xaml.dll