README.md
1# termui [](https://travis-ci.org/gizak/termui) [](https://godoc.org/github.com/gizak/termui)
2
3<img src="./_example/dashboard.gif" alt="demo cast under osx 10.10; Terminal.app; Menlo Regular 12pt.)" width="80%">
4
5`termui` is a cross-platform, easy-to-compile, and fully-customizable terminal dashboard. It is inspired by [blessed-contrib](https://github.com/yaronn/blessed-contrib), but purely in Go.
6
7Now version v2 has arrived! It brings new event system, new theme system, new `Buffer` interface and specific colour text rendering. (some docs are missing, but it will be completed soon!)
8
9## Installation
10
11`master` mirrors v2 branch, to install:
12
13 go get -u github.com/gizak/termui
14
15It is recommanded to use locked deps by using [glide](https://glide.sh): move to `termui` src directory then run `glide up`.
16
17For the compatible reason, you can choose to install the legacy version of `termui`:
18
19 go get gopkg.in/gizak/termui.v1
20
21## Usage
22
23### Layout
24
25To use `termui`, the very first thing you may want to know is how to manage layout. `termui` offers two ways of doing this, known as absolute layout and grid layout.
26
27__Absolute layout__
28
29Each widget has an underlying block structure which basically is a box model. It has border, label and padding properties. A border of a widget can be chosen to hide or display (with its border label), you can pick a different front/back colour for the border as well. To display such a widget at a specific location in terminal window, you need to assign `.X`, `.Y`, `.Height`, `.Width` values for each widget before sending it to `.Render`. Let's demonstrate these by a code snippet:
30
31`````go
32 import ui "github.com/gizak/termui" // <- ui shortcut, optional
33
34 func main() {
35 err := ui.Init()
36 if err != nil {
37 panic(err)
38 }
39 defer ui.Close()
40
41 p := ui.NewPar(":PRESS q TO QUIT DEMO")
42 p.Height = 3
43 p.Width = 50
44 p.TextFgColor = ui.ColorWhite
45 p.BorderLabel = "Text Box"
46 p.BorderFg = ui.ColorCyan
47
48 g := ui.NewGauge()
49 g.Percent = 50
50 g.Width = 50
51 g.Height = 3
52 g.Y = 11
53 g.BorderLabel = "Gauge"
54 g.BarColor = ui.ColorRed
55 g.BorderFg = ui.ColorWhite
56 g.BorderLabelFg = ui.ColorCyan
57
58 ui.Render(p, g) // feel free to call Render, it's async and non-block
59
60 // event handler...
61 }
62`````
63
64Note that components can be overlapped (I'd rather call this a feature...), `Render(rs ...Renderer)` renders its args from left to right (i.e. each component's weight is arising from left to right).
65
66__Grid layout:__
67
68<img src="./_example/grid.gif" alt="grid" width="60%">
69
70Grid layout uses [12 columns grid system](http://www.w3schools.com/bootstrap/bootstrap_grid_system.asp) with expressive syntax. To use `Grid`, all we need to do is build a widget tree consisting of `Row`s and `Col`s (Actually a `Col` is also a `Row` but with a widget endpoint attached).
71
72```go
73 import ui "github.com/gizak/termui"
74 // init and create widgets...
75
76 // build
77 ui.Body.AddRows(
78 ui.NewRow(
79 ui.NewCol(6, 0, widget0),
80 ui.NewCol(6, 0, widget1)),
81 ui.NewRow(
82 ui.NewCol(3, 0, widget2),
83 ui.NewCol(3, 0, widget30, widget31, widget32),
84 ui.NewCol(6, 0, widget4)))
85
86 // calculate layout
87 ui.Body.Align()
88
89 ui.Render(ui.Body)
90```
91
92### Events
93
94`termui` ships with a http-like event mux handling system. All events are channeled up from different sources (typing, click, windows resize, custom event) and then encoded as universal `Event` object. `Event.Path` indicates the event type and `Event.Data` stores the event data struct. Add a handler to a certain event is easy as below:
95
96```go
97 // handle key q pressing
98 ui.Handle("/sys/kbd/q", func(ui.Event) {
99 // press q to quit
100 ui.StopLoop()
101 })
102
103 ui.Handle("/sys/kbd/C-x", func(ui.Event) {
104 // handle Ctrl + x combination
105 })
106
107 ui.Handle("/sys/kbd", func(ui.Event) {
108 // handle all other key pressing
109 })
110
111 // handle a 1s timer
112 ui.Handle("/timer/1s", func(e ui.Event) {
113 t := e.Data.(ui.EvtTimer)
114 // t is a EvtTimer
115 if t.Count%2 ==0 {
116 // do something
117 }
118 })
119
120 ui.Loop() // block until StopLoop is called
121```
122
123### Widgets
124
125Click image to see the corresponding demo codes.
126
127[<img src="./_example/par.png" alt="par" type="image/png" width="45%">](https://github.com/gizak/termui/blob/master/_example/par.go)
128[<img src="./_example/list.png" alt="list" type="image/png" width="45%">](https://github.com/gizak/termui/blob/master/_example/list.go)
129[<img src="./_example/gauge.png" alt="gauge" type="image/png" width="45%">](https://github.com/gizak/termui/blob/master/_example/gauge.go)
130[<img src="./_example/linechart.png" alt="linechart" type="image/png" width="45%">](https://github.com/gizak/termui/blob/master/_example/linechart.go)
131[<img src="./_example/barchart.png" alt="barchart" type="image/png" width="45%">](https://github.com/gizak/termui/blob/master/_example/barchart.go)
132[<img src="./_example/mbarchart.png" alt="barchart" type="image/png" width="45%">](https://github.com/gizak/termui/blob/master/_example/mbarchart.go)
133[<img src="./_example/sparklines.png" alt="sparklines" type="image/png" width="45%">](https://github.com/gizak/termui/blob/master/_example/sparklines.go)
134
135## GoDoc
136
137[godoc](https://godoc.org/github.com/gizak/termui)
138
139## TODO
140
141- [x] Grid layout
142- [x] Event system
143- [x] Canvas widget
144- [x] Refine APIs
145- [ ] Focusable widgets
146
147## Changelog
148
149## License
150This library is under the [MIT License](http://opensource.org/licenses/MIT)
151
){kind=link}
){kind=link}
