Melody events (#391)

* support for custom playTone

* added music.onEvent, music.setPlayTone

* updated docs

* updated sample

docs/reference/music.md

@@ -10,8 +10,11 @@ music.beat(BeatFraction.Whole);
 music.tempo();
 music.changeTempoBy(20);
 music.setTempo(120);
+music.onEvent(MusicEvent.MelodyNotePlayed, () => {});
+music.setPlayTone((freq, ms) => {});
 ```
 
 ### See Also
 
-[playTone](/reference/music/play-tone), [ringTone](/reference/music/ring-tone), [rest](/reference/music/rest), [beat](/reference/music/beat), [tempo](/reference/music/tempo), [changeTempoBy](/reference/music/change-tempo-by), [setTempo](/reference/music/set-tempo)
+[playTone](/reference/music/play-tone), [ringTone](/reference/music/ring-tone), [rest](/reference/music/rest), [beat](/reference/music/beat), [tempo](/reference/music/tempo), [changeTempoBy](/reference/music/change-tempo-by), [setTempo](/reference/music/set-tempo),
+[setPlayTone](/reference/music/set-play-tone), [onEvent](/reference/music/on-event)

docs/reference/music/on-event.md

@@ -0,0 +1,51 @@
+# On Event
+
+Raises events for melodies or music events.
+
+```sig
+music.onEvent(MusicEvent.MelodyNotePlayed, () => {})
+```
+
+### Parameters
+
+* ``value`` the kind of event
+* ``handler`` the code to run when the event is raised.
+
+### Example
+
+This example prints all the events to the serial output.
+
+```blocks
+music.onEvent(MusicEvent.MelodyRepeated, () => {
+    serial.writeLine("melody repeated")
+})
+music.onEvent(MusicEvent.MelodyEnded, () => {
+    serial.writeLine("melody ended")
+})
+music.onEvent(MusicEvent.MelodyStarted, () => {
+    serial.writeLine("melody started")
+})
+music.onEvent(MusicEvent.MelodyRepeated, () => {
+    serial.writeLine("background melody repeated")
+})
+music.onEvent(MusicEvent.BackgroundMelodyStarted, () => {
+    serial.writeLine("background started")
+})
+music.onEvent(MusicEvent.BackgroundMelodyEnded, () => {
+    serial.writeLine("background ended")
+})
+music.onEvent(MusicEvent.BackgroundMelodyPaused, () => {
+    serial.writeLine("background paused")
+})
+music.onEvent(MusicEvent.BackgroundMelodyResumed, () => {
+    serial.writeLine("background resumed")
+})
+music.onEvent(MusicEvent.BackgroundMelodyRepeated, () => {
+    serial.writeLine("background repeated")
+})
+input.onButtonPressed(Button.A, () => {
+    music.beginMelody(music.builtInMelody(Melodies.BaDing), MelodyOptions.Once)
+})
+music.setTempo(100)
+music.beginMelody(music.builtInMelody(Melodies.Ringtone), MelodyOptions.ForeverInBackground)
+```

docs/reference/music/play-tone.md

@@ -2,10 +2,12 @@
 
 Play a musical tone through pin ``P0`` of the @boardname@ for as long as you say.
 
-## Simulator
+### ~ hint
 
 This function only works on the @boardname@ and in some browsers.
 
+### ~
+
 ```sig
 music.playTone(440, 120)
 ```

docs/reference/music/set-play-tone.md

@@ -0,0 +1,38 @@
+# Set Play Tone
+
+Replaces the implementation of the [music play tone](/reference/music/play-tone).
+
+
+```sig
+music.setPlayTone((freq, ms) => {})
+```
+
+### Parameters
+
+* ``f`` the replacement function
+
+### Example
+
+This example send the frequency and duration over radio 
+and plays it on the remote @boardname@.
+
+```typescript
+input.onButtonPressed(Button.A, () => {
+    music.playTone(440, 120)
+    led.toggle(0, 0)
+})
+radio.onDataPacketReceived( ({ receivedNumber }) =>  {
+    const freq = receivedNumber >> 16;
+    const duration = receivedNumber & 0xffff;
+    music.playTone(freq, duration);
+})
+input.onButtonPressed(Button.B, () => {
+    music.setPlayTone((frequency: number, duration: number) => {
+        radio.sendNumber((frequency << 16) | (duration & 0xffff));
+    })    
+})
+```
+### See also
+
+[rest](/reference/music/rest), [ring tone](/reference/music/ring-tone) , [tempo](/reference/music/tempo), [set tempo](/reference/music/set-tempo), 
+[change tempo by](/reference/music/change-tempo-by)