Merge pull request #4925 from samme/feature/actions-alignto

Add Phaser.Actions.AlignTo() and Phaser.Display.Align.To.QuickSet()

src/actions/AlignTo.js

@@ -0,0 +1,42 @@
+/**
+ * @author       samme
+ * @copyright    2019 Photon Storm Ltd.
+ * @license      {@link https://opensource.org/licenses/MIT|MIT License}
+ */
+
+var QuickSet = require('../display/align/to/QuickSet');
+
+/**
+ * Takes an array of Game Objects, or any objects that have public `x` and `y` properties, and aligns them next to each other.
+ *
+ * The first item isn't moved. The second item is aligned next to the first, then the third next to the second, and so on.
+ *
+ * @function Phaser.Actions.AlignTo
+ * @since 3.22.0
+ *
+ * @generic {Phaser.GameObjects.GameObject[]} G - [items,$return]
+ *
+ * @param {(array|Phaser.GameObjects.GameObject[])} items - The array of items to be updated by this action.
+ * @param {integer} position - The position to align the items with. This is an align constant, such as `Phaser.Display.Align.LEFT_CENTER`.
+ * @param {number} [offsetX=0] - Optional horizontal offset from the position.
+ * @param {number} [offsetY=0] - Optional vertical offset from the position.
+ *
+ * @return {(array|Phaser.GameObjects.GameObject[])} The array of objects that were passed to this Action.
+ */
+var AlignTo = function (items, position, offsetX, offsetY)
+{
+    var target = items[0];
+
+    for (var i = 1; i < items.length; i++)
+    {
+        var item = items[i];
+
+        QuickSet(item, target, position, offsetX, offsetY);
+
+        target = item;
+    }
+
+    return items;
+};
+
+module.exports = AlignTo;

src/actions/index.js

@@ -10,6 +10,7 @@
 
 module.exports = {
 
+    AlignTo: require('./AlignTo'),
     Angle: require('./Angle'),
     Call: require('./Call'),
     GetFirst: require('./GetFirst'),

src/display/align/to/QuickSet.js

@@ -0,0 +1,46 @@
+/**
+ * @author       samme
+ * @copyright    2019 Photon Storm Ltd.
+ * @license      {@link https://opensource.org/licenses/MIT|MIT License}
+ */
+
+var ALIGN_CONST = require('../const');
+
+var AlignToMap = [];
+
+AlignToMap[ALIGN_CONST.BOTTOM_CENTER] = require('./BottomCenter');
+AlignToMap[ALIGN_CONST.BOTTOM_LEFT] = require('./BottomLeft');
+AlignToMap[ALIGN_CONST.BOTTOM_RIGHT] = require('./BottomRight');
+AlignToMap[ALIGN_CONST.LEFT_BOTTOM] = require('./LeftBottom');
+AlignToMap[ALIGN_CONST.LEFT_CENTER] = require('./LeftCenter');
+AlignToMap[ALIGN_CONST.LEFT_TOP] = require('./LeftTop');
+AlignToMap[ALIGN_CONST.RIGHT_BOTTOM] = require('./RightBottom');
+AlignToMap[ALIGN_CONST.RIGHT_CENTER] = require('./RightCenter');
+AlignToMap[ALIGN_CONST.RIGHT_TOP] = require('./RightTop');
+AlignToMap[ALIGN_CONST.TOP_CENTER] = require('./TopCenter');
+AlignToMap[ALIGN_CONST.TOP_LEFT] = require('./TopLeft');
+AlignToMap[ALIGN_CONST.TOP_RIGHT] = require('./TopRight');
+
+/**
+ * Takes a Game Object and aligns it next to another, at the given position.
+ * The alignment used is based on the `position` argument, which is a `Phaser.Display.Align` property such as `LEFT_CENTER` or `TOP_RIGHT`.
+ *
+ * @function Phaser.Display.Align.To.QuickSet
+ * @since 3.22.0
+ *
+ * @generic {Phaser.GameObjects.GameObject} G - [child,$return]
+ *
+ * @param {Phaser.GameObjects.GameObject} child - The Game Object that will be positioned.
+ * @param {Phaser.GameObjects.GameObject} alignTo - The Game Object to base the alignment position on.
+ * @param {integer} position - The position to align the Game Object with. This is an align constant, such as `Phaser.Display.Align.LEFT_CENTER`.
+ * @param {number} [offsetX=0] - Optional horizontal offset from the position.
+ * @param {number} [offsetY=0] - Optional vertical offset from the position.
+ *
+ * @return {Phaser.GameObjects.GameObject} The Game Object that was aligned.
+ */
+var QuickSet = function (child, alignTo, position, offsetX, offsetY)
+{
+    return AlignToMap[position](child, alignTo, offsetX, offsetY);
+};
+
+module.exports = QuickSet;

src/display/align/to/index.js

@@ -16,6 +16,7 @@ module.exports = {
     LeftBottom: require('./LeftBottom'),
     LeftCenter: require('./LeftCenter'),
     LeftTop: require('./LeftTop'),
+    QuickSet: require('./QuickSet'),
     RightBottom: require('./RightBottom'),
     RightCenter: require('./RightCenter'),
     RightTop: require('./RightTop'),