Traversing the display list

As you've seen, the display list is a tree structure. At the top of the tree is the Stage, which can contain multiple display objects. Those display objects that are themselves display object containers can contain other display objects, or display object containers.

A diagram of a hypothetical display list structure of a SWF file.

The DisplayObjectContainer class includes properties and methods for traversing the display list, by means of the child lists of display object containers. For example, consider the following code, which adds two display objects, title and pict, to the container object (which is a Sprite, and the Sprite class extends the DisplayObjectContainer class):

var container:Sprite = new Sprite();
var title:TextField = new TextField();
title.text = "Hello";
var pict:Loader = new Loader();
var url:URLRequest = new URLRequest("banana.jpg");
pict.load(url);
pict.name = "banana loader";
container.addChild(title);
container.addChild(pict);

The getChildAt() method returns the child of the display list at a specific index position:

trace(container.getChildAt(0) is TextField); // true

You can also access child objects by name. Each display object has a name property, and if you don't assign it, Flash Player assigns a default value, such as "instance1". For example, the following code shows how to use the getChildByName() method to access a child display object with the name "banana loader":

trace(container.getChildByName("banana loader") is Loader); // true

Using the getChildByName() method can result in slower performance than using the getChildAt() method.

Since a display object container can contain other display object containers as child objects in its display list, you can traverse the full display list of the application as a tree. For example, in the code excerpt shown earlier, once the load operation for the pict Loader object is complete, the pict object will have one child display object, which is the bitmap, loaded. To access this bitmap display object, you can write pict.getChildAt(0). You can also write container.getChildAt(0).getChildAt(0) (since container.getChildAt(0) == pict).

The following function provides an indented trace() output of the display list from a display object container:

function traceDisplayList(container:DisplayObjectContainer,
                                                indentString:String = ""):void
{
    var child:DisplayObject;
    for (var i:uint=0; i < container.numChildren; i++)
    {
        child = container.getChildAt(i);
        trace(indentString, child, child.name); 
        if (container.getChildAt(i) is DisplayObjectContainer)
        {
            traceDisplayList(DisplayObjectContainer(child), indentString + "    ")
        }
    }
}

Flash CS3

Comments

No screen name said on Aug 16, 2007 at 10:52 AM :

It would be great if this said something about parent. None of the AS2 methods I'm using to get to parent are working, with or without the leading underscore. This is where I would expect to find some help with that.

tderich said on Sep 26, 2007 at 11:32 AM :

The following table describes the differences between ActionScript 2.0 and 3.0:
http://livedocs.adobe.com/flash/9.0/ActionScriptLangRefV3/migration.html.

In AS3, _parent is now inherited from the DisplayObject class.
Removed the initial underscore.
Data type changed from MovieClip to
DisplayObjectContainer.

fun9 said on May 1, 2008 at 8:33 AM :

It'd be nice to see an example of how traceDisplayList is used and what the output looks like.

Ergates9 said on Jul 7, 2008 at 11:06 AM :

I agree - examples would be useful to say the least. As a very, very experienced AS developer, I am not ashamed to admit that I am finding the transition to AS3 unbelievably difficult - mostly because in all but the simplest cases, it is a practical nightmare trying to navigate the display hierarchy. Determining scope, targeting scripts, objects and effects, it is all very counter intuitive, especially if you've been working in a MC oriented environment since Flash4.

I find myself again and again wondering why I am bothering when I could do it so much more quickly and efficiently in AS2. But we have to move with the times...

There are undoubtedly great OOP advantages to AS3, but without more complete documentation and better script examples, it's technically difficult to take advantage of them.

I suspect a lot of experienced developers are too shy to admit defeat and so are just putting all of this into the 'too difficult' drawer.

Come on Adobe! You can do better than this - we need a decent migration manual, not a list of changes with some sketchy comments and poorly thought out examples.

tderich - you may find it very straightforward to say that _parent is now 'inherited from the DisplayObject class. However to many of us, finding out how to 'get hold' of display objects and, for example, reposition them in relation to each other is nigh on impossible and your documentation provides little or no practical help.

For example, what if you want to drop something on a target? It took me ages to work out that the unnamed graphic shape in my named clip was the droptarget. Pretty flipping useless if you are trying to find out if you are dropping something on something called 'bin' for example!

Oh, and if you are trying to use the example to traverse something, bear in mind that even if your class extends Sprite or MovieClip, you will still need to import a bunch of stuff at the top of your code.

It's probably not efficient, but just put in
import flash.display.*

RSS feed | Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/flash/9.0/main/00000149.html