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
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.
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);
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, 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
To remove objects, you have the converse
removeChildAt methods as well as the
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
When a child is added to the display list, some events are fired on that child.
Conversely, there are also the remove events:
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.