AS3: The Display List

By Blue_Chi | Flash CS3 | ActionScript 3.0 | Beginner

The display list is the system by which objects are displayed on the screen using ActionScript 3.0. It is one of the main concepts to learn if you want to create anything visual using ActionScript. This tutorial will explain the basics concepts involved with the display list and will explore the display list API.

What is the Display List?

The display list is a list that contains all visible Flash content, it is used to control what can appear visually on the screen on the depths at which objects are placed over each other.

Basic Usage of the Display List

The basic usage of the display list involves displaying objects on the screen and removing others from the screen. These two tasks require using the .addChild() and .removeChild() methods.

In order to display an object on the screen you need to use the .addChild() method. Here is a simple example of it:

var myText:TextField = new TextField();
myText.text = "Hello!";
addChild(myText);

On the other hand, in order to remove an object from the screen you need to use the .removeChild() method. To remove any object from the main timeline you simply remove it this way:

removeChild(myObject);

Hierarchy in the Display List

Objects shown on the display list are placed in a hierarchy. If you add more than one object to the display list using the .addChild() method you will notice that objects you add later will be placed over previous objects (practically covering them).

For example, if you add to the display list an instance of a rectangle class, an instance of a circle class, and finally an instance of a star class using a code similar to the one below, your objects will be placed over each other.

var myTriangle:TriangleShape = new TriangleShape();
var myCircle:CircleShape = new CircleShape();
var myStar:StarShape = new StarShape()

addChild(myTriangle);
addChild(myCircle);
addChild(myStar);
The classes TriangleShape, CircleShape, and StarShape are fictional classes, they do not exist in AS3. However, you may create them yourself by defining them in your library.

The code above will result in your objects getting layered over each other.

AS3 Display List

The logic at which these objects are laid is simple, objects added later to the display list will be placed over objects added earlier.

The position at which an object is played on the display list is called its index. The index at which objects are placed on the list starts from zero, so the first object is placed at position zero, the second at position one, and the third at position two, etc. It is possible to manipulate the position at which your objects are laid over each other by targeting a specific index at which the object is to be placed using the .addChildAt() method.

Using the .addChildAt() Method

Unlike the .addChild() method, the .addChildAt() method requires two parameters, the first is the instance name of the object you wish to add to the list, and the second is the index position you wish to place it at. It is used in the format of generalized code below:

addChildAt(myObject,indexNumber)

For example, say that you want to add the triangle and circle first and then you want to add the star, but you want to make sure that the star object goes behind the triangle and the circle and not above them, you can do that by using the .addChildAt() method.

We will start off by adding the triangle and the circle to the display list, we can do that by using the code below:

var myTriangle:TriangleShape = new TriangleShape();
var myCircle:CircleShape = new CircleShape();
var myStar:StarShape = new StarShape()

addChild(myTriangle);
addChild(myCircle);

The code above will be create the triangle and the circle, the triangle will be at position 0 while the circle will be at position 1.

AS3 Display List - AddChildAt

We want our star to be placed below all of these objects, so we it has to be place at index Zero. We can do that this way:

var myTriangle:TriangleShape = new TriangleShape();
var myCircle:CircleShape = new CircleShape();
var myStar:StarShape = new StarShape()

addChild(myTriangle);
addChild(myCircle);
addChildAt(myStar,0);

This will make our star go behind all the currently existing objects. You should note that this pushes all the other objects 1 index position up to accommodate the star object, so that the triangle is now at index 1 and the circle is now at index 2.

AS3 Display List - AddChildAt

 

You should note that even though it is possible to place the object at any index position, this position must not exceed the maximum necessary slots for the current number of objects in the list. For example, attempting to place the object at the index position 10 will generate an error because this position goes beyond the scope of the display list. This differs from previous ActionScript versions where it was possible to place objects any any depth regardless of whether that will create a number of empty depths.

Removing Objects Using the removeChildAt() method

In addition to the possibility of adding objects directly by their position, it is also possible to remove objects by referring to their position. If for example you wanted to remove the object at index 1 you can do that by using the code below:

var myTriangle:TriangleShape = new TriangleShape();
var myCircle:CircleShape = new CircleShape();
var myStar:StarShape = new StarShape()

addChild(myTriangle);
addChild(myCircle);
addChild(myStar);

removeChildAt(1);

You should note that this will decrease the index of all objects that were placed in a higher index so that empty index slot is accommodate. This means that the star object is now placed at index position 1 and not index position 2.

Display List - removeChildAt

Swapping Index Positions

In addition to the possibility of positioning your object at a certain index position in the display list by using the .addChildAt(), you can also instantly swap the position with another object by using the .swapChildren() method. This method simply switches the index position of any two objects instantly without affecting any other object in the list.

var myTriangle:TriangleShape = new TriangleShape();
var myCircle:CircleShape = new CircleShape();
var myStar:StarShape = new StarShape()

addChild(myTriangle);
addChild(myCircle);
addChild(myStar);

swapChildren(myStar, myCircle);

The order in which these two objects are passed to the method does not matter. They will all generate the same result:

AS3 Display List - SwapChildren()

Other Display List API

In addition to the methods we mentioned earlier, there are a number of other methods and properties which can be used to retrieve info about currently displayed objects. These methods are self-explanatory:

  1. .getChildIndex(objectName) - This method is used to retrieve the index position of a displayed object by referring to it by its instance name.
  2. .getChildAt(indexPosition) - This method is used to retrieve the instance name of an object by referring to its index position.
  3. .numChildren - This is a property that can be accessed through any display object container to retrieve the number of objects currently found on its display list.

Display Objects and Display Object Containers

It is essential to realize that only Display Objects can be added to a display list. These include objects such as MovieClips, Sprites, TextFields, Videos, Bitmaps, etc. You cannot add non-visual objects to the display list, for example, you cannot add a number variable to the display list.

On the other hand, there are some Display Objects which are also Display Object Containers, these are objects which have their own display list to which other objects could be added. Examples of Display Object Containers include MovieClips and Sprites.

In the example below, a two text field instances will be added to a MovieClip instance, but they will not actually appear on the screen except when their MovieClip container is added to the display list of the main timeline:

var container_mc:MovieClip = new MovieClip();
var text1_txt:TextField = new TextField();
var text2_txt:TextField = new TextField();

container_mc.addChild(text1_txt);
container_mc.addChild(text2_txt);

text1_txt.text = "This text field will not appear on the screen";
text2_txt.text = "Except if we add its container to the main timeline display list";

addChild(container_mc);

This was an introduction to the basic role of the display list feature of ActionScript. I hope you found this tutorial helpful. Please feel free to post any questions you have at the Oman3D Forum.

- End of Tutorial