stop melody block (#1633)

* docs

* updated strings

docs/reference/music.md

@@ -7,6 +7,7 @@ music.playTone(0, 0);
 music.ringTone(0);
 music.rest(0);
 music.beginMelody(music.builtInMelody(Melodies.Entertainer), MelodyOptions.Once);
+music.stopMelody(MelodyStopOptions.All);
 music.onEvent(MusicEvent.MelodyNotePlayed, () => {});
 music.beat(BeatFraction.Whole);
 music.tempo();
@@ -17,5 +18,7 @@ music.setTempo(120);
 ## See Also
 
 [playTone](/reference/music/play-tone), [ringTone](/reference/music/ring-tone), [rest](/reference/music/rest),
-[beginMelody](/reference/music/begin-melody), [onEvent](/reference/music/on-event),
+[beginMelody](/reference/music/begin-melody), 
+[stop melody](/reference/music/stop-melody),
+[onEvent](/reference/music/on-event),
 [beat](/reference/music/beat), [tempo](/reference/music/tempo), [changeTempoBy](/reference/music/change-tempo-by), [setTempo](/reference/music/set-tempo),

docs/reference/music/stop-melody.md

@@ -0,0 +1,27 @@
+# Stop Melody
+
+Stops playing a musical melody.
+
+## Simulator
+
+```sig
+music.stopMelody(MelodyStopOptions.All)
+```
+
+## Parameters
+
+* ``options`` specifies which melodies (foreground, background or both) need to be stopped
+
+## Example
+
+This example plays the ``Entertainer`` built-in melody.
+
+```blocks
+music.beginMelody(music.builtInMelody(Melodies.Entertainer), MelodyOptions.Forever)
+basic.pause(5000)
+music.stopMelody(MelodyStopOptions.All)
+```
+
+## See also
+
+[start melody](/reference/music/begin-melody)

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
      */