Quickstart: Touch input (XAML)

Devices often have multi-touch screens that enable users to use multiple fingers simultaneously to produce different input interactions such as tapping, dragging, or pinching. The Windows Runtime has a number of different mechanisms for handling touch input, enabling you to create an immersive experience that your users can explore with confidence. This Quickstart covers the basics of using touch input in a Windows Runtime app using C++, C#, or Visual Basic. For more code examples, see the Input sample.

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

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.
• Create your first Windows Runtime app using C++, C#, or Visual Basic.
• 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.

User experience guidelines (best practices)

The platform control libraries (HTML and XAML) provide the full 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

Introduction to touch input

Many devices use touch for a majority of user input. Multi-touch screens enable users to interact with the device in natural ways. Adding touch and interaction support to your apps can greatly enhance the user experience. However, you should design your touch support carefully to ensure that your users can explore your app with confidence. Additionally, you must also be sure that your app accommodates traditional mouse and keyboard input even while it is touch optimized.

There are a number of different ways you can handle touch input in your Windows Runtime apps using C++, C#, or Visual Basic. The built-in control library provides default touch, mouse, and keyboard support using standard interactions, animated physics effects, and visual feedback.

If you do not require customized touch support, you can use what the framework provides and follow a few simple guidelines for touch optimization, described later in this Quickstart.

You can implement your own touch and interaction support, but keep in mind that users expect an intuitive experience involving direct interaction with the elements of your app. You should model your custom touch support on the built-in support in order to keep things simple and discoverable. Additionally, you should provide immediate visual feedback for all interactions to avoid user uncertainty and to encourage exploration.

To provide customized touch support, you can handle UIElement events that are grouped into three different levels of abstraction. High-level events such as Tapped enable you to respond to simple interactions. Pointer events provide lower-level details, such as pointer motion and distinguishing press and release gestures. Manipulation events provide even lower-level details, such as gesture speed and inertia and multi-touch data. These events automatically support both touch and mouse input, but also provide info to enable you to distinguish the actual input device if necessary.

Gestures

Gestures are a high-level way of interpreting touch input data into a set of common motions such as tapping, sliding, and pinching. Some common gestures used in Windows 8 are:

You can respond to simple touch and mouse gestures by handling high-level events such as Tapped, DoubleTapped, RightTapped, and Holding. You can also disable these gestures for particular elements by setting IsTapEnabled, IsDoubleTapEnabled, IsRightTapEnabled, and IsHoldingEnabled to false.

Pointer events such as PointerMoved can be used to support simple, one-finger interactions such as sliding.

For multi-touch interactions such as pinching, and interactions that use inertia and velocity data such as dragging, you use the manipulation events. The information provided by the manipulation events isn't in the form of the interaction that was performed, but rather is touch data such as position, translation delta, and velocity. You can use this touch data to determine the type of interaction that was performed. However, it is your responsibility to convert this information into the equivalent interaction.

Using pointer events

Pointer events automatically support touch and mouse input, and replace more traditional mouse events.

Touch-based pointer events are limited to single-finger interactions such as tap and slide, and they don't support velocity-based interactions. Single finger touches on the screen are converted to an equivalent Windows Runtime pointer event such as PointerPressed when you place your finger on the screen, PointerReleased when you lift your finger, and PointerMoved when you drag your finger across the screen. Other pointer events that are used by a Windows Runtime app using C++, C#, or Visual Basic are PointerExited and PointerEntered. The event arguments for the pointer events are PointerRoutedEventArgs.

The following example shows how to use the PointerPressed, PointerReleased, and the PointerExited events to handle a tap interaction on a Rectangle object.

First, a Rectangle named TestRectangle is created in XAML and event handlers are added for the PointerPressed, PointerReleased, and the PointerExited events.

<Rectangle Name="TestRectangle"
  Height="100" Width="200" Fill="Blue"
  PointerPressed="TestRectangle_PointerPressed"
  PointerReleased="TestRectangle_PointerReleased"
  PointerExited="TestRectangle_PointerExited" />

Next, event handlers for the pointer events are created. The PointerPressed event handler increases the Height and Width of the Rectangle. The PointerReleased event handler sets the Height and Width back to their starting values. Finally, the PointerExited event handler also sets the Height and Width back to their starting value.

private void TestRectangle_PointerPressed(object sender, 
    PointerRoutedEventArgs e)
{
    Rectangle rect = sender as Rectangle;

    // Change the size of the Rectangle
    if (null != rect)
    {
        rect.Width = 250;
        rect.Height = 150;
    }
}

private void TestRectangle_PointerReleased(object sender, 
    PointerRoutedEventArgs e)
{
    Rectangle rect = sender as Rectangle;

    // Reset the dimensions on the Rectangle
    if (null != rect)
    {
        rect.Width = 200;
        rect.Height = 100;
    }
}

private void TestRectangle_PointerExited(object sender, 
    PointerRoutedEventArgs e)
{
    Rectangle rect = sender as Rectangle;

    // Finger moved out of Rectangle before the pointer exited event
    // Reset the dimensions on the Rectangle
    if (null != rect)
    {
        rect.Width = 200;
        rect.Height = 100;
    }
}

Private Sub TestRectangle_PointerPressed(sender As Object, 
    e As PointerRoutedEventArgs)

    Dim rect As Rectangle = CType(sender, Rectangle)

    ' Change the size of the Rectangle
    If (rect IsNot Nothing) Then
        rect.Width = 250
        rect.Height = 150
    End If

End Sub
 
Private Sub TestRectangle_PointerReleased(sender As Object, 
    e As PointerRoutedEventArgs)

    Dim rect As Rectangle = CType(sender, Rectangle)

    ' Reset the dimensions on the Rectangle
    If (rect IsNot Nothing) Then
        rect.Width = 200
        rect.Height = 100
    End If

End Sub
 
Private Sub TestRectangle_PointerExited(sender As Object, 
    e As PointerRoutedEventArgs)

    Dim rect As Rectangle = CType(sender, Rectangle)

    ' Finger moved out of Rectangle before the pointer exited event
    ' Reset the dimensions on the Rectangle
    If (rect IsNot Nothing) Then
        rect.Width = 200
        rect.Height = 100
    End If

End Sub

Using manipulation events

If you need to support multiple finger interactions in your app, or interactions that use velocity data, then you'll need to use the manipulation events. You can use manipulation events to detect interactions such as drag, pinch, and hold. Here is a list of the manipulation events and related types for a Windows Runtime apps using C++, C#, or Visual Basic.

A gesture consists of a series of manipulation events. Each gesture starts with a ManipulationStarted event, such as when a user touches the screen. Next, one or more ManipulationDelta events are fired. For example, if you touch the screen and then drag your finger across the screen, a number of ManipulationDelta events are fired. Finally, a ManipulationCompleted event is raised when the interaction is finished.

Note  If you don't have a touch-screen monitor, you can test your manipulation event code in the simulator using a mouse and mouse wheel interface.

The following example shows how to use the ManipulationDelta events to handle a drag interaction. The sample creates a Rectangle that can be dragged across the screen.

First, a Rectangle named TestRectangle is created in XAML with a Height and Width of 200.

<Rectangle Name="TestRectangle"
  Width="200" Height="200" Fill="Blue" 
  ManipulationMode="All"/>

Next, a global TranslateTransform named dragTranslation is created for translating the Rectangle. An event handler is added to the Rectangle to handle the ManipulationDelta event, and dragTranslation is added to the RenderTransform of the Rectangle. Finally, in the ManipulationDelta event handler, the position of the Rectangle is updated by using the TranslateTransform on the Delta property.

// Global Transform used to change the position of the Rectangle.
private TranslateTransform dragTranslation;

// Constructor
public MainPage()
{
    InitializeComponent();

    // Add handler for the ManipulationDelta event
    TestRectangle.ManipulationDelta += Drag_ManipulationDelta;
    dragTranslation = new TranslateTransform();
    TestRectangle.RenderTransform = this.dragTranslation;
}

void Drag_ManipulationDelta(object sender, 
    ManipulationDeltaRoutedEventArgs e)
{
    // Move the rectangle.
    dragTranslation.X += e.Delta.Translation.X;
    dragTranslation.Y += e.Delta.Translation.Y;
}

' Global Transform used to change the position of the Rectangle.
Dim dragTranslation As TranslateTransform

' Constructor
Public Sub New()

    InitializeComponent()

    ' Add handler for the ManipulationDelta event
    AddHandler TestRectangle.ManipulationDelta, 
        AddressOf Me.Drag_ManipulationDelta
    dragTranslation = New TranslateTransform
    TestRectangle.RenderTransform = Me.dragTranslation

End Sub

Private Sub Drag_ManipulationDelta(sender As Object, 
    e As ManipulationDeltaRoutedEventArgs)

    ' Move the rectangle.
    dragTranslation.X = (dragTranslation.X + e.Delta.Translation.X)
    dragTranslation.Y = (dragTranslation.Y + e.Delta.Translation.Y)

End Sub

UI design and touch input

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

How you design your user interface can influence how easy your app is to use with touch input. To ensure that your app is touch optimized, follow these guidelines:

• Be sure to accommodate the size difference between mouse pointers and fingertips. Touch requires larger UI elements to ensure accuracy and to prevent fingers from obscuring important information.
• Always provide immediate, direct visual feedback for touch interactions. For example, you can use highlighting or tool tips to indicate the current touch target and prevent the accidental activation of other targets.
• Use physics effects such as acceleration and inertia to provide a natural feel in interactions such as panning.
• Use snap points and other constraints to help guide users to the most useful states.

For additional user experience design guidelines related to touch, see Guidelines for user interaction.

Routed events

All of the pointer events, gesture events and manipulation events mentioned here are implemented as routed events. This means that the event can potentially be handled by objects other than the one that originally raised the event. Successive parents in an object tree, such as the parent containers of a UI element or the root Page, can choose to handle these events even if the original element does not. Conversely, any object that does handle the event can mark the event handled so that it no longer reaches any parent element. For more info on the routed event concept and how it affects how you write handlers for routed events, see Events and routed events overview.

Related topics

Developers

Responding to user interaction

Developing Windows Runtime apps (XAML)

Quickstart: Touch input

Designers

Touch interaction design