Packagestarling.display
Classpublic class DisplayObjectContainer
InheritanceDisplayObjectContainer Inheritance DisplayObject Inheritance EventDispatcher Inheritance Object
Subclasses Button, Canvas, Sprite, Sprite3D, Stage, TextField

A DisplayObjectContainer represents a collection of display objects. It is the base class of all display objects that act as a container for other objects. By maintaining an ordered list of children, it defines the back-to-front positioning of the children within the display tree.

A container does not a have size in itself. The width and height properties represent the extents of its children. Changing those properties will scale all children accordingly.

As this is an abstract class, you can't instantiate it directly, but have to use a subclass instead. The most lightweight container class is "Sprite".

Adding and removing children

The class defines methods that allow you to add or remove children. When you add a child, it will be added at the frontmost position, possibly occluding a child that was added before. You can access the children via an index. The first child will have index 0, the second child index 1, etc.

Adding and removing objects from a container triggers non-bubbling events. Especially the ADDED_TO_STAGE event is very helpful, as it allows you to automatically execute some logic (e.g. start an animation) when an object is rendered the first time.

See also

Sprite
DisplayObject


Public Properties
 PropertyDefined By
 Inheritedalpha : Number
The opacity of the object.
DisplayObject
 Inheritedbase : DisplayObject
[read-only] The topmost object in the display tree the object is part of.
DisplayObject
 InheritedblendMode : String
The blend mode determines how the object is blended with the objects underneath.
DisplayObject
 Inheritedbounds : Rectangle
[read-only] The bounds of the object relative to the local coordinates of the parent.
DisplayObject
 Inheritedfilter : FragmentFilter
The filter that is attached to the display object.
DisplayObject
 Inheritedheight : Number
The height of the object in pixels.
DisplayObject
 Inheritedis3D : Boolean
[read-only] Indicates if this object or any of its parents is a 'Sprite3D' object.
DisplayObject
 Inheritedmask : DisplayObject
The display object that acts as a mask for the current object.
DisplayObject
 InheritedmaskInverted : Boolean
Indicates if the masked region of this object is set to be inverted.
DisplayObject
 Inheritedname : String
The name of the display object (default: null).
DisplayObject
  numChildren : int
[read-only] The number of children of this container.
DisplayObjectContainer
 Inheritedparent : DisplayObjectContainer
[read-only] The display object container that contains this display object.
DisplayObject
 InheritedpivotX : Number
The x coordinate of the object's origin in its own coordinate space (default: 0).
DisplayObject
 InheritedpivotY : Number
The y coordinate of the object's origin in its own coordinate space (default: 0).
DisplayObject
 InheritedrequiresRedraw : Boolean
[read-only] Indicates if the object needs to be redrawn in the upcoming frame, i.e.
DisplayObject
 Inheritedroot : DisplayObject
[read-only] The root object the display object is connected to (i.e.
DisplayObject
 Inheritedrotation : Number
The rotation of the object in radians.
DisplayObject
 Inheritedscale : Number
Sets both 'scaleX' and 'scaleY' to the same value.
DisplayObject
 InheritedscaleX : Number
The horizontal scale factor.
DisplayObject
 InheritedscaleY : Number
The vertical scale factor.
DisplayObject
 InheritedskewX : Number
The horizontal skew angle in radians.
DisplayObject
 InheritedskewY : Number
The vertical skew angle in radians.
DisplayObject
 Inheritedstage : Stage
[read-only] The stage the display object is connected to, or null if it is not connected to the stage.
DisplayObject
 Inheritedtouchable : Boolean
Indicates if this object (and its children) will receive touch events.
DisplayObject
  touchGroup : Boolean
If a container is a 'touchGroup', it will act as a single touchable object.
DisplayObjectContainer
 InheritedtransformationMatrix : Matrix
The transformation matrix of the object relative to its parent.
DisplayObject
 InheritedtransformationMatrix3D : Matrix3D
[read-only] The 3D transformation matrix of the object relative to its parent.
DisplayObject
 InheriteduseHandCursor : Boolean
Indicates if the mouse cursor should transform into a hand while it's over the sprite.
DisplayObject
 Inheritedvisible : Boolean
The visibility of the object.
DisplayObject
 Inheritedwidth : Number
The width of the object in pixels.
DisplayObject
 Inheritedx : Number
The x coordinate of the object relative to the local coordinates of the parent.
DisplayObject
 Inheritedy : Number
The y coordinate of the object relative to the local coordinates of the parent.
DisplayObject
Public Methods
 MethodDefined By
  
Adds a child to the container.
DisplayObjectContainer
  
Adds a child to the container at a certain index.
DisplayObjectContainer
 Inherited
addEventListener(type:String, listener:Function):void
[override] Registers an event listener at a certain object.
DisplayObject
 Inherited
alignPivot(horizontalAlign:String = center, verticalAlign:String = center):void
Moves the pivot point to a certain position within the local coordinate system of the object.
DisplayObject
  
broadcastEvent(event:Event):void
Dispatches an event on all children (recursively).
DisplayObjectContainer
  
broadcastEventWith(eventType:String, data:Object = null):void
Dispatches an event with the given parameters on all children (recursively).
DisplayObjectContainer
  
contains(child:DisplayObject):Boolean
Determines if a certain object is a child of the container (recursively).
DisplayObjectContainer
 Inherited
dispatchEvent(event:Event):void
Dispatches an event to all objects that have registered listeners for its type.
EventDispatcher
 Inherited
dispatchEventWith(type:String, bubbles:Boolean = false, data:Object = null):void
Dispatches an event with the given parameters to all objects that have registered listeners for the given type.
EventDispatcher
  
dispose():void
[override] Disposes the resources of all children.
DisplayObjectContainer
 Inherited
drawToBitmapData(out:BitmapData = null, color:uint = 0x0, alpha:Number = 0.0):BitmapData
Draws the object into a BitmapData object.
DisplayObject
  
getBounds(targetSpace:DisplayObject, out:Rectangle = null):Rectangle
[override] Returns a rectangle that completely encloses the object as it appears in another coordinate system.
DisplayObjectContainer
  
Returns a child object at a certain index.
DisplayObjectContainer
  
Returns a child object with a certain name (non-recursively).
DisplayObjectContainer
  
Returns the index of a child within the container, or "-1" if it is not found.
DisplayObjectContainer
 Inherited
getTransformationMatrix(targetSpace:DisplayObject, out:Matrix = null):Matrix
Creates a matrix that represents the transformation from the local coordinate system to another.
DisplayObject
 Inherited
getTransformationMatrix3D(targetSpace:DisplayObject, out:Matrix3D = null):Matrix3D
Creates a matrix that represents the transformation from the local coordinate system to another.
DisplayObject
 Inherited
globalToLocal(globalPoint:Point, out:Point = null):Point
Transforms a point from global (stage) coordinates to the local coordinate system.
DisplayObject
 Inherited
globalToLocal3D(globalPoint:Point, out:Vector3D = null):Vector3D
Transforms a point from global (stage) coordinates to the 3D local coordinate system.
DisplayObject
 Inherited
hasEventListener(type:String, listener:Function = null):Boolean
If called with one argument, figures out if there are any listeners registered for the given event type.
EventDispatcher
  
hitTest(localPoint:Point):DisplayObject
[override] Returns the object that is found topmost beneath a point in local coordinates, or nil if the test fails.
DisplayObjectContainer
 Inherited
hitTestMask(localPoint:Point):Boolean
Checks if a certain point is inside the display object's mask.
DisplayObject
 Inherited
local3DToGlobal(localPoint:Vector3D, out:Point = null):Point
Transforms a 3D point from the local coordinate system to global (stage) coordinates.
DisplayObject
 Inherited
localToGlobal(localPoint:Point, out:Point = null):Point
Transforms a point from the local coordinate system to global (stage) coordinates.
DisplayObject
  
removeChild(child:DisplayObject, dispose:Boolean = false):DisplayObject
Removes a child from the container.
DisplayObjectContainer
  
removeChildAt(index:int, dispose:Boolean = false):DisplayObject
Removes a child at a certain index.
DisplayObjectContainer
  
removeChildren(beginIndex:int = 0, endIndex:int = -1, dispose:Boolean = false):void
Removes a range of children from the container (endIndex included).
DisplayObjectContainer
 Inherited
removeEventListener(type:String, listener:Function):void
[override] Removes an event listener from the object.
DisplayObject
 Inherited
removeEventListeners(type:String = null):void
[override] Removes all event listeners with a certain type, or all of them if type is null.
DisplayObject
 Inherited
removeFromParent(dispose:Boolean = false):void
Removes the object from its parent, if it has one, and optionally disposes it.
DisplayObject
  
render(painter:Painter):void
[override] Renders the display object with the help of a painter object.
DisplayObjectContainer
  
setChildIndex(child:DisplayObject, index:int):void
Moves a child to a certain index.
DisplayObjectContainer
 Inherited
Forces the object to be redrawn in the next frame.
DisplayObject
  
sortChildren(compareFunction:Function):void
Sorts the children according to a given function (that works just like the sort function of the Vector class).
DisplayObjectContainer
  
Swaps the indexes of two children.
DisplayObjectContainer
  
swapChildrenAt(index1:int, index2:int):void
Swaps the indexes of two children.
DisplayObjectContainer
Events
 Event Summary Defined By
 InheritedDispatched when an object is added to a parent.DisplayObject
 InheritedDispatched when an object is connected to the stage (directly or indirectly).DisplayObject
 InheritedDispatched once every frame on every object that is connected to the stage.DisplayObject
 InheritedDispatched when a key on the keyboard is pressed.DisplayObject
 InheritedDispatched when a key on the keyboard is released.DisplayObject
 InheritedDispatched when an object is removed from its parent.DisplayObject
 InheritedDispatched when an object is removed from the stage and won't be rendered any longer.DisplayObject
 InheritedDispatched when an object is touched.DisplayObject
Property Detail
numChildrenproperty
numChildren:int  [read-only]

The number of children of this container.


Implementation
    public function get numChildren():int
touchGroupproperty 
touchGroup:Boolean

If a container is a 'touchGroup', it will act as a single touchable object. Touch events will have the container as target, not the touched child. (Similar to 'mouseChildren' in the classic display list, but with inverted logic.)

The default value is false.


Implementation
    public function get touchGroup():Boolean
    public function set touchGroup(value:Boolean):void
Method Detail
addChild()method
public function addChild(child:DisplayObject):DisplayObject

Adds a child to the container. It will be at the frontmost position.

Parameters

child:DisplayObject

Returns
DisplayObject
addChildAt()method 
public function addChildAt(child:DisplayObject, index:int):DisplayObject

Adds a child to the container at a certain index.

Parameters

child:DisplayObject
 
index:int

Returns
DisplayObject
broadcastEvent()method 
public function broadcastEvent(event:Event):void

Dispatches an event on all children (recursively). The event must not bubble.

Parameters

event:Event

broadcastEventWith()method 
public function broadcastEventWith(eventType:String, data:Object = null):void

Dispatches an event with the given parameters on all children (recursively). The method uses an internal pool of event objects to avoid allocations.

Parameters

eventType:String
 
data:Object (default = null)

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

Determines if a certain object is a child of the container (recursively).

Parameters

child:DisplayObject

Returns
Boolean
dispose()method 
override public function dispose():void

Disposes the resources of all children.

getBounds()method 
override public function getBounds(targetSpace:DisplayObject, out:Rectangle = null):Rectangle

Returns a rectangle that completely encloses the object as it appears in another coordinate system. If you pass an out-rectangle, the result will be stored in this rectangle instead of creating a new object.

Parameters

targetSpace:DisplayObject
 
out:Rectangle (default = null)

Returns
Rectangle
getChildAt()method 
public function getChildAt(index:int):DisplayObject

Returns a child object at a certain index. If you pass a negative index, '-1' will return the last child, '-2' the second to last child, etc.

Parameters

index:int

Returns
DisplayObject
getChildByName()method 
public function getChildByName(name:String):DisplayObject

Returns a child object with a certain name (non-recursively).

Parameters

name:String

Returns
DisplayObject
getChildIndex()method 
public function getChildIndex(child:DisplayObject):int

Returns the index of a child within the container, or "-1" if it is not found.

Parameters

child:DisplayObject

Returns
int
hitTest()method 
override public function hitTest(localPoint:Point):DisplayObject

Returns the object that is found topmost beneath a point in local coordinates, or nil if the test fails. Untouchable and invisible objects will cause the test to fail.

Parameters

localPoint:Point

Returns
DisplayObject
removeChild()method 
public function removeChild(child:DisplayObject, dispose:Boolean = false):DisplayObject

Removes a child from the container. If the object is not a child, the method returns null. If requested, the child will be disposed right away.

Parameters

child:DisplayObject
 
dispose:Boolean (default = false)

Returns
DisplayObject
removeChildAt()method 
public function removeChildAt(index:int, dispose:Boolean = false):DisplayObject

Removes a child at a certain index. The index positions of any display objects above the child are decreased by 1. If requested, the child will be disposed right away.

Parameters

index:int
 
dispose:Boolean (default = false)

Returns
DisplayObject
removeChildren()method 
public function removeChildren(beginIndex:int = 0, endIndex:int = -1, dispose:Boolean = false):void

Removes a range of children from the container (endIndex included). If no arguments are given, all children will be removed.

Parameters

beginIndex:int (default = 0)
 
endIndex:int (default = -1)
 
dispose:Boolean (default = false)

render()method 
override public function render(painter:Painter):void

Renders the display object with the help of a painter object. Never call this method directly, except from within another render method.

Parameters

painter:Painter — Captures the current render state and provides utility functions for rendering.

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

Moves a child to a certain index. Children at and after the replaced position move up.

Parameters

child:DisplayObject
 
index:int

sortChildren()method 
public function sortChildren(compareFunction:Function):void

Sorts the children according to a given function (that works just like the sort function of the Vector class).

Parameters

compareFunction:Function

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

Swaps the indexes of two children.

Parameters

child1:DisplayObject
 
child2:DisplayObject

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

Swaps the indexes of two children.

Parameters

index1:int
 
index2:int