#

API Docs for: 1.6.0
Show: Inherited Protected Private Deprecated

# File: src/pixi/display/DisplayObjectContainer.js

    /**
     * @author Mat Groves http://matgroves.com/ @Doormat23
     */

    /**
     * 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.
     *
     * @class DisplayObjectContainer
     * @extends DisplayObject
     * @constructor
     */
    PIXI.DisplayObjectContainer = function()
    {
        PIXI.DisplayObject.call( this );

        /**
         * [read-only] The array of children of this container.
         *
         * @property children
         * @type Array<DisplayObject>
         * @readOnly
         */
        this.children = [];
    };

    // constructor
    PIXI.DisplayObjectContainer.prototype = Object.create( PIXI.DisplayObject.prototype );
    PIXI.DisplayObjectContainer.prototype.constructor = PIXI.DisplayObjectContainer;

    /**
     * The width of the displayObjectContainer, setting this will actually modify the scale to achieve the value set
     *
     * @property width
     * @type Number
     */

    Object.defineProperty(PIXI.DisplayObjectContainer.prototype, 'width', {
        get: function() {
            return this.scale.x * this.getLocalBounds().width;
        },
        set: function(value) {
            this.scale.x = value / (this.getLocalBounds().width/this.scale.x);
            this._width = value;
        }
    });

    /**
     * The height of the displayObjectContainer, setting this will actually modify the scale to achieve the value set
     *
     * @property height
     * @type Number
     */

    Object.defineProperty(PIXI.DisplayObjectContainer.prototype, 'height', {
        get: function() {
            return  this.scale.y * this.getLocalBounds().height;
        },
        set: function(value) {
            this.scale.y = value / (this.getLocalBounds().height/this.scale.y);
            this._height = value;
        }
    });

    /**
     * Adds a child to the container.
     *
     * @method addChild
     * @param child {DisplayObject} The DisplayObject to add to the container
     */
    PIXI.DisplayObjectContainer.prototype.addChild = function(child)
    {
        return this.addChildAt(child, this.children.length);
    };

    /**
     * Adds a child to the container at a specified index. If the index is out of bounds an error will be thrown
     *
     * @method addChildAt
     * @param child {DisplayObject} The child to add
     * @param index {Number} The index to place the child in
     */
    PIXI.DisplayObjectContainer.prototype.addChildAt = function(child, index)
    {
        if(index >= 0 && index <= this.children.length)
        {
            if(child.parent)
            {
                child.parent.removeChild(child);
            }

            child.parent = this;

            this.children.splice(index, 0, child);

            if(this.stage)child.setStageReference(this.stage);

            return child;
        }
        else
        {
            throw new Error(child + ' The index '+ index +' supplied is out of bounds ' + this.children.length);
        }
    };

    /**
     * [NYI] Swaps the depth of 2 displayObjects
     *
     * @method swapChildren
     * @param child {DisplayObject}
     * @param child2 {DisplayObject}
     * @private
     */
    PIXI.DisplayObjectContainer.prototype.swapChildren = function(child, child2)
    {
        if(child === child2) {
            return;
        }

        var index1 = this.children.indexOf(child);
        var index2 = this.children.indexOf(child2);

        if(index1 < 0 || index2 < 0) {
            throw new Error('swapChildren: Both the supplied DisplayObjects must be a child of the caller.');
        }

        this.children[index1] = child2;
        this.children[index2] = child;

    };

    /**
     * Returns the child at the specified index
     *
     * @method getChildAt
     * @param index {Number} The index to get the child from
     */
    PIXI.DisplayObjectContainer.prototype.getChildAt = function(index)
    {
        if(index >= 0 && index < this.children.length)
        {
            return this.children[index];
        }
        else
        {
            throw new Error('Supplied index does not exist in the child list, or the supplied DisplayObject must be a child of the caller');
        }
    };

    /**
     * Removes a child from the container.
     *
     * @method removeChild
     * @param child {DisplayObject} The DisplayObject to remove
     */
    PIXI.DisplayObjectContainer.prototype.removeChild = function(child)
    {
        return this.removeChildAt( this.children.indexOf( child ) );
    };

    /**
     * Removes a child from the specified index position in the child list of the container.
     *
     * @method removeChildAt
     * @param index {Number} The index to get the child from
     */
    PIXI.DisplayObjectContainer.prototype.removeChildAt = function(index)
    {
        var child = this.getChildAt( index );
        if(this.stage)
            child.removeStageReference();

        child.parent = undefined;
        this.children.splice( index, 1 );
        return child;
    };

    /**
    * Removes all child instances from the child list of the container.
    *
    * @method removeChildren
    * @param beginIndex {Number} The beginning position. Predefined value is 0.
    * @param endIndex {Number} The ending position. Predefined value is children's array length.
    */
    PIXI.DisplayObjectContainer.prototype.removeChildren = function(beginIndex, endIndex)
    {
        var begin = beginIndex || 0;
        var end = typeof endIndex === 'number' ? endIndex : this.children.length;
        var range = end - begin;

        if (range > 0 && range <= end)
        {
            var removed = this.children.splice(begin, range);
            for (var i = 0; i < removed.length; i++) {
                var child = removed[i];
                if(this.stage)
                    child.removeStageReference();
                child.parent = undefined;
            }
            return removed;
        }
        else
        {
            throw new Error( 'Range Error, numeric values are outside the acceptable range' );
        }
    };

    /*
     * Updates the container's childrens transform for rendering
     *
     * @method updateTransform
     * @private
     */
    PIXI.DisplayObjectContainer.prototype.updateTransform = function()
    {
        //this._currentBounds = null;

        if(!this.visible)return;

        PIXI.DisplayObject.prototype.updateTransform.call( this );

        if(this._cacheAsBitmap)return;

        for(var i=0,j=this.children.length; i<j; i++)
        {
            this.children[i].updateTransform();
        }
    };

    /**
     * Retrieves the bounds of the displayObjectContainer as a rectangle object
     *
     * @method getBounds
     * @return {Rectangle} the rectangular bounding area
     */
    PIXI.DisplayObjectContainer.prototype.getBounds = function(matrix)
    {
        if(this.children.length === 0)return PIXI.EmptyRectangle;

        // TODO the bounds have already been calculated this render session so return what we have
        if(matrix)
        {
            var matrixCache = this.worldTransform;
            this.worldTransform = matrix;
            this.updateTransform();
            this.worldTransform = matrixCache;
        }

        var minX = Infinity;
        var minY = Infinity;

        var maxX = -Infinity;
        var maxY = -Infinity;

        var childBounds;
        var childMaxX;
        var childMaxY;

        var childVisible = false;

        for(var i=0,j=this.children.length; i<j; i++)
        {
            var child = this.children[i];

            if(!child.visible)continue;

            childVisible = true;

            childBounds = this.children[i].getBounds( matrix );

            minX = minX < childBounds.x ? minX : childBounds.x;
            minY = minY < childBounds.y ? minY : childBounds.y;

            childMaxX = childBounds.width + childBounds.x;
            childMaxY = childBounds.height + childBounds.y;

            maxX = maxX > childMaxX ? maxX : childMaxX;
            maxY = maxY > childMaxY ? maxY : childMaxY;
        }

        if(!childVisible)
            return PIXI.EmptyRectangle;

        var bounds = this._bounds;

        bounds.x = minX;
        bounds.y = minY;
        bounds.width = maxX - minX;
        bounds.height = maxY - minY;

        // TODO: store a reference so that if this function gets called again in the render cycle we do not have to recalculate
        //this._currentBounds = bounds;

        return bounds;
    };

    PIXI.DisplayObjectContainer.prototype.getLocalBounds = function()
    {
        var matrixCache = this.worldTransform;

        this.worldTransform = PIXI.identityMatrix;

        for(var i=0,j=this.children.length; i<j; i++)
        {
            this.children[i].updateTransform();
        }

        var bounds = this.getBounds();

        this.worldTransform = matrixCache;

        return bounds;
    };

    /**
     * Sets the container's stage reference, the stage this object is connected to
     *
     * @method setStageReference
     * @param stage {Stage} the stage that the container will have as its current stage reference
     */
    PIXI.DisplayObjectContainer.prototype.setStageReference = function(stage)
    {
        this.stage = stage;
        if(this._interactive)this.stage.dirty = true;

        for(var i=0,j=this.children.length; i<j; i++)
        {
            var child = this.children[i];
            child.setStageReference(stage);
        }
    };

    /**
     * removes the current stage reference of the container
     *
     * @method removeStageReference
     */
    PIXI.DisplayObjectContainer.prototype.removeStageReference = function()
    {

        for(var i=0,j=this.children.length; i<j; i++)
        {
            var child = this.children[i];
            child.removeStageReference();
        }

        if(this._interactive)this.stage.dirty = true;

        this.stage = null;
    };

    /**
    * Renders the object using the WebGL renderer
    *
    * @method _renderWebGL
    * @param renderSession {RenderSession}
    * @private
    */
    PIXI.DisplayObjectContainer.prototype._renderWebGL = function(renderSession)
    {
        if(!this.visible || this.alpha <= 0)return;

        if(this._cacheAsBitmap)
        {
            this._renderCachedSprite(renderSession);
            return;
        }

        var i,j;

        if(this._mask || this._filters)
        {

            // push filter first as we need to ensure the stencil buffer is correct for any masking
            if(this._filters)
            {
                renderSession.spriteBatch.flush();
                renderSession.filterManager.pushFilter(this._filterBlock);
            }

            if(this._mask)
            {
                renderSession.spriteBatch.stop();
                renderSession.maskManager.pushMask(this.mask, renderSession);
                renderSession.spriteBatch.start();
            }

            // simple render children!
            for(i=0,j=this.children.length; i<j; i++)
            {
                this.children[i]._renderWebGL(renderSession);
            }

            renderSession.spriteBatch.stop();

            if(this._mask)renderSession.maskManager.popMask(this._mask, renderSession);
            if(this._filters)renderSession.filterManager.popFilter();

            renderSession.spriteBatch.start();
        }
        else
        {
            // simple render children!
            for(i=0,j=this.children.length; i<j; i++)
            {
                this.children[i]._renderWebGL(renderSession);
            }
        }
    };

    /**
    * Renders the object using the Canvas renderer
    *
    * @method _renderCanvas
    * @param renderSession {RenderSession}
    * @private
    */
    PIXI.DisplayObjectContainer.prototype._renderCanvas = function(renderSession)
    {
        if(this.visible === false || this.alpha === 0)return;

        if(this._cacheAsBitmap)
        {

            this._renderCachedSprite(renderSession);
            return;
        }

        if(this._mask)
        {
            renderSession.maskManager.pushMask(this._mask, renderSession.context);
        }

        for(var i=0,j=this.children.length; i<j; i++)
        {
            var child = this.children[i];
            child._renderCanvas(renderSession);
        }

        if(this._mask)
        {
            renderSession.maskManager.popMask(renderSession.context);
        }
    };