stop melody block (#1633)

* docs

* updated strings

libs/core/_locales/core-jsdoc-strings.json

@@ -418,6 +418,8 @@
   "music.setPlayTone": "Sets a custom playTone function for playing melodies",
   "music.setTempo": "Sets the tempo to the specified amount",
   "music.setTempo|param|bpm": "The new tempo in beats per minute, eg: 120",
+  "music.stopMelody": "Stops the melodies",
+  "music.stopMelody|param|options": "which melody to stop",
   "music.tempo": "Returns the tempo in beats per minute. Tempo is the speed (bpm = beats per minute) at which notes play. The larger the tempo value, the faster the notes will play.",
   "parseFloat": "Convert a string to a number.",
   "parseInt": "Convert a string to an integer.",

libs/core/_locales/core-strings.json

@@ -172,6 +172,9 @@
   "MelodyOptions.Forever|block": "forever",
   "MelodyOptions.OnceInBackground|block": "once in background",
   "MelodyOptions.Once|block": "once",
+  "MelodyStopOptions.All|block": "all",
+  "MelodyStopOptions.Background|block": "background",
+  "MelodyStopOptions.Foreground|block": "foreground",
   "MesDpadButtonInfo.ADown|block": "A down",
   "MesDpadButtonInfo.AUp|block": "A up",
   "MesDpadButtonInfo.BDown|block": "B down",
@@ -320,6 +323,7 @@
   "music.rest|block": "rest(ms)|%duration=device_beat",
   "music.ringTone|block": "ring tone (Hz)|%note=device_note",
   "music.setTempo|block": "set tempo to (bpm)|%value",
+  "music.stopMelody|block": "stop melody $options",
   "music.tempo|block": "tempo (bpm)",
   "music|block": "music",
   "parseFloat|block": "parse to number %text",

libs/core/music.ts

@@ -127,7 +127,7 @@ enum BeatFraction {
 }
 
 enum MelodyOptions {
-    //% block="once""
+    //% block="once"
     Once = 1,
     //% block="forever"
     Forever = 2,
@@ -137,6 +137,15 @@ enum MelodyOptions {
     ForeverInBackground = 8
 }
 
+enum MelodyStopOptions {
+    //% block="all"
+    All = MelodyOptions.Once | MelodyOptions.OnceInBackground,
+    //% block="foreground"
+    Foreground = MelodyOptions.Once,
+    //% block="background"
+    Background = MelodyOptions.OnceInBackground
+}
+
 enum MusicEvent {
     //% block="melody note played"
     MelodyNotePlayed = 1,
@@ -349,6 +358,20 @@ namespace music {
         }
     }
 
+    /**
+     * Stops the melodies
+     * @param options which melody to stop
+     */
+    //% help=music/stop-melody weight=59 blockGap=16
+    //% blockId=device_stop_melody block="stop melody $options"
+    //% parts="headphone"
+    export function stopMelody(options: MelodyStopOptions) {
+        if (options & MelodyStopOptions.Foreground)
+            beginMelody([], MelodyOptions.Once);
+        if (options & MelodyStopOptions.Background)
+            beginMelody([], MelodyOptions.OnceInBackground);
+    }
+
     /**
      * Sets a custom playTone function for playing melodies
      */