Support & Tutorials » Multitouch Zoom Tutorial

Tutorial: Multitouch Zoom

Introduction

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

Creating Your Document Class

The “Application” class is the root object document 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. All other objects in your application should be placed within this class.

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 which script to include when extending “Main”.

Importing Flash Libraries

In this example, we’re going to load an image into our Flash application. To do this, we need to import the Loader class library into the package of our root class. Essentially this allows Flash to correctly reference and retrieve all the object resources that may be needed when using the Loader class.

2	import flash.display.Loader;

As is the case with loading other media into flash, the loader class uses the URLRequest class, so the library files for that class must also be imported.

3	import flash.net.URLRequest;

Since we will be using the Loader class to load external media, we will need the ability to track events that occur within the Loader object. To do this, we need to import “Event” libraries, which will allow us to attach listeners to our Loader and find out when loading is complete.

4	import flash.events.Event;

Importing GestureWorks Libraries

Importing the “Application” package instantiates libraries 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”

6	import id.core.Application;

In this example, we will be placing an image on stage. To do this, we import the TouchSprite class libraries. TouchSprite builds multitouch onto the Sprite class, which is a display-level 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.

7	import id.core.TouchSprite;

Since we are going to be using gesture events, we will need to import the related 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.

8	import gl.events.GestureEvent;

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.

10	public class Main extends Application {

The document class should be defined as public so that it can be called (and instances created) from outside the package.

12	public function Main() {

To load our image into our Flash application, we’re going to use the Loader class. To do this, we’re first going to create a new variable of type Loader and instantiate it as a Loader() object.

14	var imageLoader:Loader=new Loader();

Before the Loader object can do anything, it must be pointed to a source file of some kind. To do this, we can use the URLRequest class to load the text that points the loader to our local JPG file. (Note:The loader class can also load PNG, GIF or SWF files into flash).

15	imageLoader.load(new URLRequest("hibiscus.jpg"));

We need to know when the loader has finished loading our image, so we can attach an event listener to call a function when loading is “complete”.

16	imageLoader.contentLoaderInfo.addEventListener(Event.COMPLETE,completedImageLoad);

Next we need to create a new TouchSprite object to hold our loaded image. This is done to ensure that our image correctly responds to touch.

18	var container = new TouchSprite();

The image loader object is then nested inside the container, which ensures that the image is immediately drawn on stage when it has completed loading.

19	container.addChild(imageLoader);

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.

20	container.blobContainerEnabled = true;

Place the “container” TouchSprite at the center of the stage area.

21
22

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

Since we want to be able to change the scale of our image, we must listen for a “scale” or “pinch” gesture on the object and call a specific function that can handle scale changes when the scale event is triggered. To accomplish this we simply add a “GESTURE_SCALE” listener to the “container” TouchSprite. This listener will call the function “gestureScaleHandler” each time a “scale” gesture occurs on the container object.

23	container.addEventListener(GestureEvent.GESTURE_SCALE, gestureScaleHandler);

We then add the “container” to the stage so that it is added to the display list and all its associated content is drawn on screen at runtime.

24	addChild(container);

When the loading of our image file is complete, the function “completedImageLoad” shifts the image so that the point of origin/reference is in the middle of the image.

27
28
29
30

private function completedImageLoad(e:Event):void {
e.target.loader.x = -e.target.width/2;
e.target.loader.y = -e.target.height/2;
}

Each time the “scale” gesture is detected on our image, and therefore on the “container” object, a GESTURE_SCALE event is fired. This is detected by the gesture listener we placed on the container object and calls this function “gestureScaleHandler”. Each time this occurs a value for the change in scale is taken from the event and used to incrementally change the scale value of the target (in this case the “container”).

32
33
34
35

private function gestureScaleHandler(e:GestureEvent):void {
e.target.scaleX += e.value;
e.target.scaleY += e.value;
}

Note: The center of scale is dynamically set as the scale gesture is performed. If a scale gesture is performed such that the midpoint between the touch points is on the edge of the image, the image will expand away from that point (if the touch points are moving away from each other).

Complete Example Code

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
31
32
33
34
35
36
37
38

package {
import flash.display.Loader;
import flash.net.URLRequest;
import flash.events.Event;

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

public class Main extends Application {

public function Main() {

var imageLoader:Loader=new Loader();
imageLoader.load(new URLRequest("hibiscus.jpg"));
imageLoader.contentLoaderInfo.addEventListener(Event.COMPLETE,completedImage_Loader);

var container = new TouchSprite();
container.addChild(imageLoader);
container.blobContainerEnabled = true;
container.x = stage.stageWidth/2;
container.y = stage.stageHeight/2;
container.addEventListener(GestureEvent.GESTURE_SCALE, gestureScaleHandler);
addChild(container);
}

private function completedImage_Loader(e:Event):void {
e.target.loader.x = -e.target.width/2;
e.target.loader.y = -e.target.height/2;
}

private function gestureScaleHandler(e:GestureEvent):void {
e.target.scaleX += e.value;
e.target.scaleY += 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 appfolder; 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.