From 4f70d341e42ad076d4ccab0c5a7d7a2cf4960f02 Mon Sep 17 00:00:00 2001 From: Galen Nickel Date: Tue, 30 Jan 2018 17:02:22 -0800 Subject: [PATCH] Start on the 'brick' api topics (#280) * Start on the 'brick' api topics * Add the delay to clear screen example * Better output for clearsceen example --- docs/SUMMARY.md | 8 +++++ docs/reference.md | 5 ++- docs/reference/brick.md | 13 ++++++++ docs/reference/brick/clear-screen.md | 22 +++++++++++++ docs/reference/brick/print-ports.md | 19 +++++++++++ docs/reference/brick/show-image.md | 24 ++++++++++++++ docs/reference/brick/show-mood.md | 37 ++++++++++++++++++++++ docs/reference/brick/show-number.md | 24 ++++++++++++++ docs/reference/brick/show-string.md | 27 ++++++++++++++++ docs/reference/brick/show-value.md | 29 +++++++++++++++++ libs/core/_locales/core-jsdoc-strings.json | 6 ++-- libs/core/screen.ts | 12 +++++-- libs/mood/_locales/mood-jsdoc-strings.json | 2 +- libs/mood/mood.ts | 3 +- 14 files changed, 222 insertions(+), 9 deletions(-) create mode 100644 docs/reference/brick.md create mode 100644 docs/reference/brick/clear-screen.md create mode 100644 docs/reference/brick/print-ports.md create mode 100644 docs/reference/brick/show-image.md create mode 100644 docs/reference/brick/show-mood.md create mode 100644 docs/reference/brick/show-number.md create mode 100644 docs/reference/brick/show-string.md create mode 100644 docs/reference/brick/show-value.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 1ef1d4a2..0cecdb4e 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -41,3 +41,11 @@ ## Reference #reference * [Reference](/reference) + * [Brick](/reference/brick) + * [show string](/reference/brick/show-string) + * [show number](/reference/brick/show-number) + * [show value](/reference/brick/show-value) + * [show mood](/reference/brick/show-mood) + * [show image](/reference/brick/show-image) + * [clear screen](/reference/brick/clear-screen) + * [print ports](/reference/brick/print-ports) diff --git a/docs/reference.md b/docs/reference.md index 110f23ff..223f223f 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -1,8 +1,11 @@ # Reference - +```namespaces +brick.showMood(moods.sleeping); +``` ## See Also +[brick](/reference/brick), [touch sensor](/reference/sensors/touch-sensor), [color sensor](/reference/sensors/color-sensor) \ No newline at end of file diff --git a/docs/reference/brick.md b/docs/reference/brick.md new file mode 100644 index 00000000..5180c7d1 --- /dev/null +++ b/docs/reference/brick.md @@ -0,0 +1,13 @@ +# Brick + +## Screen + +```cards +brick.showMood(moods.sleeping); +brick.showImage(images.expressionsBigSmile); +brick.showString("Hello world!", 1); +brick.showNumber(0, 1); +brick.showValue("item", 0, 1); +brick.clearScreen(); +brick.printPorts(); +``` \ No newline at end of file diff --git a/docs/reference/brick/clear-screen.md b/docs/reference/brick/clear-screen.md new file mode 100644 index 00000000..7ae69310 --- /dev/null +++ b/docs/reference/brick/clear-screen.md @@ -0,0 +1,22 @@ +# clear Screen + +Clear any text or numbers displayed on the screen. The screen will be blank. + +```sig +brick.clearScreen(); +``` + +## Example + +Clear the screen after displaying the message. + +```blocks +brick.showString("This message will", 1); +brick.showString("self-destruct in:", 2); +brick.showString("seconds", 5); +for (let i = 0; i < 10; i++) { + brick.showNumber(10 - i, 4); + loops.pause(1000); +} +brick.clearScreen(); +``` diff --git a/docs/reference/brick/print-ports.md b/docs/reference/brick/print-ports.md new file mode 100644 index 00000000..697900b6 --- /dev/null +++ b/docs/reference/brick/print-ports.md @@ -0,0 +1,19 @@ +# print Ports + +Print the status of the ports on the screen. + +```sig +brick.printPorts(); +``` + +## Example + +Show the port status. + +```blocks +brick.printPorts(); +``` + +## See also + +[show string](/reference/brick/show-string), [show value](/reference/brick/show-value) \ No newline at end of file diff --git a/docs/reference/brick/show-image.md b/docs/reference/brick/show-image.md new file mode 100644 index 00000000..29c041cf --- /dev/null +++ b/docs/reference/brick/show-image.md @@ -0,0 +1,24 @@ +# show Image + +Show an image on the brick's display. + +```sig +brick.showImage(images.expressionsBigSmile); +``` +You can choose one of several images to show on the display. + +## Parameters + +**image**: A image to show on the brick's display. Use the image picker to choose the image you want to show. + +## Example + +Show a sleeping image on the brick's display. + +```blocks +brick.showImage(image.expressionsZzz) +``` + +## See also + +[show image](/reference/brick/show-mood) \ No newline at end of file diff --git a/docs/reference/brick/show-mood.md b/docs/reference/brick/show-mood.md new file mode 100644 index 00000000..effb1434 --- /dev/null +++ b/docs/reference/brick/show-mood.md @@ -0,0 +1,37 @@ +# show Mood + +Show a mood on the brick. A mood will have a image on the display along with a sound and solid or flashing light. + +```sig +brick.showMood(moods.sleeping) +``` +You can choose one of several moods to show on the display. Use a mood to help show what your @boardname@ is doing at the moment. + +## Parameters + +**mood**: A mood to show on the brick. Choose one of these moods: +>* ``sleeping`` +* ``awake`` +* ``tired`` +* ``angry`` +* ``sad`` +* ``dizzy`` +* ``knockedOut`` +* ``middleLeft`` +* ``middleRight`` +* ``love`` +* ``winking`` +* ``neutral`` + + +## Example + +Show a ``winking`` mood on the brick. + +```blocks +brick.showMood(moods.winking) +``` + +## See also + +[show image](/reference/brick/show-image) \ No newline at end of file diff --git a/docs/reference/brick/show-number.md b/docs/reference/brick/show-number.md new file mode 100644 index 00000000..552dc9ea --- /dev/null +++ b/docs/reference/brick/show-number.md @@ -0,0 +1,24 @@ +# show Number + +Show a number on the screen at the line you select. + +```sig +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`. + +## Example + +Show the number `1000` on the screen. + +```blocks +brick.showNumber(1000, 1); +``` + +## See also + +[show string](/reference/brick/show-string), [show value](/reference/brick/show-value) \ No newline at end of file diff --git a/docs/reference/brick/show-string.md b/docs/reference/brick/show-string.md new file mode 100644 index 00000000..6a1aa529 --- /dev/null +++ b/docs/reference/brick/show-string.md @@ -0,0 +1,27 @@ +# show String + +Show some text on a the screen at the line you select. + +```sig +brick.showString("Hello world", 1) +``` + +## Parameters + +* **text**: a [string](/types/string) to show on the brick's screen. +* **line**: the line [number](/types/number) on the screen where the text is displayed. The line numbers for the screen start with line `1`. + +## Example + +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.buttonEnter.onEvent(ButtonEvent.Click, function () { + brick.showString("Hey! Don't push my buttons.", 3); +}); +``` + +## See also + +[show number](/reference/brick/show-number) \ No newline at end of file diff --git a/docs/reference/brick/show-value.md b/docs/reference/brick/show-value.md new file mode 100644 index 00000000..477512bc --- /dev/null +++ b/docs/reference/brick/show-value.md @@ -0,0 +1,29 @@ +# show Value + +Show a name-value-pair on the screen at the line you select. + +```sig +brick.showNumber("item", 0, 1); +``` + +Name-value-pairs are used to report data values to the screen. If you want to show the current temperature on the screen, you might use `"temp"` as the data name for the the value. + +## 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`. + +## Example + +Show the current amount of ambient light detected by sensor 2. + +```blocks +brick.buttonEnter.onEvent(ButtonEvent.Click, function () { + brick.showValue("color", sensors.color2.light(LightIntensityMode.Ambient), 1) +}) +``` + +## See also + +[show number](/reference/brick/show-number) \ No newline at end of file diff --git a/libs/core/_locales/core-jsdoc-strings.json b/libs/core/_locales/core-jsdoc-strings.json index 52bb7874..e96cc3df 100644 --- a/libs/core/_locales/core-jsdoc-strings.json +++ b/libs/core/_locales/core-jsdoc-strings.json @@ -29,11 +29,11 @@ "brick.buttonLeft": "Left button on the EV3 Brick.", "brick.buttonRight": "Right button on the EV3 Brick.", "brick.buttonUp": "Up button on the EV3 Brick.", - "brick.clearScreen": "Clears the screen", - "brick.printPorts": "Prints the port states on the screen", + "brick.clearScreen": "Clear the screen", + "brick.printPorts": "Print the port states on the screen", "brick.setLight": "Set lights.", "brick.setLight|param|pattern": "the lights pattern to use. eg: BrickLight.Orange", - "brick.showImage": "Shows an image on screen", + "brick.showImage": "Show an image on the screen", "brick.showImage|param|image": "image to draw", "brick.showNumber": "Shows a number on the screen", "brick.showNumber|param|line": "the line number to print the text at, eg: 1", diff --git a/libs/core/screen.ts b/libs/core/screen.ts index b87d3156..0ad64046 100644 --- a/libs/core/screen.ts +++ b/libs/core/screen.ts @@ -72,6 +72,7 @@ namespace brick { */ //% blockId=screen_print block="show string %text|at line %line" //% weight=98 group="Screen" inlineInputMode="inline" blockGap=8 + //% help=brick/show-string //% line.min=1 line.max=10 export function showString(text: string, line: number) { const NUM_LINES = 9; @@ -87,6 +88,7 @@ namespace brick { */ //% blockId=screenShowNumber block="show number %name|at line %line" //% weight=96 group="Screen" inlineInputMode="inline" blockGap=8 + //% help=brick/show-number //% line.min=1 line.max=10 export function showNumber(value: number, line: number) { showString("" + value, line); @@ -99,6 +101,7 @@ namespace brick { */ //% blockId=screenShowValue block="show value %name|= %text|at line %line" //% weight=96 group="Screen" inlineInputMode="inline" blockGap=8 + //% help=brick/show-value //% line.min=1 line.max=10 export function showValue(name: string, value: number, line: number) { value = Math.round(value * 1000) / 1000; @@ -136,11 +139,12 @@ namespace brick { } /** - * Shows an image on screen + * Show an image on the screen * @param image image to draw */ //% blockId=screen_show_image block="show image %image=screen_image_picker" //% weight=100 group="Screen" blockGap=8 + //% help=brick/show-image export function showImage(image: Image) { if (!image) return; image.draw(0, 0, Draw.Normal); @@ -160,10 +164,11 @@ namespace brick { } /** - * Clears the screen + * Clear the screen */ //% blockId=screen_clear_screen block="clear screen" //% weight=90 group="Screen" + //% help=brick/clear-screen export function clearScreen() { screen.clear(); } @@ -208,9 +213,10 @@ namespace brick { } /** - * Prints the port states on the screen + * Print the port states on the screen */ //% blockId=brickPrintPorts block="print ports" + //% help=brick/print-ports //% weight=1 group="Screen" export function printPorts() { const col = 44; diff --git a/libs/mood/_locales/mood-jsdoc-strings.json b/libs/mood/_locales/mood-jsdoc-strings.json index 70e393d2..58760c0f 100644 --- a/libs/mood/_locales/mood-jsdoc-strings.json +++ b/libs/mood/_locales/mood-jsdoc-strings.json @@ -1,7 +1,7 @@ { "brick.Mood": "A mood", "brick.Mood.show": "Shows the mood on the EV3", - "brick.showMood": "Shows a mood", + "brick.showMood": "Show a mood on the brick's screen", "moods.angry": "An angry mood", "moods.awake": "A awake mood", "moods.dizzy": "A dizzy mood", diff --git a/libs/mood/mood.ts b/libs/mood/mood.ts index 75e372cc..14294e82 100644 --- a/libs/mood/mood.ts +++ b/libs/mood/mood.ts @@ -1,9 +1,10 @@ namespace brick { /** - * Shows a mood + * Show a mood on the brick's screen */ //% weight=90 //% blockId=moodShow block="show mood %mood=mood_image_picker" + //% help=brick/show-mood //% weight=101 group="Screen" blockGap=8 export function showMood(mood: Mood) { if(mood)