Skip to content

Commit 82325ec

Browse files
photonstormphotonstorm
committed
Finished Group documentation.
1 parent e5b1faa commit 82325ec

1 file changed

Lines changed: 84 additions & 78 deletions

File tree

‎src/core/Group.js‎

Lines changed: 84 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,9 @@
1010
* @classdesc A Group is a container for display objects that allows for fast pooling, recycling and collision checks.
1111
* @constructor
1212
* @param {Phaser.Game} game - A reference to the currently running game.
13-
* @param {Description} parent - Description.
14-
* @param {string} name - The unique name for this animation, used in playback commands.
15-
* @param {boolean} useStage - Description.
13+
* @param {*} parent - The parent Group or DisplayObjectContainer that will hold this group, if any.
14+
* @param {string} [name=group] - A name for this Group. Not used internally but useful for debugging.
15+
* @param {boolean} [useStage=false] - Only the root World Group should use this value.
1616
*/
1717
Phaser.Group = function (game, parent, name, useStage) {
1818

@@ -29,7 +29,7 @@ Phaser.Group = function (game, parent, name, useStage) {
2929
this.game = game;
3030

3131
/**
32-
* @property {Phaser.Game} name - Description.
32+
* @property {string} name - A name for this Group. Not used internally but useful for debugging.
3333
*/
3434
this.name = name || 'group';
3535

@@ -60,33 +60,31 @@ Phaser.Group = function (game, parent, name, useStage) {
6060
}
6161

6262
/**
63-
* @property {Description} type - Description.
63+
* @property {number} type - Internal Phaser Type value.
64+
* @protected
6465
*/
6566
this.type = Phaser.GROUP;
6667

6768
/**
68-
* @property {boolean} exists - Description.
69+
* @property {boolean} exists - If exists is true the the Group is updated, otherwise it is skipped.
6970
* @default
7071
*/
7172
this.exists = true;
72-
73-
/**
74-
* @property {string} _sortIndex - Helper for sort.
75-
* @private
76-
* @default
77-
*/
78-
this._sortIndex = 'y';
7973

8074
};
8175

8276
Phaser.Group.prototype = {
8377

8478
/**
85-
* Description.
79+
* Adds an existing object to this Group. The object can be an instance of Phaser.Sprite, Phaser.Button or any other display object.
80+
* The child is automatically added to the top of the Group, so renders on-top of everything else within the Group. If you need to control
81+
* that then see the addAt method.
8682
*
83+
* @see Phaser.Group#create
84+
* @see Phaser.Group#addAt
8785
* @method Phaser.Group#add
88-
* @param {Description} child - Description.
89-
* @return {Description} Description.
86+
* @param {*} child - An instance of Phaser.Sprite, Phaser.Button or any other display object..
87+
* @return {*} The child that was added to the Group.
9088
*/
9189
add: function (child) {
9290

@@ -107,12 +105,13 @@ Phaser.Group.prototype = {
107105
},
108106

109107
/**
110-
* Description.
108+
* Adds an existing object to this Group. The object can be an instance of Phaser.Sprite, Phaser.Button or any other display object.
109+
* The child is added to the Group at the location specified by the index value, this allows you to control child ordering.
111110
*
112111
* @method Phaser.Group#addAt
113-
* @param {Description} child - Description.
114-
* @param {Description} index - Description.
115-
* @return {Description} Description.
112+
* @param {*} child - An instance of Phaser.Sprite, Phaser.Button or any other display object..
113+
* @param {number} index - The index within the Group to insert the child to.
114+
* @return {*} The child that was added to the Group.
116115
*/
117116
addAt: function (child, index) {
118117

@@ -133,12 +132,12 @@ Phaser.Group.prototype = {
133132
},
134133

135134
/**
136-
* Description.
135+
* Returns the child found at the given index within this Group.
137136
*
138137
* @method Phaser.Group#getAt
139138
* @memberof Phaser.Group
140-
* @param {Description} index - Description.
141-
* @return {Description} Description.
139+
* @param {number} index - The index to return the child from.
140+
* @return {*} The child that was found at the given index.
142141
*/
143142
getAt: function (index) {
144143

@@ -147,15 +146,16 @@ Phaser.Group.prototype = {
147146
},
148147

149148
/**
150-
* Description.
149+
* Automatically creates a new Phaser.Sprite object and adds it to the top of this Group.
150+
* Useful if you don't need to create the Sprite instances before-hand.
151151
*
152152
* @method Phaser.Group#create
153-
* @param {number} x - Description.
154-
* @param {number} y - Description.
155-
* @param {string} key - Description.
156-
* @param {string} [frame] - Description.
157-
* @param {boolean} [exists] - Description.
158-
* @return {Description} Description.
153+
* @param {number} x - The x coordinate to display the newly created Sprite at. The value is in relation to the Group.x point.
154+
* @param {number} y - The y coordinate to display the newly created Sprite at. The value is in relation to the Group.y point.
155+
* @param {string} key - The Game.cache key of the image that this Sprite will use.
156+
* @param {number|string} [frame] - If the Sprite image contains multiple frames you can specify which one to use here.
157+
* @param {boolean} [exists] - The default exists state of the Sprite.
158+
* @return {Phaser.Sprite} The child that was created.
159159
*/
160160
create: function (x, y, key, frame, exists) {
161161

@@ -178,12 +178,12 @@ Phaser.Group.prototype = {
178178
},
179179

180180
/**
181-
* Description.
181+
* Swaps the position of two children in this Group.
182182
*
183183
* @method Phaser.Group#swap
184-
* @param {Description} child1 - Description.
185-
* @param {Description} child2 - Description.
186-
* @return {boolean} Description.
184+
* @param {*} child1 - The first child to swap.
185+
* @param {*} child2 - The second child to swap.
186+
* @return {boolean} True if the swap was successful, otherwise false.
187187
*/
188188
swap: function (child1, child2) {
189189

@@ -306,11 +306,11 @@ Phaser.Group.prototype = {
306306
},
307307

308308
/**
309-
* Description.
309+
* Brings the given child to the top of this Group so it renders above all other children.
310310
*
311311
* @method Phaser.Group#bringToTop
312-
* @param {Description} child - Description.
313-
* @return {Description} Description.
312+
* @param {*} child - The child to bring to the top of this Group.
313+
* @return {*} The child that was moved.
314314
*/
315315
bringToTop: function (child) {
316316

@@ -325,11 +325,11 @@ Phaser.Group.prototype = {
325325
},
326326

327327
/**
328-
* Description.
328+
* Get the index position of the given child in this Group.
329329
*
330330
* @method Phaser.Group#getIndex
331-
* @param {Description} child - Description.
332-
* @return {Description} Description.
331+
* @param {*} child - The child to get the index for.
332+
* @return {number} The index of the child or -1 if it's not a member of this Group.
333333
*/
334334
getIndex: function (child) {
335335

@@ -338,11 +338,11 @@ Phaser.Group.prototype = {
338338
},
339339

340340
/**
341-
* Description.
341+
* Replaces a child of this Group with the given newChild. The newChild cannot be a member of this Group.
342342
*
343343
* @method Phaser.Group#replace
344-
* @param {Description} oldChild - Description.
345-
* @param {Description} newChild - Description.
344+
* @param {*} oldChild - The child in this Group that will be replaced.
345+
* @param {*} newChild - The child to be inserted into this group.
346346
*/
347347
replace: function (oldChild, newChild) {
348348

@@ -369,14 +369,13 @@ Phaser.Group.prototype = {
369369
},
370370

371371
/**
372-
* Description.
372+
* Sets the given property to the given value on the child. The operation controls the assignment of the value.
373373
*
374374
* @method Phaser.Group#setProperty
375-
* @param {Description} child - Description.
376-
* @param {array} key - An array of values that will be set.
377-
* @param {Description} value - Description.
378-
* @param {Description} operation - Description.
379-
* @return {number} An integer value: -1 (Obj1 before Obj2), 0 (same), or 1 (Obj1 after Obj2). (TODO)
375+
* @param {*} child - The child to set the property value on.
376+
* @param {array} key - An array of strings that make up the property that will be set.
377+
* @param {*} value - The value that will be set.
378+
* @param {number} [operation=0] - Controls how the value is assigned. A value of 0 replaces the value with the new one. A value of 1 adds it, 2 subtracts it, 3 multiplies it and 4 divides it.
380379
*/
381380
setProperty: function (child, key, value, operation) {
382381

@@ -432,14 +431,15 @@ Phaser.Group.prototype = {
432431
},
433432

434433
/**
435-
* Description.
434+
* This function allows you to quickly set the same property across all children of this Group to a new value.
435+
* The operation parameter controls how the new value is assigned to the property, from simple replacement to addition and multiplication.
436436
*
437437
* @method Phaser.Group#setAll
438-
* @param {Description} key - Description.
439-
* @param {Description} value - Description.
440-
* @param {Description} checkAlive - Description.
441-
* @param {Description} checkVisible - Description.
442-
* @param {Description} operation - Description.
438+
* @param {string} key - The property, as a string, to be set. For example: 'body.velocity.x'
439+
* @param {*} value - The value that will be set.
440+
* @param {boolean} [checkAlive=false] - If set then only children with alive=true will be updated.
441+
* @param {boolean} [checkVisible=false] - If set then only children with visible=true will be updated.
442+
* @param {number} [operation=0] - Controls how the value is assigned. A value of 0 replaces the value with the new one. A value of 1 adds it, 2 subtracts it, 3 multiplies it and 4 divides it.
443443
*/
444444
setAll: function (key, value, checkAlive, checkVisible, operation) {
445445

@@ -596,13 +596,14 @@ Phaser.Group.prototype = {
596596
},
597597

598598
/**
599-
* Description.
599+
* Allows you to call your own function on each member of this Group. You must pass the callback and context in which it will run.
600600
* After the checkExists parameter you can add as many parameters as you like, which will all be passed to the callback along with the child.
601+
* For example: Group.forEach(awardBonusGold, this, true, 100, 500)
601602
*
602603
* @method Phaser.Group#forEach
603-
* @param {Description} callback - Description.
604-
* @param {Description} callbackContext - Description.
605-
* @param {boolean} checkExists - Description.
604+
* @param {function} callback - The function that will be called. Each child of the Group will be passed to it as its first parameter.
605+
* @param {Object} callbackContext - The context in which the function should be called (usually 'this').
606+
* @param {boolean} checkExists - If set only children with exists=true will be passed to the callback, otherwise all children will be passed.
606607
*/
607608
forEach: function (callback, callbackContext, checkExists) {
608609

@@ -635,11 +636,13 @@ Phaser.Group.prototype = {
635636
},
636637

637638
/**
638-
* Description.
639+
* Allows you to call your own function on each alive member of this Group (where child.alive=true). You must pass the callback and context in which it will run.
640+
* You can add as many parameters as you like, which will all be passed to the callback along with the child.
641+
* For example: Group.forEachAlive(causeDamage, this, 500)
639642
*
640643
* @method Phaser.Group#forEachAlive
641-
* @param {Description} callback - Description.
642-
* @param {Description} callbackContext - Description.
644+
* @param {function} callback - The function that will be called. Each child of the Group will be passed to it as its first parameter.
645+
* @param {Object} callbackContext - The context in which the function should be called (usually 'this').
643646
*/
644647
forEachAlive: function (callback, callbackContext) {
645648

@@ -667,11 +670,13 @@ Phaser.Group.prototype = {
667670
},
668671

669672
/**
670-
* Description.
673+
* Allows you to call your own function on each dead member of this Group (where alive=false). You must pass the callback and context in which it will run.
674+
* You can add as many parameters as you like, which will all be passed to the callback along with the child.
675+
* For example: Group.forEachDead(bringToLife, this)
671676
*
672677
* @method Phaser.Group#forEachDead
673-
* @param {Description} callback - Description.
674-
* @param {Description} callbackContext - Description.
678+
* @param {function} callback - The function that will be called. Each child of the Group will be passed to it as its first parameter.
679+
* @param {Object} callbackContext - The context in which the function should be called (usually 'this').
675680
*/
676681
forEachDead: function (callback, callbackContext) {
677682

@@ -698,10 +703,10 @@ Phaser.Group.prototype = {
698703
},
699704

700705
/**
701-
* Call this function to retrieve the first object with exists == (the given state) in the group.
706+
* Call this function to retrieve the first object with exists == (the given state) in the Group.
702707
*
703708
* @method Phaser.Group#getFirstExists
704-
* @param {Description} state - Description.
709+
* @param {boolean} state - True or false.
705710
* @return {Any} The first child, or null if none found.
706711
*/
707712
getFirstExists: function (state) {
@@ -733,7 +738,7 @@ Phaser.Group.prototype = {
733738

734739
/**
735740
* Call this function to retrieve the first object with alive == true in the group.
736-
* This is handy for checking if everything's wiped out, or choosing a squad leader, etc.
741+
* This is handy for checking if everything has been wiped out, or choosing a squad leader, etc.
737742
*
738743
* @method Phaser.Group#getFirstAlive
739744
* @return {Any} The first alive child, or null if none found.
@@ -762,7 +767,7 @@ Phaser.Group.prototype = {
762767

763768
/**
764769
* Call this function to retrieve the first object with alive == false in the group.
765-
* This is handy for checking if everything's wiped out, or choosing a squad leader, etc.
770+
* This is handy for checking if everything has been wiped out, or choosing a squad leader, etc.
766771
*
767772
* @method Phaser.Group#getFirstDead
768773
* @return {Any} The first dead child, or null if none found.
@@ -872,10 +877,10 @@ Phaser.Group.prototype = {
872877
},
873878

874879
/**
875-
* Description.
880+
* Removes the given child from this Group and sets its group property to null.
876881
*
877882
* @method Phaser.Group#remove
878-
* @param {Description} child - Description.
883+
* @param {Any} child - The child to remove.
879884
*/
880885
remove: function (child) {
881886

@@ -886,7 +891,8 @@ Phaser.Group.prototype = {
886891
},
887892

888893
/**
889-
* Description.
894+
* Removes all children from this Group, setting all group properties to null.
895+
* The Group container remains on the display list.
890896
*
891897
* @method Phaser.Group#removeAll
892898
*/
@@ -910,11 +916,11 @@ Phaser.Group.prototype = {
910916
},
911917

912918
/**
913-
* Description.
919+
* Removes all children from this Group whos index falls beteen the given startIndex and endIndex values.
914920
*
915921
* @method Phaser.Group#removeBetween
916-
* @param {Description} startIndex - Description.
917-
* @param {Description} endIndex - Description.
922+
* @param {number} startIndex - The index to start removing children from.
923+
* @param {number} endIndex - The index to stop removing children from. Must be higher than startIndex and less than the length of the Group.
918924
*/
919925
removeBetween: function (startIndex, endIndex) {
920926

@@ -938,7 +944,7 @@ Phaser.Group.prototype = {
938944
},
939945

940946
/**
941-
* Description.
947+
* Destroys this Group. Removes all children, then removes the container from the display list and nulls references.
942948
*
943949
* @method Phaser.Group#destroy
944950
*/
@@ -957,9 +963,10 @@ Phaser.Group.prototype = {
957963
},
958964

959965
/**
960-
* Description.
966+
* Dumps out a list of Group children and their index positions to the browser console. Useful for group debugging.
961967
*
962968
* @method Phaser.Group#dump
969+
* @param {boolean} [full=false] - If full the dump will include the entire display list, start from the Stage. Otherwise it will only include this container.
963970
*/
964971
dump: function (full) {
965972

@@ -1047,7 +1054,6 @@ Phaser.Group.prototype = {
10471054

10481055
};
10491056

1050-
10511057
/**
10521058
* @name Phaser.Group#length
10531059
* @property {number} length - The number of children in this Group.

0 commit comments

Comments
 (0)