Tutorial 1: How to configure Adobe Flash Professional.
In this tutorial we’ll use Flash Professional CS5.5 to create a template project that we can use to create GestureWorks 3 applications. You may also use Flash Professional CS5.0, though there might be some slight differences in the instruction.
First, let’s open the GestureWorks3 installation folder. Navigate to the "user/GestureWorks3" directory. There are several folders here:
- API_Docs (contains the AS3 class documentation)
- Config (contains the licensing info)
- lib (contains the GestureWorks.swc library file)
- Templates (contains the GestureWorks3 template projects)
Every Gestureworks3 project requires the config folder and its contents and the GestureWorks.swc library file. The first thing we’ll have to do when we set up a new project is to link these files to our project.
Open up the template folder. GestureWorks3 comes with pre-defined templates, but in this tutorial we’ll go through the process of making our own custom template.
Create a new folder inside of the "Templates" folder called: "my_flash_template". We’ll use this folder to store all the needed files that make up our project. Let’s set up a couple of sub directories within this folder before we actually create our project in Flash Professional. The first folder we need is for storing our ActionScript code. Let’s call it "src", which is short for ‘source code’. The second one we’ll make will be called "bin", which is short for ‘binaries’. This folder will store our compiled application and any needed files that the application requests during runtime.
Compiled application folders or "bin" folders often contain many files, so let’s organize it. First we’ll add a folder called "library". This folder will contain any needed files which the application requests during runtime, such as images, videos, etc. It will also storeour CML file (GestureWorks’ own Content Markup Language) and our GML file (GestureWorks’ own Gesture Markup Language).
Rather than recreate the "library" folder, let’s download the files associated with this tutorial. The download package includes a "library" folder. We’ll copy this folder and all of it contents into the "bin" folder.
Let’s investigate what’s inside of the "library" folder. There are three folders entitled: "assets", "cml", and "gml". The "assets" folder stores any external media such as images and videos. Open up this folder and we’ll see that it contains an image of the GestureWorks logo. The "cml" folder stores our application’s cml files, and the "gml" folder stores our application’s gml files. There exists one of each to get us started.
The "cml" folder contains a file called "my_application.cml". Open it up with notepad or some other text editor:
<?xml version="1.0" encoding="UTF-8"?>
<GestureWorksApplication version="1.0.0" gml="library/gml/my_gestures.gml" />
You’ll see that CML is based on the XML standard. You can use this file to create and style display objects. NOTE: one CML file is required for every GestureWorks3 project.
The markup code you see here represents the required minimum needed for the CML to be valid and work correctly. Actually it contains one extra bit of information, a path to our application’s gml file (we’ll get to this next):
gml="library/gml/my_gestures.gml"
Notice that the file path is relative to our application’s compiled directory, the "bin" folder.
The "gml" folder contains the "my_gestures.gml" file. Open it up with notepad or some other text editor. Yes, there is a lot to this, but we don’t have to worry about it now. For now just realize that it too is based on the XML standard and that it contains all the possible gestures and their settings which we can include in ourapplication. NOTE: The GML file is not a requirement for GestureWorks 3 applications, but it is good practice to include one.
Now that we have our project directories set up correctly, we can get started setting up the project within the IDE.
Let’s open up Flash Professional and create a new AIR project:
File ? New ? AIR
NOTE: You must create an AIR project for GestureWorks 3 projects in order to pass licensing verification. You can still embed the swf file that is generated from the AIR project into an HTML file and publish on the web.
Save the AIR project file within the "my_flash_template" folder that we just created. We’ll give it the same name "my_flash_template.fla".
Next, we need to create a Main source code file that we will eventually use to make our initialization statements:
File ? New ? ActionScript 3 Class
Name this class: "Main" by filling in the "Class name" text field.
Class name: Main
Save this file within our project’s "src" folder. The file name must be the same as the class name, "Main".
Next, we’re going to link the necessary files and paths to our project. We do this through Flash Professional’s ActionScript Settings window:
File ? ActionScript Settings
First we’ll include the "src" folder.
Under the "Source path" tab click on the plus icon to add a new path. Type in the following:
./src
The dot indicates the directory of the "my_flash_template.fla" project file.
The "Source path" tab should now look like this:
Next, we’ll include the GestureWorks swc library. Click on the "Library path" tab and then click the swc icon which is to the right of the minus icon. It will open a browse prompt. Navigate to the "user/GestureWorks3/lib" directory and double-click on the GestureWorks.swc file.
The "Library path" tab should now look like this:
Notice the file path:
C:UsersfogGestureWorks3lib
The first thing to note is that "fog" will be replace by your own username. The second thing is that we’ve linked this file using an absolute path. We could alternatively use a relative path, but using an absolute path allows us to move our project folder without worrying about the location of the GestureWorks library file. Therefore, we recommend keeping the GestureWorks.swc library file in the installed location and linking your projects to it through an absolute path.
The next file we’re going to link is the "Main.as" file. This is done through the same "ActionScript Settings" window. At the top there is a text field called "Document Class". In this document enter the name of the class that we created earlier:
Document class: Main
The last path that we have to set is the application output path. We do this under Flash Professional’s "Publish Setttings".
File ? Publish Settings
In the Output file text field, prepend the "bin" directory to "my_flash_template.swf" like this:
"./bin/my_flash_template.swf."
The last thing we have to do is set up our Main.as file. We’ll write a classic "Hello World" program just to verify that it’s compiling properly.
If it isn’t open already, open up the Main.as file.
Flash Professional will have already created some stub code for us. Replace it with the following:
package
{
import com.gestureworks.core.GestureWorks;
import com.gestureworks.cml.element.TextElement;
public class Main extends GestureWorks
{
public function Main():void
{
super();
settingsPath = "library/cml/my_application.cml";
}
override protected function gestureworksInit():void
{
var txt:TextElement = new TextElement;
txt.text = "Hello World";
addChild(txt);
}
}
}
Let’s look at the import statements one at a time:
3. import com.gestureworks.core.GestureWorks;
This is the superclass for every GestureWorks application. It is mandatory, and your main class must extend it like this:
6. public class Main extends GestureWorks
Lets return to the other import statement:
4. import com.gestureworks.cml.element.TextElement;
This allows us to create a text display object, which we use to print our "Hello World" message to the stage.
Our class has two methods: the constructor (Main) and the initialization callback (gestureworksInit).
Let’s look at the constructor:
public function Main():void
{
super();
settingsPath = "library/cml/my_application.cml";
}
First, it calls the superclasses’ constructor:
10. super();
Then, it provides the path of the CML file by providing a value for its own settingsPath property:
11. settingsPath = "library/cml/my_application.cml";
Now let’s look at the initialization callback:
override protected function gestureworksInit():void
{
var txt:TextElement = new TextElement;
txt.text = "Hello World";
addChild(txt);
}
Now, gestureworksInit() is an abstract protected method of the GestureWorks class. An abstract method is one that is meant to be overridden by a subclass. This allows us to provide our own custom code for the method. It is called by the GestureWorks class when all the necessary files have been loaded and processed. In other words, this is the callback that indicates when GestureWorks has been initialized and is ready. We can think of this as our entry point.
We’ve decided to print "hello world" to the stage, so we have the following body for the gestureworksInit method:
var txt:TextElement = new TextElement
txt.text = "Hello World";
addChild(txt);
First, we created a text element called "txt":
16. var txt:TextElement = new TextElement;
Then, we added the "Hello World" string to the text element’s "text" property.
17. txt.text = "Hello World";
Finally,
We added the display object to the stage:
18. addChild(txt);
Let’s run the program and see if everything went well. We can compile our application in Flash Professional by running a test:
Control ? Test Movie ? Test
