Support & Tutorials » Multitouch Scroll Tutorial

Tutorial: Multitouch Scroll

Introduction

In this tutorial you will learn how to scroll dynamically loaded text in Flex using GESTURE_SCROLL to control a text field. We’ll load html content from an external text file, format the text using a style sheet and make the text field fully scrollable using the multitouch scroll gesture. This tutorial requires Adobe Flex 4.0 RCK, Flash Player 10.1 (beta-3), and GestureWorks (download a free trial).

Before We Begin

In addition to the basic requirements listed in the introduction, you will need the following applications installed to compile Flex projects built upon GestureWorks: Adobe Flash Builder 4, version 3.5 or later of the Firefox Browser.

Because this is our first tutorial in the intermediate to advanced Flex 4 and Flash Builder tutorial series, we will establish the project as a web-based application. To this end, we will build and test against Firefox as it fully supports existing Windows 7 touch events. If you wish to build against Air 2.0, you do not need to download and use Firefox. We recommend that you have access to a multitouch input device for testing, although such a device is not needed as Gestureworks has a built-in simulator.

If you have not done so already, please download and extract the Flex SDK available from this site into your Flash Builder 4 SDK directory:

${FlashBuilder4_InstallPath}/sdks/

In the next section, we will link the custom SDK build into your first project.

Creating Your First Project

Whether you are using the Eclipse plugin on the latest version of Galileo or have installed the entire Flash Builder package, the steps found within this tutorial will remain the same.

To start, create a new Flex Project in Flash Builder by selecting File > New… > Flex Project. For this tutorial, set the application type to “Web.” As mentioned above, you can also choose to publish against Adobe Air.

Now we need to specify the SDK we will compile against. In the “Flex SDK version” options, select “Configure Flex SDKs…” located on the far right side in the “New Flex Project” dialog. To add the SDK (previously downloaded from the GestureWorks site and extracted into the sdks directory in the “Before We Begin” step), select the “Add…” button and browse to the directory into which the GestureWorks SDK was extracted; the SDK name will auto-populate as “Flex 4.5 w/GestureWorks.” Once complete, return to the “New Flex Project” dialog by hitting the “OK” button on both “Add Flex SDK” and “Preferences” pages.

Now that we’ve added the SDK, we need to select it using the “Use a specific SDK” menu. Select “Flex 4.5 w/GestureWorks” and hit the “Finish” button to create your first project.

Importing Flash Libraries

One of the first things we will be checking is whether the creation of the application object has been completed. To do this we will have to use Flex event listeners and so must import the Flex event libraries.

1	import mx.events.FlexEvent;

We’re also going to load external files into our Flex application. To do this, we will be using the HTTPService component. To use the HTTPService component we will need to import the required component and event libraries.

2
3
4

import mx.rpc.http.HTTPService;
import mx.rpc.events.FaultEvent;
import mx.rpc.events.ResultEvent;

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 GestureEvent package provides a reference to all available gesture analysis modules via their class names.

6	import gl.events.GestureEvent;

Creating Your App

In our simple Flex app we are going to:

1) load content from a plain text file;
2) load a style sheet;
3) populate a simple textarea with the loaded data; and
4) format the test area using the styles defined in the style sheet.

First, we create a variable of type “StyleSheet” that can be accessed from outside our main function.

8	private var _css:StyleSheet;

We want the main body of our app to run once all the associated assets have been created. As with other Flex applications, to do this we call our main function using a “onCreationComplete” event.

10
11

protected function onCreationComplete(event:FlexEvent):void
{

The variable “_css” is instantiated as a StyleSheet() object.

12	_css = new StyleSheet();

The styles loader object is pointed to “assets/style.css” to load the external style sheet file. Then use the HTTP method send() to send back data once loaded.

14
15

stylesLoader.url = "assets/styles.css";
stylesLoader.send();

The text loader object is pointed to “assets/text.txt” to load the external text file. Then we need to tell the textLoader to actually load the text using the send() command.

17
18

textLoader.url = "assets/text.txt";
textLoader.send();

Next we must activate gestures on “txtArea”. To do this, we first enable blob containment to make sure that any touch points placed on the text area are processed as gestures that manipulate that object. Then we simply add the GESTURE_SCROLL event listener to “txtArea”.

20
21
22

txtArea.blobContainerEnabled = true;
txtArea.addEventListener(GestureEvent.GESTURE_SCROLL, txtArea_scrollHandler);
}

Next, we need to ensure that any errors that may occur while attempting to load external files are handled correctly.

24
25
26
27

private function onLoadFault(event:FaultEvent, service:mx.rpc.http.HTTPService):void
{
// suppress error
}

Once the style sheet has sucessfully loaded, a result event is fired which calls the onStylesLoaded() function. This fucntion parses the style sheet then applys the styles to the target “txtArea”.

29
30
31
32
33

private function onStylesLoaded(event:ResultEvent):void
{
_css.parseCSS(event.result as String);
txtArea.styleSheet = _css;
}

When the text file has successfully loaded, the data is set as content for “txtArea”.

35
36
37
38

private function onTextLoaded(event:ResultEvent):void
{
txtArea.htmlText = event.result as String;
}

To add gesture controls to the “txtArea,” we attached a simple GESTURE_SCROLL listener to the text area. When two fingers are placed on the text area and dragged vertically, the gesture “scroll” is triggered. The GESTURE_SCROLL event returns a value “scrollY” relative to the vertical distance moved by the two touch points. It is this number that we use to control the scroll property on the text area. Each time GESTURE_SCROLL is triggered, the number “scrollY” is added to the current vertical scroll position only if the resulting value is less than the maximum vertical scroll position.

40
41
42
43
44
45
46
47

private function txtArea_scrollHandler(event:GestureEvent):void
{
var value:Number = (txtArea.verticalScrollPosition + event.scrollY);

txtArea.verticalScrollPosition =
value > txtArea.maxVerticalScrollPosition ? txtArea.maxVerticalScrollPosition :
value < 0 ? 0 : value;
}

Complete Example Actionscript 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
39
40
41
42
43
44
45
46
47

import mx.events.FlexEvent;
import mx.rpc.events.FaultEvent;
import mx.rpc.events.ResultEvent;
import mx.rpc.http.HTTPService;

import gl.events.GestureEvent;

private var _css:StyleSheet;

protected function onCreationComplete(event:FlexEvent):void
{
_css = new StyleSheet();

stylesLoader.url = "assets/styles.css";
stylesLoader.send();

textLoader.url = "assets/text.txt";
textLoader.send();

txtArea.blobContainerEnabled = true;
txtArea.addEventListener(GestureEvent.GESTURE_SCROLL, txtArea_scrollHandler);
}

private function onLoadFault(event:FaultEvent, service:mx.rpc.http.HTTPService):void
{
// suppress error
}

private function onStylesLoaded(event:ResultEvent):void
{
_css.parseCSS(event.result as String);
txtArea.styleSheet = _css;
}

private function onTextLoaded(event:ResultEvent):void
{
txtArea.htmlText = event.result as String;
}

private function txtArea_scrollHandler(event:GestureEvent):void
{
var value:Number = (txtArea.verticalScrollPosition + event.scrollY);

txtArea.verticalScrollPosition =
value > txtArea.maxVerticalScrollPosition ? txtArea.maxVerticalScrollPosition :
value < 0 ? 0 : value;
}

Summary

Using this method, displayed text, loaded dynamically from an external text file, can be scrolled up and down using GESTURE_SCROLL.

Testing Your Application

If you have a Flash Player 10.1-compatible multitouch device attached to your system, GestureWorks will by default specify against the native input method. However, if no input device is detected, the simulator will launch and run within the application. To verify the simulator is running, you can check to see how many touch points appear. If only one point of interaction is visible, then the simulator is running and the native device could not be found by the Flash Player. To set multiple touch points within the simulator, shift-click or control-click. If you wish to publish against a FLOSC/TUIO data stream, you will need to modify your external application settings in accordance to the following wiki post and provide security permissions to the application because it requires a socket connection.

Data Providers and Application Settings:
http://support.gestureworks.com/wiki/support/data_providers

Flash SWF Security Permissions:
http://www.macromedia.com/support/documentation/en/flashplayer/help/settings_manager04.html

Now that you are set up to compile through Flash Builder, simply hit the Debug button or right click the default application file and select “Run Application”.