mum4k/termdash

Terminal based dashboard.

Termdash is a cross-platform customizable terminal based dashboard.

The feature set is inspired by the gizak/termui project, which in turn was inspired by yaronn/blessed-contrib.

This rewrite focuses on code readability, maintainability and testability, see the design goals. It aims to achieve the following requirements. See the high-level design for more details.

Public API and status

The public API surface is documented in the wiki.

Private packages can be identified by the presence of the /private/ directory in their import path. Stability of the private packages isn't guaranteed and changes won't be backward compatible.

There might still be breaking changes to the public API, at least until the project reaches version 1.0.0. Any breaking changes will be published in the changelog.

Current feature set

• Full support for terminal window resizing throughout the infrastructure.
• Customizable layout, widget placement, borders, margins, padding, colors, etc.
• Dynamic layout changes at runtime.
• Binary tree and Grid forms of setting up the layout.
• Focusable containers and widgets.
• Processing of keyboard and mouse events.
• Periodic and event driven screen redraw.
• A library of widgets, see below.
• UTF-8 for all text elements.
• Drawing primitives (Go functions) for widget development with character and sub-character resolution.

Installation

To install this library, run the following:

go get -u github.com/mum4k/termdash
cd github.com/mum4k/termdash

Usage

The usage of most of these elements is demonstrated in termdashdemo.go. To execute the demo:

go run termdashdemo/termdashdemo.go

Documentation

Please refer to the Termdash wiki for all documentation and resources.

Implemented Widgets

The Button

Allows users to interact with the application, each button press runs a callback function. Run the buttondemo.

go run widgets/button/buttondemo/buttondemo.go

The TextInput

Allows users to interact with the application by entering, editing and submitting text data. Run the textinputdemo.

go run widgets/textinput/textinputdemo/textinputdemo.go

Can be used to create text input forms that support keyboard navigation:

go run widgets/textinput/formdemo/formdemo.go

The Gauge

Displays the progress of an operation. Run the gaugedemo.

go run widgets/gauge/gaugedemo/gaugedemo.go

The Donut

Visualizes progress of an operation as a partial or a complete donut. Run the donutdemo.

go run widgets/donut/donutdemo/donutdemo.go

The Text

Displays text content, supports trimming and scrolling of content. Run the textdemo.

go run widgets/text/textdemo/textdemo.go

The SparkLine

Draws a graph showing a series of values as vertical bars. The bars can have sub-cell height. Run the sparklinedemo.

go run widgets/sparkline/sparklinedemo/sparklinedemo.go

The BarChart

Displays multiple bars showing relative ratios of values. Run the barchartdemo.

go run widgets/barchart/barchartdemo/barchartdemo.go

The LineChart

Displays series of values on a line chart, supports zoom triggered by mouse events. Run the linechartdemo.

go run widgets/linechart/linechartdemo/linechartdemo.go

The SegmentDisplay

Displays text by simulating a 16-segment display. Run the segmentdisplaydemo.

go run widgets/segmentdisplay/segmentdisplaydemo/segmentdisplaydemo.go

Contributing

If you are willing to contribute, improve the infrastructure or develop a widget, first of all Thank You! Your help is appreciated.

Please see the CONTRIBUTING.md file for guidelines related to the Google's CLA, and code review requirements.

As stated above the primary goal of this project is to develop readable, well designed code, the functionality and efficiency come second. This is achieved through detailed code reviews, design discussions and following of the design guidelines. Please familiarize yourself with these before contributing.

If you're developing a new widget, please see the widget development section.

Termdash uses this branching model. When you fork the repository, base your changes off the devel branch and the pull request should merge it back to the devel branch. Commits to the master branch are limited to releases, major bug fixes and documentation updates.

Similar projects in Go

• clui
• gocui
• gowid
• termui
• tui-go
• tview

Projects using Termdash

• datadash: Visualize streaming or tabular data inside the terminal.
• grafterm: Metrics dashboards visualization on the terminal.
• perfstat: Analyze and show tips about possible bottlenecks in Linux systems.
• gex: Cosmos SDK explorer in-terminal.
• ali: ALI HTTP load testing tool with realtime analysis.
• suimon: SUI blockchain explorer and monitor.

Disclaimer

This is not an official Google product.

termdash's Issues

Support word wrapping for the text widget

Add support for wrapping lines at the word boundaries in the text widget.

Text wrapping is already implemented, but it only wraps at character boundaries.

Support layout changes and widgets additions / removal to container at runtime

This should start with an API design and analysis of potential use cases.

We could support dynamic additions / removal / moves of widgets at runtime.

Generalize alignment code and move it to the align package

Change of container focus using keyboard shortcuts

Currently the focus (which widget receives keyboard and mouse events) can only be moved by mouse clicks.

We could enhance the container so that widget focus is moved by configurable keyboard shortcuts. This would involve adding new container options and enhancing the container itself so that it processes events.

Widget: Line chart

Implement a line chart widget.

Similar to: https://github.com/gizak/termui/raw/master/_example/linechart.png
And: https://github.com/yaronn/blessed-contrib/raw/master/docs/images/line.gif

Also look at: https://github.com/cjbassi/termui and the use of: https://github.com/exrook/drawille-go

Rename draw.Box to draw.Border

Also add support for border title and reuse it in container.

Widget: Donut

Implement a doughnut widget.

Similar to: https://github.com/yaronn/blessed-contrib/raw/master/docs/images/donut.gif

Design and implement a keyboard trigger library

This library would receive a stream of keyboard presses and trigger a callback on the configured key or key combination.

This would ease the development of widgets or code that uses keyboard input and wants to support multi-key shortcuts.

Widget: Text input

Implement a widget that will allow the user to provide text input. Either single or multi-line.

Widget: Stacked bar chart

Implement a stacked bar chart widget.

Similar to: https://github.com/gizak/termui/raw/master/_example/mbarchart.png
And: https://github.com/yaronn/blessed-contrib/raw/master/docs/images/stacked-bar.png

Need a draw.Line() function that draws horizontal and vertical lines and uses correct corner characters where the lines meet.

Add go report status and license link to the README

https://github.com/gojp/goreportcard

Remove all occurrences of utf8.RuneCountInString

While utf8.RuneCountInString counts the number of runes, it cannot be used to determine the number of cells the text takes. Full-width runes take multiple cells.

This mostly affects the text alignment code and the gauge widget.

Allow users to set 256 colors when providing cell options

Support variable size container splits

Currently both the vertical and the horizontal splits split the container exactly in the middle.

Allow for multiple sizes. Consider using predefined sizes (like SplitHalf, SplitQuarter, ...) instead of accepting number to avoid possibility of input errors.

Display labels for the series showing the series names

As in (https://github.com/yaronn/blessed-contrib/raw/master/docs/images/line.gif)

I.e. the USA and EUROPE in the picture.

Support wide unicode characters

Some unicode characters take more than one cell to be displayed.

This must be supported by the canvas.SetCell function, the draw.Text function and the text widget.

Change default alignment of widgets in the container to middle and center

Text and ESC seq

Is it possible to use with Text widget esc seq for foreground color?
Example ESC[39;49m

Widget: Picture

Implement a picture widget.

Similar to: https://github.com/yaronn/blessed-contrib/raw/master/docs/images/picture.png

This widget would benefit from the higher resolution of the braille canvas.

Implement support for titles on containers

Generalize mouse state machine

Design and implement a library that would ease detection of mouse button presses.

A press is when both the press and the release is within a defined area.

Look at the existing implementation in the focus tracking code of the container package.

Invalid synchronisation in termdash_test

The tests (specifically the after function) is currently synchronised by waiting for the event queue to empty. This isn't a good synchronisation, since the event processing code in termdash still races with the test code that evaluates the result.

Example traceback:
The command "go test ./..." exited with 0.
12.77s$ go test -race ./...
panic: runtime error: invalid memory address or nil pointer dereference [recovered]
panic: runtime error: invalid memory address or nil pointer dereference
[signal SIGSEGV: segmentation violation code=0x1 addr=0x18 pc=0x5f1cc8]
goroutine 38 [running]:
testing.tRunner.func1(0xc4200c05a0)
/home/travis/.gimme/versions/go1.10.3.linux.amd64/src/testing/testing.go:742 +0x567
panic(0x62cf60, 0x7881a0)
/home/travis/.gimme/versions/go1.10.3.linux.amd64/src/runtime/panic.go:502 +0x24a
github.com/mum4k/termdash.TestRun.func5(0xc42009c750, 0xc42006f100)
/home/travis/gopath/src/github.com/mum4k/termdash/termdash_test.go:239 +0x68
github.com/mum4k/termdash.TestRun.func11(0xc4200c05a0)
/home/travis/gopath/src/github.com/mum4k/termdash/termdash_test.go:358 +0xa00
testing.tRunner(0xc4200c05a0, 0xc4200833e0)
/home/travis/.gimme/versions/go1.10.3.linux.amd64/src/testing/testing.go:777 +0x16e
created by testing.(*T).Run
/home/travis/.gimme/versions/go1.10.3.linux.amd64/src/testing/testing.go:824 +0x565
FAIL github.com/mum4k/termdash 1.068s

Widget: Rolling text

Implement a rolling text widget.

Similar to: https://github.com/yaronn/blessed-contrib/raw/master/docs/images/log.gif

Use fakewidget.Draw in tests that use the fake widget

All tests that use the fake widget should use fakewidget.Draw or fakewidget.MustDraw when creating the expected value.

That way changes or enhancements to fakewidget will be limited to that package.

This is an example of a test that doesn't use MustDraw and instead uses primitives directly (MustBorder, MustText):

termdash/container/draw_test.go

Line 67 in f72f1c2

desc: "draws widget with container border and title aligned on the left",

This is an example of a test that uses the desired helper instead of draw primitives:

termdash/termdash_test.go

Line 168 in 6b9ac6b

fakewidget.MustDraw(

Container title could scroll instead of be trimmed if it is too long

Draw a single line graph representing the values.

Widget: Sparkline

Implement a spark line widget.

Similar to: https://github.com/gizak/termui/raw/master/_example/sparklines.png
And: https://github.com/yaronn/blessed-contrib/raw/master/docs/images/spark.gif

Support custom colors.

Should be configurable for:

1. The line graphs.
2. The axes.
3. The values displayed next to the axes.
4. The axes labels.

Support for multiple values in the same chart (multiple lines).

Generalize the concept of a partially filled box with text label

This might be useful for more than just the Gauge widget.

The Gauge widget currently contains this logic, the idea would be to move it out elsewhere.

Add support for negative values in the LineChart widget

So that the line can go down below the bottom axis. We could also support a LineChart supporting negative values on both the axes.

Widget: Tree

Implement a tree widget.

Similar to: https://github.com/yaronn/blessed-contrib/raw/master/docs/images/tree.gif

Widget: Gauge

Implement a gauge widget.

Similar to: https://github.com/gizak/termui/raw/master/_example/gauge.png
And: https://github.com/yaronn/blessed-contrib/raw/master/docs/images/gauge.gif

There is a potential race between Options() and Draw() calls

This affects widgets that calculate their minimum size based on what data they currently have.

The following causes a race:

1. infra calls Options()
2. user changes values in the widget
3. infra calls Draw(), potentially not respecting the min size.

Widget: Table

Implement a text table widget.

Similar to: https://github.com/yaronn/blessed-contrib/blob/master/docs/images/table.gif

Targeted features:

• Support both ASCII and Unicode text.
• API to specify columns and rows.
• API to specify sizes of columns (auto based on content, fixed or percentage).
• API to merge multiple columns and rows (colspan and rowspan).
• Support content alignment within cells.
• Support Text trimming, character or word wrapping within cells.
• Support scrolling of longer tables.
• Support keyboard and mouse input to interact with the table (row by row or cell by cell).
• Visible or invisible cell and table borders.
• Support sorting by individual columns (ascending and descending).

Widget: LCD display

Implement an LCD display widget.

Similar to: https://github.com/yaronn/blessed-contrib/raw/master/docs/images/lcd.gif

This widget would benefit from using the braille canvas and its resolution.

Need a draw.BrailleLine() function that draws lines using the Braille unicode characters (http://www.alanwood.net/unicode/braille_patterns.html).

Support labels for the axes.

Add support for vertical text labels in the LineChart widget

The text can either have rotated characters, or just standard text characters flowing vertically.

This would be for the X axis, so that it can display longer custom labels.

Widget: Markdown

Implement a markdown widget.

Similar to: https://github.com/yaronn/blessed-contrib/raw/master/docs/images/markdown.png

Draw two axes with arranged values in the LineChart widget.

Support zooming of the LineChart.

Rotation of the mouse wheel or key presses could adjust the scale.

Widget: Stacked gauge

Implement a stacked gauge widget.

Similar to: https://github.com/yaronn/blessed-contrib/raw/master/docs/images/stackgauge.gif

Support custom value labels on each of the axes.

Optimize redraw of terminal

Some ideas:
The canvas can track which cells were set and only apply those to the terminal.
Widgets can indicate if they need a redraw or if the content is still the same.
Container can redraw only those widgets that changed.
Thetermdash API can support user triggered redraw instead of periodic.

Widget: Text block

Implement a simple text block that with styling and wrapping options.

Similar to gizak/termui: https://github.com/gizak/termui/raw/master/_example/par.png

The draw.Text() function needs to support vertically placed text to allow for labels on axes.

Widget: Bar chart

Implement a bar chart widget.

Similar to: https://github.com/gizak/termui/raw/master/_example/barchart.png
And: https://github.com/yaronn/blessed-contrib/raw/master/docs/images/bar.gif

Unify APIs in the draw package

All functions should define their own option type instead of accepting cell options.

One of their options would be to take in a list of cell options.