Through my travels as an instructor, I always get the question, What is a Document Class?  Well the answer is simple, but the possibilities are extreme.  During this article, I would like to explain some of the most important things to know about a Document Class….Mainly a Document Class is “Your SWF file”!

First of all, the document class is optional.  Ok, it’s 2011, most seasoned Flash Developers are NOT using the timeline anymore and are using the Document Class. And every year as someone reaches excellence, there is someone born…New to Flash/ActionScript. Someone, right now, is holding on to the timeline, as if their life depended on it. So, whatever category you may fall into, one thing is certain, Flash is OPEN to you.  Flash will let you do, pretty much, whatever you want.

• Create animation and ActionScript on the timeline
• Create animation without the timeline, using ActionScript
• Create animation with AND without the timeline, together…

You do not have use a Document Class, but you should at least understand it.

One of the reasons why you should understand it:

• 99% of all of the examples in the Adobe Help Docs, online articles and many books are written using a document class.

So, if you would like to leverage the power of “learn by example”, then you need to know, if nothing else, NOT how to WRITE a document class, but how to USE a document class.

So first things first, without getting too complicated.

• Part 1. Two of the main uses of a Document Class
• Part 2. Implement a Document Class.

Here are two of the most important topics when working with the document class?

• Separate your code from the timeline
• Let your SWF file become a Sprite vs a MovieClip

Separating your code from the timeline

I mentioned, the document class is optional.  You can have the same functionality with code running on the timeline and in the document class. The rule of thumb is if you want your ActionScript to be more portable, easier to update, and free from you FLA, then use a document class.  Take a look at the code below.

ActionScript on the Timeline inside of an FLA.
The ActionScript below draws a red circle on the stage with an x/y = 100 and radius = 50.

// DRAW A CIRCLE ON THE STAGE
var myCircle:Sprite = new Sprite();
myCircle.graphics.beginFill(0xFF0000);
myCircle.graphics.drawCircle(100, 100, 50);
addChild(myCircle);

ActionScript on in a Document Class.
The ActionScript below draws a red circle on the stage with an x/y = 100 and radius = 50.

package {

	import flash.display.Sprite;
	
	public class DCcode extends Sprite{
		
		public var myCircle:Sprite;

		public function DCcode() {
			// DRAW A CIRCLE ON THE STAGE
			myCircle = new Sprite();
			myCircle.graphics.beginFill(0xFF0000);
			myCircle.graphics.drawCircle(100, 100, 50);
			addChild(myCircle);

		}

	}

}

Both of the options above give us the same results.  As you see, there is more ActionScript that must be written in a Document Class, but it’s well worth the time. Next, I will discuss one of the benefits of using a Document Class.

Your SWF as a Sprite not a MovieClip

This may or may not be a surprise to you, but by default an SWF file is nothing more than a MovieClip.  Yes, that’s right, a MovieClip.  A MovieClip that contains other MovieClips, bitmaps, symbols, video, text, etc….  With that being said, a MovieClip is a very powerful symbol, actually, the most powerful symbol.  The thing that makes a MovieClip unique is the timeline.  The timeline allows you to create linear animations and also create linear dynamic functionality with ActionScript on keyframes.

Enter the Sprite Object.

The Sprite object, in all simple terms, can be considered a new symbol in Flash.  The only thing is that when you are converting a shape to a symbol, Sprite is not an option.  Your available options are, Graphic, Button, and MovieClip.  There are many ways to use Sprite objects in Flash, but our conversation here, is just focusing on the Document Class.

The main thing to remember about the Sprite Object/Symbol/Class is:

• The Sprite is identical to the MovieClip. Except for one thing… The Sprite does NOT have a timeline.

In many cases, when we use MovieClips, we do not use the timeline in that MovieClip.  And in cases like these, the timeline is actually taking up unnecessary resources.  For this reason, Adobe created the Sprite class, to give us the ability to have the same power of the MovieClip, but not have to worry about the resources consumption that comes along with a MovieClip.

So now by using a Document Class, your SWF file can actually be a Sprite vs a MovieClip. Once again, look at the code below. On line 5, “extends Spite”, will make your SWF file become a Sprite.  Note: A Document Class can ONLY be a MovieClip or a Sprite.

package {

	import flash.display.Sprite;
	
	public class DCcode extends Sprite{
		
		public var myCircle:Sprite;

		public function DCcode() {
			// DRAW A CIRCLE ON THE STAGE
			myCircle = new Sprite();
			myCircle.graphics.beginFill(0xFF0000);
			myCircle.graphics.drawCircle(100, 100, 50);
			addChild(myCircle);

		}

	}

}

In part 2 of this article, I will discuss how to implement and use a Document Class.

Tags: ActionScript, AS3, Document Class, Flash