2015-04-21 23:41:52 +08:00
# 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)
2015-03-21 09:11:58 +08:00
2018-09-07 07:55:27 +08:00
< img src = "./_examples/dashboard.gif" alt = "demo cast under osx 10.10; Terminal.app; Menlo Regular 12pt.)" width = "80%" >
2015-06-24 03:11:22 +08:00
2015-10-28 03:24:29 +08:00
`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.
2015-03-21 09:11:58 +08:00
2015-10-29 09:19:35 +08:00
Now 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!)
2015-02-09 01:00:00 +08:00
2015-10-28 03:24:29 +08:00
## Installation
2015-03-16 03:56:38 +08:00
2015-10-28 03:24:29 +08:00
`master` mirrors v2 branch, to install:
2015-03-20 20:24:48 +08:00
2018-09-07 07:55:27 +08:00
```bash
go get -u github.com/gizak/termui
```
2015-03-20 20:24:48 +08:00
2018-08-02 10:30:13 +08:00
It is recommanded to use locked deps by using [dep ](https://golang.github.io/dep/ ): move to `termui` src directory then run `dep ensure` .
2016-04-07 09:41:23 +08:00
2015-10-28 03:24:29 +08:00
For the compatible reason, you can choose to install the legacy version of `termui` :
2015-03-20 20:24:48 +08:00
2018-09-07 07:55:27 +08:00
```bash
go get gopkg.in/gizak/termui.v1
```
2015-03-16 03:56:38 +08:00
2015-10-28 03:24:29 +08:00
## Usage
2015-02-09 01:00:00 +08:00
2015-10-28 03:24:29 +08:00
### Layout
2015-02-09 01:00:00 +08:00
2015-10-28 03:24:29 +08:00
To 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.
2015-02-09 01:00:00 +08:00
2018-09-07 07:55:27 +08:00
**Absolute layout**
2015-02-09 01:07:18 +08:00
2016-02-21 08:48:06 +08:00
Each 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:
2015-02-09 01:00:00 +08:00
2018-09-07 07:55:27 +08:00
```go
2015-02-09 01:00:00 +08:00
import ui "github.com/gizak/termui" // < - ui shortcut , optional
func main() {
err := ui.Init()
if err != nil {
panic(err)
}
defer ui.Close()
2015-03-12 04:51:18 +08:00
p := ui.NewPar(":PRESS q TO QUIT DEMO")
2015-02-09 01:00:00 +08:00
p.Height = 3
p.Width = 50
p.TextFgColor = ui.ColorWhite
2015-10-28 03:24:29 +08:00
p.BorderLabel = "Text Box"
p.BorderFg = ui.ColorCyan
2015-02-09 01:00:00 +08:00
g := ui.NewGauge()
g.Percent = 50
g.Width = 50
g.Height = 3
g.Y = 11
2015-12-04 15:32:04 +08:00
g.BorderLabel = "Gauge"
2015-02-09 01:00:00 +08:00
g.BarColor = ui.ColorRed
2015-10-28 03:24:29 +08:00
g.BorderFg = ui.ColorWhite
g.BorderLabelFg = ui.ColorCyan
2015-02-09 01:00:00 +08:00
2015-10-28 03:24:29 +08:00
ui.Render(p, g) // feel free to call Render, it's async and non-block
2015-02-09 01:00:00 +08:00
// event handler...
}
2018-09-07 07:55:27 +08:00
```
2015-02-09 01:00:00 +08:00
2015-03-12 04:15:59 +08:00
Note 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).
2018-09-07 07:55:27 +08:00
**Grid layout:**
2015-03-12 04:15:59 +08:00
2018-09-07 07:55:27 +08:00
< img src = "./_examples/grid.gif" alt = "grid" width = "60%" >
2015-10-28 03:29:37 +08:00
2016-02-21 08:56:35 +08:00
Grid 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).
2015-03-12 04:15:59 +08:00
2015-03-12 04:22:55 +08:00
```go
2015-10-28 03:24:29 +08:00
import ui "github.com/gizak/termui"
// init and create widgets...
2015-03-14 01:20:17 +08:00
2015-10-28 03:24:29 +08:00
// build
ui.Body.AddRows(
ui.NewRow(
ui.NewCol(6, 0, widget0),
ui.NewCol(6, 0, widget1)),
ui.NewRow(
ui.NewCol(3, 0, widget2),
ui.NewCol(3, 0, widget30, widget31, widget32),
ui.NewCol(6, 0, widget4)))
2015-03-14 01:20:17 +08:00
2015-10-28 03:24:29 +08:00
// calculate layout
ui.Body.Align()
2015-03-14 01:20:17 +08:00
2015-10-28 03:24:29 +08:00
ui.Render(ui.Body)
```
2015-03-14 01:20:17 +08:00
2015-10-28 03:24:29 +08:00
### Events
2015-03-14 01:20:17 +08:00
2015-10-28 03:24:29 +08:00
`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:
2015-03-14 01:20:17 +08:00
2015-10-28 03:24:29 +08:00
```go
// handle key q pressing
2015-12-26 21:25:35 +08:00
ui.Handle("/sys/kbd/q", func(ui.Event) {
2015-10-28 03:24:29 +08:00
// press q to quit
2015-12-26 21:25:35 +08:00
ui.StopLoop()
2015-10-28 03:24:29 +08:00
})
2015-12-26 21:25:35 +08:00
ui.Handle("/sys/kbd/C-x", func(ui.Event) {
2015-10-28 03:24:29 +08:00
// handle Ctrl + x combination
})
2015-12-26 21:25:35 +08:00
ui.Handle("/sys/kbd", func(ui.Event) {
2015-10-28 03:24:29 +08:00
// handle all other key pressing
})
// handle a 1s timer
2015-12-26 21:25:35 +08:00
ui.Handle("/timer/1s", func(e ui.Event) {
t := e.Data.(ui.EvtTimer)
2015-10-28 03:24:29 +08:00
// t is a EvtTimer
if t.Count%2 ==0 {
// do something
}
})
2015-04-28 08:27:11 +08:00
2015-10-28 03:24:29 +08:00
ui.Loop() // block until StopLoop is called
```
2015-04-28 08:27:11 +08:00
2015-10-28 03:24:29 +08:00
### Widgets
2015-03-14 01:20:17 +08:00
2015-10-28 03:24:29 +08:00
Click image to see the corresponding demo codes.
2015-03-14 01:20:17 +08:00
2018-09-07 07:55:27 +08:00
[<img src="./_examples/par.png" alt="par" type="image/png" width="45%"> ](https://github.com/gizak/termui/blob/master/_examples/par.go )
[<img src="./_examples/list.png" alt="list" type="image/png" width="45%"> ](https://github.com/gizak/termui/blob/master/_examples/list.go )
[<img src="./_examples/gauge.png" alt="gauge" type="image/png" width="45%"> ](https://github.com/gizak/termui/blob/master/_examples/gauge.go )
[<img src="./_examples/linechart.png" alt="linechart" type="image/png" width="45%"> ](https://github.com/gizak/termui/blob/master/_examples/linechart.go )
[<img src="./_examples/barchart.png" alt="barchart" type="image/png" width="45%"> ](https://github.com/gizak/termui/blob/master/_examples/barchart.go )
[<img src="./_examples/mbarchart.png" alt="barchart" type="image/png" width="45%"> ](https://github.com/gizak/termui/blob/master/_examples/mbarchart.go )
[<img src="./_examples/sparklines.png" alt="sparklines" type="image/png" width="45%"> ](https://github.com/gizak/termui/blob/master/_examples/sparklines.go )
[<img src="./_examples/table.png" alt="table" type="image/png" width="45%"> ](https://github.com/gizak/termui/blob/master/_examples/table.go )
2015-02-09 01:00:00 +08:00
## GoDoc
2015-03-14 01:26:51 +08:00
[godoc ](https://godoc.org/github.com/gizak/termui )
2015-02-09 01:00:00 +08:00
2015-03-14 01:20:17 +08:00
## TODO
2015-03-20 20:24:48 +08:00
- [x] Grid layout
2015-10-28 03:24:29 +08:00
- [x] Event system
- [x] Canvas widget
- [x] Refine APIs
2015-03-20 20:24:48 +08:00
- [ ] Focusable widgets
2015-03-14 01:20:17 +08:00
2015-10-28 03:24:29 +08:00
## Changelog
2015-02-09 01:00:00 +08:00
## License
2018-09-07 07:55:27 +08:00
2015-02-09 01:00:00 +08:00
This library is under the [MIT License ](http://opensource.org/licenses/MIT )