How to Use a Document Class in Flash

We're making some changes at Activetuts+. From now on, our tutorials will be using class-based code, instead of timeline code, wherever possible. This Quick Tip explains what you'll need to know.

Why Use Class Files?

I'll admit it - sometimes, coding entirely on the timeline is useful. It's a quick way to test out an effect, and the easiest way to sync actions to specific frames of an animation.

But for any project that relies more on code than on animation, there are serious disadvantages. All your ActionScript is trapped inside the FLA file; you can't split the programming between different developers, you have to copy and paste code if you want to re-use it, and you're forced to use Flash's Actions Panel.

Using class files sets your code free. And it's really no harder than coding on the timeline; it just involves a little more setup. I'll walk you through creating a Flash project that uses classes, then break down a class file in detail.

(Part of the reason we're switching to classes is to make it easier for AS3 developers that don't use Flash itself to follow our tutorials. If you're one of them, I expect you're used to dealing with classes already, but you can always read this Quick Tip as a refresher - just ignore the bits about Flash!)

Step 1: Create a FLA

I'm sure you already know how to do this. Open Flash and click File > New ... Flash File (ActionScript 3.0). Save it wherever you like. I've called mine Example.fla, but it doesn't matter what name you choose.

Step 2: Create an ActionScript File

Click File > New ... ActionScript File. Save this as Main.as in the same folder as your FLA.

This file is where we're going to put the code that powers the FLA itself, but how will Flash know how to find it?

Step 3: Link the FLA to the AS File

You may have dozens of AS files in the same folder as the FLA, so Flash won't want to guess which one to use. We'll have to tell it.

Switch to the Selection tool (Shortcut: V), then make sure you have nothing selected (hit Ctrl-Shift-A). Open the Properties panel (Window > Properties).

If you're using Flash CS3, it'll look like this:

Enter Main in the box labeled "Document class" - that's to match the name of your ActionScript file, minus the ".as" file extension..

If you're using Flash CS4, it'll look like this:

In this case, you'll need to enter Main in the box labeled "Class". For some reason, Adobe dropped the "Document" bit.

Step 4: (Optional) Reorganize your Folder Structure

You don't have to keep all your files in the same directory. Check out this Quick Tip screencast if you'd like to know how to move things around.

Step 5: Write your Document Class

Open your Main.as file and paste the following code:


package
{
	import flash.display.MovieClip;
	public class Main extends MovieClip
	{
		public function Main()
		{
			
		}
	}
}

This is a basic empty document class. It's the smallest amount of code we can write that will actually run. Let me break it down:

The package keyword tells Flash that all of the code between its curly braces is part of a single group.

The class keyword groups functions and variables together.

Writing class Main also groups code together, but in a different way. Classes contain functions and variables; packages contain classes and import statements.

Note: you have to give your class the same name as the AS file: Main.

What about public? Well, that just means that other classes in your code will be able to see this class.

We want our class to extend the functionality of a regular MovieClip - hence, 'class Main extends MovieClip'.

This class Main is going to power our FLA. By default, our FLA is a movie clip (it has a timeline).

We want Main to be able to do everything that a movie clip can do, plus more based on the code that we write. In other words, we want to extend the functionality of a regular MovieClip.

(Sometimes, we might not need to do any animation on the stage's main timeline; in this case, we don't need to extend MovieClip, and we can just extend Sprite instead. MovieClip itself extends Sprite, but adds extra features for animation, like the nextFrame() function. So if you're not sure whether you should extend MovieClip or Sprite, go for MovieClip -- it's safer!)

The 'import' line tells Flash where to find the actual MovieClip so that we can extend it.

MovieClip is itself a class.

Flash doesn't automatically keep track of where all its class files are stored; in order for our extends MovieClip code to work, we need to tell Flash where to find the MovieClip class. That's what the import line does.

Import statements always go inside the package and outside the class, at the top.

Every class contains a function with the same name as the class. The code inside it is run when an object of this type of class is created - in our case, when the SWF is loaded.

Every class contains a function with the same name as the class. It's called the constructor function.

All the code inside this function is run when an object of this type of class is created - in our case, code between these curly braces will be run when the SWF is loaded.

Don't worry if you feel you don't quite grasp all of this yet. Once you start actually using classes and writing your own, it'll all snap into place.

Step 6: Make it do Something

As I said in Step 5, the constructor function contains the very first code to be run when your SWF is loaded. So let's put something in there to make sure everything's working:


package
{
	import flash.display.MovieClip;
	public class Main extends MovieClip
	{
		public function Main()
		{
			trace( "Yep, it's working" );
		}
	}
}

Line 8 is the only new one there. Test your SWF in the usual way (Control > Test Movie). If all's well, you should see "Yep, it's working" pop up in the Output panel. If not...

Have you saved the change you made to Main.as?
Is your FLA's Document Class set to Main?
Are you definitely testing the Example.fla movie?

If none of these questions help, please post a comment.

Step 7: Try Something a Little More Complex

Try replacing your Main.as code with this:


package
{
	import flash.display.MovieClip;
	public class Main extends MovieClip
	{
		public function Main()
		{
			var greeting:String = "Hello";
			trace( greeting );
		}
	}
}

Simple, right? We've just created a new String variable inside the constructor function. Now let's add a new function:


package
{
	import flash.display.MovieClip;
	public class Main extends MovieClip
	{
		public function Main()
		{
			var greeting:String = "Hello";
			changeGreetingToFrench();
			trace( greeting );
		}
		
		public function changeGreetingToFrench():void
		{
			greeting = "Bonjour";
		}
	}
}

There are a few things to note here.

Firstly, the new function goes inside the class, and after the constructor - by convention, the constructor is the first function in the class.

Secondly, the new function is public; when coding inside a class (and not on the timeline) it's good practice to put "public" (or "private" or "protected", but I'll leave those for another post) at the start of the line that defines the function. It's just a way of letting other classes know whether or not they can access it.

Thirdly, the new function's definition ends with :void. This just means it doesn't return a value. Constructor functions don't need the :void because they can't return a value.

If you test this movie, you'll get an error message:

Main.as, Line 15: 1120: Access of undefined property greeting.

When you create a variable inside a function, it can't be accessed by other functions. If you want every function in the class to be able to access the variable, you need to declare it inside the class but outside all of the functions:


package
{
	import flash.display.MovieClip;
	public class Main extends MovieClip
	{
		public var greeting:String = "Hello";
		
		public function Main()
		{
			changeGreetingToFrench();
			trace( greeting );
		}
		
		public function changeGreetingToFrench():void
		{
			greeting = "Bonjour";
		}
	}
}

Just as with functions, if you declare a variable outside of a function, you need to start it with "public" (or "private" or "protected"). Unlike functions, variables should be defined above the constructor.

Test your movie now and you should finally get a nice greeting in French. How useful!

Wrapping Up

So, this is not exactly an exciting result, but hopefully you now feel able to follow tutorials that don't code on the timeline.

I really want to make sure everyone understands how to use a document class, so please, if any of this was unclear, post a note in the comments. Once we've sorted out the confusion, I'll edit the Quick Tip to make it easier for the next person to understand. Thanks :)