Working with display objects -- Flex 2.01

Now that you understand the basic concepts of the Stage, display objects, display object containers, and the display list, this section provides you with some more specific information about working with display objects in ActionScript 3.0.

Subtopics

Properties and methods of the DisplayObject class

All display objects are subclasses of the DisplayObject class, and as such they inherit the properties and methods of the DisplayObject class. The properties inherited are basic properties that apply to all display objects. For example, each display object has an x property and a y property that specifies the object's position in its display object container.

There is no constructor function for the DisplayObject class. You must create another type of object (an object that is a subclass of the DisplayObject type), such as a Sprite, to instantiate an object with the new constructor. Also, if you want to create a custom display object class, you must create a subclass of one of the display object subclasses that has a usable constructor function (such as the Shape class or the Sprite class).

Adding display objects to the display list

When you instantiate a display object, it will not appear onscreen (on the Stage) until you add the display object instance to a display object container that is on the display list. For example, in the following code, the myText TextField object would not be visible if you omitted the last line of code. In the last line of code, the this keyword must refer to a display object container that is already added to the display list.

import flash.display.*;
import flash.text.TextField;
var myText:TextField = new TextField();
myText.text = "Buenos dias.";
this.addChild(myText);

When you add any visual element to the Stage, that element becomes a child of the Stage object. The first SWF file loaded in an application (for example, the one that you embed in an HTML page) is automatically added as a child of the Stage. It can be an object of any type that extends the Sprite class.

Any display objects that you create without using ActionScript--for example, by adding an MXML tag in Adobe Flex Builder 2 or by using a drawing tool in Flash--are added to the display list. Although you do not add these display objects through ActionScript, you can access them through ActionScript. For example, the following code adjusts the width of an object named button1 that was added in the authoring tool (not through ActionScript):

button1.width = 200;

Working with display object containers

If a DisplayObjectContainer object is deleted from the display list, or if it is moved or transformed in some other way, each display object in the DisplayObjectContainer is also deleted, moved, or transformed.

A display object container is itself a type of display object--it can be added to another display object container. For example, the following image shows a display object container, pictureScreen, that contains one outline shape and four other display object containers (of type PictureFrame):

In order to have a display object appear in the display list, you must add it to a display object container that is on the display list. You do this by using the addChild() method or the addChildAt() method of the container object. For example, without the final line of the following code, the myTextField object would not be displayed:

var myTextField:TextField = new TextField();
myTextField.text = "hello";
this.root.addChild(myTextField);

In this code sample, this.root points to the MovieClip display object container that contains the code. In your actual code, you may specify a different container.

Use the addChildAt() method to add the child to a specific position in the child list of the display object container. These zero-based index positions in the child list relate to the layering (the front-to-back order) of the display objects. For example, consider the following three display objects. Each object was created from a custom class called Ball.

The layering of these display objects in their container can be adjusted using the addChildAt() method. For example, consider the following code:

ball_A = new Ball(0xFFCC00, "a");
ball_A.name = "ball_A";
ball_A.x = 20;
ball_A.y = 20;
container.addChild(ball_A);

ball_B = new Ball(0xFFCC00, "b");
ball_B.name = "ball_B";
ball_B.x = 70;
ball_B.y = 20;
container.addChild(ball_B);

ball_C = new Ball(0xFFCC00, "c");
ball_C.name = "ball_C";
ball_C.x = 40;
ball_C.y = 60;
container.addChildAt(ball_C, 1);

After executing this code, the display objects are positioned as follows in the container DisplayObjectContainer object. Notice the layering of the objects.

You can use the getChildAt() method to verify the layer order of the display objects. The getChildAt() method returns child objects of a container based on the index number you pass it. For example, the following code reveals names of display objects at different positions in the child list of the container DisplayObjectContainer object:

trace(container.getChildAt(0).name); // ball_A
trace(container.getChildAt(1).name); // ball_C
trace(container.getChildAt(2).name); // ball_B

If you remove a display object from the parent container's child list, the higher elements on the list each move down a position in the child index. For example, continuing with the previous code, the following code shows how the display object that was at position 2 in the container DisplayObjectContainer moves to position 1 if a display object that is lower in the child list is removed:

container.removeChild(ball_C);
trace(container.getChildAt(0).name); // ball_A
trace(container.getChildAt(1).name); // ball_B

The removeChild() and removeChildAt() methods do not delete a display object instance entirely. They simply remove it from the child list of the container. The instance can still be referenced by another variable. (Use the delete operator to completely remove an object.)

Because a display object has only one parent container, you can add an instance of a display object to only one display object container. For example, the following code shows that the display object tf1 can exist in only one container (in this case, a Sprite, which extends the DisplayObjectContainer class):

tf1:TextField = new TextField();
tf2:TextField = new TextField();
tf1.name = "text 1";
tf2.name = "text 2";

container1:Sprite = new Sprite();
container2:Sprite = new Sprite();

container1.addChild(tf1);
container1.addChild(tf2);
container2.addChild(tf1);

trace(container1.numChildren); // 1
trace(container1.getChildAt(0).name); // text 2
trace(container2.numChildren); // 1
trace(container2.getChildAt(0).name); // text 1

If you add a display object that is contained in one display object container to another display object container, it is removed from the first display object container's child list.

Recall that a display object that is off the display list--one that is not included in a display object container that is a child of the Stage--is known as an off-list display object.

Traversing the display list

As you've seen, the display list is a tree structure. At the top of the tree is the Stage, which can contain multiple display objects. Those display objects that are themselves display object containers can contain other display objects, or display object containers.

The DisplayObjectContainer class includes properties and methods for traversing the display list, by means of the child lists of display object containers. For example, consider the following code, which adds two display objects, title and pict, to the container object (which is a Sprite, and the Sprite class extends the DisplayObjectContainer class):

var container:Sprite = new Sprite();
var title:TextField = new TextField();
title.text = "Hello";
var pict:Loader = new Loader();
var url:URLRequest = new URLRequest("banana.jpg");
pict.load(url);
pict.name = "banana loader";
container.addChild(title);
container.addChild(pict);

The getChildAt() method returns the child of the display list at a specific index position:

trace(container.getChildAt(0) is TextField); // true

You can also access child objects by name. Each display object has a name property, and if you don't assign it, Flash Player assigns a default value, such as "instance1". For example, the following code shows how to use the getChildByName() method to access a child display object with the name "banana loader":

trace(container.getChildByName("banana loader") is Loader); // true

Using the getChildByName() method can result in slower performance than using the getChildAt() method.

Since a display object container can contain other display object containers as child objects in its display list, you can traverse the full display list of the application as a tree. For example, in the code excerpt shown earlier, once the load operation for the pict Loader object is complete, the pict object will have one child display object, which is the bitmap, loaded. To access this bitmap display object, you can write pict.getChildAt(0). You can also write container.getChildAt(0).getChildAt(0) (since container.getChildAt(0) == pict).

The following function provides an indented trace() output of the display list from a display object container:

function traceDisplayList(container:DisplayObjectContainer,
                                                indentString:String = ""):void
{
    var child:DisplayObject;
    for (var i:uint=0; i < container.numChildren; i++)
    {
        child = container.getChildAt(i);
        trace (indentString, child, child.name); 
        if (container.getChildAt(i) is DisplayObjectContainer)
        {
            traceDisplayList(DisplayObjectContainer(child), indentString + "    ")
        }
    }
}

If you use Flex, you should know that Flex defines many component display object classes, and these classes override the display list access methods of the DisplayObjectContainer class. For example, the Container class of the mx.core package overrides the addChild() method and other methods of the DisplayObjectContainer class (which the Container class extends). In the case of the addChild() method, the class overrides the method in such a way that you cannot add all types of display objects to a Container instance in Flex. The overridden method, in this case, requires that the child object that you are adding be a type of mx.core.UIComponent object.

Setting Stage properties

The Stage class overrides most properties and methods of the DisplayObject class. If you call one of these overridden properties or methods, Flash Player throws an exception. For example, the Stage object does not have x or y properties, since its position is fixed as the main container for the application. The x and y properties refer to the position of a display object relative to its container, and since the Stage is not contained in another display object container, these properties do not apply.

Controlling the playback frame rate

The framerate property of the Stage class is used to set the frame rate for all SWF files loaded into the application. For more information, see the ActionScript 3.0 Language Reference.

Working with full-screen mode

Full-screen mode allows you to make a SWF fill a viewer's entire monitor, without any borders, menu bars, and so forth. The Stage class's displayState property is used to toggle full-screen mode on and off for a SWF. The displayState property can be set to one of the values defined by the constants in the flash.display.StageDisplayState class. To turn on full-screen mode, set displayState to StageDisplayState.FULL_SCREEN:

// mySprite is a Sprite instance, already added to the display list

mySprite.stage.displayState = StageDisplayState.FULL_SCREEN;

To exit full-screen mode, set the displayState property to StageDisplayState.NORMAL:

mySprite.stage.displayState = StageDisplayState.NORMAL;

In addition, a user can choose to leave full-screen mode by switching focus to a different window or by pressing one of several key combinations: the escape key (all platforms), ctrl-w (Windows), cmd-w (Mac), or alt-F4 (Windows).

Stage scaling behavior for full-screen mode is the same as under normal mode; the scaling is controlled by the Stage class's scaleMode property. As always, if the scaleMode property is set to StageScaleMode.NO_SCALE, the stage's stageWidth and stageHeight properties change to reflect the size of the screen area occupied by the SWF (the entire screen, in this case).

You can use the Stage class's fullScreen event to detect and respond when full-screen mode is turned on or off. For example, you might want to reposition, add, or remove items from the screen when entering or leaving full-screen mode, as in this example:

import flash.events.FullScreenEvent;

function fullScreenRedraw(event:FullScreenEvent):void
{
    if (event.fullScreen)
    {
        // remove input text fields
        // add a button which closes full-screen mode
    }
    else
    {
        // re-add input text fields
        // remove the button which closes full-screen mode
    }
}

mySprite.stage.addEventListener(FullScreenEvent.FULL_SCREEN, fullScreenRedraw);

As this code shows, the event object for the fullScreen event is an instance of the flash.events.FullScreenEvent class, which includes a fullScreen property indicating whether full-screen mode is enabled (true) or not (false).

When working with full-screen mode in ActionScript, you'll want to keep the following considerations in mind:

There are a few additional security-related restrictions you'll want to understand too. These are described in Full-screen mode security.

Handling events for display objects

The DisplayObject class inherits from the EventDispatcher class. This means that every display object can participate fully in the event model (described in Handling Events). Every display object can use its addEventListener() method--inherited from the EventDispatcher class--to listen for a particular event, but only if the listening object is part of the event flow for that event.

When Flash Player dispatches an event object, that event object makes a round-trip journey from the Stage to the display object where the event occurred. For example, if a user clicks on a display object named child1, Flash Player dispatches an event object from the Stage through the display list hierarchy down to the child1 display object.

The event flow is conceptually divided into three phases, as illustrated in this diagram:

Current page: http://livedocs.adobe.com/flex/201/html/05_Display_Programming_162_05.html