Brick ref topics 02 (#283)

* Add brick button topics

* Add the rest of the brick api

docs/SUMMARY.md

@@ -49,3 +49,9 @@
         * [show image](/reference/brick/show-image)
         * [clear screen](/reference/brick/clear-screen)
         * [print ports](/reference/brick/print-ports)
+        * [on event](/reference/brick/button/on-event)
+        * [is pressed](/reference/brick/button/is-pressed)
+        * [was pressed](/reference/brick/button/was-pressed)
+        * [pause until](/reference/brick/button/pause-until)
+        * [set light](/reference/brick/set-light)
+        * [battery level](/reference/brick/battery-level)

docs/reference/brick.md

@@ -10,4 +10,22 @@ brick.showNumber(0, 1);
 brick.showValue("item", 0, 1);
 brick.clearScreen();
 brick.printPorts();
-```
+```
+
+## Buttons
+
+```cards
+brick.buttonEnter.onEvent(ButtonEvent.Click, function () {
+
+});
+brick.buttonEnter.pauseUntil(ButtonEvent.Click);
+brick.buttonEnter.isPressed()
+brick.buttonEnter.wasPressed()
+brick.setLight(BrickLight.Red);
+```
+
+## Other
+
+```cards
+brick.batteryLevel()
+```

docs/reference/brick/battery-level.md

@@ -0,0 +1,33 @@
+# battery Level
+
+Return the current battery level.
+
+```sig
+brick.batteryLevel();
+```
+
+## Returns
+
+* a [number](/types/number) which is the current charge level of the brick's battery. This is a percentage of total charge left in the battery.
+
+## Example
+
+Show the battery level percentage on the screen. Also, show a green light if the battery level is above 15%. If the battery level is below 15% but above 5%, show a orange light. But, if the battery level is below 5%, show a pulsing red light.
+
+```blocks
+let battery = 0;
+loops.forever(function() {
+    brick.showString("Battery level:", 1)
+    brick.showNumber(battery, 2)
+    battery = brick.batteryLevel();
+    if (battery > 15)
+    {
+        brick.setLight(BrickLight.Green);
+    } else if (battery > 5) {
+        brick.setLight(BrickLight.Orange);
+    } else {
+        brick.setLight(BrickLight.RedPulse)
+    }
+    loops.pause(30000)
+})
+```

docs/reference/brick/button/is-pressed.md

@@ -0,0 +1,53 @@
+# is Pressed
+
+Check if a button is being pressed or not.
+
+```sig
+brick.buttonEnter.isPressed()
+```
+
+## ~hint
+
+**Touch sensors**
+
+Your @boardname@ has touch sensors that work like buttons. Instead of saying `enter` or `left` as the source button, use a touch sensor block with a sensor name like `touch 1`.
+
+```block
+if (sensors.touch1.isPressed()) {
+    console.log("Hey, I feel pressed.");
+}
+```
+
+Read about [touch sensors](/reference/sensors/touch-sensor) and using them as touch buttons.
+
+## ~
+
+## Returns
+
+* a [boolean](types/boolean): `true` if the button is pressed, `false` if the button is not pressed
+
+## Example
+
+Set the brick light to green when the `down` is pressed. When the button is not pressed, the brick light is red.
+
+```blocks
+let isRed = false;
+loops.forever(function() {
+    if (brick.buttonLeft.isPressed()) {
+        brick.setLight(BrickLight.Green);
+        isRed = false;
+    } else {
+        if (!isRed) {
+            brick.setLight(BrickLight.Red);
+            isRed = true;
+        }
+    }
+})
+```
+
+## See also
+
+[was pressed](/reference/brick/button/was-pressed),
+[on event](/reference/brick/button/on-event)
+
+[Touch sensors](/reference/sensors/touch-sensor)

docs/reference/brick/button/on-event.md

@@ -0,0 +1,57 @@
+# on Event
+
+Run some code when a button is clicked, pressed down, or released.
+
+```sig
+brick.buttonEnter.onEvent(ButtonEvent.Click, function () {
+
+});
+```
+
+## ~hint
+
+**Touch sensors**
+
+Your @boardname@ has touch sensors that work like buttons. Instead of saying `enter` or `left` as the source button, use a touch sensor block with a sensor name like `touch 1`.
+
+```block
+sensors.touch1.onEvent(TouchSensorEvent.Pressed, function () {
+    brick.setLight(BrickLight.Orange);
+});
+```
+
+Read about [touch sensors](/reference/sensors/touch-sensor) and using them as touch buttons.
+
+## ~
+
+## Parameters
+
+* **ev**: the button action to run some code for. The button actions (events) are:
+> * ``click``: button was clicked (pressed and released)
+> * ``up``: button is released from just being pressed
+> * ``down``: button is just pressed down
+* **body**: the code you want to run when something happens with a button
+
+## Example
+
+Check for event on the ENTER button. Put a message on the screen when the button is pressed, clicked, or released.
+
+```blocks
+brick.showString("ENTER is: UP", 1);
+brick.buttonEnter.onEvent(ButtonEvent.Up, function () {
+    brick.showString("ENTER is: UP      ", 1);
+});
+brick.buttonEnter.onEvent(ButtonEvent.Down, function () {
+    brick.showString("ENTER is: DOWN    ", 1);
+});
+brick.buttonEnter.onEvent(ButtonEvent.Click, function () {
+    brick.showString("ENTER was: CLICKED", 1);
+});
+```
+
+### See also
+
+[is pressed](/reference/brick/button/is-pressed),
+[was pressed](/reference/brick/button/was-pressed),
+
+[Touch sensor](/reference/sensors/touch-sensor)

docs/reference/brick/button/pause-until.md

@@ -0,0 +1,37 @@
+# pause Until
+
+Causes your program to wait until an event at a button happens.
+
+```sig
+brick.buttonEnter.pauseUntil(ButtonEvent.Click);
+```
+
+## Parameters
+
+* **ev**: the button action to wait for. The button actions (events) are:
+> * ``click``: button was clicked (pressed and released)
+> * ``up``: button is released from just being pressed
+> * ``down``: button is just pressed down
+
+## Example
+
+Wait for the `up` button to go up before continuing with displaying a message on the screen.
+
+```blocks
+let waitTime = 0;
+brick.showString("We're going to wait", 1);
+brick.showString("for you to press and", 2);
+brick.showString("release the UP button", 3);
+waitTime = control.millis();
+brick.buttonUp.pauseUntil(ButtonEvent.Click);
+brick.clearScreen();
+if (control.millis() - waitTime > 5000) {
+    brick.showString("Ok, that took awhile!", 1)
+} else {
+    brick.showString("Ah, you let go!", 1)
+}
+```
+
+## See also
+
+[on event](/reference/brick/button/on-event)

docs/reference/brick/button/was-pressed.md

@@ -0,0 +1,50 @@
+# was Pressed
+
+Check if a button was pressed earlier.
+
+```sig
+brick.buttonEnter.wasPressed()
+```
+
+The fact that a button was pressed earlier is remembered. Once **was pressed** is used, this fact is forgotten and the result is `false` the next time you check with **was pressed** button _state_ is reset). But, if you press the button again before you check with **was pressed**, it will tell you `true`. 
+
+## ~hint
+
+**Touch sensors**
+
+Your @boardname@ has touch sensors that work like buttons. Instead of saying `enter` or `left` as the source button, use a touch sensor block with a sensor name like `touch 1`.
+
+```block
+if (sensors.touch1.wasPressed()) {
+    console.log("Hey, I was pressed.");
+}
+```
+
+Read about [touch sensors](/reference/sensors/touch-sensor) and using them as touch buttons.
+
+## ~
+
+## Returns
+
+* a [boolean](types/boolean): `true` if the button was pressed before, `false` if the button was not pressed before
+
+## Example
+
+Set the brick light to green if the `right` button was pressed before the `left` button. If not, the brick light is turned off when the `left` button is pressed.
+
+```blocks
+brick.buttonLeft.onEvent(ButtonEvent.Click, function() {
+    if (brick.buttonRight.wasPressed()) {
+        brick.setLight(BrickLight.Green)
+    } else {
+        brick.setLight(BrickLight.Off)
+    }
+})
+```
+
+## See also
+
+[is pressed](/reference/brick/button/is-pressed),
+[on event](/reference/brick/button/on-event)
+
+[Touch sensors](/reference/sensors/touch-sensor)

docs/reference/brick/set-light.md

@@ -0,0 +1,37 @@
+# set Light
+
+Set the light on the brick to a solid or flashing color.
+
+```sig
+brick.setLight(BrickLight.Red);
+```
+## Parameters
+
+* **pattern**: the color or color pattern for the brick light to show. The brick light can have these color patterns:
+>* `off`: brick light is off
+>* `green`: solid green
+>* `red`: solid red
+>* `orange`: solid orange
+>* `green flash`: flashing green
+>* `red flash`: flashing red
+>* `orange flash`: flashing orange
+>* `green pulse`: pulsing green
+>* `red pulse`: pulsing red
+>* `orange pulse`: pulsing orange
+
+## Example
+
+Repeatedly show a different color pattern for the brick light.
+
+```blocks
+loops.forever(function () {
+    brick.setLight(BrickLight.Orange)
+    loops.pause(1000)
+    brick.setLight(BrickLight.GreenFlash)
+    loops.pause(2000)
+    brick.setLight(BrickLight.RedPulse)
+    loops.pause(2000)
+    brick.setLight(BrickLight.Off)
+    loops.pause(500)
+})
+```

docs/reference/brick/show-image.md

@@ -16,7 +16,7 @@ You can choose one of several images to show on the display.
 Show a sleeping image on the brick's display.
 
 ```blocks
-brick.showImage(image.expressionsZzz)
+brick.showImage(images.expressionsZzz)
 ```
 
 ## See also

docs/reference/brick/show-number.md

@@ -8,8 +8,8 @@ brick.showNumber(0, 1);
 
 ## Parameters
 
-**value**: a [number](/types/number) to show on the brick's screen.
-**line**: The line number on the screen where the value is displayed. The line numbers for the screen start with line `1`.
+* **value**: a [number](/types/number) to show on the brick's screen.
+* **line**: The line number on the screen where the value is displayed. The line numbers for the screen start with line `1`.
 
 ## Example
 

docs/reference/brick/show-string.md

@@ -16,9 +16,11 @@ brick.showString("Hello world", 1)
 Show a greeting on the screen. Then, respond with another message when ENTER is pressed.
 
 ```blocks
-brick.showString("Hello, I dare you to press ENTER...", 1);
+brick.showString("Hello, I dare you to", 1);
+brick.showString("press ENTER...", 2);
 brick.buttonEnter.onEvent(ButtonEvent.Click, function () {
-	brick.showString("Hey! Don't push my buttons.", 3);
+	brick.showString("Hey! Don't push my", 4);
+	brick.showString("buttons.", 5);
 });
 ```
 

docs/reference/brick/show-value.md

@@ -11,8 +11,8 @@ Name-value-pairs are used to report data values to the screen. If you want to sh
 ## Parameters
 
 * **name**: a [string](/types/string) which is the name of the data value.
-**value**: a [number](/types/number) to show on the brick's screen.
-**line**: The line number on the screen where the value is displayed. The line numbers for the screen start with line `1`.
+* **value**: a [number](/types/number) to show on the brick's screen.
+* **line**: The line number on the screen where the value is displayed. The line numbers for the screen start with line `1`.
 
 ## Example
 

libs/core/battery.ts

@@ -5,6 +5,7 @@ namespace brick {
      */
     //% blockId=brickBatteryLevel block="battery level"
     //% group="More"
+    //% help=brick/battery-level
     export function batteryLevel(): number {
         const info = sensors.internal.getBatteryInfo();
         return info.current;

libs/core/buttons.ts

@@ -75,7 +75,7 @@ namespace brick {
          * Check if button is currently pressed or not.
          * @param button the button to query the request
          */
-        //% help=input/button/is-pressed
+        //% help=brick/button/is-pressed
         //% block="%button|is pressed"
         //% blockId=buttonIsPressed
         //% parts="brick"
@@ -91,7 +91,7 @@ namespace brick {
          * See if the button was pressed again since the last time you checked.
          * @param button the button to query the request
          */
-        //% help=input/button/was-pressed
+        //% help=brick/button/was-pressed
         //% block="%button|was pressed"
         //% blockId=buttonWasPressed
         //% parts="brick"
@@ -111,7 +111,7 @@ namespace brick {
          * @param event the kind of button gesture that needs to be detected
          * @param body code to run when the event is raised
          */
-        //% help=input/button/on-event
+        //% help=brick/button/on-event
         //% blockId=buttonEvent block="on %button|%event"
         //% parts="brick"
         //% blockNamespace=brick
@@ -126,7 +126,7 @@ namespace brick {
          * Waits until the event is raised
          * @param ev the event to wait for
          */
-        //% help=input/button/pause-until
+        //% help=brick/button/pause-until
         //% blockId=buttonWaitUntil block="pause until %button|%event"
         //% parts="brick"
         //% blockNamespace=brick
@@ -251,6 +251,7 @@ namespace brick {
      */
     //% blockId=setLights block="set light to %pattern"
     //% weight=100 group="Buttons"
+    //% help=brick/set-light
     export function setLight(pattern: BrickLight): void {
         if (currPattern === pattern)
             return