From 0e14b43623cd8dcbf187a06e1dde90844683c0dd Mon Sep 17 00:00:00 2001 From: Richard Davey Date: Wed, 11 Apr 2018 16:58:48 +0100 Subject: [PATCH] Added `maxSize`, jsdocs and ts def fixes --- src/gameobjects/container/Container.js | 139 +++++++++++++------------ 1 file changed, 71 insertions(+), 68 deletions(-) diff --git a/src/gameobjects/container/Container.js b/src/gameobjects/container/Container.js index 5d8dd2b07..d4177169e 100644 --- a/src/gameobjects/container/Container.js +++ b/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,50 +378,48 @@ 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 - The position to get the Game Object from. * - * @param {integer} index - [description] - * - * @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) { @@ -387,20 +427,17 @@ var Container = new Class({ }, /** - * [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.} - [$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.} - [$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.} - [$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.} - [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.} - [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.