Quickstart: Touch input for Windows Phone 8

[ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]

Windows Phone devices have multi-touch screens that give users the ability to use multiple fingers simultaneously for input gestures such as tapping, flicking, and pinching. Windows Phone has multiple mechanisms for handling different kinds of touch input. This Quickstart covers the basics of using touch input in your Windows Phone app.

This topic contains the following sections.

• Introduction to touch input
• Gestures
• Using mouse events
• Using manipulation events
• UI design and touch input
• Related Topics

Introduction to touch input

Windows Phone relies on touch for a majority of user input. Windows Phone supports multi-touch screens through which users can use natural gestures to interact with the phone. Adding touch and gesture support to your apps can greatly enhance the user experience. You have several options for handling touch input in your Windows Phone apps.

• Mouse events. Mouse events can detect simple, one-finger gestures such as tap and double tap. You can add mouse event handlers to your app quickly, and they’re an easy way to get basic touch support.

• Manipulation events. You can use manipulation events like ManipulationStarted and ManipulationDelta to handle more complex gestures such as multi-touch gestures and gestures that use inertia and velocity data.

• Lower-level touch events. The TouchPoint class is another way to handle touch input in Windows Phone. TouchPoint is a lower-level input system that isn't covered in this Quickstart.

• Gesture classes. A fourth way to handle touch and gesture on the phone is with the GestureService and GestureListener classes in the Windows Phone Toolkit. You can download the toolkit from the Toolkit web site on Codeplex. The toolkit is an open-source project and not a core part of Windows Phone.

Gestures

Gestures are a high-level way of interpreting touch input data into a set of common motions such as tapping, flicking, and pinching. Some common gestures used in Windows Phone are described in the following table.

You can use Windows Phone mouse events such as MouseLeftButtonUp and MouseMove to support simple, one-finger gestures such as a tap.

For multi-touch gestures such as pinching, and gestures that use inertia and velocity data such as flicking, manipulation events are required. The info provided by manipulation events isn't in the form of the gesture that was performed, but rather it is touch data such as position, translation delta, and velocity. This touch data helps determine the type of gesture that was used. It's the responsibility of the Windows Phone developer to convert this information into the equivalent gesture. However, the Windows Phone Toolkit provides gesture support through the GestureService and GestureListener classes.

Using mouse events

The simplest way to enable touch input in your Windows Phone app is to use mouse events. Mouse events are limited to single-finger gestures such as tap and double tap, and they don't support velocity-based gestures. A single-finger touch on the screen is converted to an equivalent Windows Phone mouse event such as MouseLeftButtonDown when you place your finger on the screen, MouseLeftButtonUp when you lift your finger, and MouseMove when you drag your finger across the screen. Other mouse events that are used by Windows Phone are MouseLeave and MouseEnter. The event arguments for the mouse events are MouseButtonEventArgs. The Click event on the Button class is another easy way to add support for tap gestures on buttons.

The following example shows how to use the MouseLeftButtonDown, MouseLeftButtonUp, and MouseLeave events to handle a tap gesture on a Rectangle object.

First, a Rectangle named TestRectangle is created in XAML and event handlers are added for the MouseLeftButtonDown, MouseLeftButtonUp, and MouseLeave events.

<Rectangle Name="TestRectangle"
    Height="100"
    Width="200"
    Fill="Blue"
    MouseLeftButtonDown="Tap_LeftButtonDown"
    MouseLeftButtonUp="Tap_LeftButtonUp"
    MouseLeave="Tap_MouseLeave" />

Next, event handlers for the mouse events are created. The MouseLeftButtonDown event handler increases the Height and Width of the Rectangle. The MouseLeftButtonUp event handler sets the Height and Width back to their starting values. Finally, the MouseLeave event handler also sets the Height and Width back to their starting value.

private void Tap_LeftButtonDown(object sender, MouseButtonEventArgs e)
{
    Rectangle rect = sender as Rectangle;
    // Change the size of the Rectangle.
    if (null != rect)
    {
        rect.Width = 250;
        rect.Height = 150;
    }
}
private void Tap_LeftButtonUp(object sender, MouseButtonEventArgs e)
{
    Rectangle rect = sender as Rectangle;
    // Reset the dimensions on the Rectangle.
    if (null != rect)
    {
        rect.Width = 200;
        rect.Height = 100;
    }
}
private void Tap_MouseLeave(object sender, MouseEventArgs e)
{
    Rectangle rect = sender as Rectangle;
    // Finger moved out of Rectangle before the mouse up event.
    // Reset the dimensions on the Rectangle.
    if (null != rect)
    {
        rect.Width = 200;
        rect.Height = 100;
    }
}

Private Sub Tap_LeftButtonDown(ByVal sender As Object, ByVal e As MouseButtonEventArgs)
    Dim rect As Rectangle = CType(sender,Rectangle)
    ' Change the size of the Rectangle.
    If (Not (rect) Is Nothing) Then
        rect.Width = 250
        rect.Height = 150
    End If
End Sub
 
Private Sub Tap_LeftButtonUp(ByVal sender As Object, ByVal e As MouseButtonEventArgs)
    Dim rect As Rectangle = CType(sender,Rectangle)
    ' Reset the dimensions on the Rectangle.
    If (Not (rect) Is Nothing) Then
        rect.Width = 200
        rect.Height = 100
    End If
End Sub
 
Private Sub Tap_MouseLeave(ByVal sender As Object, ByVal e As MouseEventArgs)
    Dim rect As Rectangle = CType(sender,Rectangle)
    ' Finger moved out of Rectangle before the mouse up event.
    ' Reset the dimensions on the Rectangle.
    If (Not (rect) Is Nothing) Then
        rect.Width = 200
        rect.Height = 100
    End If
End Sub

The following image shows the sample.

The next sample shows you how to use the Click event on a Button to handle tap gestures.

First, a Button is created in XAML and an event handler is added for the Click event.

<Button Name="TestButton"
    Content="Tap"
    Height="100" Width="200"
    Click="TestButton_Click" />

In the Click event handler, the content of the button is toggled between "Tap" and "Tap Again!". The text changes each time a user taps the button.

private void TestButton_Click(object sender, RoutedEventArgs e)
{
    Button button = sender as Button;
    if (null != button)
    {
        // Toggle Button.Conten between "Tap" and "Tap Again!"
        if (button.Content as string == "Tap")
        {
            button.Content = "Tap Again!";
        }
        else
        {
            button.Content = "Tap";
        }
    }
}

Private Sub TestButton_Click(ByVal sender As Object, ByVal e As RoutedEventArgs)
    Dim button As Button = CType(sender,Button)
    If (Not (button) Is Nothing) Then
        ' Toggle Button.Content between "Tap" and "Tap Again!"
        If (CType(button.Content,String) = "Tap") Then
            button.Content = "Tap Again!"
        Else
            button.Content = "Tap"
        End If
    End If
End Sub

The following image shows the sample.

Using manipulation events

If you need to support multiple-finger gestures in your Windows Phone app, or gestures that use velocity data, then you'll need to use manipulation events. You can use manipulation events to detect gestures such as flick, drag, pinch, and hold. The following table lists the manipulation events and classes in Windows Phone.

A gesture event in Windows Phone 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, multiple ManipulationDelta events are fired. Finally, a ManipulationCompleted event is raised when the gesture is finished.

If you're using Windows Phone Emulator to test your manipulation event code and you don't have a touch-screen monitor, you'll be limited in what you can test. The emulator doesn't support multi-touch gestures with the mouse. You can test translations though, as the following example demonstrates.

The following example shows you how to use the ManipulationDelta events to handle a drag gesture. 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" />

Next, a global TranslateTransform named dragTranslation is created to translate 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 DeltaManipulation 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 +=
    new EventHandler<ManipulationDeltaEventArgs>(Drag_ManipulationDelta);
    dragTranslation = new TranslateTransform();
    TestRectangle.RenderTransform = this.dragTranslation;
}
void Drag_ManipulationDelta(object sender, ManipulationDeltaEventArgs e)
{
    // Move the rectangle.
    dragTranslation.X += e.DeltaManipulation.Translation.X;
    dragTranslation.Y += e.DeltaManipulation.Translation.Y;
}

' Global Transform used to change the position of the Rectangle.
Dim dragTranslation As TranslateTransform
' Constructor
publicMainPage
    {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(ByVal sender As Object, ByVal e As ManipulationDeltaEventArgs)
    ' Move the rectangle.
    dragTranslation.X = (dragTranslation.X + e.DeltaManipulation.Translation.X)
    dragTranslation.Y = (dragTranslation.Y + e.DeltaManipulation.Translation.Y)
End Sub

The following image shows the sample.

UI design and touch input

How you design your user interface can influence how easy your app is to use with touch input. The Design library for Windows Phone for Windows Phone discusses best practices for using touch input in your app. In particular, check out Navigation, orientation, and gestures for Windows Phone and Interactions and usability with Windows Phone. It's worth reading, but here are a few highlights related to touch and UI design:

• All simple commands in your app should be accomplished by using a single finger.

• Touch controls should respond immediately. Even a slight lag between when a user touches the screen and when the control responds can be noticeable and affect user experience.

• Provide immediate visual or auditory feedback.

• If an operation takes a long time, consider providing incremental feedback.

• Touch targets should not be smaller than 9 mm or 34 pixels.

• In rare cases, controls can be smaller, but you should never create a control smaller than 7 mm or 26 pixels square.

• For frequently used touch controls, consider making the controls larger than 9 mm.

• 2 mm or 8 pixels should be provided between touchable controls.

• The touch target can be larger than the touch element, but it should not be smaller.

• The touch element shouldn't be more than 60 percent smaller than the touch target.

• Oblong controls in vertically constrained UIs are easier to hit.

See Also

Other Resources

Navigation, orientation, and gestures for Windows Phone

Interactions and usability with Windows Phone

Gesture support for Windows Phone 8

How to handle manipulation events for Windows Phone 8