Specifying a Document Class

by kirupa   |   28 October 2011

  Have questions? Discuss this Flash / AS3 tutorial with others on the forums.

In general, it is a good idea to keep all of your code away from the timeline in Flash. To put it differently, it is a bad idea to write code on the timeline unless you really cannot avoid it. The main reason to avoid the timeline for code is that it is cleaner to separate your code from the more visual/animation-centric content that your timeline is really designed for.

Ever since you could keep your code in separate AS files, you were almost able to avoid placing any code on the timeline unless you really had to. I mention "almost" because, you always had to have some code somewhere in your Flash application to give your code in a separate AS file a jumpstart before it started running:

For example, the code that is associated with the dotted red line may have lived on the first frame of your timeline and looked something like this:

function start() {
var mainClass:ClassC = new ClassC();
mainClass.goNuts();
}
start();

Code like this seems pretty harmless. All I am doing is instantiating a class and calling a method in it - that's it. The downside is that this adds a certain dependency to the main timeline that makes maintainance and editing more difficult.

Fortunately, one of the features introduced since Flash CS3 for ActionScript 3 projects is the ability to associate a particular class with your main Flash document. This means that you can now have a class file (dubbed the Document Class) instantiated and called automatically when your application is run without you having to do anything extra, and this tutorial will show you how!

Associating a New Class with a Document
First, go ahead and launch Flash. I'm using Flash CS5, but the instructions should be similar for Flash CS3 onwards. Once you have launched Flash, create new ActionScript 3.0 project.

In the Properties panel, find the Class property:

[ you can specify your class file here ]

In the textbox right next to it, enter the name of the class you want associated with this particular document. I’m going to go with the name MainDocument:

[ give your class file a name...like MainDocument ]

 That's all there is to it if you just wanted is a class to get created for you automatically when you run your application. We don't want that for this case, because...well, what’s the fun in that? We want to see the code and make modifications to it!

To explicitly see your class so you can make changes to it, click on the pencil icon aka the Edit class definition button found right next to the textbox:

[ to edit the class that gets created, click on the Edit button ]

Once you have clicked that button, you will see the AS code that makes up your MainDocument class appearing in the background. Click OK to close this dialog and be allowed to edit the code file that you see behind you:

[ behold - your MainDocument class is visible! ]

Before you call it a day and test your application, make sure both your FLA and this AS file are saved in the same folder on disk. By default, the ActionScript file that would have been created for you will be unsaved and unnamed.

Once you have saved both your FLA and AS file, you can test everything works by adding a small trace statement to your MainDocument constructor:

package {
 
import flash.display.MovieClip;
 
public class MainDocument extends MovieClip {
public function MainDocument() {
// constructor code
trace("hello");
}
}
}

If you test your application by pressing Ctrl + Enter, you’ll see that the trace statement defined in your class file gets invoked:

[ proof that the code in your class file is actually run ]

What you have just done is designated a class file as your Document class. As Borat would say, "High five!"

Associating an Existing Class to the Document
In the previous section, we looked at how you create a new class and have it be associated with your Flash document. In some cases, you may already have the class file you want to use already created. To associate an existing class file with your document, the steps are largely similar.

In the Class property, enter the name of the class file that you already created and want to use:

[ specify a class file name as always ]

 Because you are associating a MovieClip (your main document) to the class, make sure your class extends the MovieClip type as shown earlier. Once you have done that, the constructor in your class will fire and everything will run from there.

Your class, though, may be in a different folder than the root of your FLA document. In these cases, you have to invoke the advanced ActionScript settings dialog. To do that, from the Properties panel, click the Edit button found next to ActionScript settings:

[ we need to adjust some advanced settings ]

Once you click that Edit button, the Advanced ActionScript 3.0 Settings dialog will appear. From this dialog, make sure the Source path tab is selected:

[ the paths where Flash will look for class files in ]

This path by default shows the location of your FLA file. When you build your application, any class file references you make are resolved in this location. If your class file lives in another location, you can hit the plus button to add a new location, or you can simply hit the Browse to Path button and change the currently selected path:

[ add / modify / remove paths to help your compiler out ]

As long as your referenced class file lives in one of the known Source path locations and contains a class that extends MovieClip, you are golden...like a retriever!

Conclusion
If all you are doing on the timeline is writing code to call another class file where all of your application's logic lives, strongly consider associating a class file with your Flash Document and have any relevant code there instead of in the timeline.

Getting Help

If you have questions, need some assistance on this topic, or just want to chat - post in the comments below or drop by our friendly forums (where you have a lot more formatting options) and post your question. There are a lot of knowledgeable and witty people who would be happy to help you out

Share

Did you enjoy reading this and found it useful? If so, please share it with your friends:

If you didn't like it, I always like to hear how I can do better next time. Please feel free to contact me directly via e-mail, facebook, or twitter.

Brought to you by...

Kirupa Chinnathambi
I like to talk a lot - A WHOLE LOT. When I'm not talking, I've been known to write the occasional English word. You can learn more about me by going here.

Add Your Comment (or post on the Forums)

blog comments powered by Disqus

Awesome and high-performance web hosting!
BACK TO TOP
new books - yay!!!