Added Group.cursor. This points to the first item added to a Group. You can move the cursor with Group.next() and Group.previous().

Author: photonstorm

README.md

@@ -44,6 +44,7 @@ Version 1.1.2
 * New: Added init method to plugins, to be called as they are added to the PluginManager (thanks beeglebug)
 * New: Physics.Body now has a center property (issue 142, thanks MikeMnD)
 * New: Lots of fixes across Full Screen Mode support. Input now works, scaling restores properly, world scale is correct and anti-alias support added.
+* New: Added Group.cursor. This points to the first item added to a Group. You can move the cursor with Group.next() and Group.previous().
 * Updated: Fixed a few final bugs in the Sprite body and bounds calculations, in turn this resolved the Tilemap collision issues in the 1.1 release.
 * Updated: Finished documentation for the Phaser.Button class.
 * Updated: Fixed the Invaders game sample and enhanced it.

examples/wip/cursor.js

@@ -0,0 +1,55 @@
+var game = new Phaser.Game(800, 600, Phaser.CANVAS, 'phaser-example', { preload: preload, create: create, update: update, render: render });
+
+function preload() {
+
+    game.load.image('atari1', 'assets/sprites/atari130xe.png');
+    game.load.image('atari2', 'assets/sprites/atari800xl.png');
+    game.load.image('atari4', 'assets/sprites/atari800.png');
+    game.load.image('sonic', 'assets/sprites/sonic_havok_sanity.png');
+    game.load.image('duck', 'assets/sprites/darkwing_crazy.png');
+    game.load.image('firstaid', 'assets/sprites/firstaid.png');
+    game.load.image('diamond', 'assets/sprites/diamond.png');
+    game.load.image('mushroom', 'assets/sprites/mushroom2.png');
+
+}
+
+var group;
+
+function create() {
+
+    group = game.add.group();
+
+    var sprite1 = group.create(0, 200, 'atari1');
+    sprite1.name = 'Atari 1';
+
+    var sprite2 = group.create(300, 200, 'atari2');
+    sprite2.name = 'Atari 2';
+
+    var sprite3 = group.create(600, 200, 'atari4');
+    sprite3.name = 'Atari 3';
+
+    game.input.onDown.add(moveCursor, this);
+
+    group.dump(false);
+
+}
+
+function moveCursor () {
+
+    group.next();
+    group.dump(false);
+
+}
+
+function update() {
+
+
+}
+
+function render() {
+
+    game.debug.renderText(group.cursor.name, 32, 32);
+
+    // game.debug.renderInputInfo(32, 32);
+
+}

src/core/Group.js

@@ -83,7 +83,9 @@ Phaser.Group = function (game, parent, name, useStage) {
     this.scale = new Phaser.Point(1, 1);
 
     /**
-    * @property {any} cursor - The current display object that the Group cursor is pointing to. You can move the cursor with Group.next and Group.previous.
+    * The cursor is a simple way to iterate through the objects in a Group using the Group.next and Group.previous functions.
+    * The cursor is set to the first child added to the Group and doesn't change unless you call next, previous or set it directly with Group.cursor.
+    * @property {any} cursor - The current display object that the Group cursor is pointing to.
     */ 
     this.cursor = null;
 
@@ -116,6 +118,11 @@ Phaser.Group.prototype = {
 			this._container.addChild(child);
 
 			child.updateTransform();
+
+			if (this.cursor === null)
+			{
+				this.cursor = child;
+			}
 		}
 
 		return child;
@@ -145,6 +152,11 @@ Phaser.Group.prototype = {
 			this._container.addChildAt(child, index);
 
 			child.updateTransform();
+
+			if (this.cursor === null)
+			{
+				this.cursor = child;
+			}
 		}
 
 		return child;
@@ -197,6 +209,11 @@ Phaser.Group.prototype = {
 
 		child.updateTransform();
 
+		if (this.cursor === null)
+		{
+			this.cursor = child;
+		}
+
 		return child;
 
 	},
@@ -233,6 +250,55 @@ Phaser.Group.prototype = {
 			this._container.addChild(child);
 			child.updateTransform();
 
+			if (this.cursor === null)
+			{
+				this.cursor = child;
+			}
+
+		}
+
+	},
+
+    /**
+	* Advances the Group cursor to the next object in the Group. If it's at the end of the Group it wraps around to the first object.
+	*
+    * @method Phaser.Group#next
+	*/
+	next: function () {
+
+		if (this.cursor)
+		{
+			//	Wrap the cursor?
+			if (this.cursor == this._container.last)
+			{
+				this.cursor = this._container._iNext;
+			}
+			else
+			{
+				this.cursor = this.cursor._iNext;
+			}
+		}
+
+	},
+
+    /**
+	* Moves the Group cursor to the previous object in the Group. If it's at the start of the Group it wraps around to the last object.
+	*
+    * @method Phaser.Group#previous
+	*/
+	previous: function () {
+
+		if (this.cursor)
+		{
+			//	Wrap the cursor?
+			if (this.cursor == this._container._iNext)
+			{
+				this.cursor = this._container.last;
+			}
+			else
+			{
+				this.cursor = this.cursor._iPrev;
+			}
 		}
 
 	},
@@ -423,8 +489,14 @@ Phaser.Group.prototype = {
 
 			this._container.removeChild(oldChild);
 			this._container.addChildAt(newChild, index);
+
 			newChild.events.onAddedToGroup.dispatch(newChild, this);
 			newChild.updateTransform();
+
+			if (this.cursor == oldChild)
+			{
+				this.cursor = this._container._iNext;
+			}
 		}
 
 	},
@@ -960,6 +1032,18 @@ Phaser.Group.prototype = {
 
 		this._container.removeChild(child);
 
+		if (this.cursor == child)
+		{
+			if (this._container._iNext)
+			{
+				this.cursor = this._container._iNext;
+			}
+			else
+			{
+				this.cursor = null;
+			}
+		}
+
 		child.group = null;
 
 	},
@@ -987,6 +1071,8 @@ Phaser.Group.prototype = {
 		}
 		while (this._container.children.length > 0);
 
+		this.cursor = null;
+
 	},
 
 	/**
@@ -1013,6 +1099,18 @@ Phaser.Group.prototype = {
 			var child = this._container.children[i];
 			child.events.onRemovedFromGroup.dispatch(child, this);
 			this._container.removeChild(child);
+	
+			if (this.cursor == child)
+			{
+				if (this._container._iNext)
+				{
+					this.cursor = this._container._iNext;
+				}
+				else
+				{
+					this.cursor = null;
+				}
+			}
 		}
 
 	},
@@ -1034,6 +1132,8 @@ Phaser.Group.prototype = {
 
 		this.exists = false;
 
+		this.cursor = null;
+
 	},
 
 	/**
@@ -1071,6 +1171,12 @@ Phaser.Group.prototype = {
 		do	
 		{
 			var name = displayObject.name || '*';
+
+			if (this.cursor == displayObject)
+			{
+				var name = '> ' + name;
+			}
+
 			var nameNext = '-';
 			var namePrev = '-';
 			var nameFirst = '-';