Configuring Development Environments

Tutorial 2: How to configure Adobe Flash Builder 4.5.

In this tutorial we'll use Flash Builder 4.5 to create a template project that we can use to create GestureWorks 3 applications.

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_flashbuilder_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 store our 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:

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):

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 our application. 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 Builder 4.5 and create a new ActionScript project:

    File ? New ? ActionScript

We'll need to adjust some of the settings within this dialog box.

First, let's set the "project name" the same as the project folder that we created earlier:
Project name: my_flashbuilder_template

Then, we'll set the "project location" to the project folder we created earlier:
Folder: user/GestureWorks3/my_flashbuilder_template

We must also set the "application type" to "Desktop (runs in Adobe 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.

The dialog window should now look like this:

Note that "fog" will be replaced by your own user name.
Let's click on the "Next" button to advance to the "Build Paths" settings.

We'll also need to change some of these settings.

The first thing we're going to do is to link the GestureWorks.swc library file to our project.

Click the "Add SWC" button. When the dialog window appears click on "Browse". Navigate to the "user/GestureWorks3/lib" and double click on the "GestureWorks.swc" file.

Next, we're going to change the "Main application file" from "my_flashbuilder_template.as" to "Main.as". This is really a personal preference. We could leave it as "my_flashbuilder_template.as".

The last setting we need to change is to set the output directory to the "bin" folder we created earlier. Flash Builder 4.5 sets the default name of the output folder to "bin-debug". Change it to "bin".

Below are the updated settings:

Click "Finish".
We now have our project paths set up correctly.

The last thing we have to do is set up our "Main.as" class file. We'll write a classic "Hello World" program just to verify that it's compiling properly.

Let's open the "Main.as" file using Flash Builder 4.5 by double clicking on it through the "Package Explorer".

Flash Builder 4.5 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:

This is the superclass for every GestureWorks application. It is mandatory, and your main class must extend it like this:

Lets return to the other import statement:

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:

First, it calls the superclasses' constructor:

Then, it provides the path of the CML file by providing a value for its own settingsPath property:

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":

Then, we added the "Hello World" string to the text element's "text" property.

Finally,

We added the display object to the stage:

Let's run the program and see if everything went well. We can compile our application in Flash Builder 4.5 by clicking on Run:

    Run ? Run