1# termui [![Build Status](https://travis-ci.org/gizak/termui.svg?branch=master)](https://travis-ci.org/gizak/termui) [![Doc Status](https://godoc.org/github.com/gizak/termui?status.png)](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