flash display_list_internal_list

Each DisplayObjectContainer has a list of child objects represented by an internal array. Each index has a child object. Visually the object positioned in the index 0 is underneath the object positioned in the index 1.

Here is the internal array of the access to child objects:

The DisplayObjectContainer contains three child objects. On each call the addChild method puts the visual object concerned at the end of the child object list, which translates into a stacking of them. In working with these different management methods of child objects we work in a transparent way with the internal array.

The addChild method stacks child objects but if you wish to manage the stacking order we use the addChildAt method. Here is its signature:

public function addChildAt(child:DisplayObject, index:int):DisplayObject

The addChildAt method accepts a second parameter allowing you to manage the index of the DisplayObject in the DisplayObjectContainer list.

Take the following example, we create an instance of the MovieClip and add it to the display list:

var myClipA:MovieClip = new MovieClip();
addChild ( myClipA );

The myClipA visual object is placed in the index 0. We therefore want to place a second clip in the same index. The addChildAt method places the myClipB clip in the index 0 moving myClipA to the index 1:

var myClipA:MovieClip = new MovieClip();
addChild ( myClipA );
var myClipB:MovieClip = new MovieClip();
addChildAt ( myClipB, 0 );

In order to make room for the added visual object, the child objects that are already present in the specified index aren’t replaced but simply moved from an index. This behavior saves you from accidently replacing a visual object in the display list. If we want to reproduce the idea of replacing a visual object, we need to delete it then place a new one in the liberated index.

If the index in the addChildAt method is negative or doesn’t correspond to any child object:

var myClipA:MovieClip = new MovieClip();
addChildAt ( myClipA, 10 );

An execution of the RangeError type is raised:

RangeError: Error #2006: The indicated index is not within the limits.

The addChildAt method can only therefore be used with an index going from 0 to numChildren-1. To place a DisplayObject before any others we have to write:

addChildAt ( myClipA, numChildren-1 );

No intermediary depth between two DisplayObjects can remain unoccupied. This behavior is linked to the management of the automatic depth by Flash 9 player in ActionScript 3. We will come back to this in the article called Collapse of depths.

Worth remembering

• There is only one display list
• At its summit is the Stage object
• All visual objects can be instantoated with the keyword new
• No depth or occurrence name is necessary during the initiatlisation phase
• When a visual object is created, it is not automatically added to the display list
• To see a visual object you need to add it to the display list
• To choose the position of the DisplayObject when it is added to the display list, we use the addChildAt method.