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¶

screen.open()

screen.close()¶

Description¶

Deoccupy the screen.

Parameters¶

nil

Return value¶

nil

Example call¶

screen.close()

screen.clear()¶

Description¶

Clear the screen (Set to all black).

Parameters¶

nil

Return value¶

nil

Example call¶

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¶

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¶

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¶

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¶

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¶

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¶

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	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¶

screen.showDialogue("This is title","This is content",1000,true,color.yellow)

screen.popHint()¶

Description¶

Pop up a small hint box.

Parameters¶

Name	Type	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¶

screen.popHint("Hint Box",1000)

screen.popYesOrNo()¶

Description¶

Pop up a confirm box.

Parameters¶

Name	Type	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¶

if(screen.popYesOrNo("Do you want to fire the boss?")) then 
    FireTheBoss();
end

screen.popMenu()¶

Description¶

Pop up a menu.

Parameters¶

Name	Type	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¶

result = screen.popMenu({"Small","Middle","Grand"})
if(result ~= 255) then
    -- do your stuff
end