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

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

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

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

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