『Golang』跨平台TUI（基于文字的用户界面）库Terbox-Go文档翻译

时间：2022-03-09 04:42:29

原文

package termbox

import "github.com/nsf/termbox-go"

termbox-go 是一个用于创建跨平台TUI（基于文本的用户界面）的库。

索引

包文件

api.go

api_common.go

syscalls_linux.go

termbox.go

termbox_common.go

terminfo.go

terminfo_builtin.go

变量

var (

    IsInit bool = false

)

查看termbox是否已经被初始化。

func CellBuffer 

func CellBuffer() []Cell

返回一个slice到termbox的后台缓存。你可以使用Size方法来获取后台缓存的大小。如果调用当前方法后，没有使用Clear或Flush方法清理缓存，后台缓存的Slice将会一直存在。

func Clear 

func Clear(fg, bg Attribute) error

清理内部后台缓存。

func Close 

func Close()

当termbox已经被成功初始化且termbox的方法不再被需要的时候，调用这个方法来终止termbox库。

func Flush 

func Flush() error

与终端同步内部后台缓存。

func HideCursor 

func HideCursor()

设置SetCursor(-1,-1)的快捷键。

func Init 

func Init() error

初始化termbox库。这个方法需要在其他方法之前被调用。在成功过初始化后，库必须使用Close方法结束。

示例:

err := termbox.Init()

if err != nil {

        panic(err)

}

defer termbox.Close()

func Interrupt 

func Interrupt()

通过返回一个EventInterrupt来终止一个正在进行中的到PollEvent的调用。需要注意的是，这个方法在PollEvent方法被成功中断前，将会被阻塞。

func SetCell 

func SetCell(x, y int, ch rune, fg, bg Attribute)

在指定的位置改变内部后台缓存中单元格的参数。

func SetCursor 

func SetCursor(x, y int)

设置光标的位置。参见HideCursor()

func Size 

func Size() (int, int)

返回内部缓存的大小（几乎与终端窗口尺寸同样大小）。但是当终端的大小被改变后，它并不总是与终端窗口的大小一致，内部后台缓存仅仅在Clear或Flush方法调用后才会获得同步。

func Sync 

func Sync() error

当有事务引起termbox对于终端缓存和实际情况的解析不同步时，立即同步。

type Attribute

type Attribute uint16
const (

    ColorDefault Attribute = iota

    ColorBlack

    ColorRed

    ColorGreen

    ColorYellow

    ColorBlue

    ColorMagenta

    ColorCyan

    ColorWhite

)

单元格颜色，你可以通过使用bitwise或|混合多个属性。

const (

    AttrBold Attribute = 1 << (iota + 9)

    AttrUnderline

    AttrReverse

)

单元格属性，通过使用bitwise或|来混合多个属性。虽然颜色不能被混合，但是你可以混合多个属性和一个独立的颜色。

值得一提的是，一些平台不支持某些的属性。例如Windows Console不支持下划线属性。在一些终端上，应用AttrBold到背景，可能会引起文字的闪烁。小心的使用他们，并且在不同的终端上测试你的代码。

type Cell 

type Cell struct {

    Ch  rune

    Fg  Attribute

    Bg  Attribute

}

一个单元格，在屏幕上的独立概念实体。屏幕是基于单元格的一个2d数组。Ch是一个unicode字符，Fg和Bg是前景和背景属性。

type Event 

type Event struct {

    Type   EventType // one of Event* constants

    Mod    Modifier  // one of Mod* constants or 0

    Key    Key       // one of Key* constants, invalid if 'Ch' is not 0

    Ch     rune      // a unicode character

    Width  int       // width of the screen

    Height int       // height of the screen

    Err    error     // error in case if input failed

    MouseX int       // x coord of mouse

    MouseY int       // y coord of mouse

}

此类型描述一个termbox事件。Mod、Key以及Ch字段是对Type是否是一个键值事件的验证。Width和Height字段是对于Type是否是重置重置的验证。Err字段是对于Type是否是错误事件的验证。

func PollEvent 

func PollEvent() Event

等待一个事件，并返回它。这事一个阻塞方法调用。

type EventType 

type EventType uint8
const (

    EventKey EventType = iota

    EventResize

    EventMouse

    EventError

    EventInterrupt

)

指示事件类型，祥见Event.Type字段。

type InputMode 

type InputMode int
const (

    InputEsc InputMode = 1 << iota

    InputAlt

    InputMouse

    InputCurrent InputMode = 0

)

输入模式，详见SetInputMode方法。

func SetInputMode 

func SetInputMode(mode InputMode) InputMode

设置termbox输入模式。Termbox有两种输入模式：

  1. Esc输入模式。当ESC在缓冲序列当中，并且它与任何已知的序列匹配。ESC表示KeyEsc（ESC键值）。此为默认的输入模式。
  2. Alt输入模式。当ESC在缓冲序列当中，并且它与任何已知的序列匹配。ESC为下一个键盘事件启用ModAlt修改器。

这两个模式都可以与Mouse模式混用。设置Mouse模式将启用鼠标点击事件。

如果mode是InputCurrent，返回当前的输入模式。详见输入模式与Input*常量。

type Key 

type Key uint16
const (

    KeyF1 Key = 0xFFFF - iota

    KeyF2

    KeyF3

    KeyF4

    KeyF5

    KeyF6

    KeyF7

    KeyF8

    KeyF9

    KeyF10

    KeyF11

    KeyF12

    KeyInsert

    KeyDelete

    KeyHome

    KeyEnd

    KeyPgup

    KeyPgdn

    KeyArrowUp

    KeyArrowDown

    KeyArrowLeft

    KeyArrowRight

    MouseLeft

    MouseMiddle

    MouseRight

)

键值常量，详见Event.Key字段。

const (

    KeyCtrlTilde      Key = 0x00

    KeyCtrl2          Key = 0x00

    KeyCtrlSpace      Key = 0x00

    KeyCtrlA          Key = 0x01

    KeyCtrlB          Key = 0x02

    KeyCtrlC          Key = 0x03

    KeyCtrlD          Key = 0x04

    KeyCtrlE          Key = 0x05

    KeyCtrlF          Key = 0x06

    KeyCtrlG          Key = 0x07

    KeyBackspace      Key = 0x08

    KeyCtrlH          Key = 0x08

    KeyTab            Key = 0x09

    KeyCtrlI          Key = 0x09

    KeyCtrlJ          Key = 0x0A

    KeyCtrlK          Key = 0x0B

    KeyCtrlL          Key = 0x0C

    KeyEnter          Key = 0x0D

    KeyCtrlM          Key = 0x0D

    KeyCtrlN          Key = 0x0E

    KeyCtrlO          Key = 0x0F

    KeyCtrlP          Key = 0x10

    KeyCtrlQ          Key = 0x11

    KeyCtrlR          Key = 0x12

    KeyCtrlS          Key = 0x13

    KeyCtrlT          Key = 0x14

    KeyCtrlU          Key = 0x15

    KeyCtrlV          Key = 0x16

    KeyCtrlW          Key = 0x17

    KeyCtrlX          Key = 0x18

    KeyCtrlY          Key = 0x19

    KeyCtrlZ          Key = 0x1A

    KeyEsc            Key = 0x1B

    KeyCtrlLsqBracket Key = 0x1B

    KeyCtrl3          Key = 0x1B

    KeyCtrl4          Key = 0x1C

    KeyCtrlBackslash  Key = 0x1C

    KeyCtrl5          Key = 0x1D

    KeyCtrlRsqBracket Key = 0x1D

    KeyCtrl6          Key = 0x1E

    KeyCtrl7          Key = 0x1F

    KeyCtrlSlash      Key = 0x1F

    KeyCtrlUnderscore Key = 0x1F

    KeySpace          Key = 0x20

    KeyBackspace2     Key = 0x7F

    KeyCtrl8          Key = 0x7F

)

type Modifier 

type Modifier uint8
const (

    ModAlt Modifier = 0x01

)

Alt修改常量，祥见Event.Mod字段与SetInputMode方法。

type OutputMode 

type OutputMode int
const (

    OutputCurrent OutputMode = iota

    OutputNormal

    Output256

    Output216

    OutputGrayscale

)

输出模式。详见SetOutputMode方法。

func SetOutputMode

func SetOutputMode(mode OutputMode) OutputMode

设置termbox输出模式。Termbox有四种输出选项：

  1. OutputNormal => [1..8]
此模式提供8个不同的颜色：

    黑，红，绿，黄，蓝，品红，蓝绿色，白

快捷方式：ColorBlack，ColorRec，……

属性：AttrBold，AttrUnderline，AttrReverse

示例：

    SetCell(x, y, '@', ColorBlack | AttrBold, ColorRed);
  1. Output256 => [1..256]
此模式你可以使用256色的终端模式：

0x00 - 0x07: 与OutputNormal一致的8个颜色

0x08 - 0x0f: Color* 或 AttrBold

0x10 - 0xe7: 216种不同的颜色

0xe8 - 0xff: 24种灰度

示例：

    SetCell(x, y, '@', 184, 240);

    SetCell(x, y, '@', 0xb8, 0xf0);
  1. Output216 => [1..216]

此种模式仅仅支持256色模式的第三种情况。但是你不需要提供偏移。

  1. OutputGrayscale => [1..24]

这个模式仅仅支持256色模式的第四种情况。但是你不需要提供偏移。在所有模式中0表示默认的颜色。

使用go run _demos/output.go查看它在你终端的响应。

如果mode是OutputCurrent它返回当前的输出模式。

需要注意的是，这将会返回一个不同的OutputMode超过一个请求，当请求模式也许在目标平台上不可用时。

相关文章