DisplayObjectContainer  - AS3

Determines whether or not the children of the object are mouse, or user input device, enabled. If an object is enabled, a user can interact with it by using a mouse or user input device. The default is true.

This property is useful when you create a button with an instance of the Sprite class (instead of using the SimpleButton class). When you use a Sprite instance to create a button, you can choose to decorate the button by using the addChild() method to add additional Sprite instances. This process can cause unexpected behavior with mouse events because the Sprite instances you add as children can become the target object of a mouse event when you expect the parent instance to be the target object. To ensure that the parent instance serves as the target objects for mouse events, you can set the mouseChildren property of the parent instance to false.

No event is dispatched by setting this property. You must use the addEventListener() method to create interactive functionality.

Related API Elements

import flash.display.Sprite;
import flash.events.MouseEvent;

var container:Sprite = new Sprite();
container.name = "container";
addChild(container);

var circle:Sprite = new Sprite();
circle.name = "circle";
circle.graphics.beginFill(0xFFCC00);
circle.graphics.drawCircle(40, 40, 40);

container.addChild(circle);

container.mouseChildren = false;

container.addEventListener(MouseEvent.CLICK, clicked);

function clicked(event:MouseEvent):void {
    trace(event.target.name); // container
}

Returns the number of children of this object.

Learn more

import flash.display.Sprite;

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

var circle1:Sprite = new Sprite();
circle1.graphics.beginFill(0xFFCC00);
circle1.graphics.drawCircle(40, 40, 40);

var circle2:Sprite = new Sprite();
circle2.graphics.beginFill(0x00CCFF);
circle2.graphics.drawCircle(80, 40, 40);

container2.addChild(container1);
container1.addChild(circle1);
container1.addChild(circle2);

trace(container1.numChildren); // 2
trace(container2.numChildren); // 1
trace(circle1.numChildren); // 0
trace(circle2.numChildren); // 0

Determines whether the children of the object are tab enabled. Enables or disables tabbing for the children of the object. The default is true.

Note: Do not use the tabChildren property with Flex. Instead, use the mx.core.UIComponent.hasFocusableChildren property.

import flash.display.Sprite;

var container:Sprite = new Sprite();
container.tabChildren = false;

var circle1:Sprite = new Sprite();
circle1.graphics.beginFill(0xFFCC00);
circle1.graphics.drawCircle(40, 40, 40);
circle1.tabIndex = 1;

var circle2:Sprite = new Sprite();
circle2.graphics.beginFill(0x00CCFF);
circle2.graphics.drawCircle(120, 40, 40);
circle2.tabIndex = 0;

container.addChild(circle1);
container.addChild(circle2);

Returns a TextSnapshot object for this DisplayObjectContainer instance.

Related API Elements

trace(this.textSnapshot.getText(0, this.textSnapshot.charCount));

Calling the new DisplayObjectContainer() constructor throws an ArgumentError exception. You can, however, call constructors for the following subclasses of DisplayObjectContainer:

• new Loader()
• new Sprite()
• new MovieClip()

Adds a child DisplayObject instance to this DisplayObjectContainer instance. The child is added to the front (top) of all other children in this DisplayObjectContainer instance. (To add a child to a specific index position, use the addChildAt() method.)

If you add a child object that already has a different display object container as a parent, the object is removed from the child list of the other display object container.

Note: The command stage.addChild() can cause problems with a published SWF file, including security problems and conflicts with other loaded SWF files. There is only one Stage within a Flash runtime instance, no matter how many SWF files you load into the runtime. So, generally, objects should not be added to the Stage, directly, at all. The only object the Stage should contain is the root object. Create a DisplayObjectContainer to contain all of the items on the display list. Then, if necessary, add that DisplayObjectContainer instance to the Stage.

Parameters

More examples

Learn more

Related API Elements

import flash.display.Sprite;

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

var circle1:Sprite = new Sprite();
circle1.graphics.beginFill(0xFFCC00);
circle1.graphics.drawCircle(40, 40, 40);

var circle2:Sprite = new Sprite();
circle2.graphics.beginFill(0x00CCFF);
circle2.graphics.drawCircle(80, 40, 40);

container2.addChild(container1);
container1.addChild(circle1);
container1.addChild(circle2);

trace(container1.numChildren); // 2
trace(container2.numChildren); // 1
trace(circle1.numChildren); // 0
trace(circle2.numChildren); // 0

Adds a child DisplayObject instance to this DisplayObjectContainer instance. The child is added at the index position specified. An index of 0 represents the back (bottom) of the display list for this DisplayObjectContainer object.

For example, the following example shows three display objects, labeled a, b, and c, at index positions 0, 2, and 1, respectively:

If you add a child object that already has a different display object container as a parent, the object is removed from the child list of the other display object container.

Parameters

More examples

Learn more

Related API Elements

import flash.display.Sprite;

var container:Sprite = new Sprite();

var circle1:Sprite = new Sprite();
var circle2:Sprite = new Sprite();

container.addChild(circle1);
container.addChildAt(circle2, 0);

trace(container.getChildAt(0) == circle2); // true
trace(container.getChildAt(1) == circle1); // true

Indicates whether the security restrictions would cause any display objects to be omitted from the list returned by calling the DisplayObjectContainer.getObjectsUnderPoint() method with the specified point point. By default, content from one domain cannot access objects from another domain unless they are permitted to do so with a call to the Security.allowDomain() method. For more information, related to security, see the Flash Player Developer Center Topic: Security.

The point parameter is in the coordinate space of the Stage, which may differ from the coordinate space of the display object container (unless the display object container is the Stage). You can use the globalToLocal() and the localToGlobal() methods to convert points between these coordinate spaces.

Parameters

Related API Elements

import flash.display.Sprite;
import flash.display.Loader;
import flash.system.LoaderContext;
import flash.net.URLRequest;
import flash.events.Event;
import flash.geom.Point;

var container:Sprite = new Sprite();

var urlReq:URLRequest = new URLRequest("http://localhost/RemoteFile.swf");
var ldr:Loader = new Loader();
var context:LoaderContext = new LoaderContext();
context.checkPolicyFile = false;
ldr.load(urlReq, context);

ldr.contentLoaderInfo.addEventListener(Event.COMPLETE, loaded);
ldr.contentLoaderInfo.addEventListener(IOErrorEvent.IO_ERROR, urlNotFound);

function loaded(event:Event):void {
    var pt:Point = new Point(1, 1);
    trace(container.areInaccessibleObjectsUnderPoint(pt)); // true
}

function urlNotFound(event:Event):void {
    trace("The URL was not found."); 
}

Determines whether the specified display object is a child of the DisplayObjectContainer instance or the instance itself. The search includes the entire display list including this DisplayObjectContainer instance. Grandchildren, great-grandchildren, and so on each return true.

Parameters

import flash.display.Sprite;

var sprite1:Sprite = new Sprite();
var sprite2:Sprite = new Sprite();
var sprite3:Sprite = new Sprite();
var sprite4:Sprite = new Sprite();

sprite1.addChild(sprite2);
sprite2.addChild(sprite3);

trace(sprite1.contains(sprite1)); // true
trace(sprite1.contains(sprite2)); // true
trace(sprite1.contains(sprite3)); // true
trace(sprite1.contains(sprite4)); // false

Returns the child display object instance that exists at the specified index.

Parameters

More examples

Related API Elements

import flash.display.Sprite;

var container:Sprite = new Sprite();

var sprite1:Sprite = new Sprite();
var sprite2:Sprite = new Sprite();
var sprite3:Sprite = new Sprite();

container.addChild(sprite1);
container.addChild(sprite2);
container.addChildAt(sprite3, 0);

trace(container.getChildAt(0) == sprite3); // true
trace(container.getChildAt(1) == sprite1); // true
trace(container.getChildAt(2) == sprite2); // true

Returns the child display object that exists with the specified name. If more that one child display object has the specified name, the method returns the first object in the child list.

The getChildAt() method is faster than the getChildByName() method. The getChildAt() method accesses a child from a cached array, whereas the getChildByName() method has to traverse a linked list to access a child.

Parameters

More examples

Learn more

Related API Elements

import flash.display.Sprite;
import flash.display.DisplayObject;

var container:Sprite = new Sprite();

var sprite1:Sprite = new Sprite();
sprite1.name = "sprite1";
var sprite2:Sprite = new Sprite();
sprite2.name = "sprite2";

container.addChild(sprite1);
container.addChild(sprite2);

var target:DisplayObject = container.getChildByName("sprite1"); 
trace(container.getChildIndex(target)); // 0

Returns the index position of a child DisplayObject instance.

Parameters

import flash.display.Sprite;
import flash.display.DisplayObject;

var container:Sprite = new Sprite();

var sprite1:Sprite = new Sprite();
sprite1.name = "sprite1";
var sprite2:Sprite = new Sprite();
sprite2.name = "sprite2";

container.addChild(sprite1);
container.addChild(sprite2);

var target:DisplayObject = container.getChildByName("sprite1"); 
trace(container.getChildIndex(target)); // 0

Returns an array of objects that lie under the specified point and are children (or grandchildren, and so on) of this DisplayObjectContainer instance. Any child objects that are inaccessible for security reasons are omitted from the returned array. To determine whether this security restriction affects the returned array, call the areInaccessibleObjectsUnderPoint() method.

The point parameter is in the coordinate space of the Stage, which may differ from the coordinate space of the display object container (unless the display object container is the Stage). You can use the globalToLocal() and the localToGlobal() methods to convert points between these coordinate spaces.

Parameters

Related API Elements

import flash.display.Sprite;
import flash.geom.Point;

var container:Sprite = new Sprite();

var square1:Sprite = new Sprite();
square1.graphics.beginFill(0xFFCC00);
square1.graphics.drawRect(0, 0, 40, 40);

var square2:Sprite = new Sprite();
square2.graphics.beginFill(0x00CCFF);
square2.graphics.drawRect(20, 0, 30, 40);

container.addChild(square1);
container.addChild(square2);

var pt:Point = new Point(10, 20);
var objects:Array = container.getObjectsUnderPoint(pt); 
trace(objects.length); // 1

pt = new Point(35, 20);
objects = container.getObjectsUnderPoint(pt);
trace(objects.length);  // 2

Removes the specified child DisplayObject instance from the child list of the DisplayObjectContainer instance. The parent property of the removed child is set to null , and the object is garbage collected if no other references to the child exist. The index positions of any display objects above the child in the DisplayObjectContainer are decreased by 1.

The garbage collector reallocates unused memory space. When a variable or object is no longer actively referenced or stored somewhere, the garbage collector sweeps through and wipes out the memory space it used to occupy if no other references to it exist.

Parameters

 
import flash.display.DisplayObject;
import flash.display.Sprite;
import flash.events.MouseEvent;

var container:Sprite = new Sprite();
addChild(container);

var circle1:Sprite = new Sprite();
circle1.graphics.beginFill(0xFFCC00);
circle1.graphics.drawCircle(40, 40, 40);

var circle2:Sprite = new Sprite();
circle2.graphics.beginFill(0x00CCFF);
circle2.graphics.drawCircle(120, 40, 40);

container.addChild(circle1);
container.addChild(circle2);

container.addEventListener(MouseEvent.CLICK, clicked);

function clicked(event:MouseEvent):void {
    container.removeChild(DisplayObject(event.target)); 
}

Removes a child DisplayObject from the specified index position in the child list of the DisplayObjectContainer. The parent property of the removed child is set to null, and the object is garbage collected if no other references to the child exist. The index positions of any display objects above the child in the DisplayObjectContainer are decreased by 1.

The garbage collector reallocates unused memory space. When a variable or object is no longer actively referenced or stored somewhere, the garbage collector sweeps through and wipes out the memory space it used to occupy if no other references to it exist.

Parameters

import flash.display.Sprite;

var container:Sprite = new Sprite();

var sprite1:Sprite = new Sprite();
sprite1.name = "sprite1";
var sprite2:Sprite = new Sprite();
sprite2.name = "sprite2";

container.addChild(sprite1);
container.addChild(sprite2);

trace(container.numChildren) // 2
container.removeChildAt(0); 
trace(container.numChildren) // 1
trace(container.getChildAt(0).name); // sprite2

Removes all child DisplayObject instances from the child list of the DisplayObjectContainer instance. The parent property of the removed children is set to null , and the objects are garbage collected if no other references to the children exist.

The garbage collector reallocates unused memory space. When a variable or object is no longer actively referenced or stored somewhere, the garbage collector sweeps through and wipes out the memory space it used to occupy if no other references to it exist.

Parameters

Changes the position of an existing child in the display object container. This affects the layering of child objects. For example, the following example shows three display objects, labeled a, b, and c, at index positions 0, 1, and 2, respectively:

When you use the setChildIndex() method and specify an index position that is already occupied, the only positions that change are those in between the display object's former and new position. All others will stay the same. If a child is moved to an index LOWER than its current index, all children in between will INCREASE by 1 for their index reference. If a child is moved to an index HIGHER than its current index, all children in between will DECREASE by 1 for their index reference. For example, if the display object container in the previous example is named container, you can swap the position of the display objects labeled a and b by calling the following code:

container.setChildIndex(container.getChildAt(1), 0);

This code results in the following arrangement of objects:

Parameters

Related API Elements

import flash.display.Sprite;
import flash.events.MouseEvent;

var container:Sprite = new Sprite();
addChild(container);

var circle1:Sprite = new Sprite();
circle1.graphics.beginFill(0xFF0000);
circle1.graphics.drawCircle(40, 40, 40);
circle1.addEventListener(MouseEvent.CLICK, clicked);
 
var circle2:Sprite = new Sprite();
circle2.graphics.beginFill(0x00FF00);
circle2.graphics.drawCircle(100, 40, 40);
circle2.addEventListener(MouseEvent.CLICK, clicked);
 
var circle3:Sprite = new Sprite();
circle3.graphics.beginFill(0x0000FF);
circle3.graphics.drawCircle(70, 80, 40);
circle3.addEventListener(MouseEvent.CLICK, clicked);
 
container.addChild(circle1);
container.addChild(circle2);
container.addChild(circle3);
addChild(container);
 
function clicked(event:MouseEvent):void {
    var circle:Sprite = Sprite(event.target);
    var topPosition:uint = container.numChildren - 1;
    container.setChildIndex(circle, topPosition);
}

Recursively stops the timeline execution of all MovieClips rooted at this object.

Child display objects belonging to a sandbox to which the excuting code does not have access are ignored.

Note: Streaming media playback controlled via a NetStream object will not be stopped.

Swaps the z-order (front-to-back order) of the two specified child objects. All other child objects in the display object container remain in the same index positions.

Parameters

import flash.display.Sprite;

var container:Sprite = new Sprite();

var sprite1:Sprite = new Sprite();
sprite1.name = "sprite1";
var sprite2:Sprite = new Sprite();
sprite2.name = "sprite2";

container.addChild(sprite1);
container.addChild(sprite2);

trace(container.getChildAt(0).name); // sprite1
trace(container.getChildAt(1).name); // sprite2

container.swapChildren(sprite1, sprite2);

trace(container.getChildAt(0).name); // sprite2
trace(container.getChildAt(1).name); // sprite1

Swaps the z-order (front-to-back order) of the child objects at the two specified index positions in the child list. All other child objects in the display object container remain in the same index positions.

Parameters

import flash.display.Sprite;

var container:Sprite = new Sprite();

var sprite1:Sprite = new Sprite();
sprite1.name = "sprite1";
var sprite2:Sprite = new Sprite();
sprite2.name = "sprite2";
var sprite3:Sprite = new Sprite();
sprite3.name = "sprite3";

container.addChild(sprite1);
container.addChild(sprite2);
container.addChild(sprite3);

trace(container.getChildAt(0).name); // sprite1
trace(container.getChildAt(1).name); // sprite2
trace(container.getChildAt(2).name); // sprite3

container.swapChildrenAt(0, 2);

trace(container.getChildAt(0).name); // sprite3
trace(container.getChildAt(1).name); // sprite2
trace(container.getChildAt(2).name); // sprite1

1. The constructor calls the configureAssets() method.
2. The configureAssets() method creates child and lastChild Sprite objects.
3. A for loop creates the five orange squares and positions them one after another.
4. Each time a CustomSprite object is created, its constructor calls the draw() method of the CustomSprite object, which creates a 50-by-50-pixel square by calling the beginFill(), drawRect(), and endFill() methods of the Graphics class. The addChild() method adds each square to the display list.

package {
    import flash.display.DisplayObject;
    import flash.display.Sprite;

    public class DisplayObjectContainerExample extends Sprite {
        private var gutter:uint     = 5;
        private var childCount:uint = 5;

        public function DisplayObjectContainerExample() {
            configureAssets();
        }

        private function configureAssets():void {
            var child:Sprite = new CustomSprite();
            var lastChild:Sprite = child;
            for (var i:uint = 1; i <= childCount; i++) {
                child = new CustomSprite();
                child.x = lastChild.x + lastChild.width + gutter;
                addChild(child);
                lastChild = child;
            }
        }
    }
}

import flash.display.Sprite;

class CustomSprite extends Sprite {
    private var size:uint = 50;
    private var bgColor:uint = 0xFFCC00;

    public function CustomSprite() {
        draw(size, size);
    }

    private function draw(w:uint, h:uint):void {
        graphics.beginFill(bgColor);
        graphics.drawRect(0, 0, w, h);
        graphics.endFill();
    }
}