This article describes the purpose and usage of the Windows Phone 7 multitouch behavior that can be used to easily add multitouch gestures (scale, rotate, translate) to elements in a Windows Phone 7 Silverlight application. The source code and an installer are available at http://multitouch.codeplex.com.
What is the Windows Phone 7 multitouch behavior?
Basic multitouch in Windows Phone 7 is not super hard, but there are a few things that need to be taken in account:
- The biggest issue with the high level multitouch events that are exposed (called ManipulationStarted, ManipulationDelta and ManipulationCompleted) is that they do not support rotation.
- The deltas must be corrected when the orientation of the device changes.
- It is very easy to get unwanted effects on such a small screen (for example that the element becomes too big/too small).
The multitouch behavior encapsulates all these concerns and expose a set of easy-to-understand properties to govern its usage. These properties can be databound, so you can even change their value during runtime.
In addition to this, the multitouch behavior offers a Debug mode and a Visualization mode which help to debug a multitouch application that does not exactly react as wanted. Finally, when the multitouch experience is flaky on the development PC (as is often the case in the April CTP of the phone development tools), or missing altogether (as is the case for most PCs…), a Mock mode can be switched on to simulate that fingers with the mouse.
Note: I was not able to test on a real device yet. Microsoft, if you listen, writing multitouch code without a real device to test is super hard. You know I am a good guy, and I share my knowledge, please give me a development device… thanks!
Where can I get it?
The Windows Phone 7 multitouch behavior is part of a larger initiative on Codeplex, aiming to provide a unified interface and similar multitouch functionalities in Windows Presentation Foundation, Silverlight and Windows Phone 7. This project started by Davide Zordan can be found at http://multitouch.codeplex.com.
The latest version of the installer (with the Windows Phone 7 assembly only) is also available on Codeplex under Download. To install, simply download the file MultiTouchBehaviors.Setup.msi and execute it.
- Use V0.5.0 with the developer tools April CTP
- Use V0.5.1 with the developer tools Beta (July 2010)
How does it work?
Behaviors are small encapsulated objects that can be attached to an element in XAML or in C# code. The experience is optimized for Expression Blend but you do not need Blend to use behaviors.
In Blend it is very easy: Simply find the MultiTouchBehavior in the Assets library, and the drag/drop it on the element you want to multitouch-enable. Then, set the properties in the Properties panel. The assemblies that are needed are automatically referenced and added to your application.
Figure 1: MultiTouchBehavior in Blend’s assets library
Figure 2: Properties for MultiTouchBehavior
To multitouch-enable an element in your Windows Phone 7 application:
Put this in the PhoneApplicationPage tag:
- In your WP7 project, add a reference to C:\Program Files\MultiTouch Behaviors\WP7\MultiTouch.Behaviors.WP7.dll and to C:\Program Files\MultiTouch Behaviors\WP7\System.Windows.Interactivity.dll.
- Add two xmlns statements in the page's root (see listing below).
- Make sure that the element you want to transform is in a Grid or a Canvas. Using other panels might bring unexpected results.
- Edit the element’s XAML markup as shown below. Note that an Image control is used here, but the MultiTouch behavior can be applied to any FrameworkElement. More information about the properties and their default value is found in the section titled List of properties.
And in the element you want to manipulate:
List of properties:
- AreFingersVisible: If true, shows a small ellipse below each finger pressed on the screen (see figure 3 and figure 4). This is not a dependency property. It must be set before the application starts, in XAML. Also, it is only active when the application runs in the DEBUG configuration.
- IsDebugModeActive (optional, default=false): If true, shows additional debug information on the screen (see figure 4). This is not a dependency property. It must be set before the application starts, in XAML. Also, it is only active when the application runs in the DEBUG configuration.
- IsMockActive (optional, default=false): If true, enables the mock mode (see the corresponding section below).This is not a dependency property. It must be set before the application starts, in XAML. Also, it is only active when the application runs in the DEBUG configuration.
- IsRotateEnabled (optional, default=true): if true, rotate manipulations are supported on the element. If false, the rotate gesture does not have an effect. This is a dependency property.
- IsTranslateEnabled (optional, default=true): if true, translate manipulations are supported on the element. If false, the translate gesture does not have an effect. This is a dependency property.
- IsScaleEnabled (optional, default=true): if true, scale manipulations are supported on the element. If false, the pinch gesture does not have an effect. This is a dependency property.
- MaximumScale (optional, default = 100.0): If set, specifies the maximum scale factor for the element. This is a dependency property.
- MinimumScale (optional, default = 0.5): if set, specifies the minimum scale factor for the element. This is dependency property.
List of events:
The events are useful for example to differentiate between a MouseLeftButtonDown event and a manipulation gesture.
- ManipulationStarted: Raised when a manipulation starts (for example when a pressed finger starts to move).
- ManipulationCompleted: Raised when all fingers are lifted after a manipulation has started.
Using the Mock mode
Nowadays one of the obstacles to multitouch programming is the cost and availability of touch screens on computers. In order to palliate this and make multitouch programming available to everyone, the MultiTouch Behavior for Windows Phone 7 has a Mock mode which can be enabled by setting the IsMockActive property to true. In Mock mode, the behavior stops reacting to the fingers manipulations, but instead reacts to the mouse only.
Note that in Mock mode, all other features work the same, including fingers markers and debug mode.
Translation in Mock mode
Translating the element in Mock mode is very easy: Simply press the mouse and drag the element. Release the mouse button to release the element.
Rotation and Scale in Mock mode
To rotate and/or scale an element in Mock mode, you need to simulate two fingers.
- For the primary finger (red marker), double click at a location on the element. This “fixes” the first finger.
- Then, move the mouse to another location on the element.
- For the seconday finger (blue marker), press and drag the mouse.
- To end the manipulation, release the mouse. You must then start again with the primary finger.
In the moment, the following are not supported (but they will be as shorter or longer term).
- Multitouch can only be enabled on one element on the screen. Adding the MultiTouch Behavior to multiple elements causes unexpected effects. Supporting multiple elements is very high in my backlog.
- Events marking the beginning and the end of a manipulation will be added.
- Inertia is not supported in this release. It is something I would like to add.
- The movement is not constrained to the phone’s screen. I would like to add an optional property allowing to constrain the movement in order to avoid “losing” the element. This will obviously become very important when inertia is supported.
Figure 3: Visualize fingers
Figure 4: Debug mode and visualize fingers
Figure 5: Sample application settings