gizak / termui

Golang terminal dashboard

termui

termui is a cross-platform and fully-customizable terminal dashboard and widget library built on top of termbox-go. It is inspired by blessed-contrib and tui-rs and written purely in Go.

Note

Please be aware that due to my fluctuating availability, the frequency of updates to this project may not always follow a consistent schedule. I would like to invite potential maintainers to contribute to this project. If you are interested in becoming a maintainer, please do not hesitate to reach out to me.

Versions

termui is currently compatible with Go 1.15 (as in go.mod) and above (tracking the Debian's oldstable). Please use the version-numbered branch as stable release. The new changes will be pushed to master branch first and then merge to version branch.

Features

• Several premade widgets for common use cases
• Easily create custom widgets
• Position widgets either in a relative grid or with absolute coordinates
• Keyboard, mouse, and terminal resizing events
• Colors and styling

Installation

Go modules

It is not necessary to go get termui, since Go will automatically manage any imported dependencies for you. Do note that you have to include /v3 in the import statements as shown in the 'Hello World' example below.

Dep

Add with dep ensure -add github.com/gizak/termui. With Dep, /v3 should not be included in the import statements.

Hello World

package main

import (
	"log"

	ui "github.com/gizak/termui/v3"
	"github.com/gizak/termui/v3/widgets"
)

func main() {
	if err := ui.Init(); err != nil {
		log.Fatalf("failed to initialize termui: %v", err)
	}
	defer ui.Close()

	p := widgets.NewParagraph()
	p.Text = "Hello World!"
	p.SetRect(0, 0, 25, 5)

	ui.Render(p)

	for e := range ui.PollEvents() {
		if e.Type == ui.KeyboardEvent {
			break
		}
	}
}

Widgets

• BarChart
• Canvas (for drawing braille dots)
• Gauge
• Image
• List
• Tree
• Paragraph
• PieChart
• Plot (for scatterplots and linecharts)
• Sparkline
• StackedBarChart
• Table
• Tabs

Run an example with go run _examples/{example}.go or run each example consecutively with make run-examples.

Documentation

• wiki

Uses

• dockdash
• expvarmon
• go-ethereum/monitorcmd
• go-jira-ui
• gotop
• termeter
• updo

Related Works

• blessed-contrib
• gocui
• termdash
• tui-rs
• tview

License

MIT

termui's Issues

EditBox / Input / Text editing

Hi,

Is there an easy way to make an edit box with termui ?

Tks,

Suggestion: plain-text configuration

This is a surprising and awesome tool, but you need to write Go to use it.

Reading widgets from a configuration file, in any popular format, would make the tool easier to configure and available to a much larger range of developers.

Does not support Windows?

rt...

Inability to plot datapoints with both coordinates defined.

Your library's rather neat, but it appears that LineChart currently determines the X-axis coordinate of a given datapoint by itself. If I'm not missing something, there seems to be no way to go about plotting a dataset where all the datapoints have both their X and Y coordinates predefined.

Are there any plans to implement this capability?

panic: open /dev/tty: device not configured

Panic when List height is less than 2 (and borders are enabled)

Hi,

I've found an issue with Lists. The following code will generate a panic:

package main

import "github.com/gizak/termui"
import "github.com/nsf/termbox-go"

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

    termui.UseTheme("helloworld")

    ls := termui.NewList()
    ls.Items = []string{"[0] github.com/gizak/termui"}
    ls.Width = 25
    ls.Height = 1

    termui.Render(ls)
    termbox.PollEvent()
}

panic: runtime error: slice bounds out of range

goroutine 1 [running]:
github.com/gizak/termui.(*List).Buffer(0xc208066000, 0x0, 0x0, 0x0)
    /home/warmans/go/src/github.com/gizak/termui/list.go:82 +0x490
github.com/gizak/termui.Render(0xc20805af50, 0x1, 0x1)
    /home/warmans/go/src/github.com/gizak/termui/render.go:51 +0xc7
main.main()
    /home/warmans/go/src/github.com/gizak/termui/example/list.go:26 +0x1fc

goroutine 5 [runnable]:
os/signal.loop()
    /home/warmans/Downloads/go/src/os/signal/signal_unix.go:21 +0x1f
created by os/signal.init·1
    /home/warmans/Downloads/go/src/os/signal/signal_unix.go:27 +0x35
exit status 2

line 82 of list is:

trimItems = trimItems[:l.innerHeight]

It would seem that l.innerHeight is set to -1 which prevents the slice from working. I believe the reason for this is that it deducts 2 from Height for the top and bottom border to get innerHeight. As such setting the Height to 2 will avoid the error. This is fine if you understand that the borders contribute to the height but is a bit unintuitive, particularly when the heights are calculated dynamically.

The following code prevents the error but renders a blank list

if l.innerHeight < 0 {
    trimItems = make([]string, 0)
} else {
    if len(trimItems) > l.innerHeight {
        trimItems = trimItems[:l.innerHeight]
    }
}

New feature : List - color per line

Hi,

It would be nice to be able to define a line (per line) color in the widget list.

Thks !

termbox-go copyright notice on events.go

Noticed events.go uses source from termbox-go, you might want to make sure their license appears somewhere relevant. Perhaps appending their license to your own LICENSE file and preceding it with something like "Portions of this library uses source from termbox-go under the following license".

Line chart renders incorrectly if initialized with empty dataset

If a line chart starts with no values and values are added later the points are drawn into the title line.

For example:

    writeLatency := ui.NewLineChart()
    writeLatency.Border.Label = "Write Latency"
    writeLatency.Data = []float64{} //no values
    writeLatency.Height = 10
    writeLatency.AxesColor = ui.ColorWhite
    writeLatency.LineColor = ui.ColorGreen

        //now start updating 

Feature Request: popup dialog

I am using your nice library for a dashboard.

To keep the error handling simple I channel all errors to the same place. It would be nice to be able to show the current error in a popup using the same select loop, showing it over rest of the layout.

New widgets

Hi,

Have-you got a roadmap with futurs widgets ?

Ball, Triangle, ...

Feature Request: Text wrapping

I'd love some sort of text wrapping; I can't figure out how to get text to wrap automatically without breaking in the middle of words. Thanks!

Windows sparklines show question marks for lines

Windows sparklines from master look like this:

Flickering render

I just upgraded my project (https://github.com/byrnedo/dockdash/tree/feature/new_termui) to the latest termui. Maybe not according to best practices but just to make an easy first port I've done the following:

I have one main select loop where I hold state ( up/down position, displayable data... )
All my key handlers are signalling to a channel which is read by this select.
Any data updates are also sent to a channel which is read by the select as well.
Any of these events will trigger a render.
I also have a timer (1s) running which signals another channel also read by this select which renders.

The basic rendering flow I have is the same as before I upgraded ( ie all rendering is done in the same select ).

I'm experiencing flickering now though with every render.

Is there a likely cause of this? I see that the rendering in termui is now done in a routine ( perhaps it was before too?)

EDIT:

I notice it gets worse the larger the size of the terminal window.

Data race

When just running init and the main event loop I get a data race.

WARNING: DATA RACE
Read by goroutine 9: github.com/gizak/termui.hookTermboxEvt()                                                                                                     /home/vrecan/go/src/github.com/gizak/termui/events.go:132 +0xba
                                                                                                                                                                   Previous write by main goroutine:                                                                                                                                                                                                       github.com/gizak/termui.Init()                                                                                                                                                                                       /home/vrecan/go/src/github.com/gizak/termui/render.go:40 +0x3d0                                                                                                                                                                                                                                                                                                             main.main()                                                                                                                                                                                                                    /home/vrecan/go/src/github.com/vrecan/FluxDash/fluxDash.go:25 +0x104
 Goroutine 9 (running) created at: github.com/gizak/termui.Init()
/home/vrecan/go/src/github.com/gizak/termui/render.go:28 +0x12d
main.main()
/home/vrecan/go/src/github.com/vrecan/FluxDash/fluxDash.go:25 +0x104

Some explanation of how it was done?

The project looks fantastic.

It would be cool if there were some WIKI page explaining how it was done :).

Mac: Can't select text in any term window after running a termui app for a while

I've written a new app using termui, which is marvellous. Unfortunately I've found that I can't select text with the mouse in any terminal window after running termui for a while. This has happened to two people so far, both using Macs. The problem doesn't disappear when the app is terminated - you need to quit out of term and restart.

Any ideas? What information can I give you?

Grid.gif shows traces of gridlayout bug

So there is border misalignment in the demo gif, remains of fixed bug, and it doesn't look good.

API stabilization/versioning

With incoming refactoring there appears to be API-breaking changes.

I propose using something like gopkg.in of gopkgs.com to pin down current API as v1, and then go on with breaking changes as v2.

Max value in sparkline/multivalue chart

hi,

i'm using your library for https://github.com/ulrichSchreiner/dockmon. it would be great to have

• a max value for sparklines. i render the CPU value with sparklines. it would be great to set the maxvalue for sparklines to a specific value because i know the maximal value and so the sparklines would be comparable.
• another great option would be a chart widget with multiple lines in differen colors. so i could render all cpu-values in one diagram. or should i use a canvas for this?

thx, your library is great

Feature Request:GUI Builder

Hi, do you mind doing a winforms style GUI builder for this? Golang is really lacking in decent native easy-to-use GUI libraries and termui seems to fit this niche perfectly. Thanks in advance!

Can't insert DataLabels after Render

hello,

is this char able to do like below:

bc.DataLabels = append(bc.DataLabels,"S6")
termui.Render(bc)

thx

Run under Tmux ??

On Ubuntu 14.04 - everything looks great in Terminator (xterm).

But - from Tmux 1.9a the screen looks bad. Anyone have any luck running termui under Tmux??

Add possibility to add Rows/Cols dynamically to the Grid.

The Grid layout idea is amazing, but here is the situation that cannot be solved with current design: adding arbitrary number of Rows/Cols, calculating it's number dynamically.

I can do:

col1 := termui.NewCol()
col2 := termui.NewCol()
termui.NewRow(col1, col2)

but if I need to create 4 or 10 cols, depending on some state, I cannot create slice of termui.*row, because it's unexported.

So, here are two most obvious solutions:

• make row type exported
• add new functions for that, like AddCol()

Maybe there is another way to accomplish that? Or should we wait until refactoring branch will be merged and it will have Grid redesigned?

Screen flicker every one second.

When I run dashboard demo ,my screen flicker every one second when screen is rerender.

I use putty to login Ubuntu 14.

It also occurred on my MacBook Pro with Mac OS X 10.10.

I will upload an gif picture to show the issue.

Make Block.inner* values public

I'm currently writing a rich text widget which has a cursor and allows input, essentially allowing text editing using this library.

Basic functionality is already there but I'm not able to cleanly embed Block into my widget because the innerX, innerY, innerWidth and innerHeight values are all private.

If you're happy to make them public somehow, would you prefer just expose the properties, or expose them through methods like InnerX() etc.? Or perhaps an InnerBounds() (x, y, width, height int) method to get them all at once?

If you're happy with one of those I'll throw something together and make a PR.

Feature request: "Table" widget

This is really cool, but do you know what would make it cooler? A table widget! Maybe something like https://github.com/olekukonko/tablewriter

undefined: termui.EventCh, termui.EventKey

A bit new to Go. I've imported the library, then I've ran go run against the grid.go example, but I'm getting undefined errors.

Have the examples not been updated lately or is this a noob mistake?

❯ go get github.com/gizak/termui

~/test   
❯ go run grid.go 
# command-line-arguments
./grid.go:101: undefined: termui.EventCh
./grid.go:107: undefined: termui.EventKey

Thanks for being patient with me!

Handle timers

Hi,

how is handling timers supposed to work with new API?

Initially I thought, Handle("/timer/Ns") or Handle("/timer/200ms") should work, but it works only with 1s timer and it seems to be hardcoded or am I missing something?

utf8 characters problem

I've run the examples with utf8(Chinese) characters, but can't see right result. How to fix that? thanks.

Screen blinking on each refresh

Hello!
When I refresh data on the screen via ui.Render(...) I see blinking. How can I avoid this?

Parameters for ic50 plot need consistant name

change is necessary for ic50plot.js
and for database

Is it possible to get more colors then are in termui.Attribute (e.x. purple)?

And how would I do that?

TextFgColor and TextBgColor of termui.Par seem to only accept termui.Attribute, which is a uint16, and I've tried random uint16 numbers but that doesn't seem to work.

Get Current Theme

Is there any reason why the variable for getting the current theme is not exported?

This makes creating custom widgets impossible...

How can I implement a 'list' to handle upcoming strings (eg. log info pipeline)?

example ttop: not building, leaking goroutines

a302a52/_example/ttop.go#L351 - each time first case happens, another one of time.After channels gets permanently blocked.
Also, uses extra instead of _extra for import and in general v1 api.

Is it possible to align 2 or more paragraphs next to each other horizontally as if they were a single paragraph?

And if so, how would I do it? (I'm new to terminal ui in general)

I generate the paragraphs like so:

...
    var pars []*ui.Par
    for i := 0; i < len(blocks); i++ {
      b := ""
      for x := 0; x < blocks[i]; x++ {
        b += "#"
      }
      par0 := ui.NewPar(b)
      par0.HasBorder = false
      par0.Height = 1
      pars = append(pars, par0)
    }
...

Then I put it in a column:

...
    // build layout
    ui.Body.AddRows(
      ui.NewRow(
        ui.NewCol(3, 0, gs[0])))
    ui.Body.AddRows(
      ui.NewRow(
        ui.NewCol(3, 0, pars[0], pars[1], pars[2])))
    ui.Body.AddRows(
      ui.NewRow(
        ui.NewCol(3, 0, par)))
    // calculate layout
    ui.Body.Align()
...

And get the following results:

And as you can see the ####'s are in 3 lines and not one.

I need this because eventually I'll want to have separate colors for different parts of the paragraph/seemingly-singular-paragraph (or is that maybe possible with a single paragraph?)

Label not shown or incorrect while Gauge.X is set higher than 0

g = termui.NewGauge()
g.Width = 30
g.Height = 3
g.X = 30
termui.Render(g)

The percent label display incorrectly.

According to gaugo.go, pos of label is not play with g.innerX, that's issue.

LineChart Y-Axis doesn't scale

The scale will start at 0 no matter what. If you have values, in say, the 40-60 range, they will get smashed into a tiny part of the range which will be from 0-60.

Panic on resize.

In any terminal, if I try to resize, termui.v2 app panics with:

panic: bytes.Buffer: truncation out of range

goroutine 416 [running]:
bytes.(*Buffer).Truncate(0x69ac60, 0x0)
    /usr/lib/go/src/bytes/buffer.go:69 +0xbf
bytes.(*Buffer).WriteTo(0x69ac60, 0x7fd1fb362510, 0xc8200320c0, 0xae8, 0x0, 0x0)
    /usr/lib/go/src/bytes/buffer.go:222 +0x1af
io.copyBuffer(0x7fd1fb362510, 0xc8200320c0, 0x7fd1fb362538, 0x69ac60, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0)
    /usr/lib/go/src/io/io.go:371 +0xd0
io.Copy(0x7fd1fb362510, 0xc8200320c0, 0x7fd1fb362538, 0x69ac60, 0xc820101da8, 0x0, 0x0)
    /usr/lib/go/src/io/io.go:351 +0x64
github.com/nsf/termbox-go.flush(0x0, 0x0)
    /home/nho/golang/src/github.com/nsf/termbox-go/termbox.go:234 +0x96
github.com/nsf/termbox-go.Flush(0x0, 0x0)
    /home/nho/golang/src/github.com/nsf/termbox-go/api.go:200 +0x224
github.com/nsf/termbox-go.Sync(0x0, 0x0)
    /home/nho/golang/src/github.com/nsf/termbox-go/api.go:458 +0x61
gopkg.in/gizak/termui%2ev2.TermWidth(0x0)
    /home/nho/golang/src/gopkg.in/gizak/termui.v2/render.go:65 +0x18
main.main.func6(0x5b64c0, 0x6, 0x5b7ba0, 0xf, 0x5b6238, 0x7, 0x0, 0x0, 0x57f780, 0xc8201211b0, ...)
    /home/nho/workshop/tgotop/draw.go:102 +0x1c
gopkg.in/gizak/termui%2ev2.(*EvtStream).Loop.func1(0xc8200183c0, 0x5b64c0, 0x6, 0x5b7ba0, 0xf, 0x5b6238, 0x7, 0x0, 0x0, 0x57f780, ...)
    /home/nho/golang/src/gopkg.in/gizak/termui.v2/events.go:254 +0x109
created by gopkg.in/gizak/termui%2ev2.(*EvtStream).Loop
    /home/nho/golang/src/gopkg.in/gizak/termui.v2/events.go:256 +0x121

Function around line 102:

ui.Handle("/sys/wnd/resize", func(ui.Event) {
    if ui.TermWidth() > 20 {
        ui.Body.Width = ui.TermWidth()
        ui.Body.Align()
    }
    ui.Render(ui.Body)
})

Happens in mate-terminal and terminology

ui.TermWidth() returns incorrect value if ui.Render() has not being called first

I was updating grid.go so that it didn't use 100% CPU, and I ran across this bug.

    go func() {
        for _ = range time.Tick(time.Second * 4) {
            update <- true
        }
    }()
    ui.Render(ui.Body)
    for {
        select {
        case e := <-evt:
            if e.Type == ui.EventKey && e.Ch == 'q' {
                return
            }
            if e.Type == ui.EventResize {
                ui.Body.Width = ui.TermWidth()
                ui.Body.Align()
                ui.Render(ui.Body)
            }
        case <-done:
            return
        case <-update:
            ui.Render(ui.Body)
        }
    }

here's the updated redraw code and you can pretty much immediately see the problem if you try this.

However, if you write it like this:

    for {
        select {
        case e := <-evt:
            if e.Type == ui.EventKey && e.Ch == 'q' {
                return
            }
            if e.Type == ui.EventResize {
                ui.Render(ui.Body)
                ui.Body.Width = ui.TermWidth()
                ui.Body.Align()
                ui.Render(ui.Body)
            }
        case <-done:
            return
        case <-update:
            ui.Render(ui.Body)
        }
    }

then it works fine. I expect ui.TermWidth() to return the current terminals width. Not the width of the terminal when ui.Render() last ran, so this was very confusing!

negative numbers in sparklines cause a panic

panic: runtime error: index out of range
goroutine 16 [running]:
github.com/vrecan/FluxDash/vendor/github.com/gizak/termui.(*Sparklines).Buffer(0xc08243a1e0, 0x0, 0x
0, 0x0, 0x0, 0x0)
        C:/Users/ben.aldrich/go/src/github.com/vrecan/FluxDash/vendor/github.com/gizak/termui/sparkl
ine.go:146 +0x916
github.com/vrecan/FluxDash/vendor/github.com/gizak/termui.(*Row).Buffer(0xc08245ae40, 0x0, 0x0, 0x0,
 0x0, 0x0)
        C:/Users/ben.aldrich/go/src/github.com/vrecan/FluxDash/vendor/github.com/gizak/termui/grid.g
o:167 +0x185
github.com/vrecan/FluxDash/vendor/github.com/gizak/termui.(*Row).Buffer(0xc08244cf60, 0x0, 0x0, 0x0,
 0x0, 0x0)
        C:/Users/ben.aldrich/go/src/github.com/vrecan/FluxDash/vendor/github.com/gizak/termui/grid.g
o:178 +0x35b
github.com/vrecan/FluxDash/vendor/github.com/gizak/termui.Grid.Buffer(0xc082452c00, 0x3, 0x4, 0x64,
0x0, 0x0, 0x0, 0x0, 0x0, 0x0, ...)
        C:/Users/ben.aldrich/go/src/github.com/vrecan/FluxDash/vendor/github.com/gizak/termui/grid.g
o:274 +0x176
github.com/vrecan/FluxDash/vendor/github.com/gizak/termui.(*Grid).Buffer(0xc082304c80, 0x0, 0x0, 0x0
, 0x0, 0x0)
        <autogenerated>:78 +0xc1
github.com/vrecan/FluxDash/vendor/github.com/gizak/termui.render(0xc08245ca90, 0x1, 0x1)
        C:/Users/ben.aldrich/go/src/github.com/vrecan/FluxDash/vendor/github.com/gizak/termui/render
.go:95 +0xb9
github.com/vrecan/FluxDash/vendor/github.com/gizak/termui.Init.func2()
        C:/Users/ben.aldrich/go/src/github.com/vrecan/FluxDash/vendor/github.com/gizak/termui/render
.go:55 +0x9c
created by github.com/vrecan/FluxDash/vendor/github.com/gizak/termui.Init
        C:/Users/ben.aldrich/go/src/github.com/vrecan/FluxDash/vendor/github.com/gizak/termui/render
.go:57 +0x391

goroutine 1 [chan receive]:
github.com/vrecan/FluxDash/vendor/github.com/gizak/termui.(*EvtStream).Loop(0xc08200e7d0)
        C:/Users/ben.aldrich/go/src/github.com/vrecan/FluxDash/vendor/github.com/gizak/termui/events
.go:238 +0x74
github.com/vrecan/FluxDash/vendor/github.com/gizak/termui.Loop()
        C:/Users/ben.aldrich/go/src/github.com/vrecan/FluxDash/vendor/github.com/gizak/termui/events
.go:274 +0x2a

Feature Request: status bar

I am using your nice library for a dashboard and one feature I am missing a lot if the ability to have a single 1-character status bar at the bottom (like tmux) to show some help, hot-keys, etc.

I may be able to send a patch myself, but until I dig into it, I track it here.

GridLayout doesn't render the borders consistently

When using the GridLayout with different spans (that add up to 12), the border is not rendered consistently (i.e. the width of the first row is longer/short then the width of the second one).

Here is an example:

Here is the example code..

When I set an offset of 1 (the second parameter of NewCol()), that seems fix it but I'm not quite sure whether it's a bug or a feature. The docs don't mention the offset, either (maybe you could at least explain what offset does)...

sparklines and line chart from example/theme.go don't look right on raspberry pi (should they?)

Using raspbian wheezy (2015-02-16). Cross compiled example/theme.go and ran it on the console of the pi.

Maybe the pi is missing a font?

g.Block.Border.Label undefined (type bool has no field or method Label)

I'm new to golang and I suspect I'm just doing it wrong.

I installed the termui library following the instructions here and created a simple test program termui.go which is a copy/paste of the "simplest example" shown here https://godoc.org/github.com/gizak/termui

When I try to run the code I get the following error.

go run termui.go
# command-line-arguments
./termui.go:14: g.Block.Border.Label undefined (type bool has no field or method Label)

Sparkline doesn't 'fill' Sparklines

If I have a sparkline with 200 data points, and add it to a Sparklines that is in a Row/Col that takes up half the width of the terminal (width 6?), i can't see the newest data that should be on the sparkline. The width of the vertical bars can't adjust to scale the full range of sparkline data into the box.

Also if I then resize the terminal to full screen, the sparkline stops about 3/4th of the way instead of filling it's box.

some error on ubuntu 12.04

panic: termbox: error while reading terminfo data: termbox: unsupported terminal

goroutine 1 [running]:
main.main()
/home/cwx/d/gopath/src/goexample/main.go:8 +0x60

goroutine 5 [syscall]:
os/signal.loop()
/home/cwx/go/src/os/signal/signal_unix.go:22 +0x18
created by os/signal.init.1
/home/cwx/go/src/os/signal/signal_unix.go:28 +0x37
exit status 2

Author's desktop visible in screenshots.

Author used a terminal with translucent background theme and as a result, HTML passages and other text is visible in the background of the example screen-shots. Please, re-take the screen-shots either with a fully opaque terminal or with a plain white window behind them.

Feature Request:

The ability to use 256-colour support in terminals that support it. I can do a fork and make a PR for this if you'd like.

I'm thinking of doing it with something like an Attribute that you | with the 0-256 value or so?

So you'd have:

  Point{
    Ch: ' ',
    Bg: termui.Attr256Colour | 12,
  }