If you’re brand new to Action script 3.0 and the new Adobe Flash CS3 or CS4 IDE, you may find yourself having some questions about basic project & file organization-management. For example, you may be wondering how best to organize project resources (e.g., class and other files). Further, you may be wondering how a particular project & file organization-management scheme will effect symbol linking and the importing of classes.

This tutorial will take you through three levels of project file organization – each more complex than the next. At each level, I’ll talk about symbols & classes and instances of those symbols & classes and how to “link” (or bind) them. I’ll also talk about packages. Everything a beginner needs to know.

1. The Simple Dumb Plan

When just starting out, the easiest thing to do is just put everything into one project folder.

First, create a folder called “Stars.” Then go here and download the Sky.as, Star.as and a Sky.fla files. Then create a folder called “Stars.” (These files come from Colin Moock’s Essential ActionScript 3.0, Chapter 29, “The Document Class.” You can also get the files from Colin’s site by going here).

After you download the files, create a project called moock Stars Project.flp and put the Sky.as, Star.as and the Sky.fla file in the project (You can also get the completed project by going here and downloading the “Stars.zip” file).

Let’s take a few minutes to look at this project.

The Sky.fla is the main timeline of the project. Action script 3.0 has designed the .fla files to be an instance of the document class. What this means is that we can create a class that’s an extension of the movieclip class and “link” that class to the Sky.fla file. (See Colin Moock’s Essential ActionScript 3.0, Chapter 29, “The Document Class” for more details). With such a class, we can create variables and methods to control our project’s main timeline.

If you look at the properties of the Sky.fla file, you can see the class name Sky in the document class dialog box:

This is the name of the class defined in the Sky.as file. Specifying the name of a class in the fla. property’s “Document class” field serves to “link” that class (the Sky class) to the Sky.fla file.

In the library of the Sky.fla file, you’ll see a symbol called “star.” It’s of type movieclip. On the stage, you’ll see five instances of the “star” symbol, each of a different size and orientation. The instance names are ‘star1’, ‘star2’, etc.

If you look in the Star.as file, you see a class called Star. We now want to set things up so that each time the runtime engine of flash creates an instance of the “star” symbol on the stage, it’ll also create five instances of the Star class, and it’ll “link” those class instances with the five symbol instances on the stage. Each class instance will extend the functionality of the five “star” symbol instances on the stage.

Linking The “star” Symbol to the Star Class

We have to link the “star” symbol in the library to the Star class. To do this, right click on the “star” symbol in the library of the Sky.fla file and then select the “Linkage” item from the drop down menu. You should see the “Linkage Properties” dialog box (see the figure below). Now follow these steps:

  • Step 1. In the “Class” textbox, type the name of the class that will extend the functionality of instances of the “star” symbol.
  • Step 2. Because we want to control instances of the “star” symbol with instances of a class, the “Base class” textbox should hold: flash.display.MovieClip. This is the default setting.
  • Step 3. Select Export for ActionScript: This forces flash to include the symbol in the swf file. This isn’t strictly necessary in our case since placing instances of the “star” symbol on the stage accomplishes the same thing.
  • Step 4. Select Export in first frame: this is also a default setting, but in most cases, you’ll want it.

The "Automatically Declare Stage Instances" Setting

Now let’s talk briefly about the "Automatically declare stage instances" setting. First, make sure you’re looking at the Sky.fla file. Then go to the File menu, select “Publish Settings,” then select the “Flash” tab, choose “Action script 3.0” in the Action script Version drop down menu, and then press the “Settings” button. You’ll see this dialog box:


You may see a check in the checkbox next to the "Automatically declare stage instances." While this is the default setting, it’s better to turn it off. This is to enhance explicitness and clarity in the code, as we’ll see in a second.

Because we’ve “linked” the “star” symbol to the Star class, the flash runtime engine (i.e., the Flash “player”) at runtime will automatically create five Star class instances using the names of the “star” symbol instances on the stage. It will then “link” each star symbol instance on the stage with an instance of the Star class that has the same name.

At runtime, we want access to both the “star” movieclip instances on the stage and their corresponding Star class instances. For this to happen, because we’ve disabled "Automatically declare stage instances," we’re forced to declare publically the stage instance names in the Sky.as file:

public var star1;
public var star2;
public var star3;
public var star4;
public var star5;

Now at runtime, we’ll have access to the methods of the five Star class instances and the five “star” movieclip instances on the stage. The Star class and the “star” symbol on the stage are separate resources in the project, but at runtime, the Star class instances in memory called ‘star1,’ ‘star2,’ ‘star3,’ ‘star4,’ & ‘star5’ and the “star” symbol instances on the stage called ‘star1,’ ‘star2,’ ‘star3,’ ‘star4,’ & ‘star5’ are effectively the same things.

For example, in the Sky class constructor, we have the code:

star3.x = 490;
star3.y = 370;

This code accesses the native “x” & “y” public position variables of the “star3” movieclip on the stage and moves it to the lower right hand corner of the stage.

Below these two statements, include the following statement:

star3.dispose();

This statement accesses the dispose() method of the particular instance of the Star class that’s attached to the ‘star3’ symbol instance on the stage. This method stops the timer that controls the fade of each star. If you comment that line of code out, you’ll see the ‘star3’ instance fade in and out as well as twinkle.

Because we put all three resources, the Sky.fla, the Sky.as, and the Star.as files, in the same folder, the compiler (the process that creates the swf file) has no trouble finding them to build the swf file – it first looks for all the resources in the folder where it found the Sky.fla. But what if you don’t want to put everything in the same folder?

2. Putting Project Resources in their Own Folders

For large projects, everything in one folder is sloppy. Ideally, each resource should have its own folder.

So now create a new folder called “Stars_withClassesSubDir” and create another folder inside that called “Classes.” Put the Sky.fla files in the “Stars_withClassesSubDir” folder and put the Sky.as & Star.as files inside the “Classes” folder. Inside the “Stars_withClassesSubDir” folder create a new flash project called stars with class subdir Project.flp and add all three files to the project.

If you run the project as is, you’ll see the stars twinkle but you won’t see them fade. This is because the compiler can’t find the two classes because it has no idea where they are. This is because the default location is the same folder where the Sky.fla file is, but -- they aren’t there. They’re in the “Classes” subfolder.

If you put your classes in a folder different from where your .fla file is, you’ll need to tell the flash compiler where they are by setting a variable called the classpath variable to the correct location. To do this, make sure you’re looking at the Sky.fla file, and then go to the File menu, select “Publish Settings,” then select the “Flash” tab, choose “Action script 3.0” in the Action script Version drop down menu, and then press the “Settings” button. You’ll see this dialog box:

We want to set the classpath variable to the location to our class files. To do this, press the “+” button and enter the FULL path including the “Classes “ name itself. The best way to do this is to use the middle “path” button (just to the right of the “-“ button) and browse into the “Classes” folder. Press “OK” and you’re done.

Note that my full classpath is:

F:\Projects\BrooklynSkyDesign\Training\AS 3.0\linkage_symbols_classes_package_example\Stars_withClassesSubDir\Classes

Yours will probably be different. Use yours.

You can also get the completed project by going here and downloading the “Stars_withClassesSubDir.zip” file, but be sure to change the classpath so it “points” into your “Classes” folder.

3. Using Packages

For large projects with many classes, using just one subdirectory to hold them all again starts to get sloppy and inefficient.

First, create a folder called “Stars_withPackages” and put the Sky.as & Sky.fla files inside.

Now somewhere else on your machine, create a new folder called “ProjectPackageClasses” and inside that folder create a folder called “Stars.” Put the Star.as file in the “Stars” folder.

The “ProjectPackageClasses” folder exists only to be a parent directory for all project package classes. You don’t strictly need it for this tutorial, but its good organization to have such a parent directory.

Now go back to the “Stars_withPackages” folder and inside that folder create a flash project file called stars with packages Project.flp and add the Sky.as, Sky.fla and the Star.as files to the project.

Now, to use the Star class, we need to make a couple of changes:

First, if you look at the Star.as file in one of the other two projects, you see the entire Star class is “wrapped” in an unspecified package statement:

package {

import flash.display.MovieClip;
import flash.utils.Timer;
import flash.events.TimerEvent;

public class Star extends MovieClip {

private var timer:Timer;

public function Star () {

trace("create: "+this.name);
timer = new Timer(100, 0);
timer.addEventListener(TimerEvent.TIMER, timerListener);
timer.start();

}

Now we want to specify a package name, i.e., “Stars.” So go to the “ProjectPackageClasse/Stars” folder where your Star.as file is, and add the “Stars” name to the package statement:

package Stars {

import flash.display.MovieClip;
import flash.utils.Timer;
import flash.events.TimerEvent;

public class Star extends MovieClip {

private var timer:Timer;

public function Star () {

trace("create: "+this.name);
timer = new Timer(100, 0);
timer.addEventListener(TimerEvent.TIMER, timerListener);
timer.start();

}

Second, go to the “star” symbol in the library of the Sky.fla file and right click on the “star” symbol and select the “Linkage” item from the drop down menu and let the name of the class include the name of the package it is in, i.e., “Stars.Star.” The first name, ‘Stars,’ is the package name, the second, ‘Star,’ is the class name:

Third, we need to tell the Sky class that the Star class it references is now part of a package. To do this, go the Sky.as file and below the “import flash.display.MovieClip;” statement, add this statement:

import Stars.Star;

Finally, we need to tell the flash compiler where the Star class is. There’s a couple of ways to do this. The first is to again to go to the File menu, select “Publish Settings,” then select the “Flash” tab, choose “Action script 3.0” in the Action script Version drop down menu, and then press the “Settings” button. When you see the “Action script 3.0 Settings” dialog box, you can use the middle “path” button (just to the right of the “-“ button) and browse into the “StarsWithPackages” folder where you placed your Star.as file.

However, what I like to do, if I’m creating and using my own packages, is create a separate folder that will hold all my packages. For example, you already created a folder called “ProjectPackageClasses” and inside you created a “Stars” folder to hold the Star.as file.

Let's create two classpath variables – think of one as a “global” classpath variable and the other as a “local” or project specific classpath variable. First, make sure you’re looking at the Sky.fla file, and then go to the Edit menu and select “Preferences.” In the “Preferences” dialog box, select “Action script” in the category window and then press the “Action script 3.0 Settings” button on the right side of the “Preferences” dialog box:


You’ll see the “Action script 3.0 Settings” dialog box and you’ll see a classpath already specified:

DON’T CHANGE OR DELETE THIS CLASSPATH.

What we want to do is ADD another classpath that will point into our “ProjectPackageClasses” folder. The best way to do this FIRST press the “+” and THEN use the middle “path” button (just to the right of the “-“ button) and browse into the “ProjectPackageClasses” folder:

Press “OK” and you’re done (with this step). What we’ve done is specify another classpath that will apply to ANY projects you make. Think of this as a “global” classpath variable. There’s actually two here – the one you MUST have is the “$(AppConfig)/ActionScript 3.0/Classes.” That’s always there by default, so never delete that.

Note that my full classpath is:

F:\Projects\BrooklynSkyDesign\Training\AS 3.0\ProjectPackageClasses

Yours will probably be different. Use yours.

However, we’re not quite done yet. All we have is a classpath to the directory that will hold all our packages; we don’t yet have a fully qualified path name to the “Stars” folder where the Star.as file is located.

To do this, be sure you’re looking at the Sky.fla, and then go to the File menu, select “Publish Settings,” then select the “Flash” tab, choose “Action script 3.0” in the Action script Version drop down menu, and then press the “Settings” button. When you see the “Action script 3.0 Settings” dialog box, press the “+” button and just type “Stars:”

Think of this as “local” or project specific classpath.

So the complier locates the Star.as file by first using the ‘global’ classpath:

F:\Projects\BrooklynSkyDesign\Training\AS 3.0\ProjectPackageClasses

and then the ‘local’ classpath:

‘Stars.’

This is my full path name to my Star.as file:

F:\Projects\BrooklynSkyDesign\Training\AS 3.0\ProjectPackageClasses\Stars

So, that’s it! The project organization & management schemes I’ve laid out here should give you a firm foundation for all your projects. If your project is simple, just put all the relevant files in a single directory and forget all that classpath stuff. If you want a bit more organization, create subfolders for your classes (and other resources, i.e., images, videos, etc.) and set the classpath for the class folder accordingly. If your project uses classes that you’ll use repeatedly, perhaps even across different projects, then you’ll want to create and use packages.

Happy coding!