class flash.display.DisplayObjectContainer extends InteractiveObject
Available on all platforms
Sub classes | ||||||||
![]() | Loader, Sprite, Stage |
|
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.new DisplayObjectContainer()
constructor throws an
* ArgumentError
exception.
*
For more information, see the "Display Programming" chapter of the * ActionScript 3.0 Developer's Guide.
Instance Fields
var mouseChildren:Bool
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
* 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 true
.
* 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.
var tabChildren:Bool
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.
function addChild(child:DisplayObject):DisplayObject
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 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. addChildAt()
method.)
*
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.
child | The DisplayObject instance to add as a child of this DisplayObjectContainer instance. |
returns | The DisplayObject instance that you pass in the |
function addChildAt(child:DisplayObject, index:Int):DisplayObject
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.
* * @event added Dispatched when a display object is added to the display * list.child | The DisplayObject instance to add as a child of this DisplayObjectContainer instance. |
index | 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 | The DisplayObject instance that you pass in the |
function areInaccessibleObjectsUnderPoint(point:Point):Bool
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: <a href="http://www.adobe.com/go/devnetsecurityen"
* scope="external">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.
point | The point under which to look. * |
returns | true if the point contains child display objects with
* security restrictions. |
function contains(child:DisplayObject):Bool
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
.
*
*
child | The child object to test. * |
returns | true if the child object is a child of
* the DisplayObjectContainer or the container itself; otherwise
* false . |
function getChildAt(index:Int):DisplayObject
Returns the child display object instance that exists at the specified * index. * *
index | The index position of the child object. * |
returns | The child display object at the specified index position. * |
function getChildByName(name:String):DisplayObject
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.
name | The name of the child to return. * |
returns | The child display object with the specified name. * |
function getChildIndex(child:DisplayObject):Int
Returns the index position of a child
DisplayObject instance.
*
*
child | The DisplayObject instance to identify. * |
returns | The index position of the child display object to identify. * |
function getObjectsUnderPoint(point:Point):Array<DisplayObject>
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.
point | The point under which to look. * |
returns | An array of objects that lie under the specified point and are children(or grandchildren, and so on) of this DisplayObjectContainer instance. |
function removeChild(child:DisplayObject):DisplayObject
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.
* *child | The DisplayObject instance to remove. * |
returns | The DisplayObject instance that you pass in the |
function removeChildAt(index:Int):DisplayObject
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.
* *index | The child index of the DisplayObject to remove. * |
returns | The DisplayObject instance that was removed. * |
function setChildIndex(child:DisplayObject, index:Int):Void
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:
This code results in the following arrangement of objects:
* *child | The child DisplayObject instance for which you want to change the index number. |
index | The resulting index number for the |
function swapChildren(child1:DisplayObject, child2:DisplayObject):Void
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. * *
child1 | The first child object. * |
child2 | The second child object. * |
function 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. All other child objects in * the display object container remain in the same index positions. * *
index1 | The index position of the first child object. * |
index2 | The index position of the second child object. * |