ActionScript 3 Working With Display Objects 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:
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
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.ADDEDEvent.ADDED_TO_STAGE
Conversely, there are also the remove events:
Event.REMOVEDEvent.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.
