# screen模块

| 状态 | 最后更新 | API版本 |
| ------ | ------ | ------ |
| Active | 2020-1-7 | V1.00.00 |


## 描述

这个模块提供对屏幕及一些UI控件的访问。

## MainUI
MainUI是一般用户使用表头的地方，一般情况下，表头界面上的所有操作都是由MainUI完成的。当您调用screen.open()时，MainUI进程被挂起，您可能会遇到一些诸如MainUI在screen.close()后没有自动重新渲染，或者在screen.open()后仍有MainUI的控件残留的情况。您可以很容易避免这些问题，这些问题可能会在未来的结构性优化里解决。


## THEME_COLOR

`THEME_COLOR` 是用户设定的主题色。

## 刷新实现
为了避免出现用户可察觉的刷新感，表头实现一个GRAM。
当显示内容发生过更改（如，画一个矩形，显示字符串），且GRAM不再更改时，后台一个进程会将GRAM送到屏幕中完成刷新。
如果您希望在更改后立刻刷新屏幕，请调用`screen.forceUpdate()`函数。



## color
表头实现一个有限颜色的GRAM，您不能选择任意颜色显示，这里是当前的调色板：


| 颜色              | 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 | 常作为背景色使用 |



## font
表头有几种字库，其中有的是部分字库，有的是全字库：


| 字体      | Note                                                         |
| ---------- | ------------------------------------------------------------ |
| font.f1616 | 16*16字体, ASCII字符为半宽。 这包含了常用汉字及日文汉字与假名(请使用UTF-8编码)。 |
| font.f1212 | 12*12字体, ASCII字符为半宽。 这包含了常用汉字及日文汉字与假名(请使用UTF-8编码)。 |
| font.f0508 | 5*8字体, 仅包含ASCII字符。               |
| font.f1424 | 14*24字体, 只有数字和部分字母有包含 (通常用于显示读数)。 |
| font.f2030 | 20*30字体, 字体, 只有数字和部分字母有包含 (通常用于显示读数)。|



## screen.open()

### 描述
打开屏幕，屏幕不再被默认用户界面MainUI占用。

### 参数

nil

### 返回值

nil

### 调用例

```lua
screen.open()
```



## screen.close()

### 描述
关闭屏幕，将控制权转回默认用户界面。

### 参数

nil

### 返回值

nil

### 调用例

```lua
screen.close()
```



## screen.clear()

### 描述

清空屏幕（全黑）。

### 参数

nil

### 返回值

nil

### 调用例

```lua
screen.clear()
```



## screen.drawPoint()

### 描述

在指定位置画指定颜色的点。

### 参数

| 名称 | 类型 | 范围 | 用途 |
| --------- | ------ | ----- | ------------------------------------------------------- |
| <x> | number | 0-159 | 指定x位置                                      |
| <y> | number | 0-127 | 指定y位置                                      |
| [color]   | color  |       | 可选参数，指定颜色,如果不存在 , 颜色为`THEME_COLOR` |

### 返回值

nil

### 调用例

```lua
screen.drawPoint(0,0,color.white)
```



## screen.drawRect()

### 描述

在指定位置画指定颜色的矩形。

### 参数

| 名称 | 类型 | 范围 | 用途 |
| ---------- | ------ | ----- | ------------------------------------------------------- |
| <x1> | number | 0~159 | 指定第一个点的x坐标                                 |
| <y1> | number | 0~127 | 指定第一个点的y坐标                                |
|     <x2>      | number | `x1`~159 | 指定第二个点的x坐标 |
|     <y2>      | number | `y1`~159 | 指定第二个点的y坐标    |
| [color]    | color  |       | 可选参数，指定颜色，如果不存在，颜色为 `THEME_COLOR`|

### 返回值

nil

### 调用例

```lua
screen.drawRect(0,0,159,127,color.white)
```



## screen.fillRect()

### 描述

在指定位置填充指定颜色的矩形。

### 参数

| 名称 | 类型 | 范围 | 用途 |
| ---------- | ------ | -------- | ------------------------------------------------------- |
| <x1> | number | 0~159    | 指定第一个点的x坐标                                |
| <y1> | number | 0~127    | 指定第一个点的y坐标                                |
| <x2> | number | `x1`~159 | 指定第二个点的x坐标                                  |
| <y2> | number | `y1`~159 | 指定第二个点的y坐标                                  |
| [color]    | color  |          | 可选参数，指定颜色，如果不存在，颜色为 `THEME_COLOR` |

### 返回值

nil

### 调用例

```lua
screen.fillRect(0,0,159,127,color.white)
```



## screen.forceUpdate()

### 描述

强制将GRAM送到屏幕，大多数情况下无需使用。

### 参数

nil

### 返回值

nil

### 调用例

```lua
screen.forceUpdate()
```



## screen.showString()

### 描述

在指定位置以指定颜色显示字符串。

### 参数

| 名称 | 类型 | 范围 | 用途 |
| ---------- | ------ | ----- | ------------------------------------------------------- |
| <x1> | number | 0~159 | 指定x起始坐标                               |
| <y1> | number | 0~127 | 指定y起始坐标                               |
| <string>   | string |       | 要显示的字符串 |
|    <font>      | font |       | 指定字体 |
| [foreground_color] | color  |       | 可选参数，指定前景色，若不存在, 前景色为 `THEME_COLOR` |
| [background_color] | color | | 可选参数，指定背景色，若不存在, 背景色为 `THEME_BACK_COLOR` |
| [inverted] | boolean | | 可选参数,指定是否反转显示（即，前景色背景色互换），若不存在，默认不反转 |

### 返回值

nil

### 调用例

```lua
screen.showString(0,0,"Hello World",font.f1616)
```



## screen.printInBox()

### 描述

在一个矩形区域显示字符串。

### 参数

| 名称 | 类型 | 范围 | 用途 |
| ------------------ | ------- | ----- | ------------------------------------------------------------ |
| <x1> | number | 0~159    | 指定范围第一个点的x坐标                                |
| <y1> | number | 0~127    | 指定范围第一个点的y坐标                                |
| <x2> | number | `x1`~159 | 指定范围第二个点的x坐标                                  |
| <y2> | number | `y1`~159 | 指定范围第二个点的y坐标                                  |
| <string>   | string |       | 要显示的字符串 |
|    <font>      | font |       | 要使用的字体 |
| [foreground_color] | color  |       | 可选参数，指定前景色，若不存在, 前景色为 `THEME_COLOR` |
| [background_color] | color | | 可选参数，指定背景色，若不存在, 背景色为 `THEME_BACK_COLOR` |
| [inverted] | boolean | | 可选参数,指定是否反转显示（即，前景色背景色互换），若不存在，默认不反转 |

### 返回值

nil

### 调用例

```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()

### 描述

画一个没有按钮的对话框。

### 参数

| 名称 | 类型 | 范围 | 用途 |
| --------------- | ------- | ----- | ------------------------------------------------------------ |
| <title>   | string  |       | 指定标题                                           |
| [content]       | string  |       | 可选参数，指定内容，如果不存在，则不显示内容 |
| [block_time]    | number  |       | 可选参数, 指定阻塞时间(ms)，如果阻塞时间为0，则函数调用后立刻返回，默认为0（立刻返回） |
| [titleCentered] | boolean |       | 可选参数, 设置标题是否剧中，默认为不居中 |
| [color]         | color   |       | 可选参数, 指定对话框的颜色，如果不存在，颜色为 `THEME_COLOR`                 |

### 返回值

nil

### 调用例

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



## screen.popHint()

### 描述

弹出一个提示框。

### 参数

| 名称 | 类型 | 范围 | 用途 |
| --------------- | ------ | ----- | ------------------------------------------------------------ |
| <content> | string |       | 指定内容。                                         |
| [block_time]    | number |       | 可选参数, 指定显示时间(ms)，若为0，则函数立刻返回，若不为0，等待指定时间后返回，默认立刻返回。 |
| [color]         | color  |       | 可选参数，指定提示框的颜色，如果不存在，颜色为 `THEME_COLOR`              |

### 返回值

nil

### 调用例

```lua
screen.popHint("Hint Box",1000)
```



## screen.popYesOrNo()

### 描述

弹出确认框。

### 参数

| 名称 | 类型 | 范围 | 用途 |
| ------------------ | -------- | ----- | ------------------------------------------------------------ |
| <content>    | string   |       | 提问字符串                                           |
| [color]            | color    |       | 可选参数。 指定对话框的颜色, 如果不存在，颜色为 `THEME_COLOR` |
| [completecallback] | function |       | 可选参数。 指定确认框完成后的回调函数，结果为回调函数调用时的第一个参数。如果不指定，则函数在用户选择后才返回 |

### 返回值

| 名称 | 类型 | 范围 | 用途 |
| -------------- | ------- | ----- | ------------------------------------------------------------ |
| <result> | boolean |       | 结果, `true` 为确认, `false` 为取消。 如果指定了回调函数，返回值无意义 |

### 调用例

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



## screen.popMenu()

### 描述

弹出一个菜单。

### 参数

| 名称 | 类型 | 范围 | 用途 |
| ------------------ | -------- | ----- | ------------------------------------------------------------ |
| <content>    | table    |       | 指定菜单项，最多可有254个菜单项 |
| [color]            | color    |       | 可选参数。 指定菜单的颜色, 如果不存在，颜色为 `THEME_COLOR`  |
| [completecallback] | function |       | 可选参数。 指定确认框完成后的回调函数，结果为回调函数调用时的第一个参数。如果不指定，则函数在用户选择后才返回 |

### 返回值

| 名称 | 类型 | 范围 | 用途 |
| -------------- | ------ | ----- | ------------------------------------------------------------ |
| <result> | number |       | 结果。如果为255，用户双击退出了选择。 |

### 调用例

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