From 822227eb4880eacf0b2b6d3c4ff45af45219b01c Mon Sep 17 00:00:00 2001 From: Galen Nickel Date: Tue, 30 Jan 2018 20:58:18 -0800 Subject: [PATCH] Brick ref topics 02 (#283) * Add brick button topics * Add the rest of the brick api --- docs/SUMMARY.md | 6 ++ docs/reference/brick.md | 20 ++++++- docs/reference/brick/battery-level.md | 33 +++++++++++ docs/reference/brick/button/is-pressed.md | 53 +++++++++++++++++ docs/reference/brick/button/on-event.md | 57 +++++++++++++++++++ docs/reference/brick/button/pause-until.md | 37 ++++++++++++ docs/reference/brick/button/was-pressed.md | 50 ++++++++++++++++ docs/reference/brick/set-light.md | 37 ++++++++++++ docs/reference/brick/show-image.md | 2 +- docs/reference/brick/show-number.md | 4 +- docs/reference/brick/show-string.md | 6 +- docs/reference/brick/show-value.md | 4 +- libs/core/battery.ts | 1 + libs/core/buttons.ts | 9 +-- .../mood/docs}/reference/brick/show-mood.md | 0 15 files changed, 307 insertions(+), 12 deletions(-) create mode 100644 docs/reference/brick/battery-level.md create mode 100644 docs/reference/brick/button/is-pressed.md create mode 100644 docs/reference/brick/button/on-event.md create mode 100644 docs/reference/brick/button/pause-until.md create mode 100644 docs/reference/brick/button/was-pressed.md create mode 100644 docs/reference/brick/set-light.md rename {docs => libs/mood/docs}/reference/brick/show-mood.md (100%) diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 0cecdb4e..7a0c9d11 100644 --- a/docs/SUMMARY.md +++ b/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) diff --git a/docs/reference/brick.md b/docs/reference/brick.md index 5180c7d1..f2770e4f 100644 --- a/docs/reference/brick.md +++ b/docs/reference/brick.md @@ -10,4 +10,22 @@ brick.showNumber(0, 1); brick.showValue("item", 0, 1); brick.clearScreen(); brick.printPorts(); -``` \ No newline at end of file +``` + +## 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() +``` diff --git a/docs/reference/brick/battery-level.md b/docs/reference/brick/battery-level.md new file mode 100644 index 00000000..0968f3a4 --- /dev/null +++ b/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) +}) +``` \ No newline at end of file diff --git a/docs/reference/brick/button/is-pressed.md b/docs/reference/brick/button/is-pressed.md new file mode 100644 index 00000000..b7b77073 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/docs/reference/brick/button/on-event.md b/docs/reference/brick/button/on-event.md new file mode 100644 index 00000000..fa59b752 --- /dev/null +++ b/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) diff --git a/docs/reference/brick/button/pause-until.md b/docs/reference/brick/button/pause-until.md new file mode 100644 index 00000000..9540d2c4 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/docs/reference/brick/button/was-pressed.md b/docs/reference/brick/button/was-pressed.md new file mode 100644 index 00000000..56454f99 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/docs/reference/brick/set-light.md b/docs/reference/brick/set-light.md new file mode 100644 index 00000000..56c29bb5 --- /dev/null +++ b/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) +}) +``` diff --git a/docs/reference/brick/show-image.md b/docs/reference/brick/show-image.md index 29c041cf..edbd1327 100644 --- a/docs/reference/brick/show-image.md +++ b/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 diff --git a/docs/reference/brick/show-number.md b/docs/reference/brick/show-number.md index 552dc9ea..fe46560f 100644 --- a/docs/reference/brick/show-number.md +++ b/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 diff --git a/docs/reference/brick/show-string.md b/docs/reference/brick/show-string.md index 6a1aa529..31331b61 100644 --- a/docs/reference/brick/show-string.md +++ b/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); }); ``` diff --git a/docs/reference/brick/show-value.md b/docs/reference/brick/show-value.md index 477512bc..1f71d16e 100644 --- a/docs/reference/brick/show-value.md +++ b/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 diff --git a/libs/core/battery.ts b/libs/core/battery.ts index 66d478b2..688b3440 100644 --- a/libs/core/battery.ts +++ b/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; diff --git a/libs/core/buttons.ts b/libs/core/buttons.ts index 3d5e9758..a1c6524b 100644 --- a/libs/core/buttons.ts +++ b/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 diff --git a/docs/reference/brick/show-mood.md b/libs/mood/docs/reference/brick/show-mood.md similarity index 100% rename from docs/reference/brick/show-mood.md rename to libs/mood/docs/reference/brick/show-mood.md