Each application built with ActionScript 3.0 has a hierarchy of displayed objects known as the display list. The display list contains all the visible elements in the application. Display elements fall into one or more of the following groups:

The Stage: The Stage is the base container of display objects. Each application has one Stage object, which contains all on-screen display objects. The Stage is the top-level container and is at the top of the display list hierarchy. Each SWF file has an associated ActionScript class, known as the main class of the SWF file. When Flash Player opens a SWF file in an HTML page, Flash Player calls the constructor function for that class and the instance that is created (which is always a type of display object) is added as a child of the Stage object. The main class of a SWF file always extends the Sprite class. You can access the Stage through the stage property of any DisplayObject instance.
Display objects: In ActionScript 3.0, all elements that appear on screen in an application are types of display objects. The flash.display package includes a DisplayObject class, which is a base class extended by a number of other classes. These different classes represent different types of display objects, such as vector shapes, movie clips, and text fields, to name a few.
Display object containers: Display object containers are special types of display objects that, in addition to having their own visual representation, can also contain child objects that are display objects. The DisplayObjectContainer class is a subclass of the DisplayObject class. A DisplayObjectContainer object can contain multiple display objects in its child list.

Although all visible display objects inherit from the DisplayObject class, the type of each is of a specific subclass of DisplayObject class. You can only create instances of the specific display objects that have a defined visual representation. For example, you can use the appropriate constructor methods to create an instance of the Sprite class, the Shape class, or the Video class, but you cannot call the DisplayObject() constructor to create an instance of the DisplayObject class.

The display list for an ActionScript application contains all of the visible objects in the application. You can think of the display list as a hierarchy or tree structure, with the Stage as the object that's behind all the other content. The stage contains the instance of the main class of the SWF file (for example, the main timeline of a Flash SWF or the Application component of a Flex SWF). That main object can in turn contain one or more display objects or display object containers; and any containers can contain additional child objects. The following diagram shows an example of a hyphothetical display list hierarchy in a SWF:

A diagram of a hypothetical display list structure in a SWF file. Stage is at the root of the hierarchy. It contains the instance of the main class, which in turn contains a Display Object and a Display Object Container.

Child content (any display objects inside of containers) is always displayed in front of its parent container. If a display object container includes multiple child display objects, they are stacked in front of each other; the display object container keeps track of their order. The order of child display objects inside a display object container is often described as the display objects' depth, stacking order, or index (since the depth of each display object is stored as an integer index, like the index of an array, with the bottom-most child at position 0, the next at position 1, and so on).

While there are many things that can be done with display objects on the display list, this Quick Start covers the following common tasks that you'll want to perform when you're working with the display list.

Adding objects to the display list

The most common thing you'll want to do is add a display object to the display list. To do that, you create the child display object and add it to a display object container by calling the container's addChild() method. By default, the display object is added to the front of the container's children; if you want to insert it somewhere else in the stack of child objects, you can use the addChildAt() method instead.

The following example creates three display objects (instances of the Shape class) and adds them to the display list as children of the object named container. The first two objects (circle and triangle) are added using the addChild() method, so they are added at index positions zero and one. The third one (square) is added at index position one using the addChildAt() method, which puts it at index position one and pushes triangle forward to position two.

To simplify the example, the code calls the createShape() function to create the Shape instances; the process of adding the objects to the display list happens in the main code listing.

Example

        // This code must be attached to a DisplayObjectContainer, such
// as a Sprite or MovieClip instance.
import flash.display.Shape;

var circle:Shape = createShape("circle");
this.addChild(circle);

var triangle:Shape = createShape("triangle");
this.addChild(triangle);

var square:Shape = createShape("square");
this.addChildAt(square, 1);

function createShape(shapeType:String):Shape
{
   var size:int = 100;
   var result:Shape = new Shape();
   result.graphics.lineStyle(1, 0x000000);
   
   switch (shapeType)
   {
      case "circle":
         result.graphics.beginFill(0x990000);
         result.graphics.drawCircle(size / 2, size / 2, size / 2);
         result.graphics.endFill();
         result.x = 10;
         result.y = 10;
         break;
      case "square":
         result.graphics.beginFill(0x009900);
         result.graphics.drawRect(0, 0, size, size);
         result.graphics.endFill();
         result.x = 50;
         result.y = 50;
         break;
      case "triangle":
         result.graphics.beginFill(0x000099);
         result.graphics.moveTo(size / 2, 0);
         result.graphics.lineTo(size, size);
         result.graphics.lineTo(0, size);
         result.graphics.lineTo(size / 2, 0);
         result.graphics.endFill();
         result.x = 80;
         result.y = 10;
         break;
   }
   
   return result;
}

    

Result

This content requires Flash To view this content, JavaScript must be enabled, and you need the latest version of the Adobe Flash Player. To view this content, JavaScript must be enabled, and you need the latest version of the Adobe Flash Player.

To get the source files for this example, either download add_children_source.zip from the top of the page or else right-click the SWF and select Download Source from the context menu. The Flash Professional CS5 version of the FLA file is in the ZIP file as add_children_CS5.fla.

The SWF above shows the three shapes that were created and how their display list position affects how they are drawn. The circle, which is at position zero in the list, is below the others and the triangle, at position 2, is on the top.

Changing an object's depth in the display list

There are several techniques for moving a display object forward or backwards (changing its depth) within the stack of objects in its parent container. A display object container can position a child object using the setChildIndex() method, or swap the depths of two of its children using the swapChildren() method (if you have a reference to both child objects) or the swapChildrenAt() method (if you know the index positions of each child). If you need to know the index of an object you can use the container's getChildIndex() method; alternatively, if you know the index and need a reference to the object, you can use the getChildAt() method.

This example creates five shapes: two circles, two squares, and a triangle. Clicking on any shape changes its depth on the display list, according to which of the radio button values ("Move to back," "Move backward," Move forward," or "Move to front") is selected. To perform the "Move to back" and "Move to front" operations, the code uses the container.setChildIndex() method with index 0 to make it the back object and index numChildren - 1 to make it the front object. To perform the "Move forward" and "Move backward" operations, the code uses container.getChildAt() to get a reference to the object whose index is one less than the clicked object (to move back) or one more than the clicked object (to move forward), then uses container.swapChildren() to swap the clicked object with its neighbor.

Note: This code listing assumes there are classes defined for each of the shapes: RedCircle, GreenSquare, BlueTriangle, YellowCircle, and PurpleSquare. In addition, for the sake of brevity the code listing shows only the most relevent parts of the code. To view the complete source right-click the Flash application and choose Download Source.

Example

        // This code must be attached to a DisplayObjectContainer, such
// as a Sprite or MovieClip instance.
import flash.display.DisplayObject;
import flash.display.Sprite;
import flash.events.MouseEvent;

// create the container Sprite
var container:Sprite = new Sprite();
this.addChild(container);

// create child shapes, position them, and add them to the container
...

// register the event handler function with the shapes
redCircle.addEventListener(MouseEvent.CLICK, shapeClickHandler);
greenSquare.addEventListener(MouseEvent.CLICK, shapeClickHandler);
blueTriangle.addEventListener(MouseEvent.CLICK, shapeClickHandler);
yellowCircle.addEventListener(MouseEvent.CLICK, shapeClickHandler);
purpleSquare.addEventListener(MouseEvent.CLICK, shapeClickHandler);

// This function will be called when any of the shapes is clicked.
function shapeClickHandler(event:MouseEvent):void
{
   var clickedShape:DisplayObject = event.target as DisplayObject;
   
   // perform the appropriate action according to
   // which radio button is selected
   ...
}

function moveToBack(shapeToMove:DisplayObject):void
{
   // move the shape to the back by setting it to index 0
   // in the container's child list
   container.setChildIndex(shapeToMove, 0);
}

function moveBackward(shapeToMove:DisplayObject):void
{
   // get the index of the clicked shape and destination
   var shapeIndex:int = container.getChildIndex(shapeToMove);
   var destinationIndex:int = shapeIndex - 1;
   
   // make sure it's not already the bottom shape
   if (destinationIndex >= 0)
   {
      // get a reference to the shape in the destination index
      var destination:DisplayObject = container.getChildAt(destinationIndex);
      // swap the shapes
      container.swapChildren(shapeToMove, destination);
   }
}

function moveForward(shapeToMove:DisplayObject):void
{
   // get the index of the clicked shape and destination
   var shapeIndex:int = container.getChildIndex(shapeToMove);
   var destinationIndex:int = shapeIndex + 1;
   
   // make sure it's not already the top shape
   if (destinationIndex < container.numChildren)
   {
      // get a reference to the shape in the destination index
      var destination:DisplayObject = container.getChildAt(destinationIndex);
      // swap the shapes
      container.swapChildren(shapeToMove, destination);
   }
}

function moveToFront(shapeToMove:DisplayObject):void
{
   // move the shape to the front by moving it to the front-most
   // index (which is always numChildren - 1)
   container.setChildIndex(shapeToMove, container.numChildren - 1);
}
    

Result

To download the source files for this example, either download reorder_children_source.zip from the top of the page or else right-click the SWF and select Download Source from the context menu. The Flash Professional CS5 version of the FLA file is in the ZIP file as reorder_children_CS5.fla.

Removing an object from the display list

Another task you may want to perform is to remove a display object from the display list. To remove a display object from a container's child list, call the container's removeChild() method, passing the display object to remove as a parameter.

The following example demonstrates removing a child display object from the display list. In this example, there are nine squares (display objects) attached to the instance of the main class of the SWF, and a star-shaped display object is hidden underneath one of them. Clicking on any of the squares calls the removeChild() method of the display object container, passing the square as a parameter, which removes the square from the display list (and consequently removes it from the screen, revealing whether the star is hidden behind it or not).

Note: The following code listing shows only the most relevent parts of the code. To view the complete source right-click the Flash application and choose Download Source.

Example

        ...
// register the appropriate listener function with the squares
one.addEventListener(MouseEvent.CLICK, pickSquare);
two.addEventListener(MouseEvent.CLICK, pickSquare);
three.addEventListener(MouseEvent.CLICK, pickSquare);
four.addEventListener(MouseEvent.CLICK, pickSquare);
five.addEventListener(MouseEvent.CLICK, pickSquare);
six.addEventListener(MouseEvent.CLICK, pickSquare);
seven.addEventListener(MouseEvent.CLICK, pickSquare);
eight.addEventListener(MouseEvent.CLICK, pickSquare);
nine.addEventListener(MouseEvent.CLICK, pickSquare);

// This function is called when a square is clicked.
function pickSquare(event:MouseEvent):void
{
   ...

   // get a reference to the square that was clicked on
   var clickedSquare:DisplayObject = event.target as DisplayObject;
   
   // remove the square from the display list
   this.removeChild(clickedSquare);
   
   ...
}
    

Result

To download the source files for this example, either download remove_children_source.zip from the top of the page or else right-click the SWF and select Download Source from the context menu. The Flash Professional CS5 version of the FLA file is in the ZIP file as remove_children_CS5.fla.

For more information

Portions of this article were adapted from Display programming in the ActionScript 3.0 Developer's Guide.

Related Flash Quick Starts

Display list programming in ActionScript 3

by H. Paul Robertson

Content

Modified

Page tools

Requirements

Prerequisite knowledge

User level

Required products

Sample files

Adding objects to the display list

Changing an object's depth in the display list

Removing an object from the display list

For more information

More Like This

Products

Solutions

Industries

Help

Learning

Ways to buy

Downloads

Company