GODPAPER | All Packages | All Classes | Index | Frames No Frames |
DisplayObjectContainer

Package | starling.display
Class | public class DisplayObjectContainer
Inheritance | DisplayObjectContainer DisplayObject EventDispatcher Object
Subclasses | Button, Sprite, 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.

- `Event.ADDED`: the object was added to a parent.
- `Event.ADDED_TO_STAGE`: the object was added to a parent that is connected to the stage, thus becoming visible now.
- `Event.REMOVED`: the object was removed from a parent.
- `Event.REMOVED_FROM_STAGE`: the object was removed from a parent that is connected to the stage, thus becoming invisible now.

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
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | alpha : Number The opacity of the object. | DisplayObject
|  | base : DisplayObject [read-only] The topmost object in the display tree the object is part of. | DisplayObject
|  | blendMode : String The blend mode determines how the object is blended with the objects underneath. | DisplayObject
|  | bounds : Rectangle [read-only] The bounds of the object relative to the local coordinates of the parent. | DisplayObject
|  | filter : FragmentFilter The filter that is attached to the display object. | DisplayObject
|  | hasVisibleArea : Boolean [read-only] Indicates if an object occupies any visible area. | DisplayObject
|  | height : Number The height of the object in pixels. | DisplayObject
|  | name : String The name of the display object (default: null). | DisplayObject
|  | numChildren : int [read-only] The number of children of this container. | DisplayObjectContainer
|  | parent : DisplayObjectContainer [read-only] The display object container that contains this display object. | DisplayObject
|  | pivotX : Number The x coordinate of the object's origin in its own coordinate space (default: 0). | DisplayObject
|  | pivotY : Number The y coordinate of the object's origin in its own coordinate space (default: 0). | DisplayObject
|  | root : DisplayObject [read-only] The root object the display object is connected to (i.e. | DisplayObject
|  | rotation : Number The rotation of the object in radians. | DisplayObject
|  | scaleX : Number The horizontal scale factor. | DisplayObject
|  | scaleY : Number The vertical scale factor. | DisplayObject
|  | skewX : Number The horizontal skew angle in radians. | DisplayObject
|  | skewY : Number The vertical skew angle in radians. | DisplayObject
|  | stage : Stage [read-only] The stage the display object is connected to, or null if it is not connected to the stage. | DisplayObject
|  | touchable : Boolean Indicates if this object (and its children) will receive touch events. | DisplayObject
|  | transformationMatrix : Matrix The transformation matrix of the object relative to its parent. | DisplayObject
|  | useHandCursor : Boolean Indicates if the mouse cursor should transform into a hand while it's over the sprite. | DisplayObject
|  | visible : Boolean The visibility of the object. | DisplayObject
|  | width : Number The width of the object in pixels. | DisplayObject
|  | x : Number The x coordinate of the object relative to the local coordinates of the parent. | DisplayObject
|  | y : Number The y coordinate of the object relative to the local coordinates of the parent. | DisplayObject

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | addChild(child:DisplayObject):DisplayObject Adds a child to the container. | DisplayObjectContainer
|  | addChildAt(child:DisplayObject, index:int):DisplayObject Adds a child to the container at a certain index. | DisplayObjectContainer
|  | addEventListener(type:String, listener:Function):void [override] | DisplayObject
|  | alignPivot(hAlign:String = center, vAlign: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(type: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
|  | dispatchEvent(event:Event):void Dispatches an event to all objects that have registered listeners for its type. | EventDispatcher
|  | 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
|  | getBounds(targetSpace:DisplayObject, resultRect:Rectangle = null):Rectangle [override] Returns a rectangle that completely encloses the object as it appears in another coordinate system. | DisplayObjectContainer
|  | getChildAt(index:int):DisplayObject Returns a child object at a certain index. | DisplayObjectContainer
|  | getChildByName(name:String):DisplayObject Returns a child object with a certain name (non-recursively). | DisplayObjectContainer
|  | getChildIndex(child:DisplayObject):int Returns the index of a child within the container, or "-1" if it is not found. | DisplayObjectContainer
|  | getTransformationMatrix(targetSpace:DisplayObject, resultMatrix:Matrix = null):Matrix Creates a matrix that represents the transformation from the local coordinate system to another. | DisplayObject
|  | globalToLocal(globalPoint:Point, resultPoint:Point = null):Point Transforms a point from global (stage) coordinates to the local coordinate system. | DisplayObject
|  | hasEventListener(type:String):Boolean Returns if there are listeners registered for a certain event type. | EventDispatcher
|  | hitTest(localPoint:Point, forTouch:Boolean = false):DisplayObject [override] Returns the object that is found topmost beneath a point in local coordinates, or nil if the test fails. | DisplayObjectContainer
|  | localToGlobal(localPoint:Point, resultPoint: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
|  | removeEventListener(type:String, listener:Function):void [override] | DisplayObject
|  | removeEventListeners(type:String = null):void [override] | DisplayObject
|  | removeFromParent(dispose:Boolean = false):void Removes the object from its parent, if it has one, and optionally disposes it. | DisplayObject
|  | render(support:RenderSupport, parentAlpha:Number):void [override] Renders the display object with the help of a support object. | DisplayObjectContainer
|  | setChildIndex(child:DisplayObject, index:int):void Moves a child to a certain index. | DisplayObjectContainer
|  | sortChildren(compareFunction:Function):void Sorts the children according to a given function (that works just like the sort function of the Vector class). | DisplayObjectContainer
|  | swapChildren(child1:DisplayObject, child2:DisplayObject):void Swaps the indexes of two children. | DisplayObjectContainer
|  | swapChildrenAt(index1:int, index2:int):void Swaps the indexes of two children. | DisplayObjectContainer

Events
Hide Inherited Events
Show Inherited Events

| Event | Summary | Defined By
--- | --- | --- | ---
|  | added | Dispatched when an object is added to a parent. | DisplayObject
|  | addedToStage | Dispatched when an object is connected to the stage (directly or indirectly). | DisplayObject
|  | enterFrame | Dispatched once every frame on every object that is connected to the stage. | DisplayObject
|  | keyDown | Dispatched when a key on the keyboard is pressed. | DisplayObject
|  | keyUp | Dispatched when a key on the keyboard is released. | DisplayObject
|  | removed | Dispatched when an object is removed from its parent. | DisplayObject
|  | removedFromStage | Dispatched when an object is removed from the stage and won't be rendered any longer. | DisplayObject
|  | touch | Dispatched when an object is touched. | DisplayObject

Property Detail

numChildren | property

`numChildren:int` [read-only]

The number of children of this container.

Implementation
`public function get numChildren():int`
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(type: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

| `type: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, resultRect:Rectangle = null):Rectangle`

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

Parameters

| `targetSpace:DisplayObject`
| `resultRect:Rectangle` (default = `null`)``

Returns

| `Rectangle`

getChildAt | () | method |

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

Returns a child object at a certain index.

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, forTouch:Boolean = false):DisplayObject`

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

Parameters

| `localPoint:Point`
| `forTouch:Boolean` (default = `false`)``

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, nothing happens. 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. Children above the child will move down. 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(support:RenderSupport, parentAlpha:Number):void`

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

Parameters

| `support:RenderSupport` — Provides utility functions for rendering.
| `parentAlpha:Number` — The accumulated alpha value from the object's parent up to the stage.

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`

Thu Jan 16 2014, 01:11 PM +08:00