Quickstart: Pointers (XAML)
Touch, mouse, and pen/stylus interactions are received, processed, and managed as pointer input in Windows Runtime apps using C++, C#, or Visual Basic.
If you're new to developing Windows Runtime app using C++, C#, or Visual Basic: Have a look through these topics to get familiar with the technologies discussed here.
Create your first Windows Store app using C# or Visual Basic
Create your first Windows Store app using C++
Roadmap for Windows Runtime apps using C# or Visual Basic
Roadmap for Windows Runtime apps using C++
Learn about events with Events and routed events overview
App features, start to finish: Explore this functionality in more depth as part of our App features, start to finish series
User interaction, start to finish (XAML)
User interaction customization, start to finish (XAML)
User experience guidelines:
The platform control libraries (HTML and XAML) provide the full Windows user interaction experience, including standard interactions, animated physics effects, and visual feedback. If you don't need customized interaction support, use these built-in controls.
If the platform controls are not sufficient, these user interaction guidelines can help you provide a compelling and immersive interaction experience that is consistent across input modes. These guidelines are primarily focused on touch input, but they are still relevant for touchpad, mouse, keyboard, and stylus input.
- Guidelines for common user interactions
- Guidelines for cross-slide
- Guidelines for optical zoom and resizing
- Guidelines for panning
- Guidelines for rotation
- Guidelines for Semantic Zoom
- Guidelines for selecting text and images
- Guidelines for targeting
- Guidelines for visual feedback
Samples: See this functionality in action in our Windows Store app samples.
Input: XAML user input events sample
Input: Device capabilities sample
Input: Manipulations and gestures (C++) sample
Input: Touch hit testing sample
XAML scrolling, panning, and zooming sample
Objective: To learn how to listen for and handle pointer input.
Prerequisites
We assume that you can create a basic Windows Runtime app using C++, C#, or Visual Basic.
To complete this tutorial, you need to:
- Install Windows 8
- Install Microsoft Visual Studio.
- Get a developer license. For instructions, see Develop using Visual Studio 2013.
- Review Adding controls and content (Windows Runtime apps using C#/VB/C++ and XAML) to learn about Windows Runtime app using C++, C#, or Visual Basic objects and controls.
Time to complete: 30 minutes.
Instructions
What is pointer input?
By unifying mouse, pen/stylus, and touch input as abstract pointer input you can handle user interactions with your app independently of the type of input device being used.
A Pointer object represents a single, unique input contact from an input device (such as a mouse, pen/stylus, single finger, or multiple fingers). The system creates a pointer when a contact is first detected and destroys it when the pointer leaves (departs) detection range or is canceled. In the case of multiple devices or multi-touch input, each contact is treated as a unique pointer.
There is an extensive set of pointer-based input APIs that can intercept input data directly from various devices. You can handle pointer events to get basic info such as detection state (in range or in contact) and device type, and extended info such as location, pressure, and contact geometry. Because, in many cases, apps must respond to different input modes in different ways, specific device properties such as which mouse button a user pressed or whether a user is using the pen eraser tip are also available. For example, touch can be filtered to support interactions such as panning and scrolling while mouse and pen/stylus are typically more suited to tasks such as ink and drawing. If your app needs to differentiate between input devices and their capabilities, see Quickstart: Identifying input devices.
If you implement your own interaction support, keep in mind that users expect an intuitive experience involving direct interaction with the UI elements in your app. We recommend that you model your custom interactions on the platform control libraries (HTML and XAML) to keep things consistent and discoverable. The controls in these libraries provide the full Windows 8.1 user interaction experience, including standard interactions, animated physics effects, visual feedback, and accessibility. Create custom interactions only if there is a clear, well-defined requirement and basic interactions don't support your scenario.
Create the UI
For this example, we use a rectangle (targetContainer) as the target object for pointer input. The color of the target changes when the pointer status changes.
Details for each pointer are displayed under the rectangle and the pointer events themselves are displayed to the left of the rectangle (to report event sequence).
This is the Extensible Application Markup Language (XAML) for this example.
<Page
x:Class="PointerInput.MainPage"
IsTabStop="false"
xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml"
xmlns:local="using:PointerInput"
xmlns:d="https://schemas.microsoft.com/expression/blend/2008"
xmlns:mc="https://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>
Listen for pointer events
In most cases, we recommend that you get pointer info through the event argument of the pointer event handlers in your chosen Windows 8 language framework (Windows Runtime apps using JavaScript, Windows Runtime apps using C++, C#, or Visual Basic, or Windows Store apps using DirectX with C++).
If the event argument doesn't intrinsically expose the pointer details required by your app, you can get access to extended pointer data exposed by a PointerPoint object through the GetCurrentPoint and GetIntermediatePoints methods of PointerRoutedEventArgs.
For this example, we use a rectangle (targetContainer) as the target object for pointer input. The color of the target changes when the pointer status changes.
Details for each pointer are displayed in a floating text block associated with the pointer and the pointer events themselves are displayed to the right of the rectangle (to report event sequence).
The following code sets up the target object, declares global variables, and identifies the various pointer event listeners for the target.
// For this example, we track simultaneous contacts in case the
// number of contacts has reached the maximum supported by the device.
// Depending on the device, additional contacts might be ignored
// (PointerPressed not fired).
uint numActiveContacts;
Windows.Devices.Input.TouchCapabilities touchCapabilities = new Windows.Devices.Input.TouchCapabilities();
// Dictionary to maintain information about each active contact.
// An entry is added during PointerPressed/PointerEntered events and removed
// during PointerReleased/PointerCaptureLost/PointerCanceled/PointerExited events.
Dictionary<uint, Windows.UI.Xaml.Input.Pointer> contacts;
public MainPage()
{
this.InitializeComponent();
numActiveContacts = 0;
// Initialize the dictionary.
contacts = new Dictionary<uint, Windows.UI.Xaml.Input.Pointer>((int)touchCapabilities.Contacts);
// Declare the pointer event handlers.
Target.PointerPressed += new PointerEventHandler(Target_PointerPressed);
Target.PointerEntered += new PointerEventHandler(Target_PointerEntered);
Target.PointerReleased += new PointerEventHandler(Target_PointerReleased);
Target.PointerExited += new PointerEventHandler(Target_PointerExited);
Target.PointerCanceled += new PointerEventHandler(Target_PointerCanceled);
Target.PointerCaptureLost += new PointerEventHandler(Target_PointerCaptureLost);
Target.PointerMoved += new PointerEventHandler(Target_PointerMoved);
Target.PointerWheelChanged += new PointerEventHandler(Target_PointerWheelChanged);
}
Handle pointer events
Next, we use UI feedback to demonstrate basic pointer event handlers.
This handler manages a pointer contact (down, pressed) event. We add the event to the event log, add the pointer to the pointer array used for tracking the pointers of interest, and display the pointer details.
Note PointerPressed and PointerReleased events do not always occur in pairs. Your app should listen for and handle any event that might conclude a pointer down action (such as PointerExited, PointerCanceled, and PointerCaptureLost).
// PointerPressed and PointerReleased events do not always occur in pairs. // Your app should listen for and handle any event that might conclude a pointer down action // (such as PointerExited, PointerCanceled, and PointerCaptureLost). // For this example, we track the number of contacts in case the // number of contacts has reached the maximum supported by the device. // Depending on the device, additional contacts might be ignored // (PointerPressed not fired). void Target_PointerPressed(object sender, PointerRoutedEventArgs e) { if (Convert.ToBoolean(touchCapabilities.TouchPresent) && (numActiveContacts > touchCapabilities.Contacts)) { // Number of supported contacts exceeded. return; } Windows.UI.Xaml.Input.Pointer ptr = e.Pointer; // Update event sequence. eventLog.Text += "\nDown: " + ptr.PointerId; // Change background color of target when pointer contact detected. Target.Fill = new SolidColorBrush(Windows.UI.Colors.Green); // Check if pointer already exists (for example, enter occurred prior to press). if (contacts.ContainsKey(ptr.PointerId)) { return; } // Add contact to dictionary. contacts[ptr.PointerId] = ptr; ++numActiveContacts; // Prevent most handlers along the event route from handling the same event again. e.Handled = true; // Display pointer details. createInfoPop(e); }This handler manages a pointer enter (over, hover for pen) event. We add the event to the event log, add the pointer to the pointer collection, and display the pointer details.
private void Target_PointerEntered(object sender, PointerRoutedEventArgs e) { Windows.UI.Xaml.Input.Pointer ptr = e.Pointer; // Update event sequence. eventLog.Text += "\nOver: " + ptr.PointerId; if (contacts.Count == 0) { // Change background color of target when pointer contact detected. Target.Fill = new SolidColorBrush(Windows.UI.Colors.Blue); } // Check if pointer already exists (if enter occurred prior to down). if (contacts.ContainsKey(ptr.PointerId)) { return; } // Add contact to dictionary. contacts[ptr.PointerId] = ptr; ++numActiveContacts; // Prevent most handlers along the event route from handling the same event again. e.Handled = true; // Display pointer details. createInfoPop(e); }This handler manages a pointer move event. We add the event to the event log and update the pointer details.
Important 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.
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); }This handler manages a mouse wheel event (rotation). We add the event to the event log, add the pointer to the pointer array (if necessary), and display the pointer details.
private void Target_PointerWheelChanged(object sender, PointerRoutedEventArgs e) { Windows.UI.Xaml.Input.Pointer ptr = e.Pointer; // Update event sequence. eventLog.Text += "\nMouse wheel: " + ptr.PointerId; // Check if pointer already exists (for example, enter occurred prior to wheel). if (contacts.ContainsKey(ptr.PointerId)) { return; } // Add contact to dictionary. contacts[ptr.PointerId] = ptr; ++numActiveContacts; // Prevent most handlers along the event route from handling the same event again. e.Handled = true; // Display pointer details. createInfoPop(e); }This handler manages a pointer departure (lifted, up) event where contact with the digitizer is terminated. We add the event to the event log, remove the pointer from the pointer collection, and update the pointer details.
void Target_PointerReleased(object sender, PointerRoutedEventArgs e) { Windows.UI.Xaml.Input.Pointer ptr = e.Pointer; // Update event sequence. eventLog.Text += "\nUp: " + ptr.PointerId; // If event source is mouse pointer and the pointer is still // over the target, retain pointer and pointer details. // Return without removing pointer from pointers dictionary. // For this example, we assume a maximum of one mouse pointer. if (ptr.PointerDeviceType == Windows.Devices.Input.PointerDeviceType.Mouse) { Target.Fill = new SolidColorBrush(Windows.UI.Colors.Blue); return; } // Update target UI. Target.Fill = new SolidColorBrush(Windows.UI.Colors.Red); destroyInfoPop(ptr); // Remove contact from dictionary. if (contacts.ContainsKey(ptr.PointerId)) { contacts[ptr.PointerId] = null; contacts.Remove(ptr.PointerId); --numActiveContacts; } // Prevent most handlers along the event route from handling the same event again. e.Handled = true; }This handler manages a pointer departure (out) event where contact with the digitizer is maintained. We add the event to the event log, remove the pointer from the pointer array, and update the pointer details.
private void Target_PointerExited(object sender, PointerRoutedEventArgs e) { Windows.UI.Xaml.Input.Pointer ptr = e.Pointer; // Update event sequence. eventLog.Text += "\nPointer exited: " + ptr.PointerId; // Remove contact from dictionary. if (contacts.ContainsKey(ptr.PointerId)) { contacts[ptr.PointerId] = null; contacts.Remove(ptr.PointerId); --numActiveContacts; } // Update the UI and pointer details. destroyInfoPop(ptr); if (contacts.Count == 0) { Target.Fill = new SolidColorBrush(Windows.UI.Colors.Red); } // Prevent most handlers along the event route from handling the same event again. e.Handled = true; }This handler manages a pointer canceled event. We add the event to the event log, remove the pointer from the pointer array, and update the pointer details.
// Fires for for various reasons, including: // - Touch contact canceled by pen coming into range of the surface. // - The device doesn't report an active contact for more than 100ms. // - The desktop is locked or the user logged off. // - The number of simultaneous contacts exceeded the number supported by the device. private void Target_PointerCanceled(object sender, PointerRoutedEventArgs e) { Windows.UI.Xaml.Input.Pointer ptr = e.Pointer; // Update event sequence. eventLog.Text += "\nPointer canceled: " + ptr.PointerId; // Remove contact from dictionary. if (contacts.ContainsKey(ptr.PointerId)) { contacts[ptr.PointerId] = null; contacts.Remove(ptr.PointerId); --numActiveContacts; } destroyInfoPop(ptr); if (contacts.Count == 0) { Target.Fill = new SolidColorBrush(Windows.UI.Colors.Black); } // Prevent most handlers along the event route from handling the same event again. e.Handled = true; }This handler manages a lost pointer capture event. We add the event to the event log, remove the pointer from the pointer array, and update the pointer details.
Note PointerCaptureLost can occur instead of PointerReleased. Pointer capture can be lost because of user interactions or because another pointer was captured programmatically or the current pointer capture was deliberately released.
// Fires for for various reasons, including: // - User interactions // - Programmatic capture of another pointer // - Captured pointer was deliberately released // PointerCaptureLost can fire instead of PointerReleased. private void Target_PointerCaptureLost(object sender, PointerRoutedEventArgs e) { Windows.UI.Xaml.Input.Pointer ptr = e.Pointer; // Update event sequence. eventLog.Text += "\nPointer capture lost: " + ptr.PointerId; // Remove contact from dictionary. if (contacts.ContainsKey(ptr.PointerId)) { contacts[ptr.PointerId] = null; contacts.Remove(ptr.PointerId); --numActiveContacts; } destroyInfoPop(ptr); if (contacts.Count == 0) { Target.Fill = new SolidColorBrush(Windows.UI.Colors.Black); } // Prevent most handlers along the event route from handling the same event again. e.Handled = true; }
Get pointer properties
As stated earlier, the language framework you choose for your app dictates how you get pointer properties. Windows Runtime apps using C++, C#, or Visual Basic must get most extended pointer info through a Windows.UI.Input.PointerPoint object obtained through the GetCurrentPoint and GetIntermediatePoints methods of PointerRoutedEventArgs.
First, we create a new TextBlock for each pointer.
void createInfoPop(PointerRoutedEventArgs e) { TextBlock pointerDetails = new TextBlock(); Windows.UI.Input.PointerPoint ptrPt = e.GetCurrentPoint(Target); pointerDetails.Name = ptrPt.PointerId.ToString(); pointerDetails.Foreground = new SolidColorBrush(Windows.UI.Colors.White); pointerDetails.Text = queryPointer(ptrPt); TranslateTransform x = new TranslateTransform(); x.X = ptrPt.Position.X + 20; x.Y = ptrPt.Position.Y + 20; pointerDetails.RenderTransform = x; Container.Children.Add(pointerDetails); }Then we provide a way to update the pointer info in an existing TextBlock associated with that pointer.
void updateInfoPop(PointerRoutedEventArgs e) { foreach (var pointerDetails in Container.Children) { if (pointerDetails.GetType().ToString() == "Windows.UI.Xaml.Controls.TextBlock") { TextBlock _TextBlock = (TextBlock)pointerDetails; if (_TextBlock.Name == e.Pointer.PointerId.ToString()) { // To get pointer location details, we need extended pointer info. // We get the pointer info through the getCurrentPoint method // of the event argument. Windows.UI.Input.PointerPoint ptrPt = e.GetCurrentPoint(Target); TranslateTransform x = new TranslateTransform(); x.X = ptrPt.Position.X + 20; x.Y = ptrPt.Position.Y + 20; pointerDetails.RenderTransform = x; _TextBlock.Text = queryPointer(ptrPt); } } } }Finally, we query various pointer properties.
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; }
Complete example
The following is the C# code for this example. See Related topics at the bottom of this page for links to more complex samples.
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using Windows.Foundation;
using Windows.Foundation.Collections;
using Windows.UI.Input;
using Windows.UI.Xaml;
using Windows.UI.Xaml.Controls;
using Windows.UI.Xaml.Controls.Primitives;
using Windows.UI.Xaml.Data;
using Windows.UI.Xaml.Input;
using Windows.UI.Xaml.Media;
using Windows.UI.Xaml.Navigation;
// The Blank Page item template is documented at https://go.microsoft.com/fwlink/?LinkId=234238
namespace PointerInput
{
/// <summary>
/// An empty page that can be used on its own or navigated to within a Frame.
/// </summary>
public sealed partial class MainPage : Page
{
// For this example, we track simultaneous contacts in case the
// number of contacts has reached the maximum supported by the device.
// Depending on the device, additional contacts might be ignored
// (PointerPressed not fired).
uint numActiveContacts;
Windows.Devices.Input.TouchCapabilities touchCapabilities = new Windows.Devices.Input.TouchCapabilities();
// Dictionary to maintain information about each active contact.
// An entry is added during PointerPressed/PointerEntered events and removed
// during PointerReleased/PointerCaptureLost/PointerCanceled/PointerExited events.
Dictionary<uint, Windows.UI.Xaml.Input.Pointer> contacts;
public MainPage()
{
this.InitializeComponent();
numActiveContacts = 0;
// Initialize the dictionary.
contacts = new Dictionary<uint, Windows.UI.Xaml.Input.Pointer>((int)touchCapabilities.Contacts);
// Declare the pointer event handlers.
Target.PointerPressed += new PointerEventHandler(Target_PointerPressed);
Target.PointerEntered += new PointerEventHandler(Target_PointerEntered);
Target.PointerReleased += new PointerEventHandler(Target_PointerReleased);
Target.PointerExited += new PointerEventHandler(Target_PointerExited);
Target.PointerCanceled += new PointerEventHandler(Target_PointerCanceled);
Target.PointerCaptureLost += new PointerEventHandler(Target_PointerCaptureLost);
Target.PointerMoved += new PointerEventHandler(Target_PointerMoved);
Target.PointerWheelChanged += new PointerEventHandler(Target_PointerWheelChanged);
}
// PointerPressed and PointerReleased events do not always occur in pairs.
// Your app should listen for and handle any event that might conclude a pointer down action
// (such as PointerExited, PointerCanceled, and PointerCaptureLost).
// For this example, we track the number of contacts in case the
// number of contacts has reached the maximum supported by the device.
// Depending on the device, additional contacts might be ignored
// (PointerPressed not fired).
void Target_PointerPressed(object sender, PointerRoutedEventArgs e)
{
if (Convert.ToBoolean(touchCapabilities.TouchPresent) && (numActiveContacts > touchCapabilities.Contacts))
{
// Number of supported contacts exceeded.
return;
}
Windows.UI.Xaml.Input.Pointer ptr = e.Pointer;
// Update event sequence.
eventLog.Text += "\nDown: " + ptr.PointerId;
// Change background color of target when pointer contact detected.
Target.Fill = new SolidColorBrush(Windows.UI.Colors.Green);
// Check if pointer already exists (for example, enter occurred prior to press).
if (contacts.ContainsKey(ptr.PointerId))
{
return;
}
// Add contact to dictionary.
contacts[ptr.PointerId] = ptr;
++numActiveContacts;
// Prevent most handlers along the event route from handling the same event again.
e.Handled = true;
// Display pointer details.
createInfoPop(e);
}
void Target_PointerReleased(object sender, PointerRoutedEventArgs e)
{
Windows.UI.Xaml.Input.Pointer ptr = e.Pointer;
// Update event sequence.
eventLog.Text += "\nUp: " + ptr.PointerId;
// If event source is mouse pointer and the pointer is still
// over the target, retain pointer and pointer details.
// Return without removing pointer from pointers dictionary.
// For this example, we assume a maximum of one mouse pointer.
if (ptr.PointerDeviceType == Windows.Devices.Input.PointerDeviceType.Mouse)
{
Target.Fill = new SolidColorBrush(Windows.UI.Colors.Blue);
return;
}
// Update target UI.
Target.Fill = new SolidColorBrush(Windows.UI.Colors.Red);
destroyInfoPop(ptr);
// Remove contact from dictionary.
if (contacts.ContainsKey(ptr.PointerId))
{
contacts[ptr.PointerId] = null;
contacts.Remove(ptr.PointerId);
--numActiveContacts;
}
// Prevent most handlers along the event route from handling the same event again.
e.Handled = true;
}
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_PointerEntered(object sender, PointerRoutedEventArgs e)
{
Windows.UI.Xaml.Input.Pointer ptr = e.Pointer;
// Update event sequence.
eventLog.Text += "\nOver: " + ptr.PointerId;
if (contacts.Count == 0)
{
// Change background color of target when pointer contact detected.
Target.Fill = new SolidColorBrush(Windows.UI.Colors.Blue);
}
// Check if pointer already exists (if enter occurred prior to down).
if (contacts.ContainsKey(ptr.PointerId))
{
return;
}
// Add contact to dictionary.
contacts[ptr.PointerId] = ptr;
++numActiveContacts;
// Prevent most handlers along the event route from handling the same event again.
e.Handled = true;
// Display pointer details.
createInfoPop(e);
}
private void Target_PointerWheelChanged(object sender, PointerRoutedEventArgs e)
{
Windows.UI.Xaml.Input.Pointer ptr = e.Pointer;
// Update event sequence.
eventLog.Text += "\nMouse wheel: " + ptr.PointerId;
// Check if pointer already exists (for example, enter occurred prior to wheel).
if (contacts.ContainsKey(ptr.PointerId))
{
return;
}
// Add contact to dictionary.
contacts[ptr.PointerId] = ptr;
++numActiveContacts;
// Prevent most handlers along the event route from handling the same event again.
e.Handled = true;
// Display pointer details.
createInfoPop(e);
}
// Fires for for various reasons, including:
// - User interactions
// - Programmatic capture of another pointer
// - Captured pointer was deliberately released
// PointerCaptureLost can fire instead of PointerReleased.
private void Target_PointerCaptureLost(object sender, PointerRoutedEventArgs e)
{
Windows.UI.Xaml.Input.Pointer ptr = e.Pointer;
// Update event sequence.
eventLog.Text += "\nPointer capture lost: " + ptr.PointerId;
// Remove contact from dictionary.
if (contacts.ContainsKey(ptr.PointerId))
{
contacts[ptr.PointerId] = null;
contacts.Remove(ptr.PointerId);
--numActiveContacts;
}
destroyInfoPop(ptr);
if (contacts.Count == 0)
{
Target.Fill = new SolidColorBrush(Windows.UI.Colors.Black);
}
// Prevent most handlers along the event route from handling the same event again.
e.Handled = true;
}
// Fires for for various reasons, including:
// - Touch contact canceled by pen coming into range of the surface.
// - The device doesn't report an active contact for more than 100ms.
// - The desktop is locked or the user logged off.
// - The number of simultaneous contacts exceeded the number supported by the device.
private void Target_PointerCanceled(object sender, PointerRoutedEventArgs e)
{
Windows.UI.Xaml.Input.Pointer ptr = e.Pointer;
// Update event sequence.
eventLog.Text += "\nPointer canceled: " + ptr.PointerId;
// Remove contact from dictionary.
if (contacts.ContainsKey(ptr.PointerId))
{
contacts[ptr.PointerId] = null;
contacts.Remove(ptr.PointerId);
--numActiveContacts;
}
destroyInfoPop(ptr);
if (contacts.Count == 0)
{
Target.Fill = new SolidColorBrush(Windows.UI.Colors.Black);
}
// Prevent most handlers along the event route from handling the same event again.
e.Handled = true;
}
private void Target_PointerExited(object sender, PointerRoutedEventArgs e)
{
Windows.UI.Xaml.Input.Pointer ptr = e.Pointer;
// Update event sequence.
eventLog.Text += "\nPointer exited: " + ptr.PointerId;
// Remove contact from dictionary.
if (contacts.ContainsKey(ptr.PointerId))
{
contacts[ptr.PointerId] = null;
contacts.Remove(ptr.PointerId);
--numActiveContacts;
}
// Update the UI and pointer details.
destroyInfoPop(ptr);
if (contacts.Count == 0)
{
Target.Fill = new SolidColorBrush(Windows.UI.Colors.Red);
}
// Prevent most handlers along the event route from handling the same event again.
e.Handled = true;
}
void createInfoPop(PointerRoutedEventArgs e)
{
TextBlock pointerDetails = new TextBlock();
Windows.UI.Input.PointerPoint ptrPt = e.GetCurrentPoint(Target);
pointerDetails.Name = ptrPt.PointerId.ToString();
pointerDetails.Foreground = new SolidColorBrush(Windows.UI.Colors.White);
pointerDetails.Text = queryPointer(ptrPt);
TranslateTransform x = new TranslateTransform();
x.X = ptrPt.Position.X + 20;
x.Y = ptrPt.Position.Y + 20;
pointerDetails.RenderTransform = x;
Container.Children.Add(pointerDetails);
}
void destroyInfoPop(Windows.UI.Xaml.Input.Pointer ptr)
{
foreach (var pointerDetails in Container.Children)
{
if (pointerDetails.GetType().ToString() == "Windows.UI.Xaml.Controls.TextBlock")
{
TextBlock _TextBlock = (TextBlock)pointerDetails;
if (_TextBlock.Name == ptr.PointerId.ToString())
{
Container.Children.Remove(pointerDetails);
}
}
}
}
void updateInfoPop(PointerRoutedEventArgs e)
{
foreach (var pointerDetails in Container.Children)
{
if (pointerDetails.GetType().ToString() == "Windows.UI.Xaml.Controls.TextBlock")
{
TextBlock _TextBlock = (TextBlock)pointerDetails;
if (_TextBlock.Name == e.Pointer.PointerId.ToString())
{
// To get pointer location details, we need extended pointer info.
// We get the pointer info through the getCurrentPoint method
// of the event argument.
Windows.UI.Input.PointerPoint ptrPt = e.GetCurrentPoint(Target);
TranslateTransform x = new TranslateTransform();
x.X = ptrPt.Position.X + 20;
x.Y = ptrPt.Position.Y + 20;
pointerDetails.RenderTransform = x;
_TextBlock.Text = queryPointer(ptrPt);
}
}
}
}
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;
}
}
}
Summary and next steps
In this Quickstart, you learned about pointer input in Windows Runtime apps using C++, C#, or Visual Basic.
Pointer events are useful for managing simple interactions such as tap, slide, and device-specific interactions including input from secondary mouse buttons, mouse wheel, pen barrel button, and pen eraser.
For handling more elaborate interactions, such as the gestures described in the Windows 8 touch language, see Quickstart: Touch input.
For more information on the Windows 8 touch language, see Touch interaction design.
Related topics
Developers
Responding to user interaction
Developing Windows Store apps (XAML)
Designers