Added maxSize, jsdocs and ts def fixes

Author: photonstorm

src/gameobjects/container/Container.js

@@ -18,6 +18,36 @@ var Vector2 = require('../../math/Vector2');
  * @classdesc
  * A Container Game Object.
  *
+ * A Container, as the name implies, can 'contain' other types of Game Object.
+ * When a Game Object is added to a Container, the Container becomes responsible for the rendering of it.
+ * By default it will be removed from the Display List and instead added to the Containers own internal list.
+ *
+ * The position of the Game Object automatically becomes relative to the position of the Container.
+ * 
+ * When the Container is rendered, all of its children are rendered as well, in the order in which they exist
+ * within the Container. Container children can be repositioned using methods such as `MoveUp`, `MoveDown` and `SendToBack`.
+ *
+ * If you modify a transform property of the Container, such as `Container.x` or `Container.rotation` then it will
+ * automatically influence all children as well.
+ *
+ * Containers can include other Containers for deeply nested transforms.
+ *
+ * Containers can have masks set on them and can be used as a mask too. However, Container children cannot be masked.
+ * The masks do not 'stack up'. Only a Container on the root of the display list will use its mask.
+ *
+ * Containers can be enabled for input. Because they do not have a texture you need to provide a shape for them
+ * to use as their hit area. Container children can also be enabled for input, independent of the Container.
+ *
+ * Containers can be given a physics body for either Arcade Physics, Impact Physics or Matter Physics. However,
+ * if Container children are enabled for physics you may get unexpected results,such as offset bodies,
+ * if the Container itself, or any of its ancestors, is positioned anywhere other than at 0x0.
+ *
+ * It's important to understand the impact of using Containers. They add additional processing overhead into
+ * every one of their children. The deeper you nest them, the more the cost escalates. This is especially true
+ * for input events. You also loose the ability to set the display depth of Container children in the same
+ * flexible manner as those not within them. In short, don't use them for the sake of it. You pay a small cost
+ * every time you create one, try to structure your game around avoiding that where possible.
+ *
  * @class Container
  * @extends Phaser.GameObjects.GameObject
  * @memberOf Phaser.GameObjects
@@ -87,6 +117,18 @@ var Container = new Class({
          */
         this.exclusive = true;
 
+        /**
+         * Containers can have an optional maximum size. If set to anything above 0 it
+         * will constrict the addition of new Game Objects into the Container, capping off
+         * the maximum limit the Container can grow in size to.
+         *
+         * @name Phaser.GameObjects.Container#maxSize
+         * @type {integer}
+         * @default -1
+         * @since 3.4.0
+         */
+        this.maxSize = -1;
+
         /**
          * The cursor position.
          *
@@ -336,71 +378,66 @@ var Container = new Class({
      * @method Phaser.GameObjects.Container#add
      * @since 3.4.0
      *
-     * @genericUse {T} - [child,$return]
-     *
-     * @param {*|Array.<*>} child - The item, or array of items, to add to the array. Each item must be unique within the array.
+     * @param {Phaser.GameObjects.GameObject|Phaser.GameObjects.GameObject[]} child - The Game Object, or array of Game Objects, to add to the Container.
      *
      * @return {Phaser.GameObjects.Container} This Container instance.
      */
     add: function (child)
     {
-        ArrayUtils.Add(this.list, child, 0, this.addHandler, this);
+        ArrayUtils.Add(this.list, child, this.maxSize, this.addHandler, this);
 
         return this;
     },
 
     /**
-     * [description]
+     * Adds the given Game Object, or array of Game Objects, to this Container at the specified position.
+     * 
+     * Existing Game Objects in the Container are shifted up.
+     * 
+     * Each Game Object must be unique within the Container.
      *
      * @method Phaser.GameObjects.Container#addAt
      * @since 3.4.0
      *
-     * @genericUse {T} - [child,$return]
-     *
-     * @param {*} child - [description]
-     * @param {integer} [index=0] - [description]
+     * @param {Phaser.GameObjects.GameObject|Phaser.GameObjects.GameObject[]} child - The Game Object, or array of Game Objects, to add to the Container.
+     * @param {integer} [index=0] - The position to insert the Game Object/s at.
      *
      * @return {Phaser.GameObjects.Container} This Container instance.
      */
     addAt: function (child, index)
     {
-        ArrayUtils.AddAt(this.list, child, index, 0, this.addHandler, this);
+        ArrayUtils.AddAt(this.list, child, index, this.maxSize, this.addHandler, this);
 
         return this;
     },
 
     /**
-     * [description]
+     * Returns the Game Object at the given position in this Container.
      *
      * @method Phaser.GameObjects.Container#getAt
      * @since 3.4.0
      *
-     * @genericUse {T} - [$return]
-     *
-     * @param {integer} index - [description]
+     * @param {integer} index - The position to get the Game Object from.
      *
-     * @return {Phaser.GameObjects.GameObject|null} The Game Object at the specified index, or `null` if none found.
+     * @return {?Phaser.GameObjects.GameObject} The Game Object at the specified index, or `null` if none found.
      */
     getAt: function (index)
     {
         return this.list[index];
     },
 
     /**
-     * [description]
+     * Returns the index of the given Game Object in this Container.
      *
      * @method Phaser.GameObjects.Container#getIndex
      * @since 3.4.0
      *
-     * @genericUse {T} - [child]
-     *
      * @param {Phaser.GameObjects.GameObject} child - The Game Object to search for in this Container.
      *
      * @return {integer} The index of the Game Object in this Container, or -1 if not found.
      */
     getIndex: function (child)
     {
-        //  Return -1 if given child isn't a child of this display list
         return this.list.indexOf(child);
     },
 
@@ -411,8 +448,6 @@ var Container = new Class({
      * @method Phaser.GameObjects.Container#sort
      * @since 3.4.0
      *
-     * @genericUse {T[]} - [children,$return]
-     *
      * @param {string} property - The property to lexically sort by.
      *
      * @return {Phaser.GameObjects.Container} This Container instance.
@@ -436,8 +471,6 @@ var Container = new Class({
      * @private
      * @since 3.4.0
      *
-     * @genericUse {T} - [childA,childB]
-     *
      * @param {Phaser.GameObjects.GameObject} childA - The first child to sort.
      * @param {Phaser.GameObjects.GameObject} childB - The second child to sort.
      *
@@ -455,8 +488,6 @@ var Container = new Class({
      * @method Phaser.GameObjects.Container#getByName
      * @since 3.4.0
      *
-     * @genericUse {T | null} - [$return]
-     *
      * @param {string} name - The name to search for.
      *
      * @return {?Phaser.GameObjects.GameObject} The first child with a matching name, or `null` if none were found.
@@ -472,8 +503,6 @@ var Container = new Class({
      * @method Phaser.GameObjects.Container#getRandom
      * @since 3.4.0
      *
-     * @genericUse {T | null} - [$return]
-     *
      * @param {integer} [startIndex=0] - An optional start index.
      * @param {integer} [length] - An optional length, the total number of elements (from the startIndex) to choose from.
      *
@@ -528,7 +557,7 @@ var Container = new Class({
      * @since 3.4.0
      *
      * @param {string} [property] - The property to test on each Game Object in the Container.
-     * @param {*} [value] - If property is set then the `property` must strictly equal this value to be included in the results.
+     * @param {any} [value] - If property is set then the `property` must strictly equal this value to be included in the results.
      * @param {integer} [startIndex=0] - An optional start index to search from.
      * @param {integer} [endIndex=Container.length] - An optional end index to search up to (but not included)
      *
@@ -551,7 +580,7 @@ var Container = new Class({
      * @since 3.4.0
      *
      * @param {string} property - [description]
-     * @param {*} value - [description]
+     * @param {any} value - [description]
      * @param {integer} [startIndex=0] - An optional start index to search from.
      * @param {integer} [endIndex=Container.length] - An optional end index to search up to (but not included)
      *
@@ -569,8 +598,6 @@ var Container = new Class({
      * @method Phaser.GameObjects.Container#swap
      * @since 3.4.0
      *
-     * @genericUse {T} - [child1,child2]
-     *
      * @param {Phaser.GameObjects.GameObject} child1 - The first Game Object to swap.
      * @param {Phaser.GameObjects.GameObject} child2 - The second Game Object to swap.
      * 
@@ -594,8 +621,6 @@ var Container = new Class({
      * @method Phaser.GameObjects.Container#moveTo
      * @since 3.4.0
      *
-     * @genericUse {T} - [child,$return]
-     *
      * @param {Phaser.GameObjects.GameObject} child - The Game Object to move.
      * @param {integer} index - The new position of the Game Object in this Container.
      *
@@ -618,8 +643,6 @@ var Container = new Class({
      * @method Phaser.GameObjects.Container#remove
      * @since 3.4.0
      *
-     * @genericUse {T} - [child,$return]
-     *
      * @param {Phaser.GameObjects.GameObject|Phaser.GameObjects.GameObject[]} child - The Game Object, or array of Game Objects, to be removed from the Container.
      * @param {boolean} [destroyChild=false] - Optionally call `destroy` on each child successfully removed from this Container.
      *
@@ -653,8 +676,6 @@ var Container = new Class({
      * @method Phaser.GameObjects.Container#removeAt
      * @since 3.4.0
      *
-     * @genericUse {T} - [$return]
-     *
      * @param {integer} index - The index of the Game Object to be removed.
      * @param {boolean} [destroyChild=false] - Optionally call `destroy` on the Game Object if successfully removed from this Container.
      *
@@ -680,8 +701,6 @@ var Container = new Class({
      * @method Phaser.GameObjects.Container#removeBetween
      * @since 3.4.0
      *
-     * @genericUse {T[]} - [$return]
-     *
      * @param {integer} [startIndex=0] - An optional start index to search from.
      * @param {integer} [endIndex=Container.length] - An optional end index to search up to (but not included)
      * @param {boolean} [destroyChild=false] - Optionally call `destroy` on each Game Object successfully removed from this Container.
@@ -711,8 +730,6 @@ var Container = new Class({
      * @method Phaser.GameObjects.Container#removeAll
      * @since 3.4.0
      *
-     * @genericUse {Phaser.GameObjects.Container.<T>} - [$return]
-     * 
      * @param {boolean} [destroyChild=false] - Optionally call `destroy` on each Game Object successfully removed from this Container.
      *
      * @return {Phaser.GameObjects.Container} This Container instance.
@@ -739,8 +756,6 @@ var Container = new Class({
      * @method Phaser.GameObjects.Container#bringToTop
      * @since 3.4.0
      *
-     * @genericUse {T} - [child,$return]
-     *
      * @param {Phaser.GameObjects.GameObject} child - The Game Object to bring to the top of the Container.
      *
      * @return {Phaser.GameObjects.Container} This Container instance.
@@ -759,8 +774,6 @@ var Container = new Class({
      * @method Phaser.GameObjects.Container#sendToBack
      * @since 3.4.0
      *
-     * @genericUse {T} - [child,$return]
-     *
      * @param {Phaser.GameObjects.GameObject} child - The Game Object to send to the bottom of the Container.
      *
      * @return {Phaser.GameObjects.Container} This Container instance.
@@ -778,8 +791,6 @@ var Container = new Class({
      * @method Phaser.GameObjects.Container#moveUp
      * @since 3.4.0
      *
-     * @genericUse {T} - [child,$return]
-     *
      * @param {Phaser.GameObjects.GameObject} child - The Game Object to be moved in the Container.
      *
      * @return {Phaser.GameObjects.Container} This Container instance.
@@ -797,8 +808,6 @@ var Container = new Class({
      * @method Phaser.GameObjects.Container#moveDown
      * @since 3.4.0
      *
-     * @genericUse {T} - [child,$return]
-     *
      * @param {Phaser.GameObjects.GameObject} child - The Game Object to be moved in the Container.
      *
      * @return {Phaser.GameObjects.Container} This Container instance.
@@ -816,8 +825,6 @@ var Container = new Class({
      * @method Phaser.GameObjects.Container#reverse
      * @since 3.4.0
      *
-     * @genericUse {Phaser.GameObjects.Container.<T>} - [$return]
-     *
      * @return {Phaser.GameObjects.Container} This Container instance.
      */
     reverse: function ()
@@ -833,8 +840,6 @@ var Container = new Class({
      * @method Phaser.GameObjects.Container#shuffle
      * @since 3.4.0
      *
-     * @genericUse {Phaser.GameObjects.Container.<T>} - [$return]
-     *
      * @return {Phaser.GameObjects.Container} This Container instance.
      */
     shuffle: function ()
@@ -851,8 +856,6 @@ var Container = new Class({
      * @method Phaser.GameObjects.Container#replace
      * @since 3.4.0
      *
-     * @genericUse {T} - [oldChild,newChild,$return]
-     *
      * @param {Phaser.GameObjects.GameObject} oldChild - The Game Object in this Container that will be replaced.
      * @param {Phaser.GameObjects.GameObject} newChild - The Game Object to be added to this Container.
      * @param {boolean} [destroyChild=false] - Optionally call `destroy` on the Game Object if successfully removed from this Container.
@@ -885,8 +888,6 @@ var Container = new Class({
      * @method Phaser.GameObjects.Container#exists
      * @since 3.4.0
      *
-     * @genericUse {T} - [child]
-     *
      * @param {Phaser.GameObjects.GameObject} child - The Game Object to check for within this Container.
      *
      * @return {boolean} True if the Game Object is an immediate child of this Container, otherwise false.
@@ -906,10 +907,8 @@ var Container = new Class({
      * @method Phaser.GameObjects.Container#setAll
      * @since 3.4.0
      *
-     * @genericUse {T} - [value]
-     *
      * @param {string} property - The property that must exist on the Game Object.
-     * @param {*} value - The value to get the property to.
+     * @param {any} value - The value to get the property to.
      * @param {integer} [startIndex=0] - An optional start index to search from.
      * @param {integer} [endIndex=Container.length] - An optional end index to search up to (but not included)
      * 
@@ -922,6 +921,14 @@ var Container = new Class({
         return this;
     },
 
+    /**
+     * @callback EachContainerCallback
+     * @generic I - [item]
+     *
+     * @param {*} item - [description]
+     * @param {...*} [args] - Additional arguments that will be passed to the callback, after the child.
+     */
+
     /**
      * Passes all Game Objects in this Container to the given callback.
      *
@@ -934,10 +941,8 @@ var Container = new Class({
      * @method Phaser.GameObjects.Container#each
      * @since 3.4.0
      *
-     * @genericUse {EachListCallback.<T>} - [callback]
-     *
-     * @param {EachListCallback} callback - The function to call.
-     * @param {*} [context] - Value to use as `this` when executing callback.
+     * @param {function} callback - The function to call.
+     * @param {object} [context] - Value to use as `this` when executing callback.
      * @param {...*} [args] - Additional arguments that will be passed to the callback, after the child.
      * 
      * @return {Phaser.GameObjects.Container} This Container instance.
@@ -973,10 +978,8 @@ var Container = new Class({
      * @method Phaser.GameObjects.Container#iterate
      * @since 3.4.0
      *
-     * @genericUse {EachListCallback.<T>} - [callback]
-     *
-     * @param {EachListCallback} callback - The function to call.
-     * @param {*} [context] - Value to use as `this` when executing callback.
+     * @param {function} callback - The function to call.
+     * @param {object} [context] - Value to use as `this` when executing callback.
      * @param {...*} [args] - Additional arguments that will be passed to the callback, after the child.
      * 
      * @return {Phaser.GameObjects.Container} This Container instance.