How to handle manipulation events for Windows Phone 8

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

Handling manipulation events is one method for processing touch input. When you handle these events, you can move and scale objects in response to touch and multitouch input.

For info about other methods for processing touch input, see Quickstart: Touch input for Windows Phone 8.

This topic contains the following sections.

• Supported and unsupported manipulation events
• Processing touch input by handling manipulation events
• ManipulationCompleted event of Panorama, Pivot, and LongListSelector
• Related Topics

Supported and unsupported manipulation events

Manipulation events are supported on objects derived from UIElement.

The following manipulation events are supported:

• ManipulationCompleted

• ManipulationStarted

• ManipulationDelta

The following gesture events are supported:

• Tap

• DoubleTap

• Hold

The following items are not supported on the Windows Phone platform:

• The IsManipulationEnabled property is not supported. Manipulation events are enabled by default on Windows Phone.

• Rotate transforms are not supported.

• Inertia events are not supported.

Processing touch input by handling manipulation events

This example creates a simple app that contains a blue rectangle on a Canvas. The app subscribes to multiple manipulation events. The event handlers move or resize the Rectangle when the you manipulate it. The event handlers also change the color of the rectangle while you are moving or resizing it.

The ManipulationDelta event occurs when the touch input changes position. This event can occur multiple times during a manipulation. For example, if you drag a finger across the screen, the ManipulationDelta event occurs multiple times as the finger moves. This event can also occur after the user's finger is raised.

To process touch input by handling manipulation events

1. Create a new Windows Phone project in Visual C# or Visual Basic.

2. In MainPage.xaml, add the following XAML inside the Grid named ContentPanel.

   <Canvas>
       <Rectangle 
           x:Name="rectangle"
           Width="200" Height="200"
           Fill="Blue" Stroke="Blue" StrokeThickness="1" />
   </Canvas>
   

3. In MainPage.xaml.cs, in the MainPage class, import the following namespaces.

   using System.Windows.Media;
   using System.Windows.Input;
   

4. In the MainPage class, declare the following variables.

           private TranslateTransform move = new TranslateTransform();
           private ScaleTransform resize = new ScaleTransform();
           private TransformGroup rectangleTransforms = new TransformGroup();
   
           private Brush stationaryBrush;
           private Brush transformingBrush = new SolidColorBrush(Colors.Orange);
   

5. In the MainPage class, add the following event handler for the ManipulationStarted event. When a manipulation starts, this event handler changes the color of the Rectangle.

           void Rectangle_ManipulationStarted(object sender, ManipulationStartedEventArgs e)
           {
               // Save the original color before changing the color.
               stationaryBrush = rectangle.Fill;
               rectangle.Fill = transformingBrush;
           }
   

6. In the MainPage class, add the following event handler for the ManipulationDelta event. This event handler applies the DeltaManipulation to the RenderTransform of the Rectangle to move and resize it as you manipulate it.

           void Rectangle_ManipulationDelta(object sender, ManipulationDeltaEventArgs e)
           {
               // Move the rectangle.
               move.X += e.DeltaManipulation.Translation.X;
               move.Y += e.DeltaManipulation.Translation.Y;
   
               // Resize the rectangle.
               if (e.DeltaManipulation.Scale.X > 0 && e.DeltaManipulation.Scale.Y > 0)
               {
                   // Scale the rectangle.
                   resize.ScaleX *= e.DeltaManipulation.Scale.X;
                   resize.ScaleY *= e.DeltaManipulation.Scale.Y;
               }
           }
   

7. In the MainPage class, add the following event handler for the ManipulationCompleted event. When a manipulation ends, this event handler restores the original color of the Rectangle.

           void Rectangle_ManipulationCompleted(object sender, ManipulationCompletedEventArgs e)
           {
               // Restore the original color.
               rectangle.Fill = stationaryBrush;
           }
   

8. In the MainPage class constructor, combine the two transforms into a TransformGroup and register the event handlers.

           // Constructor
           public MainPage()
           {
               InitializeComponent();
   
               // Combine the moving and resizing tranforms into one TransformGroup.
               // The rectangle's RenderTransform can only contain a single transform or TransformGroup.
               rectangleTransforms.Children.Add(move);
               rectangleTransforms.Children.Add(resize);
               rectangle.RenderTransform = rectangleTransforms;
   
               // Handle manipulation events.
               rectangle.ManipulationStarted +=
                   new EventHandler<ManipulationStartedEventArgs>(Rectangle_ManipulationStarted);
               rectangle.ManipulationDelta +=
                   new EventHandler<ManipulationDeltaEventArgs>(Rectangle_ManipulationDelta);
               rectangle.ManipulationCompleted +=
                   new EventHandler<ManipulationCompletedEventArgs>(Rectangle_ManipulationCompleted);
           }
   

9. Build and run the project. You see a blue square in the app window.

10. Try the following manipulations to test the app. Notice that you can do more than one of the following at the same time.

    • To move the Rectangle, put one finger on the Rectangle and move the finger across the screen.

    • To resize the Rectangle, put two fingers on the Rectangle and move the fingers closer together or farther apart from each other.

ManipulationCompleted event of Panorama, Pivot, and LongListSelector

In Windows Phone 8, the ManipulationCompleted event is marked as handled for the Panorama, Pivot, and LongListSelector controls to make the UI more responsive.

If you try to handle the ManipulationCompleted event for one of the specified controls by using the following code in Windows Phone 8, the code never runs. In Windows Phone OS 7.1, this code does run.

myPivot.ManipulationCompleted += (s, e) =>
{
    ...
}

If you want to handle the ManipulationCompleted event in both Windows Phone 8 and Windows Phone OS 7.1, use the AddHandler method. For example:

this.myPivot.AddHandler(Pivot.ManipulationCompletedEvent,
    new EventHandler<ManipulationCompletedEventArgs>
    (MyPivot_ManipulationCompleted), true);

See Also

Other Resources

Quickstart: Touch input for Windows Phone 8