WP7 GestureService in depth | key concepts and API

published on: 11/26/2010 | Views: N/A | Tags: WP7Toolkit Gestures

by WindowsPhoneGeek

I am starting a series of "WP7 GestureService in depth" articles in which I will explain everything you need to know about the WP7 GestureService in details.

In the first article of this series: "WP7 GestureService in depth | key concepts and API" I am going to talk about the different touch gestures in Silverlight for WP7 and how to detect  them using the GestureService from the Silverlight Toolkit for Windows Phone 7.

Touch gestures are the primary method for a user to interact with a Windows Phone, requiring a user-initiated movement with single or multiple fingers on a touch screen.  Developers can implement gesture support in their application using either the Silverlight or XNA frameworks. Each framework offers unique ways to handle touch input to create compelling, interactive end user applications. In this article I will focus on Silverlight.

The controls provided in the Windows Phone Developer tools are used as touch interaction elements and are properly sized for touch interaction. According to the  UI Design and Interaction Guide, the supported Windows Phone 7 gestures are:

Single-touch:			Multi-touch:
Tap	Touch and Hold		Pinch and Stretch
Double Tap	Pan
Flick

By default Silverlight for Windows Phone allows you to process touch input by using manipulation events. Manipulation events are supported on objects derived from UIElement and enables users to you move and scale objects in response to touch and multitouch input.

Note:Rotate transforms are not supported on Windows Phone 7 Series.

The following manipulation events are supported in Silverlight for Windows Phone 7:

• ManipulationStarted This event occurs when the user starts a direct manipulation by placing their finger or fingers on the screen.
• ManipulationDelta This event occurs repeatedly while the user is moving their finger or fingers on the screen.
• ManipulationCompleted This event occurs when the user removed their finger or fingers from the screen

Note:You can also handle simple gestures such as tap, double-tap, and tap-and-hold by using mouse events.

Manipulation events can detect touch input but in order to determine any particular gesture you need to write some custom code. Here is the place where you can use the newly added GestureService class from the toolkit.

In the latest release of the Silverlight for Windows Phone Toolkit you can find the  GestureService which provides an event-driven model for handling gestures in an application. The GestureService can be used by attaching a GestureListener to an element. At that point the element can listen for the gestures that it supports, such as Tap, Hold, Pinch, Flick and others.

To begin using GestureService first  add a reference to  the Microsoft.Phone.Controls.Toolkit.dll  assembly which is installed with the toolkit and you can find it in :
       C:\Program Files (x86)\Microsoft SDKs\Windows Phone\v7.0\Toolkit\Nov10\Bin\Microsoft.Phone.Controls.Toolkit.dll.

You will also need to add the "toolkit" prefix declaration. Make sure that your page declaration includes the "toolkit" namespace:

       xmlns:toolkit="clr-namespace:Microsoft.Phone.Controls;assembly=Microsoft.Phone.Controls.Toolkit"

Lets say that we have an orange rectangle and want to change its color depending on the way the user touch the screen. If the user Tap the screen then the color become White and if Hold the finger over the rectangle its color become red.

The sample code should looks like:

XAML:

<Rectangle Fill="Orange" x:Name="rect">
    <toolkit:GestureService.GestureListener>
        <toolkit:GestureListener  Tap="GestureListener_Tap" Hold="GestureListener_Hold"  />
    </toolkit:GestureService.GestureListener>
</Rectangle>

private void GestureListener_Tap(object sender, GestureEventArgs e)
{
    this.rect.Fill = new SolidColorBrush(Colors.White);
}

private void GestureListener_Hold(object sender, GestureEventArgs e)
{
    this.rect.Fill = new SolidColorBrush(Colors.Red);
}

You can attach the events programmatically in this way:

C#:

var gl = GestureService.GetGestureListener(rect);
gl.Tap += new EventHandler<GestureEventArgs>(GestureListener_Tap);
gl.Hold += new EventHandler<GestureEventArgs>(GestureListener_Hold);

Note: SetGestureListener was deprecated , so instead you can use GetGestureListener.

The GestureListener provides an easy way for you to detect touch gestures in your application.  It allows you to implement listeners for the following gestures:

•     Double-tap
•     DragStarted, DragDelta, and DragCompleted: Three events that can be used together to implement easy drag-and-drop on Windows Phone
•     Flick
•     Hold
•     PinchStarted, PinchDelta, and PinchCompleted: Three events that can be used together to tell if a user is pinching something, typically to zoom in or out
•     Tap

Note:The Windows Phone Emulator does not support multitouch input through the mouse, so you must test scale transforms on a development computer that supports touch input, or test on an actual device.

GestureService 

Basically GestureService  is a static class that has an attached property GestureListenerProperty of type GestureListener.

GestureListener

Key event

• GestureBegin

       The GestureBegin event.
       public event EventHandler<GestureEventArgs> GestureBegin;

• GestureCompleted

       The GestureCompleted event.
        public event EventHandler<GestureEventArgs> GestureCompleted;

• Tap

       The Tap event (touch, release, no movement).
       public event EventHandler<GestureEventArgs> Tap;

• DoubleTap

       The DoubleTap event is raised instead of Tap if the time between two taps is short enough.
       public event EventHandler<GestureEventArgs> DoubleTap;

• Hold

       The Hold event (touch and hold for one second)
        public event EventHandler<GestureEventArgs> Hold;

• DragStarted

       The DragStarted event.
       public event EventHandler<DragStartedGestureEventArgs> DragStarted;

• DragDelta

       The DragDelta event.
       public event EventHandler<DragDeltaGestureEventArgs> DragDelta;

• DragCompleted

       The DragCompleted event. Will be raised on touch release after a drag, or when a second touch point is added.
        public event EventHandler<DragCompletedGestureEventArgs> DragCompleted;

• Flick

       The Flick event. Raised when a drag that was fast enough ends with a release.
       public event EventHandler<FlickGestureEventArgs> Flick;

• PinchStarted

      The PinchStarted event.
       public event EventHandler<PinchStartedGestureEventArgs> PinchStarted;

• PinchDelta

       Any two-touch point (two finger) operation.
       public event EventHandler<PinchGestureEventArgs> PinchDelta;

• PinchCompleted

        The end of a pinch operation.
        public event EventHandler<PinchGestureEventArgs> PinchCompleted;

GestureEventArgs

This is the base class for all gesture events is GestureEventArgs. It exposes the following properties and methods:

• OriginalSource

      This is the first hit-testable item under the touch point. Determined by a combination of order in the tree and Z-order.  
      public object OriginalSource { get; internal set; }

• Handled 

       If an event handler sets this to true, it stops event bubbling. 
       public bool Handled { get; set; }

• GetPosition(UIElement relativeTo)
  

      Returns the position of the gesture's starting point relative to a given UIElement.

      public Point GetPosition(UIElement relativeTo)

DragStartedGestureEventArgs

The event args used in the DragStarted event (derives from GestureEventArgs). So they have all methods and properties of the GestureEventArgs plus one more:

• Direction

      The direction of the drag gesture, as determined by the initial drag change.  
       public Orientation Direction { get; private set; }

DragDeltaGestureEventArgs

The event args used by the DragDelta event(derives from GestureEventArgs). They have all methods and properties of the GestureEventArgs plus :

• HorizontalChange

      The horizontal (X) change for this drag event. 
      public double HorizontalChange { get; private set; }

• VerticalChange

      The vertical (Y) change for this drag event. 
      public double VerticalChange { get; private set; }

• Direction

       The direction of the drag gesture, as determined by the initial drag change. 
       public Orientation Direction { get; private set; }

DragCompletedGestureEventArgs

The event args used by the DragCompleted event(derives from GestureEventArgs). They have all methods and properties of the GestureEventArgs plus:

• HorizontalChange

      The total horizontal (X) change of the drag event. 
      public double HorizontalChange { get; private set; }

• VerticalChange

      The total vertical (Y) change of the drag event.

      public double VerticalChange { get; private set; }

• Direction

      The direction of the drag gesture, as determined by the initial drag change.
      public Orientation Direction { get; private set; }

• HorizontalVelocity

      The final horizontal (X) velocity of the drag, if the drag was inertial.
      public double HorizontalVelocity { get; private set; }

• VerticalVelocity

      The final vertical (Y) velocity of the drag, if the drag was inertial.

      public double VerticalVelocity { get; private set; }

FlickGestureEventArgs

The event args used by the Flick event(derives from GestureEventArgs). They have all methods and properties of the GestureEventArgs plus:

• HorizontalVelocity

      The horizontal (X) velocity of the flick.
      public double HorizontalVelocity { get { return _velocity.X; } }

• VerticalVelocity

      The vertical (Y) velocity of the flick.
      public double VerticalVelocity { get { return _velocity.Y; } }

• Angle

      The angle of the flick

      public double Angle {get { return MathHelpers.GetAngle(_velocity.X, _velocity.Y); }  }

• Direction

      The direction of the flick gesture, as determined by the flick velocities. 
      public Orientation Direction {get { return Math.Abs(_velocity.X) >= Math.Abs(_velocity.Y) ? Orientation.Horizontal : Orientation.Vertical; }  }

MultiTouchGestureEventArgs

The base class for multi-touch gesture event args(derives from GestureEventArgs). Currently used only for two-finger (pinch) operations. They have all methods and properties of the GestureEventArgs plus:

• GetPosition(UIElement relativeTo, int index)

      Returns the position of either of the two touch points (0 or 1) relative to the UIElement provided. The parameter "index" is the touchpoint to use (0 or 1)(generally the    method returns the gesture's starting point relative to the given UIElement.)

publc Point GetPosition(UIElement relativeTo, int index)

PinchStartedGestureEventArgs

The event args used by the PinchDelta and PinchCompleted events(derives from MultiTouchGestureEventArgs). .It exposes the following properties and methods:

• Distance

      The distance between the two touch points.
      public double Distance { get { return MathHelpers.GetDistance(TouchPosition, TouchPosition2); } }

• Angle 

     The angle defined by the two touch points.
     public double Angle{ get { return MathHelpers.GetAngle(TouchPosition2.X - TouchPosition.X, TouchPosition2.Y - TouchPosition.Y); } }

PinchGestureEventArgs

The event args used by the PinchDelta and PinchCompleted events(derives from MultiTouchGestureEventArgs). .It exposes the following properties and methods:

• DistanceRatio

      Returns the ratio of the current distance between touchpoints / the original distance between the touchpoints.
      public double DistanceRatio

• TotalAngleDelta

      Returns the difference in angle between the current touch positions and the original touch positions. 
      public double TotalAngleDelta

That was all about the basic usage of the toolkit`s GestureService   and all about the available public APi in details. In the next few articles of this series I will give some more complex examples about how to use GestureListener  in composite scenarios when implementing different touch manipulations in a Windows Phone 7 application.

I hope that the article was helpful. The source code is available here (with the updated version 57505 of Microsoft.Phone.Controls.Toolkit.dll ):

You can also follow us on Twitter @winphonegeek

Comments

Add comment to 'WP7 GestureService in depth | key concepts and API'

Title Your Name

Comment