Support & Tutorials » Multitouch Rotation Tutorial

Tutorial: Multitouch Rotation

Introduction

Learn how to dynamically rotate objects using the gesture rotate event. The gesture rotate event is triggered by placing two or more points on an object and rotating the cluster. In this tutorial, you will learn how to attach a GESTURE_ROTATE event listener on a display object and control its orientation using dynamic output from captured events. This tutorial requires Adobe Flash CS4 and GestureWorks (download a free trial).

Creating Your Document Class

The document class also known as the “Application” class is the root object class for your application. The primary purpose of the document class is to extend the main timeline; it does this in the form of a custom MovieClip. This means that all other objects in your application are placed within it.

To set the document class for your application, open mainApp.fla. Then, in the main menu, go to File > Publish Settings. In the Flash tab, select the Script “settings” button. Then, in the “Advanced Actionscript 3 Settings” window, set the “Document Class” to “Main“. Press the “OK” button and apply the changes to publishing settings.

In the main menu go to: File > New. Then in the “New Document” window, select “Actionscript File” and press the “OK” button. Save the file as “Main.as” and make sure it is saved in the same folder as your application file.

In the first line of your ActionScript file, add the following code to open a new package structure:

package {

This defines the beginning of the root package which defines the code used in your root class “Main”. This tells Flash what script to include when extending “Main”.

Importing Flash Libraries

The first thing we are going to do next is import the Flash display package into the package of our root class. Essentially this allows Flash to correctly reference and retrieve all the object resources you may need to use in the display objects on stage. In this case we will only need the MovieClip class as we will be using MovieClips from the library.

2	import flash.display.MovieClip;

Importing GestureWorks Libraries

Since we are going to be using touch events and gesture events, we will need to import these classes into our file. As with importing other packages, importing the GestureEvents package provides a reference to all available gesture analysis modules via their class name.

4	import gl.events.GestureEvent;

Importing the “Application” package instantiates libraries for and builds a framework of control structures for managing multitouch events and methods for object tracking within Flash. To edit these settings, open “How to Customize Application.xml.”

5	import id.core.Application;

A display level class must be set up to be used for stage objects. To do this, we import the TouchSprite class libraries. TouchSprite builds multitouch onto the Sprite class. This means that TouchSprite inherits all the properties of Sprite and adds new event targeting features that act systematically to determine multitouch event ownership at the object level.

6	import id.core.TouchSprite

Creating Your App

In order to build our multitouch application, we are going to create what is essentially a custom class in Flash. We begin this process by extending the “Application” class & setting up our new class to automatically inherit a multitouch framework that will manage touch events behind the scenes.

8	public class Main extends Application {

The document class should be defined as public so that it can be called from outside the package.

10	public function Main() {

Create a new instance of a “Stick” library object, set the x and y position and place it on stage.

11
12
13
14

var stick = new Stick();
stick.x = stage.stageWidth/2;
stick.y = stage.stageHeight/2;
addChild(stick);

The next step is to create a new TouchSprite object to hold your Sprite. To ensure that multitouch events are tracked correctly through all display levels of our applications, we must make sure that the parents of any touchable objects are of a touch class. We can use either TouchMovieClip() or TouchSprite() as the parent for any object we create. Since we won’t be using any timeline methods in this example, we can use the TouchSprite class. This instantizes a new object “container” of type TouchSprite.

16	var container = new TouchSprite();

Next we can create an new instance of the library item “pinWheel()” and nest it inside our TouchSprite to enable touch events to be captured on “pinwheel”.

17
18

var pinwheel = new pinWheel();
container.addChild(pinwheel);

This sets the x and y position of “container” to the center of the stage.

19
20

container.x = stage.stageWidth/2;
container.y = stage.stageHeight/2;

To make sure that all touch points placed over the container object are explicitly associated with that object we need to set the “blobContainerEnabled” property to true. This ensures that when touch points are made over the object and translated into gestures the points remain associated with the object/gesture throughout the motion of the gesture even if all points do not remain over the object. Only once a touch point is removed is it then disassociated from the touch object.

21	container.blobContainerEnabled = true;

Attach a GestureEvent listener to your touchSprite() object. This calls the function “gestureRotateHandler()” each time a GESTURE_ROTATE event is detected on your touchSprite.

22	container.addEventListener(GestureEvent.GESTURE_ROTATE, gestureRotateHandler);

Add the TouchSprite to the stage.

23
24

addChild(container);
}

Each time a GESTURE_ROTATE event is dispatched from your TouchSprite, a value is returned which measures the calculated change in orientation (rotation) of the cluster of touch points on your touch object. This value is used to incrementally change the angle of orientation of “container”, adding the change to the previous value each time the event is detected.

26
27
28

private function gestureRotateHandler(event:GestureEvent):void {
e.target.rotation += e.value;
}

Here is the completed code for our document class. It creates a TouchSprite in the center of the stage which can be rotated witn a two-finger or multiple-finger rotation gesture. This allows the spin wheel to be rotated clockwise or counterclockwise depending on the direction of rotation of the gesture. =

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

package {
import flash.display.MovieClip;

import gl.events.GestureEvent;
import id.core.Application;
import id.core.TouchSprite;

public class Main extends Application {

public function Main() {
var stick = new Stick();
stick.x = stage.stageWidth/2;
stick.y = stage.stageHeight/2;
addChild(stick);

var container = new TouchSprite();
var pinwheel = new pinWheel();
container.addChild(pinwheel);
container.x = stage.stageWidth/2;
container.y = stage.stageHeight/2;
container.blobContainerEnabled = true;
container.addEventListener(GestureEvent.GESTURE_ROTATE, gestureRotateHandler);
addChild(container);
}

private function gestureRotateHandler(e:GestureEvent):void {
e.target.rotation += e.value;
}
}
}

Testing Your Application

There are various ways to test your multitouch application. If you have a multitouch imput device, events can be directly streamed to your Flash application via TUIO. If you do not have a device that can output multitouch events, you can use the built-in simulator in GestureWorks. To test your app in the main menu, go to Control > Test Movie or press “Ctrl + Enter” on the keyboard. Alternatively, you can publish your application as a self-contained executable by following these steps:

In your open Flash application “myApp.fla”, go to File > Publish Settings.
Then in the Formats tab, select “Windows Projector” or “Macintosh Projector,” then press the “Publish” button.
The application will be published to your app folder; from there, you can simply double click on myApp.exe (Windows) or myApp.app (Mac) and run your multitouch application.

NOTE - To build and test these tutorials on a computer without a touchscreen display, pressing “Shift” or “Control” while clicking on an object with the mouse will create additional touch points within the simulator. To remove touch points, simply click them.

Rotate

Calculates the change in orientation (rotation) of the touch points on an object relative to the orientation of the stage and adds the change to the previous value each time the event is detected.