# screen module | Status | Last Update | API Version | | ------ | ------ | ------ | | Active | 2019-11-20 | V1.00.00 | ## Description This module provides access to screen and some UI controls. ## MainUI MainUI is where regular users operates on the meter, when you use the screen, MainUI process is simply suspended, you might encounter some problems like MainUI won't automatically re-render after your use of the screen, or some controls still in operation when you occupy the screen. You can avoid these problems easily, and these minor problems might be solved with better implementation in the future. ## THEME_COLOR `THEME_COLOR` is the accent color set by the user. ## Update method To prevent noticeable screen refresh from the user, the meter implements a GRAM. When a change in the GRAM is made (Draw a rectangle, some text etc.), and the GRAM no longer changes, a process in background flush the GRAM to the screen to complete a refresh. That process flush the GRAM when no change is made in 10 miliseconds (This is considered a new frame is made completely). If you want to flush the GRAM immediately, use `screen.forceUpdate()` function. ## color The meter implements a limited colored GRAM. You cannot display any color you want, here is the presently used palette: | Color | Note | | ----------------- | ----------------------------------------------------------- | | color.red | | | color.blue | | | color.green | | | color.cyan | | | color.black | | | color.white | | | color.purple | | | color.orange | | | color.grey | | | color.yellow | | | color.lightGreen | | | color.lightRed | | | color.lightYellow | | | color.lightBlue | | | color.lightPurple | | | color.dimGray | | | color.transparent | This is usually used when you want a transparent background | ## font The meter contains different fonts, some of those are full and some of those is partial: | Font | Note | | ---------- | ------------------------------------------------------------ | | font.f1616 | 16*16 font, when ASCII characters are mentioned, it's in western half-width. This contains full Chinese and Japanese(Please use UTF-8 encoding) characters. | | font.f1212 | 12*12 font, when ASCII characters are mentioned, it's in western half-width. This contains full Chinese and Japanese(Please use UTF-8 encoding) characters. | | font.f0508 | 5*8 font, only ASCII characters are possible. | | font.f1424 | 14*24 font, only figures and some English characters are included (Usually used to display readings). | | font.f2030 | 20*30 font, only figures and some English characters are included (Usually used to display readings). | ## screen.open() ### Description Occupy the screen, screen will no longer be controlled by MainUI (Where regular users operates on the meter). Notice that you'd better to call this when MainUI is on main page, when MainUI didn't use any control. It's also no problem when you execute your program on boot or by selecting script in MainUI, MainUI is designed to not to use controls in these cases. ### Parameters nil ### Return value nil ### Example call ```lua screen.open() ``` ## screen.close() ### Description Deoccupy the screen. ### Parameters nil ### Return value nil ### Example call ```lua screen.close() ``` ## screen.clear() ### Description Clear the screen (Set to all black). ### Parameters nil ### Return value nil ### Example call ```lua screen.clear() ``` ## screen.drawPoint() ### Description Draw a point on specified position. ### Parameters | Name | Type | Range | Usage | | --------- | ------ | ----- | ------------------------------------------------------- | | <x> | number | 0-159 | Specify x position | | <y> | number | 0-127 | Specify y position | | [color] | color | | Specify color, if not specified, `THEME_COLOR` is used. | ### Return value nil ### Example call ```lua screen.drawPoint(0,0,color.white) ``` ## screen.drawRect() ### Description Draw a rectangle with specified position. ### Parameters | Name | Type | Range | Usage | | ---------- | ------ | ----- | ------------------------------------------------------- | | <x1> | number | 0~159 | Specify x start position | | <y1> | number | 0~127 | Specify y start position | | <x2> | number | `x1`~159 | Specify x end position | | <y2> | number | `y1`~159 | Specify y end position | | [color] | color | | Specify color, if not specified, `THEME_COLOR` is used. | ### Return value nil ### Example call ```lua screen.drawRect(0,0,159,127,color.white) ``` ## screen.fillRect() ### Description Fill a rectangular area with specified position. ### Parameters | Name | Type | Range | Usage | | ---------- | ------ | -------- | ------------------------------------------------------- | | <x1> | number | 0~159 | Specify x start position | | <y1> | number | 0~127 | Specify y start position | | <x2> | number | `x1`~159 | Specify x end position | | <y2> | number | `y1`~159 | Specify y end position | | [color] | color | | Specify color, if not specified, `THEME_COLOR` is used. | ### Return value nil ### Example call ```lua screen.fillRect(0,0,159,127,color.white) ``` ## screen.forceUpdate() ### Description Flush GRAM to the screen immediately, it's not used in most applications, avoid using it if possible. ### Parameters nil ### Return value nil ### Example call ```lua screen.forceUpdate() ``` ## screen.showString() ### Description Show a string at specified position, with specified font and color. ### Parameters | Name | Type | Range | Usage | | ---------- | ------ | ----- | ------------------------------------------------------- | | <x1> | number | 0~159 | Specify x start position. | | <y1> | number | 0~127 | Specify y start position. | | <string> | string | | String be shown. | | <font> | font | | Font being used. | | [foreground_color] | color | | Specify foreground color, if not specified, `THEME_COLOR` is used. | | [background_color] | color | | Specify background color, if not specified, `THEME_BACK_COLOR` is used. | | [inverted] | boolean | | Specify if the text is inverted (swap foreground/background color). If not specified, it's not inverted. | ### Return value nil ### Example call ```lua screen.showString(0,0,"Hello World",font.f1616) ``` ## screen.printInBox() ### Description Print string in a box area. ### Parameters | Name | Type | Range | Usage | | ------------------ | ------- | ----- | ------------------------------------------------------------ | | <x1> | number | 0~159 | Specify x start position | | <y1> | number | 0~127 | Specify y start position | | <x2> | number | `x1`~159 | Specify x end position | | <y2> | number | `y1`~159 | Specify y end position | | <string> | string | | String be shown. | | <font> | font | | Font being used. | | [foreground_color] | color | | Specify foreground color, if not specified, `THEME_COLOR` is used. | | [background_color] | color | | Specify background color, if not specified, `THEME_BACK_COLOR` is used. | | [inverted] | boolean | | Specify if the text is inverted (swap foreground/background color). If not specified, it's not inverted. | ### Return value nil ### Example call ```lua screen.printInBox(0,0,159,127,"This is a text box. A happy text box, A very happy text box.",font.f1616) ``` ## screen.showDialogue() ### Description Print a dialogue-like UI without selections (It's more like a window). ### Parameters | Name | Type | Range | Usage | | --------------- | ------- | ----- | ------------------------------------------------------------ | | <title> | string | | Specify the title. | | [content] | string | | Optional, specify the content, if not specified, no content will be drawn. | | [block_time] | number | | Optional, specify the time to wait after the dialogue shown, if it is 0, the function returns immediately after rendering, if not specified, it is 0. | | [titleCentered] | boolean | | Optional, specify if the title is centered, if not specified, it's not centered. | | [color] | color | | Optional, specify the color of the dialogue. | ### Return value nil ### Example call ```lua screen.showDialogue("This is title","This is content",1000,true,color.yellow) ``` ## screen.popHint() ### Description Pop up a small hint box. ### Parameters | Name | Type | Range | Usage | | --------------- | ------ | ----- | ------------------------------------------------------------ | | <content> | string | | Specify the content. | | [block_time] | number | | Optional, specify the time(ms) to wait after the dialogue shown, if it is 0, the function returns immediately after rendering, if not specified, it is 0. | | [color] | color | | Optional, specify the color of the dialogue. | ### Return value nil ### Example call ```lua screen.popHint("Hint Box",1000) ``` ## screen.popYesOrNo() ### Description Pop up a confirm box. ### Parameters | Name | Type | Range | Usage | | ------------------ | -------- | ----- | ------------------------------------------------------------ | | <content> | string | | String of asking. | | [color] | color | | Optional. Specify the color of dialogue, if not present, the color is `THEME_COLOR`. | | [completecallback] | function | | Optional. Specify the callback function when the dialogue finished. If not present, the function returns after the user made the choice. If present, the return value of this function should be ignored, and the result is passed to the callback function as the first argument. | ### Return value | Name | Type | Range | Usage | | -------------- | ------- | ----- | ------------------------------------------------------------ | | <result> | boolean | | Result, `true` for OK, `false` for cancel. Shall be ignored if a callback function is specified. | ### Example call ```lua if(screen.popYesOrNo("Do you want to fire the boss?")) then FireTheBoss(); end ``` ## screen.popMenu() ### Description Pop up a menu. ### Parameters | Name | Type | Range | Usage | | ------------------ | -------- | ----- | ------------------------------------------------------------ | | <content> | table | | Specify menu items, each item should be a string, you can give 254 items at most. | | [color] | color | | Optional. Specify the color of menu, if not present, the color is `THEME_COLOR`. | | [completecallback] | function | | Optional. Specify the callback function when the menu finished. If not present, the function returns after the user made the choice. If present, the return value of this function should be ignored, and the result is passed to the callback function as the first argument. | ### Return value | Name | Type | Range | Usage | | -------------- | ------ | ----- | ------------------------------------------------------------ | | <result> | number | | Result. If the result is 255, the user cancelled the menu with a double-click, otherwise, returns the item index (from 0) of the item selected. | ### Example call ```lua result = screen.popMenu({"Small","Middle","Grand"}) if(result ~= 255) then -- do your stuff end ```