No children on the stage – a confusing Flash CS3 display list issue

A reader wrote to me with an interesting Flash CS3 problem that had me stumped at first (mostly because I use FlexBuilder instead of Flash). I thought I’d post the answer here so we can all benefit from it.

The Problem

Ben H. writes…

I’ve been trying to get familiar with a “best practice” on [looping through the display list]. The trouble is, when I enter the following on the first frame of a blank .fla file:

trace("Number of Children in a blank SWF:"+stage.numChildren);
trace("Child 1:" + stage.getChildAt(0));

I get this:

Number of Children in a blank SWF:1
Child 1:[object MainTimeline]

Now that may seem grand, but I’ve drawn several shapes and have a text field and named movieclip instances on stage as well – so why [does it only count one child?]

Solution after the jump.

The Solution

The first thing I noticed here is that the trace statement seems to be tracing out an instance of the MainTimeline class. I tried seeing if the objects appear inside of the MainTimeline with this code (notice i had to cast the timeline to a DisplayObjectContainer to check its children):
[ftf]
import flash.display.*;
var timeline:DisplayObjectContainer = DisplayObjectContainer(stage.getChildAt(0));
trace(“Number of Children in a blank SWF:” + timeline.numChildren);
trace(“Child 1:” + timeline.getChildAt(0));
[/ftf]
Which displayed:

Number of Children in a blank SWF:3
Child 1:[object Shape]

OK. So the shapes are there, it’s just that they are inside the MainTimeline’s display list instead of in the Stage’s. Since I’m a little rusty on the Flash authoring tool, it took me a minute to realize that the MainTimeline is the class that Flash automatically creates when a Document Class is not specified by the developer. (By the way, I just want to say that I officially do not condone putting actions on frames when you’re using AS3. I really think you should always use a Document Class (which is a way to specify a class to use as your main timeline (I know, nested parentheses!)). You can use any class as long as it extends Sprite or MovieClip. In case you’re not familiar with this, Roger made a nifty screencast that shows how to set up your .FLA to use classes.) I was reminded that when you do define a Document Class such as this one:
[ftf]
package {
import flash.display.*;
public class Demo extends Sprite {
public function Demo() {
trace(“Number of Children in this SWF:” + numChildren);
trace(“Child 1:” + getChildAt(0));
}
}
}
[/ftf]
You simply access the children with getChildren() or this.getChildren() instead of referencing the Stage or the MainTimeline (because this is the main timeline). Try this on the first frame of the FLA (no don’t!) and you’ll get the same result.
So what’s the difference between the Stage and the Document Class? The Stage is a special type of Display Object that is ‘owned and operated’ by the Flash Player. It also contains some special properties, such as frameRate, which affect all the other display lists. The Document Class, on the other hand, is defined by the developer and can be customized to fit your needs.
Good question Ben. It really is confusing that you’re drawing objects on the ‘stage’ but calling stage.getChildren() doesn’t return those objects.