ActionScript 3.0 Language and Components Reference | All Packages | All Classes | Language Elements | Index | Appendixes | Conventions | Frames No Frames |
DisplayObjectContainer

Package | flash.display
Class | public class DisplayObjectContainer
Inheritance | DisplayObjectContainer InteractiveObject DisplayObject EventDispatcher Object
Subclasses | Loader, Sprite, Stage, TextLine

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

The DisplayObjectContainer class is the base class for all objects that can serve as display object containers on the display list. The display list manages all objects displayed in Flash Player. Use the DisplayObjectContainer class to arrange the display objects in the display list. Each DisplayObjectContainer object has its own child list for organizing the z-order of the objects. The z-order is the front-to-back order that determines which object is drawn in front, which is behind, and so on.

DisplayObject is an abstract base class; therefore, you cannot call DisplayObject directly. Invoking `new DisplayObject()` throws an `ArgumentError` exception.

The DisplayObjectContainer class is an abstract base class for all objects that can contain child objects. It cannot be instantiated directly; calling the `new DisplayObjectContainer()` constructor throws an `ArgumentError` exception.

For more information, see the "Display Programming" chapter of the Programming ActionScript 3.0 book.

View the examples

See also

flash.display.DisplayObject
Core display classes
Working with display object containers

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | accessibilityProperties : AccessibilityProperties The current accessibility options for this display object. | DisplayObject
|  | alpha : Number Indicates the alpha transparency value of the object specified. | DisplayObject
|  | blendMode : String A value from the BlendMode class that specifies which blend mode to use. | DisplayObject
|  | cacheAsBitmap : Boolean If set to true, Flash Player caches an internal bitmap representation of the display object. | DisplayObject
|  | constructor : Object A reference to the class object or constructor function for a given object instance. | Object
|  | contextMenu : ContextMenu Specifies the context menu associated with this object. | InteractiveObject
|  | doubleClickEnabled : Boolean Specifies whether the object receives doubleClick events. | InteractiveObject
|  | filters : Array An indexed array that contains each filter object currently associated with the display object. | DisplayObject
|  | focusRect : Object Specifies whether this object displays a focus rectangle. | InteractiveObject
|  | height : Number Indicates the height of the display object, in pixels. | DisplayObject
|  | loaderInfo : LoaderInfo [read-only] Returns a LoaderInfo object containing information about loading the file to which this display object belongs. | DisplayObject
|  | mask : DisplayObject The calling display object is masked by the specified mask object. | DisplayObject
|  | mouseChildren : Boolean Determines whether or not the children of the object are mouse enabled. | DisplayObjectContainer
|  | mouseEnabled : Boolean Specifies whether this object receives mouse messages. | InteractiveObject
|  | mouseX : Number [read-only] Indicates the x coordinate of the mouse position, in pixels. | DisplayObject
|  | mouseY : Number [read-only] Indicates the y coordinate of the mouse position, in pixels. | DisplayObject
|  | name : String Indicates the instance name of the DisplayObject. | DisplayObject
|  | numChildren : int [read-only] Returns the number of children of this object. | DisplayObjectContainer
|  | opaqueBackground : Object Specifies whether the display object is opaque with a certain background color. | DisplayObject
|  | parent : DisplayObjectContainer [read-only] Indicates the DisplayObjectContainer object that contains this display object. | DisplayObject
|  | prototype : Object [static] A reference to the prototype object of a class or function object. | Object
|  | root : DisplayObject [read-only] For a display object in a loaded SWF file, the root property is the top-most display object in the portion of the display list's tree structure represented by that SWF file. | DisplayObject
|  | rotation : Number Indicates the rotation of the DisplayObject instance, in degrees, from its original orientation. | DisplayObject
|  | scale9Grid : Rectangle The current scaling grid that is in effect. | DisplayObject
|  | scaleX : Number Indicates the horizontal scale (percentage) of the object as applied from the registration point. | DisplayObject
|  | scaleY : Number Indicates the vertical scale (percentage) of an object as applied from the registration point of the object. | DisplayObject
|  | scrollRect : Rectangle The scroll rectangle bounds of the display object. | DisplayObject
|  | stage : Stage [read-only] The Stage of the display object. | DisplayObject
|  | tabChildren : Boolean Determines whether the children of the object are tab enabled. | DisplayObjectContainer
|  | tabEnabled : Boolean Specifies whether this object is in the tab order. | InteractiveObject
|  | tabIndex : int Specifies the tab ordering of objects in a SWF file. | InteractiveObject
|  | textSnapshot : TextSnapshot [read-only] Returns a TextSnapshot object for this DisplayObjectContainer instance. | DisplayObjectContainer
|  | transform : Transform An object with properties pertaining to a display object's matrix, color transform, and pixel bounds. | DisplayObject
|  | visible : Boolean Whether or not the display object is visible. | DisplayObject
|  | width : Number Indicates the width of the display object, in pixels. | DisplayObject
|  | x : Number Indicates the x coordinate of the DisplayObject instance relative to the local coordinates of the parent DisplayObjectContainer. | DisplayObject
|  | y : Number Indicates the y coordinate of the DisplayObject instance relative to the local coordinates of the parent DisplayObjectContainer. | DisplayObject

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | DisplayObjectContainer() Calling the new DisplayObjectContainer() constructor throws an ArgumentError exception. | DisplayObjectContainer
|  | addChild(child:DisplayObject):DisplayObject Adds a child DisplayObject instance to this DisplayObjectContainer instance. | DisplayObjectContainer
|  | addChildAt(child:DisplayObject, index:int):DisplayObject Adds a child DisplayObject instance to this DisplayObjectContainer instance. | DisplayObjectContainer
|  | addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event. | EventDispatcher
|  | areInaccessibleObjectsUnderPoint(point:Point):Boolean 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. | DisplayObjectContainer
|  | contains(child:DisplayObject):Boolean Determines whether the specified display object is a child of the DisplayObjectContainer instance or the instance itself. | DisplayObjectContainer
|  | dispatchEvent(event:Event):Boolean Dispatches an event into the event flow. | EventDispatcher
|  | getBounds(targetCoordinateSpace:DisplayObject):Rectangle Returns a rectangle that defines the area of the display object relative to the coordinate system of the targetCoordinateSpace object. | DisplayObject
|  | getChildAt(index:int):DisplayObject Returns the child display object instance that exists at the specified index. | DisplayObjectContainer
|  | getChildByName(name:String):DisplayObject Returns the child display object that exists with the specified name. | DisplayObjectContainer
|  | getChildIndex(child:DisplayObject):int Returns the index position of a child DisplayObject instance. | DisplayObjectContainer
|  | getObjectsUnderPoint(point:Point):Array Returns an array of objects that lie under the specified point and are children (or grandchildren, and so on) of this DisplayObjectContainer instance. | DisplayObjectContainer
|  | getRect(targetCoordinateSpace:DisplayObject):Rectangle Returns a rectangle that defines the boundary of the display object, based on the coordinate system defined by the targetCoordinateSpace parameter, excluding any strokes on shapes. | DisplayObject
|  | globalToLocal(point:Point):Point Converts the point object from the Stage (global) coordinates to the display object's (local) coordinates. | DisplayObject
|  | hasEventListener(type:String):Boolean Checks whether the EventDispatcher object has any listeners registered for a specific type of event. | EventDispatcher
|  | hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined. | Object
|  | hitTestObject(obj:DisplayObject):Boolean Evaluates the display object to see if it overlaps or intersects with the obj display object. | DisplayObject
|  | hitTestPoint(x:Number, y:Number, shapeFlag:Boolean = false):Boolean Evaluates the display object to see if it overlaps or intersects with the point specified by the x and y parameters. | DisplayObject
|  | isPrototypeOf(theClass:Object):Boolean Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter. | Object
|  | localToGlobal(point:Point):Point Converts the point object from the display object's (local) coordinates to the Stage (global) coordinates. | DisplayObject
|  | propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable. | Object
|  | removeChild(child:DisplayObject):DisplayObject Removes the specified child DisplayObject instance from the child list of the DisplayObjectContainer instance. | DisplayObjectContainer
|  | removeChildAt(index:int):DisplayObject Removes a child DisplayObject from the specified index position in the child list of the DisplayObjectContainer. | DisplayObjectContainer
|  | removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void Removes a listener from the EventDispatcher object. | EventDispatcher
|  | setChildIndex(child:DisplayObject, index:int):void Changes the position of an existing child in the display object container. | DisplayObjectContainer
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations. | Object
|  | swapChildren(child1:DisplayObject, child2:DisplayObject):void Swaps the z-order (front-to-back order) of the two specified child objects. | DisplayObjectContainer
|  | swapChildrenAt(index1:int, index2:int):void Swaps the z-order (front-to-back order) of the child objects at the two specified index positions in the child list. | DisplayObjectContainer
|  | toString():String Returns the string representation of the specified object. | Object
|  | valueOf():Object Returns the primitive value of the specified object. | Object
|  | willTrigger(type:String):Boolean Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type. | EventDispatcher

Events
Hide Inherited Events
Show Inherited Events

| Event | Summary | Defined By
--- | --- | --- | ---
|  | activate | Dispatched when Flash Player gains operating system focus and becomes active. | EventDispatcher
|  | added | Dispatched when a display object is added to the display list. | DisplayObject
|  | addedToStage | Dispatched when a display object is added to the on stage display list, either directly or through the addition of a sub tree in which the display object is contained. | DisplayObject
|  | clear | Dispatched when the user selects 'Clear' (or 'Delete') from the text context menu. | InteractiveObject
|  | click | Dispatched when a user presses and releases the main button of the user's pointing device over the same InteractiveObject. | InteractiveObject
|  | copy | Dispatched when the user activates the platform specific accelerator key combination for a copy operation or selects 'Copy' from the text context menu. | InteractiveObject
|  | cut | Dispatched when the user activates the platform specific accelerator key combination for a cut operation or selects 'Cut' from the text context menu. | InteractiveObject
|  | deactivate | Dispatched when Flash Player loses operating system focus and is becoming inactive. | EventDispatcher
|  | doubleClick | Dispatched when a user presses and releases the main button of a pointing device twice in rapid succession over the same InteractiveObject when that object's doubleClickEnabled flag is set to true. | InteractiveObject
|  | enterFrame | Dispatched when the playhead is entering a new frame. | DisplayObject
|  | exitFrame | Dispatched when the playhead is exiting the current frame. | DisplayObject
|  | focusIn | Dispatched after a display object gains focus. | InteractiveObject
|  | focusOut | Dispatched after a display object loses focus. | InteractiveObject
|  | frameConstructed | Dispatched after the constructors of frame display objects have run but before frame scripts have run. | DisplayObject
|  | keyDown | Dispatched when the user presses a key. | InteractiveObject
|  | keyFocusChange | Dispatched when the user attempts to change focus by using keyboard navigation. | InteractiveObject
|  | keyUp | Dispatched when the user releases a key. | InteractiveObject
|  | mouseDown | Dispatched when a user presses the pointing device button over an InteractiveObject instance in the Flash Player window. | InteractiveObject
|  | mouseFocusChange | Dispatched when the user attempts to change focus by using a pointer device. | InteractiveObject
|  | mouseMove | Dispatched when a user moves the pointing device while it is over an InteractiveObject. | InteractiveObject
|  | mouseOut | Dispatched when the user moves a pointing device away from an InteractiveObject instance. | InteractiveObject
|  | mouseOver | Dispatched when the user moves a pointing device over an InteractiveObject instance in the Flash Player window. | InteractiveObject
|  | mouseUp | Dispatched when a user releases the pointing device button over an InteractiveObject instance in the Flash Player window. | InteractiveObject
|  | mouseWheel | Dispatched when a mouse wheel is spun over an InteractiveObject instance in the Flash Player window. | InteractiveObject
|  | paste | Dispatched when the user activates the platform specific accelerator key combination for a paste operation or selects 'Paste' from the text context menu. | InteractiveObject
|  | removed | Dispatched when a display object is about to be removed from the display list. | DisplayObject
|  | removedFromStage | Dispatched when a display object is about to be removed from the display list, either directly or through the removal of a sub tree in which the display object is contained. | DisplayObject
|  | render | Dispatched when the display list is about to be updated and rendered. | DisplayObject
|  | rollOut | Dispatched when the user moves a pointing device away from an InteractiveObject instance. | InteractiveObject
|  | rollOver | Dispatched when the user moves a pointing device over an InteractiveObject instance. | InteractiveObject
|  | selectAll | Dispatched when the user activates the platform specific accelerator key combination for a select all operation or selects 'Select All' from the text context menu. | InteractiveObject
|  | tabChildrenChange | Dispatched when the value of the object's tabChildren flag changes. | InteractiveObject
|  | tabEnabledChange | Dispatched when the object's tabEnabled flag changes. | InteractiveObject
|  | tabIndexChange | Dispatched when the value of the object's tabIndex property changes. | InteractiveObject

Property Detail

mouseChildren | property

`mouseChildren:Boolean` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Determines whether or not the children of the object are mouse enabled. If an object is mouse enabled, a user can interact with it by using a mouse. 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.

Implementation
`public function get mouseChildren():Boolean`
`public function set mouseChildren(value:Boolean):void`

See also

flash.display.Sprite.buttonMode
flash.events.EventDispatcher.addEventListener()
Example
The following example sets up a Sprite object (a type of display object container) named `container` and shows that when you set its `mouseChildren` property to `false`, the target of a `mouseClick` event is the `container` object, not any one of its child objects:

    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
    }

numChildren | property |

`numChildren:int` [read-only]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Returns the number of children of this object.

Implementation
`public function get numChildren():int`

See also

Advantages of the display list approach
Example
The following example sets up two Sprite objects named `container1` and `container2`. A Sprite is a type of display object container. The example calls the `addChild()` method to set up the display hierarchy: `container1` is a child of `container2`, and two other display objects, `circle1` and `circle2`, are children of `container1`. The calls to the `trace()` method show the number of children of each object. Note that grandchildren are not included in the `numChildren` count:

    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

tabChildren | property |

`tabChildren:Boolean` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

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

Implementation
`public function get tabChildren():Boolean`
`public function set tabChildren(value:Boolean):void`
Throws

| `IllegalOperationError` — Calling this property of the Stage object throws an exception. The Stage object does not implement this property.

Example
The following example creates a `container1` display object container and adds two display objects, `circle1` and `circle2`, to its child list. The example sets tabChildren to `false` for the children so it can manage its own tab order using `tabIndex`:

    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);

To see the results of this example, compile and run the file. When you click one of the circles, you can press the TAB key to switch the display object that has focus (indicated by a yellow highlight rectangle).

textSnapshot | property |

`textSnapshot:TextSnapshot` [read-only]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Returns a TextSnapshot object for this DisplayObjectContainer instance.

Implementation
`public function get textSnapshot():TextSnapshot`

See also

flash.text.TextSnapshot
Example
The following example works only in the Flash authoring environment. Flex does not include any ways of adding static text to a file. To prepare the Flash file for this example, add one or more static text fields in the first frame of a movie. Then insert the following script into the first frame and run the file. The output will be the static text that you added:

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

Constructor Detail

DisplayObjectContainer | () | Constructor

`public function DisplayObjectContainer()`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

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()`

Method Detail

addChild | () | method

`public function addChild(child:DisplayObject):DisplayObject`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

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.

Parameters

| `child:DisplayObject` — The DisplayObject instance to add as a child of this DisplayObjectContainer instance.

Returns

| `DisplayObject` — The DisplayObject instance that you pass in the `child` parameter.

Events

| `added:`Event`` — Dispatched when a display object is added to the display list.

Throws

| `ArgumentError` — Throws if the child is the same as the parent. Also throws if the caller is a child (or grandchild etc.) of the child being added.

See also

addChildAt()
Advantages of the display list approach
Adding display objects to the display list
Adding display objects to the display list
Adding display objects to the display list
Example
The following example sets up two Sprite objects named `container1` and `container2`. A Sprite is a type of display object container. The example calls the `addChild()` method to set up the display hierarchy: `container1` is a child of `container2`, and two other display objects, `circle1` and `circle2`, are children of `container1`. The calls to the `trace()` method show the number of children of each object. Note that grandchildren are not included in the `numChildren` count:

    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

addChildAt | () | method |

`public function addChildAt(child:DisplayObject, index:int):DisplayObject`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

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

| `child:DisplayObject` — The DisplayObject instance to add as a child of this DisplayObjectContainer instance.
| `index:int` — The index position to which the child is added. If you specify a currently occupied index position, the child object that exists at that position and all higher positions are moved up one position in the child list.

Returns

| `DisplayObject` — The DisplayObject instance that you pass in the `child` parameter.

Events

| `added:`Event`` — Dispatched when a display object is added to the display list.

Throws

| `RangeError` — Throws if the index position does not exist in the child list.
| `ArgumentError` — Throws if the child is the same as the parent. Also throws if the caller is a child (or grandchild etc.) of the child being added.

See also

addChild()
Advantages of the display list approach
Adding display objects to the display list
Adding display objects to the display list
Adding display objects to the display list
Example
The following example creates a `container` display object container and adds a display objects `circle1` to its display list. Then, by calling `container.addChildAt(circle2, 0)`, it adds the `circle2` object to index position zero (the back), and moves the `circle1` object to index position 1:

    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

areInaccessibleObjectsUnderPoint | () | method |

`public function areInaccessibleObjectsUnderPoint(point:Point):Boolean`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

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, see the following:

- The security chapter in the Programming ActionScript 3.0 book and the latest comments on LiveDocs
- 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

| `point:Point` — The point under which to look.

Returns

| `Boolean` — `true` if the point contains child display objects with security restrictions.

See also

flash.system.Security.allowDomain()
getObjectsUnderPoint()
DisplayObject.globalToLocal()
DisplayObject.localToGlobal()
Example
The following code creates a display object container named `container`. The next block of code uses a Loader object to load a JPEG file named "test.jpg" from a remote file server. Note that the `checkPolicyFile` property of the LoaderContext object used as a parameter in the `load()` method is set to `false`. Once the file is loaded, the code calls the `loaded()` method, which in turn calls `container.areInaccessibleObjectsUnderPoint()`, which returns a value of `true` because the loaded content is assumed to be from an inaccessible domain:

    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.");
    }

This example assumes that the SWF file produced by this code is loaded from a different domain than that of the JPEG file, and that the loaded JPEG file occupies the point (1, 1).

contains | () | method |

`public function contains(child:DisplayObject):Boolean`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

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

| `child:DisplayObject` — The child object to test.

Returns

| `Boolean` — `true` if the `child` object is a child of the DisplayObjectContainer or the container itself; otherwise `false`.

Example
The following example sets up a number of Sprite objects and adds some to the child list of others. (A Sprite object is a type of display object container.) The relationship between various objects is shown by calling the `contains()` method:

    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

getChildAt | () | method |

`public function getChildAt(index:int):DisplayObject`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

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

Parameters

| `index:int` — The index position of the child object.

Returns

| `DisplayObject` — The child display object at the specified index position.

Throws

| `RangeError` — Throws if the index does not exist in the child list.
| `SecurityError` — This child display object belongs to a sandbox to which you do not have access. You can avoid this situation by having the child movie call `Security.allowDomain()`.

See also

getChildByName()
Example
The following example creates a display object container named `container` and then adds a three display objects to the child list of the `container` object. The calls to the `getChildAt()` method then reveal the positions of the child objects:

    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

getChildByName | () | method |

`public function getChildByName(name:String):DisplayObject`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

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

| `name:String` — The name of the child to return.

Returns

| `DisplayObject` — The child display object with the specified name.

Throws

| `SecurityError` — This child display object belongs to a sandbox to which you do not have access. You can avoid this situation by having the child movie call the `Security.allowDomain()` method.

See also

getChildAt()
flash.display.DisplayObject.name
Advantages of the display list approach
Example
The following example creates a display object container named `container` and then adds two child display objects to the container. Then, the code calls the `getChildByName()` and `getChildIndex()` methods to return the index position of the child of the `container` object that has the `name "sprite1"`.

    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

getChildIndex | () | method |

`public function getChildIndex(child:DisplayObject):int`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Returns the index position of a `child` DisplayObject instance.

Parameters

| `child:DisplayObject` — The DisplayObject instance to identify.

Returns

| `int` — The index position of the child display object to identify.

Throws

| `ArgumentError` — Throws if the child parameter is not a child of this object.

Example
The following example creates a display object container named `container` and then adds two child display objects to the container. Then, the code calls the `getChildByName()` and `getChildIndex()` methods to return the index position of the child of the `container` object that has the `name "sprite1"`.

    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

getObjectsUnderPoint | () | method |

`public function getObjectsUnderPoint(point:Point):Array`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

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

| `point:Point` — The point under which to look.

Returns

| `Array` — An array of objects that lie under the specified point and are children (or grandchildren, and so on) of this DisplayObjectContainer instance.

See also

areInaccessibleObjectsUnderPoint()
DisplayObject.globalToLocal()
DisplayObject.localToGlobal()
Example
The following example creates a display object container named `container` and then adds two overlapping child display objects to the container. Then the code calls the `getObjectsUnderPoint()` twice — first using a point that touches only one object, then using a point where the objects overlap — and the `length` of the return Array shows the number of objects at each point in the container:

    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

removeChild | () | method |

`public function removeChild(child:DisplayObject):DisplayObject`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

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 is the process by which Flash Player 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

| `child:DisplayObject` — The DisplayObject instance to remove.

Returns

| `DisplayObject` — The DisplayObject instance that you pass in the `child` parameter.

Throws

| `ArgumentError` — Throws if the child parameter is not a child of this object.

Example
The following example creates a display object container named `container` and then adds two child display objects to the container. An event listener is added to the `container` object, so that when the user clicks a child object of the container, the `removeChild()` method removes the child clicked from the child list of the container:

    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));
    }

removeChildAt | () | method |

`public function removeChildAt(index:int):DisplayObject`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

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 is the process by which Flash Player 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

| `index:int` — The child index of the DisplayObject to remove.

Returns

| `DisplayObject` — The DisplayObject instance that was removed.

Throws

| `SecurityError` — This child display object belongs to a sandbox to which the calling object does not have access. You can avoid this situation by having the child movie call the `Security.allowDomain()` method.
| `RangeError` — Throws if the index does not exist in the child list.

Example
The following example creates a display object container named `container` and then adds two child display objects to the container. The code then shows that when you call the `removeChildAt()` method to remove the child at the lowest index position (0), any other child object in the list moves down one position:

    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

setChildIndex | () | method |

`public function setChildIndex(child:DisplayObject, index:int):void`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

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

| `child:DisplayObject` — The child DisplayObject instance for which you want to change the index number.
| `index:int` — The resulting index number for the `child` display object.

Throws

| `RangeError` — Throws if the index does not exist in the child list.
| `ArgumentError` — Throws if the child parameter is not a child of this object.

See also

addChildAt()
getChildIndex()
Example
The following example creates a display object container named `container` and then adds three slightly overlapping child display objects to the container. When the user clicks any of these objects, the `clicked()` method calls the `setChildIndex()` method to move the clicked object to the top-most position in the child list of the `container` object:

    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);
    }

swapChildren | () | method |

`public function swapChildren(child1:DisplayObject, child2:DisplayObject):void`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

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

| `child1:DisplayObject` — The first child object.
| `child2:DisplayObject` — The second child object.

Throws

| `ArgumentError` — Throws if either child parameter is not a child of this object.

Example
The following example creates a display object container named `container`, then adds two child display objects to the container, and then shows the effect of a call to the `swapChildren()` method:

    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

swapChildrenAt | () | method |

`public function swapChildrenAt(index1:int, index2:int):void`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

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

| `index1:int` — The index position of the first child object.
| `index2:int` — The index position of the second child object.

Throws

| `RangeError` — If either index does not exist in the child list.

Example
The following example creates a display object container named `container`, then adds three child display objects to the container, and then shows how a call to the `swapChildrenAt()` method rearranges the child list of the display object container:

    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

Examples How to use examples
DisplayObjectContainerExample.as
The following example uses the class `DisplayObjectContainerExample` to create five orange squares in succession. This task is accomplished by performing the following steps:

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();
        }
    }

Submit Feedback on LiveDocs
© 2004-2008 Adobe Systems Incorporated. All rights reserved.
Tue May 20 2008, 04:02 AM -07:00