added input.onPinRelease. Fix for #294

docs/reference/input/on-pin-released.md

@@ -0,0 +1,48 @@
+# On Pin Released
+
+Start an [event handler](/reference/event-handler) (part of the
+program that will run when something happens, like when a button is
+pressed).  This handler works when you release pin `0`, `1`, or `2`
+together with `GND`.  When you are using this function in a web
+browser, click and release the pins on the screen instead of the ones on the BBC
+micro:bit.
+
+If you hold the `GND` pin with one hand and touch pin `0`, `1`, or `2`
+with the other, a very small (safe) amount of electricity will flow
+through your body and back into the micro:bit. This is called
+**completing a circuit**. It's like you're a big wire!
+
+```sig
+input.onPinReleased(TouchPin.P0, () => {
+})
+```
+
+## ~hint
+
+This function works best when the BBC micro:bit is using batteries for power,
+instead of the USB cable.
+
+## ~
+
+## Parameters
+
+* ``name`` means the pin that is being released, either `P0`, `P1`, or `P2`
+
+### Example: pin pressed counter
+
+This program counts how many times you release the `P0` pin. 
+Every time you release the pin, the program shows the number of times on the screen.
+
+```blocks
+let count = 0
+basic.showNumber(count, 100)
+input.onPinReleased(TouchPin.P0, () => {
+    count = count + 1
+    basic.showNumber(count, 100)
+})
+```
+
+### See also
+
+[BBC micro:bit pins](/device/pins), [pin is pressed](/reference/input/pin-is-pressed), [analog read pin](/reference/pins/analog-read-pin), [analog write pin](/reference/pins/analog-write-pin), [digital read pin](/reference/pins/digital-read-pin), [digital write pin](/reference/pins/digital-write-pin)
+

libs/microbit/input.cpp

@@ -135,12 +135,12 @@ namespace input {
     }
 
     /**
-     * Do something when a pin(``P0``, ``P1`` or both ``P2``) is pressed.
-     * @param name TODO
-     * @param body TODO
+     * Do something when a pin is pressed.
+     * @param name the pin that needs to be pressed
+     * @param body the code to run when the pin is pressed
      */
     //% help=input/on-pin-pressed weight=83
-    //% blockId=device_pin_event block="on pin|%NAME|pressed" icon="\uf094"
+    //% blockId=device_pin_event block="on pin %NAME|pressed" icon="\uf094"
     void onPinPressed(TouchPin name, Action body) {
         auto pin = getPin((int)name);
         if (!pin) return;
@@ -150,6 +150,22 @@ namespace input {
         registerWithDal((int)name, MICROBIT_BUTTON_EVT_CLICK, body);
     }
 
+    /**
+     * Do something when a pin is released.
+     * @param name the pin that needs to be released
+     * @param body the code to run when the pin is released
+     */
+    //% help=input/on-pin-released weight=6 blockGap=8
+    //% blockId=device_pin_released block="on pin %NAME|released" icon="\uf094"
+    void onPinReleased(TouchPin name, Action body) {
+        auto pin = getPin((int)name);
+        if (!pin) return;
+
+        // Forces the PIN to switch to makey-makey style detection.
+        pin->isTouched();
+        registerWithDal((int)name, MICROBIT_BUTTON_EVT_UP, body);
+    }
+
     /**
      * Get the button state (pressed or not) for ``A`` and ``B``.
      */

libs/microbit/shims.d.ts

@@ -213,14 +213,23 @@ declare namespace input {
     function onGesture(gesture: Gesture, body: () => void): void;
 
     /**
-     * Do something when a pin(``P0``, ``P1`` or both ``P2``) is pressed.
-     * @param name TODO
-     * @param body TODO
+     * Do something when a pin is pressed.
+     * @param name the pin that needs to be pressed
+     * @param body the code to run when the pin is pressed
      */
     //% help=input/on-pin-pressed weight=83
-    //% blockId=device_pin_event block="on pin|%NAME|pressed" icon="\uf094" shim=input::onPinPressed
+    //% blockId=device_pin_event block="on pin %NAME|pressed" icon="\uf094" shim=input::onPinPressed
     function onPinPressed(name: TouchPin, body: () => void): void;
 
+    /**
+     * Do something when a pin is released.
+     * @param name the pin that needs to be released
+     * @param body the code to run when the pin is released
+     */
+    //% help=input/on-pin-released weight=6 blockGap=8
+    //% blockId=device_pin_released block="on pin %NAME|released" icon="\uf094" shim=input::onPinReleased
+    function onPinReleased(name: TouchPin, body: () => void): void;
+
     /**
      * Get the button state (pressed or not) for ``A`` and ``B``.
      */

sim/libmbit.ts

@@ -294,7 +294,14 @@ namespace pxsim.input {
         let pin = getPin(pinId);
         if (!pin) return;
         pin.isTouched();
-        input.onButtonPressed(pin.id, handler);
+        pxt.registerWithDal(pin.id, DAL.MICROBIT_BUTTON_EVT_CLICK, handler);
+    }
+
+    export function onPinReleased(pinId: number, handler: RefAction) {
+        let pin = getPin(pinId);
+        if (!pin) return;
+        pin.isTouched();
+        pxt.registerWithDal(pin.id, DAL.MICROBIT_BUTTON_EVT_UP, handler);
     }
 
     export function pinIsPressed(pinId: number): boolean {