The Stage Object in a Flash CS3 Movie

"The Stage" has two very different meanings that must not be confused. Commonly, we refer to "the Stage" when talking about the area in the Flash's authoring tool where you place all your authoring time drawings and other creations. This area becomes later the display area of your movie where all the action happens. However, from the ActionScript 3 point of view, "the Stage" refers to the main, top-level container that holds the entire object hirerachy of everything in your movie that is diplayed on the screen. This container is automatically created when your movie opens in the Flash Player. Each movie has a single Stage object which typically contains only one child. This one child is the main timeline of your movie, MainTimeline. All other display objects in your movie are usually descendants of the MainTimeline.

To be more precise, when the movie opens the Player creates an instance of the Stage class and assigns the MainTimeline of your movie as its child. The Stage class is a subclass of the DisplayObjectContainer class. (The MainTimeline, technically speaking, is an instance of the Document Class that you can assign to your fla file. If you don't specify a Document Class, Flash will create one automatically. The MainTimeline is an instance of the MovieClip class or an instance of its subclass defined by the Document Class.)

Curiosly, the keyword "stage" does not refer to the Stage directly. The Stage, which constitues the root DisplayObjectContainer, cannot be accessed directly. "stage" is a property of a display object that is currently on the Display List and is a descendant of the Stage. "stage" property refers to the Stage indirectly. When you are referring to "stage", for example, stage.addEventListener, you are really referring to "this.stage"; that is, to the stage property of the MainTimeline. "stage" is a shorthand for "this.stage".

To clarify things, lets perform a few experiments. Open a new ActionScript 3 document and save it as children_test_2.fla. Open the Actions panel and type:

 

trace("Number of children of the Stage: ");

trace(stage.numChildren);

trace("What are children of Stage: ");

trace(stage.getChildAt(0));

trace("What does the keyword this refer to? ");

trace(this);

trace("Number of children of MainTimeline: ");

trace(this.numChildren);

trace("Are this.stage and stage the same? ");

trace(this.stage == stage);

trace("How many children does this.stage have? ");

trace(this.stage.numChildren);

trace("What are the children of this.stage? ");

trace(this.stage.getChild(0));

 

Test the movie. The output window reads:

Number of children of Stage:

1

What are children of Stage:

[object MainTimeline]

What does the keyword this refer to?

[object MainTimeline]

Number of children of MainTimeline:

0

Are this.stage and stage the same?

true

How many children does this.stage have?

1

What are the children of this.stage?

[object MainTimeline]

As you see, an empty Flash CS3 fla file has a Stage object. The Stage object has one child, the MainTimeline. Since the file is empty, except for the short script, the number of children of the MainTimeline is 0. "this.stage" and "stage" are the same.

Download

If you don't feel like typing, download the fla file with the above code and test it.

One moral that follows: you should avoid adding children to the Stage. That is, you should avoid using "stage.addChild(...)" which is short for "this.stage.addChild(...)". By using stage.addChild(..) , you are forcing the MainTimeline to create its own siblings. Although most of the time the method works, it is not a good idea. All your assests should be descendants of the MainTimeline.

Back to Intermediate Tutorials              Back to Flash and Math Home

We welcome your comments, suggestions, and contributions. Click the Contact Us link below and email one of us.

Adobe®, Flash®, ActionScript®, Flex® are registered trademarks of Adobe Systems Incorporated.