Adobe® Flex® 4 Language Reference
Show Packages and Classes List |  Packages  |  Classes  |  Index  |  Appendixes
flash.display 
DisplayObjectContainer 
Packageflash.display
Classpublic class DisplayObjectContainer
InheritanceDisplayObjectContainer Inheritance InteractiveObject Inheritance DisplayObject Inheritance EventDispatcher Inheritance Object
Subclasses Loader, Sprite, Stage, TextLine

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9, Flash Lite 4

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 the Flash runtimes. 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 ActionScript 3.0 Developer's Guide.

View the examples

See also



Public Properties
 PropertyDefined By
 InheritedaccessibilityImplementation : AccessibilityImplementation
The current accessibility implementation (AccessibilityImplementation) for this InteractiveObject instance.
InteractiveObject
 InheritedaccessibilityProperties : AccessibilityProperties
The current accessibility options for this display object.
DisplayObject
 Inheritedalpha : Number
Indicates the alpha transparency value of the object specified.
DisplayObject
 InheritedblendMode : String
A value from the BlendMode class that specifies which blend mode to use.
DisplayObject
 InheritedblendShader : Shader
[write-only] Sets a shader that is used for blending the foreground and background.
DisplayObject
 InheritedcacheAsBitmap : Boolean
If set to true, Flash runtimes cache an internal bitmap representation of the display object.
DisplayObject
 InheritedAIR-only cacheAsBitmapMatrix : Matrix
If non-null, this Matrix object defines how a display object is rendered when cacheAsBitmap is set to true.
DisplayObject
 Inheritedconstructor : Object
A reference to the class object or constructor function for a given object instance.
Object
 InheritedcontextMenu : NativeMenu
Specifies the context menu associated with this object.
InteractiveObject
 InheriteddoubleClickEnabled : Boolean
Specifies whether the object receives doubleClick events.
InteractiveObject
 Inheritedfilters : Array
An indexed array that contains each filter object currently associated with the display object.
DisplayObject
 InheritedfocusRect : Object
Specifies whether this object displays a focus rectangle.
InteractiveObject
 Inheritedheight : Number
Indicates the height of the display object, in pixels.
DisplayObject
 InheritedloaderInfo : LoaderInfo
[read-only] Returns a LoaderInfo object containing information about loading the file to which this display object belongs.
DisplayObject
 Inheritedmask : 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, or user input device, enabled.
DisplayObjectContainer
 InheritedmouseEnabled : Boolean
Specifies whether this object receives mouse, or other user input, messages.
InteractiveObject
 InheritedmouseX : Number
[read-only] Indicates the x coordinate of the mouse or user input device position, in pixels.
DisplayObject
 InheritedmouseY : Number
[read-only] Indicates the y coordinate of the mouse or user input device position, in pixels.
DisplayObject
 Inheritedname : String
Indicates the instance name of the DisplayObject.
DisplayObject
  numChildren : int
[read-only] Returns the number of children of this object.
DisplayObjectContainer
 InheritedopaqueBackground : Object
Specifies whether the display object is opaque with a certain background color.
DisplayObject
 Inheritedparent : DisplayObjectContainer
[read-only] Indicates the DisplayObjectContainer object that contains this display object.
DisplayObject
 Inheritedprototype : Object
[static] A reference to the prototype object of a class or function object.
Object
 Inheritedroot : 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
 Inheritedrotation : Number
Indicates the rotation of the DisplayObject instance, in degrees, from its original orientation.
DisplayObject
 InheritedrotationX : Number
Indicates the x-axis rotation of the DisplayObject instance, in degrees, from its original orientation relative to the 3D parent container.
DisplayObject
 InheritedrotationY : Number
Indicates the y-axis rotation of the DisplayObject instance, in degrees, from its original orientation relative to the 3D parent container.
DisplayObject
 InheritedrotationZ : Number
Indicates the z-axis rotation of the DisplayObject instance, in degrees, from its original orientation relative to the 3D parent container.
DisplayObject
 Inheritedscale9Grid : Rectangle
The current scaling grid that is in effect.
DisplayObject
 InheritedscaleX : Number
Indicates the horizontal scale (percentage) of the object as applied from the registration point.
DisplayObject
 InheritedscaleY : Number
Indicates the vertical scale (percentage) of an object as applied from the registration point of the object.
DisplayObject
 InheritedscaleZ : Number
Indicates the depth scale (percentage) of an object as applied from the registration point of the object.
DisplayObject
 InheritedscrollRect : Rectangle
The scroll rectangle bounds of the display object.
DisplayObject
 Inheritedstage : Stage
[read-only] The Stage of the display object.
DisplayObject
  tabChildren : Boolean
Determines whether the children of the object are tab enabled.
DisplayObjectContainer
 InheritedtabEnabled : Boolean
Specifies whether this object is in the tab order.
InteractiveObject
 InheritedtabIndex : int
Specifies the tab ordering of objects in a SWF file.
InteractiveObject
  textSnapshot : flash.text:TextSnapshot
[read-only] Returns a TextSnapshot object for this DisplayObjectContainer instance.
DisplayObjectContainer
 Inheritedtransform : flash.geom:Transform
An object with properties pertaining to a display object's matrix, color transform, and pixel bounds.
DisplayObject
 Inheritedvisible : Boolean
Whether or not the display object is visible.
DisplayObject
 Inheritedwidth : Number
Indicates the width of the display object, in pixels.
DisplayObject
 Inheritedx : Number
Indicates the x coordinate of the DisplayObject instance relative to the local coordinates of the parent DisplayObjectContainer.
DisplayObject
 Inheritedy : Number
Indicates the y coordinate of the DisplayObject instance relative to the local coordinates of the parent DisplayObjectContainer.
DisplayObject
 Inheritedz : Number
Indicates the z coordinate position along the z-axis of the DisplayObject instance relative to the 3D parent container.
DisplayObject
Public Methods
 MethodDefined By
  
Calling the new DisplayObjectContainer() constructor throws an ArgumentError exception.
DisplayObjectContainer
  
Adds a child DisplayObject instance to this DisplayObjectContainer instance.
DisplayObjectContainer
  
Adds a child DisplayObject instance to this DisplayObjectContainer instance.
DisplayObjectContainer
 Inherited
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
  
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
  
Determines whether the specified display object is a child of the DisplayObjectContainer instance or the instance itself.
DisplayObjectContainer
 Inherited
Dispatches an event into the event flow.
EventDispatcher
 Inherited
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
  
Returns the child display object instance that exists at the specified index.
DisplayObjectContainer
  
Returns the child display object that exists with the specified name.
DisplayObjectContainer
  
Returns the index position of a child DisplayObject instance.
DisplayObjectContainer
  
Returns an array of objects that lie under the specified point and are children (or grandchildren, and so on) of this DisplayObjectContainer instance.
DisplayObjectContainer
 Inherited
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
 Inherited
Converts the point object from the Stage (global) coordinates to the display object's (local) coordinates.
DisplayObject
 Inherited
Converts a two-dimensional point from the Stage (global) coordinates to a three-dimensional display object's (local) coordinates.
DisplayObject
 Inherited
Checks whether the EventDispatcher object has any listeners registered for a specific type of event.
EventDispatcher
 Inherited
Indicates whether an object has a specified property defined.
Object
 Inherited
Evaluates the bounding box of the display object to see if it overlaps or intersects with the bounding box of the obj display object.
DisplayObject
 Inherited
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
 Inherited
Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter.
Object
 Inherited
Converts a three-dimensional point of the three-dimensional display object's (local) coordinates to a two-dimensional point in the Stage (global) coordinates.
DisplayObject
 Inherited
Converts the point object from the display object's (local) coordinates to the Stage (global) coordinates.
DisplayObject
 Inherited
Indicates whether the specified property exists and is enumerable.
Object
  
Removes the specified child DisplayObject instance from the child list of the DisplayObjectContainer instance.
DisplayObjectContainer
  
Removes a child DisplayObject from the specified index position in the child list of the DisplayObjectContainer.
DisplayObjectContainer
 Inherited
removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void
Removes a listener from the EventDispatcher object.
EventDispatcher
  
Changes the position of an existing child in the display object container.
DisplayObjectContainer
 Inherited
Sets the availability of a dynamic property for loop operations.
Object
  
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
 Inherited
Returns the string representation of this object, formatted according to locale-specific conventions.
Object
 Inherited
Returns the string representation of the specified object.
Object
 Inherited
Returns the primitive value of the specified object.
Object
 Inherited
Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type.
EventDispatcher
Events
 Event Summary Defined By
 Inherited[broadcast event] Dispatched when the Flash Player or AIR application gains operating system focus and becomes active.EventDispatcher
 InheritedDispatched when a display object is added to the display list.DisplayObject
 InheritedDispatched 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
 InheritedDispatched when the user selects 'Clear' (or 'Delete') from the text context menu.InteractiveObject
 InheritedDispatched when a user presses and releases the main button of the user's pointing device over the same InteractiveObject.InteractiveObject
 InheritedDispatched when a user gesture triggers the context menu associated with this interactive object in an AIR application.InteractiveObject
 InheritedDispatched when the user activates the platform specific accelerator key combination for a copy operation or selects 'Copy' from the text context menu.InteractiveObject
 InheritedDispatched when the user activates the platform specific accelerator key combination for a cut operation or selects 'Cut' from the text context menu.InteractiveObject
 Inherited[broadcast event] Dispatched when the Flash Player or AIR application operating loses system focus and is becoming inactive.EventDispatcher
 InheritedDispatched 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
 Inherited[broadcast event] Dispatched when the playhead is entering a new frame.DisplayObject
 Inherited[broadcast event] Dispatched when the playhead is exiting the current frame.DisplayObject
 InheritedDispatched after a display object gains focus.InteractiveObject
 InheritedDispatched after a display object loses focus.InteractiveObject
 Inherited[broadcast event] Dispatched after the constructors of frame display objects have run but before frame scripts have run.DisplayObject
 InheritedDispatched when the user moves a point of contact over the InteractiveObject instance on a touch-enabled device (such as moving a fingers from left to right over a display object on a mobile phone or tablet with a touch screen).InteractiveObject
 InheritedDispatched when the user creates a point of contact with an InteractiveObject instance, then taps on a touch-enabled device (such as placing several fingers over a display object to open a menu and then taps one finger to select a menu item on a mobile phone or tablet with a touch screen).InteractiveObject
 InheritedDispatched when the user performs a rotation gesture at a point of contact with an InteractiveObject instance (such as touching two fingers and rotating them over a display object on a mobile phone or tablet with a touch screen).InteractiveObject
 InheritedDispatched when the user performs a swipe gesture at a point of contact with an InteractiveObject instance (such as touching three fingers to a screen and then moving them in parallel over a display object on a mobile phone or tablet with a touch screen).InteractiveObject
 InheritedDispatched when the user presses two points of contact over the same InteractiveObject instance on a touch-enabled device (such as presses and releases two fingers over a display object on a mobile phone or tablet with a touch screen).InteractiveObject
 InheritedDispatched when the user performs a zoom gesture at a point of contact with an InteractiveObject instance (such as touching two fingers to a screen and then quickly spreading the fingers apart over a display object on a mobile phone or tablet with a touch screen).InteractiveObject
 InheritedThis event is dispatched to any client app that supports inline input with an IMEInteractiveObject
 InheritedDispatched when the user presses a key.InteractiveObject
 InheritedDispatched when the user attempts to change focus by using keyboard navigation.InteractiveObject
 InheritedDispatched when the user releases a key.InteractiveObject
 InheritedDispatched when a user presses and releases the middle button of the user's pointing device over the same InteractiveObject.InteractiveObject
 InheritedDispatched when a user presses the middle pointing device button over an InteractiveObject instance.InteractiveObject
 InheritedDispatched when a user releases the pointing device button over an InteractiveObject instance.InteractiveObject
 InheritedDispatched when a user presses the pointing device button over an InteractiveObject instance.InteractiveObject
 InheritedDispatched when the user attempts to change focus by using a pointer device.InteractiveObject
 InheritedDispatched when a user moves the pointing device while it is over an InteractiveObject.InteractiveObject
 InheritedDispatched when the user moves a pointing device away from an InteractiveObject instance.InteractiveObject
 InheritedDispatched when the user moves a pointing device over an InteractiveObject instance.InteractiveObject
 InheritedDispatched when a user releases the pointing device button over an InteractiveObject instance.InteractiveObject
 InheritedDispatched when a mouse wheel is spun over an InteractiveObject instance.InteractiveObject
 InheritedDispatched by the drag initiator InteractiveObject when the user releases the drag gesture.InteractiveObject
 InheritedDispatched by the target InteractiveObject when a dragged object is dropped on it and the drop has been accepted with a call to DragManager.acceptDragDrop().InteractiveObject
 InheritedDispatched by an InteractiveObject when a drag gesture enters its boundary.InteractiveObject
 InheritedDispatched by an InteractiveObject when a drag gesture leaves its boundary.InteractiveObject
 InheritedDispatched by an InteractiveObject continually while a drag gesture remains within its boundary.InteractiveObject
 InheritedDispatched at the beginning of a drag operation by the InteractiveObject that is specified as the drag initiator in the DragManager.doDrag() call.InteractiveObject
 InheritedDispatched during a drag operation by the InteractiveObject that is specified as the drag initiator in the DragManager.doDrag() call.InteractiveObject
 InheritedDispatched when the user activates the platform specific accelerator key combination for a paste operation or selects 'Paste' from the text context menu.InteractiveObject
 InheritedDispatched when a display object is about to be removed from the display list.DisplayObject
 InheritedDispatched 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
 Inherited[broadcast event] Dispatched when the display list is about to be updated and rendered.DisplayObject
 InheritedDispatched when a user presses and releases the right button of the user's pointing device over the same InteractiveObject.InteractiveObject
 InheritedDispatched when a user presses the pointing device button over an InteractiveObject instance.InteractiveObject
 InheritedDispatched when a user releases the pointing device button over an InteractiveObject instance.InteractiveObject
 InheritedDispatched when the user moves a pointing device away from an InteractiveObject instance.InteractiveObject
 InheritedDispatched when the user moves a pointing device over an InteractiveObject instance.InteractiveObject
 InheritedDispatched 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
 InheritedDispatched when the value of the object's tabChildren flag changes.InteractiveObject
 InheritedDispatched when the object's tabEnabled flag changes.InteractiveObject
 InheritedDispatched when the value of the object's tabIndex property changes.InteractiveObject
 InheritedDispatched when a user enters one or more characters of text.InteractiveObject
 InheritedDispatched when the user first contacts a touch-enabled device (such as touches a finger to a mobile phone or tablet with a touch screen).InteractiveObject
 InheritedDispatched when the user removes contact with a touch-enabled device (such as lifts a finger off a mobile phone or tablet with a touch screen).InteractiveObject
 InheritedDispatched when the user moves the point of contact with a touch-enabled device (such as drags a finger across a mobile phone or tablet with a touch screen).InteractiveObject
 InheritedDispatched when the user moves the point of contact away from InteractiveObject instance on a touch-enabled device (such as drags a finger from one display object to another on a mobile phone or tablet with a touch screen).InteractiveObject
 InheritedDispatched when the user moves the point of contact over an InteractiveObject instance on a touch-enabled device (such as drags a finger from a point outside a display object to a point over a display object on a mobile phone or tablet with a touch screen).InteractiveObject
 InheritedDispatched when the user moves the point of contact away from an InteractiveObject instance on a touch-enabled device (such as drags a finger from over a display object to a point outisde the display object on a mobile phone or tablet with a touch screen).InteractiveObject
 InheritedDispatched when the user moves the point of contact over an InteractiveObject instance on a touch-enabled device (such as drags a finger from a point outside a display object to a point over a display object on a mobile phone or tablet with a touch screen).InteractiveObject
 InheritedDispatched when the user lifts the point of contact over the same InteractiveObject instance on which the contact was initiated on a touch-enabled device (such as presses and releases a finger from a single point over a display object on a mobile phone or tablet with a touch screen).InteractiveObject
Property Detail

mouseChildren

property
mouseChildren:Boolean

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9, Flash Lite 4

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.



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

See also


Example  ( How to use this 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
Runtime Versions: AIR 1.0 Flash Player 9, Flash Lite 4

Returns the number of children of this object.



Implementation
    public function get numChildren():int

Example  ( How to use this 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

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9, Flash Lite 4

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.



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  ( How to use this 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 select 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:flash.text:TextSnapshot  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9

Returns a TextSnapshot object for this DisplayObjectContainer instance.



Implementation
    public function get textSnapshot():flash.text:TextSnapshot

See also


Example  ( How to use this 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
Runtime Versions: AIR 1.0 Flash Player 9, Flash Lite 4

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
Runtime Versions: AIR 1.0 Flash Player 9, Flash Lite 4

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

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


Example  ( How to use this 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
Runtime Versions: AIR 1.0 Flash Player 9, Flash Lite 4

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:

b over c over a

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


Example  ( How to use this 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
Runtime Versions: AIR 1.0 Flash Player 9, Flash Lite 4

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

point:Point — The point under which to look.

Returns
Booleantrue if the point contains child display objects with security restrictions.

See also


Example  ( How to use this 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
Runtime Versions: AIR 1.0 Flash Player 9, Flash Lite 4

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
Booleantrue if the child object is a child of the DisplayObjectContainer or the container itself; otherwise false.

Example  ( How to use this 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
Runtime Versions: AIR 1.0 Flash Player 9, Flash Lite 4

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


Example  ( How to use this 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
Runtime Versions: AIR 1.0 Flash Player 9, Flash Lite 4

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


Example  ( How to use this 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
Runtime Versions: AIR 1.0 Flash Player 9, Flash Lite 4

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  ( How to use this 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
Runtime Versions: AIR 1.0 Flash Player 9, Flash Lite 4

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


Example  ( How to use this 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
Runtime Versions: AIR 1.0 Flash Player 9, Flash Lite 4

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

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  ( How to use this 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
Runtime Versions: AIR 1.0 Flash Player 9, Flash Lite 4

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

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  ( How to use this 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
Runtime Versions: AIR 1.0 Flash Player 9, Flash Lite 4

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:

c over b over a

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:

c over a over b

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


Example  ( How to use this 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
Runtime Versions: AIR 1.0 Flash Player 9, Flash Lite 4

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  ( How to use this 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
Runtime Versions: AIR 1.0 Flash Player 9, Flash Lite 4

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  ( How to use this 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
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();
    }
}