ActionScript 3 Introduction To The Display List


Example

In AS3, display assets are not visible until they are added to the Display List.

The AIR/Flash runtime has a hierarchical display structure (parent child relationship where children can have their own children), with the stage being the top level parent.

To add something to the display list, you use addChild or addChildAt. Here is a basic example of drawing a circle and adding it to the display list:

var myCircle:Shape = new Shape();
        
myCircle.graphics.beginFill(0xFF0000); //red
myCircle.graphics.drawCircle(25, 25, 50);
myCircle.graphics.endFill();
        
this.addChild(myCircle); //add the circle as a child of `this`

To see the object in the example above, this (the context of the code) also must be on the display list, as well any parents it may have. In AS3, the stage is the top most parent.

Display objects can only have one parent. So if a child already has a parent, and you add it to another object, it will be removed from it's previous parent.

Z-Order / Layering

Let's say you replicated the code from the previous example so you had 3 circles:

var redCircle:Shape = new Shape();
redCircle.graphics.beginFill(0xFF0000); //red
redCircle.graphics.drawCircle(50, 50, 50); //graphics.endFill is not required

var greenCircle:Shape = new Shape();
greenCircle.graphics.beginFill(0x00FF00); //green
greenCircle.graphics.drawCircle(75, 75, 50);
        
var blueCircle:Shape = new Shape();
blueCircle.graphics.beginFill(0x0000FF); //blue
blueCircle.graphics.drawCircle(100, 100, 50);

this.addChild(redCircle); 
this.addChild(greenCircle); 
this.addChild(blueCircle); 

Since the addChild method adds the child on top of everything else in the same parent, you'll get this result with the items layered in the same order you use addChild:

enter image description here

If you wanted a child layered different relative to it's siblings, you can use addChildAt. With addChildAt, you pass in another parameter that indicates the index (z-order) the child should be at. 0 being the bottom most position/layer.

this.addChild(redCircle); 
this.addChild(greenCircle); 
this.addChildAt(blueCircle,0); //This will add the blue circle at the bottom

enter image description here

Now the blue circle is under it's siblings. If later on, you want to change the index of a child, you can use the setChildIndex method (on the child's parent).

this.setChildIndex(redCircle, this.numChildren - 1); //since z-index is 0 based, the top most position is amount of children less 1.

This will rearrange the red circle so it's above everything else. The code above produces the exact same result as this.addChild(redCircle).

Removing Display Objects

To remove objects, you have the converse removeChild and removeChildAt methods as well as the removeChildren method.

removeChild(redCircle); //this will take redCircle off the display list

removeChildAt(0); //this will take the bottom most object off the display list 

removeChildren(); //this will clear all children from the display list

removeChildren(1); //this would remove all children except the bottom most

removeChildren(1,3); //this would remove the children at indexes 1, 2 & 3

Events

When a child is added to the display list, some events are fired on that child.

  • Event.ADDED
  • Event.ADDED_TO_STAGE

Conversely, there are also the remove events:

  • Event.REMOVED
  • Event.REMOVED_FROM_STAGE

Adobe Animate / Flash Professional

When dealing with FlashProfessional/Adobe Animate timelines, adding something to the timeline handles the display list nuances automatically. They added and removed from the display list automatically by the timeline.

However, it's good to keep in mind that:

If you manipulate through code the parentage of a display object created by the timeline (by using addChild/setChildIndex), that child will no longer be removed automatically by the timeline and will need to be removed via code.