Golang terminal dashboard (evacuated from NSA/Microsoft Github)

anonymous af568e536b nitpick who maintains 5 months ago
_docs 91b776e7aa packaging 10 months ago
_example 8d977ebe58 typo? 5 months ago
_test de04c28ea9 no longer build test by default, minor tweaks 9 months ago
debian af568e536b nitpick who maintains 5 months ago
debug 1fd509e58d Fix https://github.com/gizak/termui/issues/97 2 years ago
extra 91b776e7aa packaging 10 months ago
.travis.yml bffab774f5 Update travis config 4 years ago
LICENSE fff745a9a0 Initial commit 4 years ago
README.md 91b776e7aa packaging 10 months ago
barchart.go ba69a564f2 Fix a couple small typos 2 years ago
block.go d921faeffe Update copyright 2 years ago
block_common.go d921faeffe Update copyright 2 years ago
block_test.go d921faeffe Update copyright 2 years ago
block_windows.go 6d9a109edf add missing characters 2 years ago
buffer.go d921faeffe Update copyright 2 years ago
buffer_test.go d921faeffe Update copyright 2 years ago
canvas.go d921faeffe Update copyright 2 years ago
canvas_test.go d921faeffe Update copyright 2 years ago
config.py d921faeffe Update copyright 2 years ago
doc.go d22d4fac69 de-githubbing 7 months ago
events.go 3b3aa549db expose ResetHandlers 2 years ago
events_test.go d921faeffe Update copyright 2 years ago
gauge.go d921faeffe Update copyright 2 years ago
glide.yaml 91b776e7aa packaging 10 months ago
grid.go d22d4fac69 de-githubbing 7 months ago
grid_test.go d921faeffe Update copyright 2 years ago
helper.go ba69a564f2 Fix a couple small typos 2 years ago
helper_test.go d921faeffe Update copyright 2 years ago
linechart.go 0f42a2ee00 Merge branch 'martinlindhe-linechart-auto-height' 1 year ago
linechart_others.go d921faeffe Update copyright 2 years ago
linechart_windows.go d921faeffe Update copyright 2 years ago
list.go d22d4fac69 de-githubbing 7 months ago
mbarchart.go 23118e571a spelling: previous 3 years ago
mkdocs.yml 91b776e7aa packaging 10 months ago
par.go d921faeffe Update copyright 2 years ago
par_test.go d921faeffe Update copyright 2 years ago
pos.go d921faeffe Update copyright 2 years ago
pos_test.go d921faeffe Update copyright 2 years ago
render.go 8ae812e738 building, but empty debian package 10 months ago
sparkline.go 6b3d91f8d1 spelling: sparklines 3 years ago
table.go d921faeffe Update copyright 2 years ago
textbuilder.go d921faeffe Update copyright 2 years ago
textbuilder_test.go d921faeffe Update copyright 2 years ago
theme.go d921faeffe Update copyright 2 years ago
theme_test.go d921faeffe Update copyright 2 years ago
widget.go d921faeffe Update copyright 2 years ago

README.md

termui

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

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 "notabug.org/themusicgod1/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 "notabug.org/themusicgod1/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

License

This library is under the MIT License