Golang terminal dashboard
Go Other
Latest commit 991cd3d Jan 17, 2017 @gizak committed on GitHub Merge pull request #119 from vitan/master
Typo: renamed DefualtHandler to DefaultHandler
Permalink
Failed to load latest commit information.
_docs Add readthedocs Doc Mar 9, 2016
_example Update table example Jan 16, 2017
debug Update copyright Jan 14, 2017
extra Update copyright Jan 14, 2017
test Update copyright Jan 14, 2017
.gitignore Remove vendor in git Apr 7, 2016
.travis.yml Update travis config Mar 20, 2015
LICENSE Initial commit Feb 3, 2015
README.md Correct table example Jan 14, 2017
barchart.go Update copyright Jan 14, 2017
block.go Update copyright Jan 14, 2017
block_common.go Update copyright Jan 14, 2017
block_test.go Update copyright Jan 14, 2017
block_windows.go Update copyright Jan 14, 2017
buffer.go Update copyright Jan 14, 2017
buffer_test.go Update copyright Jan 14, 2017
canvas.go Update copyright Jan 14, 2017
canvas_test.go Update copyright Jan 14, 2017
config.py Update copyright Jan 14, 2017
doc.go Update copyright Jan 14, 2017
events.go Typo: renamed DefualtHandler to DefaultHandler Jan 17, 2017
events_test.go Update copyright Jan 14, 2017
gauge.go Update copyright Jan 14, 2017
glide.lock Lock deps Nov 3, 2016
glide.yaml Lock deps Nov 3, 2016
grid.go Update copyright Jan 14, 2017
grid_test.go Update copyright Jan 14, 2017
helper.go Update copyright Jan 14, 2017
helper_test.go Update copyright Jan 14, 2017
linechart.go Update copyright Jan 14, 2017
linechart_others.go Update copyright Jan 14, 2017
linechart_windows.go Update copyright Jan 14, 2017
list.go Update copyright Jan 14, 2017
mbarchart.go Update copyright Jan 14, 2017
mkdocs.yml Add readthedocs Doc Mar 9, 2016
par.go Update copyright Jan 14, 2017
par_test.go Update copyright Jan 14, 2017
pos.go Update copyright Jan 14, 2017
pos_test.go Update copyright Jan 14, 2017
render.go Typo: renamed DefualtHandler to DefaultHandler Jan 17, 2017
sparkline.go Update copyright Jan 14, 2017
table.go Update copyright Jan 14, 2017
textbuilder.go Update copyright Jan 14, 2017
textbuilder_test.go Update copyright Jan 14, 2017
theme.go Update copyright Jan 14, 2017
theme_test.go Update copyright Jan 14, 2017
widget.go Update copyright Jan 14, 2017

README.md

termui Build Status Doc Status

demo cast under osx 10.10; Terminal.app; Menlo Regular 12pt.)

termui is a cross-platform, easy-to-compile, and fully-customizable terminal dashboard. It is inspired by blessed-contrib, but purely in Go.

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!)

Installation

master mirrors v2 branch, to install:

go get -u github.com/gizak/termui

It is recommanded to use locked deps by using glide: move to termui src directory then run glide up.

For the compatible reason, you can choose to install the legacy version of termui:

go get gopkg.in/gizak/termui.v1

Usage

Layout

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.

Absolute layout

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:

    import ui "github.com/gizak/termui" // <- ui shortcut, optional

    func main() {
        err := ui.Init()
        if err != nil {
            panic(err)
        }
        defer ui.Close()

        p := ui.NewPar(":PRESS q TO QUIT DEMO")
        p.Height = 3
        p.Width = 50
        p.TextFgColor = ui.ColorWhite
        p.BorderLabel = "Text Box"
        p.BorderFg = ui.ColorCyan

        g := ui.NewGauge()
        g.Percent = 50
        g.Width = 50
        g.Height = 3
        g.Y = 11
        g.BorderLabel = "Gauge"
        g.BarColor = ui.ColorRed
        g.BorderFg = ui.ColorWhite
        g.BorderLabelFg = ui.ColorCyan

        ui.Render(p, g) // feel free to call Render, it's async and non-block

        // event handler...
    }

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).

Grid layout:

grid

Grid layout uses 12 columns grid system with expressive syntax. To use Grid, all we need to do is build a widget tree consisting of Rows and Cols (Actually a Col is also a Row but with a widget endpoint attached).

    import ui "github.com/gizak/termui"
    // init and create widgets...

    // 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)))

    // calculate layout
    ui.Body.Align()

    ui.Render(ui.Body)

Events

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:

    // handle key q pressing
    ui.Handle("/sys/kbd/q", func(ui.Event) {
        // press q to quit
        ui.StopLoop()
    })

    ui.Handle("/sys/kbd/C-x", func(ui.Event) {
        // handle Ctrl + x combination
    })

    ui.Handle("/sys/kbd", func(ui.Event) {
        // handle all other key pressing
    })

    // handle a 1s timer
    ui.Handle("/timer/1s", func(e ui.Event) {
        t := e.Data.(ui.EvtTimer)
        // t is a EvtTimer
        if t.Count%2 ==0 {
            // do something
        }
    })

    ui.Loop() // block until StopLoop is called

Widgets

Click image to see the corresponding demo codes.

par list gauge linechart barchart barchart sparklines table

GoDoc

godoc

TODO

  • Grid layout
  • Event system
  • Canvas widget
  • Refine APIs
  • Focusable widgets

Changelog

License

This library is under the MIT License