Windows UWP API Reference

Pointer

Represents a pointer input device, such as a mouse, pen, or finger, that interacts with the application window. This topic provides an overview of pointer input in Universal Windows Platform (UWP) applications.

Overview

Pointer input is a fundamental aspect of modern user interfaces, enabling a rich and intuitive interaction model across various devices. UWP abstracts different pointer devices into a unified model, allowing developers to write code that responds to touch, pen, and mouse input in a consistent manner.

Key concepts related to pointer input include:

• Pointer types: Distinguishing between touch, pen, and mouse inputs.
• Pointer properties: Accessing information like position, pressure, and contact shape.
• Pointer events: Handling events like PointerEntered, PointerMoved, PointerPressed, PointerReleased, and PointerCanceled.
• Pointer Capture: Maintaining exclusive input events for a specific element.
• Multi-touch gestures: Recognizing common user gestures like pinch-to-zoom and rotate.

Core Concepts

Pointer Types

The PointerPointProperties class provides information about the type of pointer device involved in an input event. You can check these properties to differentiate between:

• Touch: Input from a finger.
• Pen: Input from a stylus or digital pen.
• Mouse: Input from a physical mouse device.

Pointer Events

UWP applications handle pointer input through a series of events fired by UI elements. The most common events are:

• PointerEntered: Fired when a pointer enters the bounds of an element.
• PointerMoved: Fired when a pointer moves within the bounds of an element.
• PointerPressed: Fired when a pointer button is pressed or a touch/pen contact begins.
• PointerReleased: Fired when a pointer button is released or a touch/pen contact ends.
• PointerCanceled: Fired when a pointer event is canceled (e.g., due to system interruption).
• PointerExited: Fired when a pointer leaves the bounds of an element.

PointerDeviceType

The PointerDeviceType enumeration identifies the type of pointer device.

Working with Pointer Events

You can handle pointer events by attaching event handlers to UI elements in your XAML or C# code.

Example: Handling Pointer Pressed and Moved

This example shows how to handle the PointerPressed and PointerMoved events on a Grid element.

// In your C# code-behind file (e.g., MainPage.xaml.cs)

public sealed partial class MainPage : Page
{
    public MainPage()
    {
        this.InitializeComponent();
        MyGrid.PointerPressed += MyGrid_PointerPressed;
        MyGrid.PointerMoved += MyGrid_PointerMoved;
    }

    private void MyGrid_PointerPressed(object sender, PointerRoutedEventArgs e)
    {
        var pointerProperties = e.GetCurrentPoint(MyGrid).Properties;
        var pointerType = pointerProperties.PointerDeviceType;
        var position = e.GetCurrentPoint(MyGrid).Position;

        System.Diagnostics.Debug.WriteLine($"Pointer Pressed: Type={pointerType}, Position=({position.X}, {position.Y})");

        // You can also check for specific properties like IsPrimary, IsInRange, etc.
        if (pointerProperties.IsLeftButtonPressed)
        {
            System.Diagnostics.Debug.WriteLine("Left mouse button is pressed.");
        }
    }

    private void MyGrid_PointerMoved(object sender, PointerRoutedEventArgs e)
    {
        // Only process if the pointer is pressed and is the primary pointer for this event
        if (e.Pointer.IsInContact && e.Pointer.IsPrimary)
        {
            var pointerProperties = e.GetCurrentPoint(MyGrid).Properties;
            var position = e.GetCurrentPoint(MyGrid).Position;
            var pressure = pointerProperties.Pressure; // For touch/pen

            System.Diagnostics.Debug.WriteLine($"Pointer Moved: Position=({position.X}, {position.Y}), Pressure={pressure}");
        }
    }
}

Example: XAML Setup

Ensure your XAML includes the element you want to attach events to, for example, a Grid named MyGrid.

<Grid x:Name="MyGrid" Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
    <TextBlock Text="Interact with me!" HorizontalAlignment="Center" VerticalAlignment="Center" FontSize="24"/>
</Grid>

PointerPoint and PointerPointProperties

The PointerPoint object provides detailed information about a pointer at a specific point in time. It's accessed via PointerRoutedEventArgs.GetCurrentPoint().

PointerPointProperties Members:

PointerDeviceType PointerDeviceType

Gets the type of the pointer device (Touch, Pen, Mouse).

bool IsPrimary

Gets a value indicating whether this pointer is the primary pointer for the current interaction.

bool IsInRange

Gets a value indicating whether the pointer is within the range of the device.

bool IsCanceled

Gets a value indicating whether the pointer interaction was canceled.

double Pressure

Gets the pressure exerted by the pointer (for pen and touch).

uint Twist

Gets the twist of the pointer (for pen).

uint Rotation

Gets the rotation of the pointer (for pen).

bool IsLeftButtonPressed

Gets a value indicating whether the left mouse button is pressed.

bool IsRightButtonPressed

Gets a value indicating whether the right mouse button is pressed.

bool IsMiddleButtonPressed

Gets a value indicating whether the middle mouse button is pressed.

bool IsXButton1Pressed

Gets a value indicating whether the first XButton (e.g., Back) is pressed.

bool IsXButton2Pressed

Gets a value indicating whether the second XButton (e.g., Forward) is pressed.

Pointer Capture

Pointer capture allows an element to continue receiving pointer events even if the pointer moves outside its bounds. This is useful for scenarios like dragging or manipulating elements.

Further Reading

• Handling Touch Input
• Handling Pen Input
• Handling Mouse Input
• Handling Gestures