Merge pull request phaserjs#5095 from samme/feature/new-soundmanager-methods

Add new Sound Manager methods

Author: photonstorm

src/sound/BaseSoundManager.js

@@ -11,6 +11,8 @@ var EventEmitter = require('eventemitter3');
 var Events = require('./events');
 var GameEvents = require('../core/events');
 var NOOP = require('../utils/NOOP');
+var GetAll = require('../utils/array/GetAll');
+var GetFirst = require('../utils/array/GetFirst');
 
 /**
  * @classdesc
@@ -225,6 +227,36 @@ var BaseSoundManager = new Class({
         return sound;
     },
 
+    /**
+     * Gets the first sound in the manager matching the given key, if any.
+     *
+     * @method Phaser.Sound.BaseSoundManager#get
+     * @since 3.23.0
+     *
+     * @param {string} key - Sound asset key.
+     *
+     * @return {?Phaser.Sound.BaseSound} - The sound, or null.
+     */
+    get: function (key)
+    {
+        return GetFirst(this.sounds, 'key', key);
+    },
+
+    /**
+     * Gets any sounds in the manager matching the given key.
+     *
+     * @method Phaser.Sound.BaseSoundManager#getAll
+     * @since 3.23.0
+     *
+     * @param {string} key - Sound asset key.
+     *
+     * @return {Phaser.Sound.BaseSound[]} - The sounds, or an empty array.
+     */
+    getAll: function (key)
+    {
+        return GetAll(this.sounds, 'key', key);
+    },
+
     /**
      * Adds a new sound to the sound manager and plays it.
      * The sound will be automatically removed (destroyed) once playback ends.
@@ -315,6 +347,23 @@ var BaseSoundManager = new Class({
         return false;
     },
 
+
+    /**
+     * Removes all sounds from the manager, destroying the sounds.
+     *
+     * @method Phaser.Sound.BaseSoundManager#removeAll
+     * @since 3.23.0
+     */
+    removeAll: function ()
+    {
+        this.sounds.forEach(function (sound)
+        {
+            sound.destroy();
+        });
+
+        this.sounds.length = 0;
+    },
+
     /**
      * Removes all sounds from the sound manager that have an asset key matching the given value.
      * The removed sounds are destroyed before removal.
@@ -398,6 +447,29 @@ var BaseSoundManager = new Class({
         this.emit(Events.STOP_ALL, this);
     },
 
+
+    /**
+     * Stops any sounds matching the given key.
+     *
+     * @method Phaser.Sound.BaseSoundManager#stopByKey
+     * @since 3.23.0
+     *
+     * @param {string} key - Sound asset key.
+     *
+     * @return {number} - How many sounds were stopped.
+     */
+    stopByKey: function (key)
+    {
+        var stopped = 0;
+
+        this.getAll(key).forEach(function (sound)
+        {
+            if (sound.stop()) { stopped++; }
+        });
+
+        return stopped;
+    },
+
     /**
      * Method used internally for unlocking audio playback on devices that
      * require user interaction before any sound can be played on a web page.
@@ -479,10 +551,7 @@ var BaseSoundManager = new Class({
     {
         this.removeAllListeners();
 
-        this.forEachActiveSound(function (sound)
-        {
-            sound.destroy();
-        });
+        this.removeAll();
 
         this.sounds.length = 0;
         this.sounds = null;