Container + List.sort scope fixed and custom handler option added. Fix …

…#4241

CHANGELOG.md

@@ -320,6 +320,8 @@ one set of bindings ever created, which makes things a lot cleaner.
 * `Tween.seek` now returns the Tween instance (thanks @rexrainbow)
 * `Tween.complete` now returns the Tween instance (thanks @rexrainbow)
 * `Tween.stop` now returns the Tween instance (thanks @rexrainbow)
+* `List.sort` now has an optional parameter `handler` which allows you to provide your own sort handling function (thanks @jcyuan)
+* `Container.sort` now has an optional parameter `handler` which allows you to provide your own sort handling function (thanks @jcyuan)
 
 ### Bug Fixes
 
@@ -373,6 +375,8 @@ one set of bindings ever created, which makes things a lot cleaner.
 * Arcade Physics could trigger a `collide` event on a Body even if it performing an overlap check, if the `onCollide` property was true (thanks @samme)
 * TileSprites no longer cause a crash when using the Headless mode renderer. Fix #4297 (thanks @clesquir)
 * The WebGLRenderer will now apply a transparent background if `transparent = true` in the game config (thanks @gomachan7)
+* `List.sort` was missing the scope required for the sort handler, this is now correctly provided internally. Fix #4241 (thanks @jcyuan)
+* `Container.sort` was missing the scope required for the sort handler, this is now correctly provided internally. Fix #4241 (thanks @jcyuan)
 
 ### Examples and TypeScript
 

src/gameobjects/container/Container.js

@@ -525,36 +525,28 @@ var Container = new Class({
      * @since 3.4.0
      *
      * @param {string} property - The property to lexically sort by.
+     * @param {function} [handler] - Provide your own custom handler function. Will receive 2 children which it should compare and return a boolean.
      *
      * @return {Phaser.GameObjects.Container} This Container instance.
      */
-    sort: function (property)
+    sort: function (property, handler)
     {
-        if (property)
+        if (!property)
         {
-            this._sortKey = property;
+            return this;
+        }
 
-            ArrayUtils.StableSort.inplace(this.list, this.sortHandler);
+        if (handler === undefined)
+        {
+            handler = function (childA, childB)
+            {
+                return childA[property] - childB[property];
+            };
         }
 
-        return this;
-    },
+        ArrayUtils.StableSort.inplace(this.list, handler);
 
-    /**
-     * Internal sort handler method.
-     *
-     * @method Phaser.GameObjects.Container#sortHandler
-     * @private
-     * @since 3.4.0
-     *
-     * @param {Phaser.GameObjects.GameObject} childA - The first child to sort.
-     * @param {Phaser.GameObjects.GameObject} childB - The second child to sort.
-     *
-     * @return {integer} The sort results.
-     */
-    sortHandler: function (childA, childB)
-    {
-        return childA[this._sortKey] - childB[this._sortKey];
+        return this;
     },
 
     /**

src/structs/List.js

@@ -183,48 +183,37 @@ var List = new Class({
     },
 
     /**
-     * Sort the contents of this List so the items are in order based
-     * on the given property. For example, `sort('alpha')` would sort the List
-     * contents based on the value of their `alpha` property.
+     * Sort the contents of this List so the items are in order based on the given property.
+     * For example, `sort('alpha')` would sort the List contents based on the value of their `alpha` property.
      *
      * @method Phaser.Structs.List#sort
      * @since 3.0.0
      *
      * @genericUse {T[]} - [children,$return]
      *
      * @param {string} property - The property to lexically sort by.
+     * @param {function} [handler] - Provide your own custom handler function. Will receive 2 children which it should compare and return a boolean.
      *
      * @return {Phaser.Structs.List} This List object.
      */
-    sort: function (property)
+    sort: function (property, handler)
     {
-        if (property)
+        if (!property)
         {
-            this._sortKey = property;
+            return this;
+        }
 
-            StableSort.inplace(this.list, this.sortHandler);
+        if (handler === undefined)
+        {
+            handler = function (childA, childB)
+            {
+                return childA[property] - childB[property];
+            };
         }
 
-        return this;
-    },
+        StableSort.inplace(this.list, handler);
 
-    /**
-     * Internal handler for the {@link #sort} method which compares two items.
-     *
-     * @method Phaser.Structs.List#sortHandler
-     * @private
-     * @since 3.4.0
-     *
-     * @genericUse {T} - [childA,childB]
-     *
-     * @param {*} childA - The first item to compare.
-     * @param {*} childB - The second item to compare.
-     *
-     * @return {integer} The result of the comparison, which will be negative if the first item is smaller then second, positive if the first item is larger than the second, or 0 if they're equal.
-     */
-    sortHandler: function (childA, childB)
-    {
-        return childA[this._sortKey] - childB[this._sortKey];
+        return this;
     },
 
     /**