termdash

package module
Version: v0.16.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 3, 2021 License: Apache-2.0 Imports: 8 Imported by: 37

README

Doc Status Build Status Sourcegraph Coverage Status Go Report Card License Mentioned in Awesome Go

termdashlogo

Termdash is a cross-platform customizable terminal based dashboard.

termdashdemo

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

buttondemo

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

textinputdemo

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

go run widgets/textinput/formdemo/formdemo.go

formdemo

The Gauge

Displays the progress of an operation. Run the gaugedemo.

go run widgets/gauge/gaugedemo/gaugedemo.go

gaugedemo

The Donut

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

go run widgets/donut/donutdemo/donutdemo.go

donutdemo

The Text

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

go run widgets/text/textdemo/textdemo.go

textdemo

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

sparklinedemo

The BarChart

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

go run widgets/barchart/barchartdemo/barchartdemo.go

barchartdemo

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

linechartdemo

The SegmentDisplay

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

go run widgets/segmentdisplay/segmentdisplaydemo/segmentdisplaydemo.go

segmentdisplaydemo

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

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.

Disclaimer

This is not an official Google product.

Documentation

Overview

Package termdash implements a terminal based dashboard.

While running, the terminal dashboard performs the following:

- Periodic redrawing of the canvas and all the widgets.
- Event based redrawing of the widgets (i.e. on Keyboard or Mouse events).
- Forwards input events to widgets and optional subscribers.
- Handles terminal resize events.
Example

Example shows how to setup and run termdash with periodic redraw.

// Create the terminal.
t, err := tcell.New()
if err != nil {
	panic(err)
}
defer t.Close()

// Create some widgets.
bc, err := barchart.New()
if err != nil {
	panic(err)
}
g, err := gauge.New()
if err != nil {
	panic(err)
}

// Create the container with two widgets.
c, err := container.New(
	t,
	container.SplitVertical(
		container.Left(
			container.PlaceWidget(bc),
		),
		container.Right(
			container.PlaceWidget(g),
		),
		container.SplitPercent(30),
	),
)
if err != nil {
	panic(err)
}

// Termdash runs until the context expires.
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
if err := Run(ctx, t, c); err != nil {
	panic(err)
}
Output:

Example (Triggered)

Example shows how to setup and run termdash with manually triggered redraw.

// Create the terminal.
t, err := tcell.New()
if err != nil {
	panic(err)
}
defer t.Close()

// Create a widget.
bc, err := barchart.New()
if err != nil {
	panic(err)
}

// Create the container with a widget.
c, err := container.New(
	t,
	container.PlaceWidget(bc),
)
if err != nil {
	panic(err)
}

// Create the controller and disable periodic redraw.
ctrl, err := NewController(t, c)
if err != nil {
	panic(err)
}
// Close the controller and termdash once it isn't required anymore.
defer ctrl.Close()

// Redraw the terminal manually.
if err := ctrl.Redraw(); err != nil {
	panic(err)
}
Output:

Index

Examples

Constants

View Source
const DefaultRedrawInterval = 250 * time.Millisecond

DefaultRedrawInterval is the default for the RedrawInterval option.

Variables

This section is empty.

Functions

func Run

Run runs the terminal dashboard with the provided container on the terminal. Redraws the terminal periodically. If you prefer a manual redraw, use the Controller instead. Blocks until the context expires.

Types

type Controller added in v0.2.0

type Controller struct {
	// contains filtered or unexported fields
}

Controller controls a termdash instance. The controller instance is only valid until Close() is called. The controller is not thread-safe.

func NewController added in v0.2.0

func NewController(t terminalapi.Terminal, c *container.Container, opts ...Option) (*Controller, error)

NewController initializes termdash and returns an instance of the controller. Periodic redrawing is disabled when using the controller, the RedrawInterval option is ignored. Close the controller when it isn't needed anymore.

func (*Controller) Close added in v0.2.0

func (c *Controller) Close()

Close closes the Controller and its termdash instance.

func (*Controller) Redraw added in v0.2.0

func (c *Controller) Redraw() error

Redraw triggers redraw of the terminal.

type Option

type Option interface {
	// contains filtered or unexported methods
}

Option is used to provide options.

func ErrorHandler

func ErrorHandler(f func(error)) Option

ErrorHandler is used to provide a function that will be called with all errors that occur while the dashboard is running. If not provided, any errors panic the application. The provided function must be thread-safe.

func KeyboardSubscriber

func KeyboardSubscriber(f func(*terminalapi.Keyboard)) Option

KeyboardSubscriber registers a subscriber for Keyboard events. Each keyboard event is forwarded to the container and the registered subscriber. The provided function must be thread-safe.

func MouseSubscriber

func MouseSubscriber(f func(*terminalapi.Mouse)) Option

MouseSubscriber registers a subscriber for Mouse events. Each mouse event is forwarded to the container and the registered subscriber. The provided function must be thread-safe.

func RedrawInterval

func RedrawInterval(t time.Duration) Option

RedrawInterval sets how often termdash redraws the container and all the widgets. Defaults to DefaultRedrawInterval. Use the controller to disable the periodic redraw.

Source Files

Directories

Path Synopsis
Package align defines constants representing types of alignment.
Package align defines constants representing types of alignment.
Package cell implements cell options and attributes.
Package cell implements cell options and attributes.
Package container defines a type that wraps other containers or widgets.
Package container defines a type that wraps other containers or widgets.
grid
Package grid helps to build grid layouts.
Package grid helps to build grid layouts.
Package keyboard defines well known keyboard keys and shortcuts.
Package keyboard defines well known keyboard keys and shortcuts.
Package linestyle defines various line styles.
Package linestyle defines various line styles.
Package mouse defines known mouse buttons.
Package mouse defines known mouse buttons.
private
alignfor
Package alignfor provides functions that align elements.
Package alignfor provides functions that align elements.
area
Package area provides functions working with image areas.
Package area provides functions working with image areas.
attrrange
Package attrrange simplifies tracking of attributes that apply to a range of items.
Package attrrange simplifies tracking of attributes that apply to a range of items.
button
Package button implements a state machine that tracks mouse button clicks.
Package button implements a state machine that tracks mouse button clicks.
canvas
Package canvas defines the canvas that the widgets draw on.
Package canvas defines the canvas that the widgets draw on.
canvas/braille
Package braille provides a canvas that uses braille characters.
Package braille provides a canvas that uses braille characters.
canvas/braille/testbraille
Package testbraille provides helpers for tests that use the braille package.
Package testbraille provides helpers for tests that use the braille package.
canvas/buffer
Package buffer implements a 2-D buffer of cells.
Package buffer implements a 2-D buffer of cells.
canvas/testcanvas
Package testcanvas provides helpers for tests that use the canvas package.
Package testcanvas provides helpers for tests that use the canvas package.
draw
Package draw provides functions that draw lines, shapes, etc on 2-D terminal like canvases.
Package draw provides functions that draw lines, shapes, etc on 2-D terminal like canvases.
draw/testdraw
Package testdraw provides helpers for tests that use the draw package.
Package testdraw provides helpers for tests that use the draw package.
event
Package event provides a non-blocking event distribution and subscription system.
Package event provides a non-blocking event distribution and subscription system.
event/eventqueue
Package eventqueue provides an unboud FIFO queue of events.
Package eventqueue provides an unboud FIFO queue of events.
event/testevent
Package testevent provides utilities for tests that deal with concurrent events.
Package testevent provides utilities for tests that deal with concurrent events.
faketerm
Package faketerm is a fake implementation of the terminal for the use in tests.
Package faketerm is a fake implementation of the terminal for the use in tests.
fakewidget
Package fakewidget implements a fake widget that is useful for testing the termdash infrastructure.
Package fakewidget implements a fake widget that is useful for testing the termdash infrastructure.
numbers
Package numbers implements various numerical functions.
Package numbers implements various numerical functions.
numbers/trig
Package trig implements various trigonometrical calculations.
Package trig implements various trigonometrical calculations.
runewidth
Package runewidth is a wrapper over github.com/mattn/go-runewidth which gives different treatment to certain runes with ambiguous width.
Package runewidth is a wrapper over github.com/mattn/go-runewidth which gives different treatment to certain runes with ambiguous width.
segdisp
Package segdisp provides utilities used by all segment display types.
Package segdisp provides utilities used by all segment display types.
segdisp/dotseg
Package dotseg simulates a segment display that can draw dots.
Package dotseg simulates a segment display that can draw dots.
segdisp/dotseg/testdotseg
Package testdotseg provides helpers for tests that use the dotseg package.
Package testdotseg provides helpers for tests that use the dotseg package.
segdisp/segment
Package segment provides functions that draw a single segment.
Package segment provides functions that draw a single segment.
segdisp/segment/testsegment
Package testsegment provides helpers for tests that use the segment package.
Package testsegment provides helpers for tests that use the segment package.
segdisp/sixteen
Package sixteen simulates a 16-segment display drawn on a canvas.
Package sixteen simulates a 16-segment display drawn on a canvas.
segdisp/sixteen/testsixteen
Package testsixteen provides helpers for tests that use the sixteen package.
Package testsixteen provides helpers for tests that use the sixteen package.
wrap
Package wrap implements line wrapping at character or word boundaries.
Package wrap implements line wrapping at character or word boundaries.
Binary termdashdemo demonstrates the functionality of termdash and its various widgets.
Binary termdashdemo demonstrates the functionality of termdash and its various widgets.
terminal
termbox
Package termbox implements terminal using the nsf/termbox-go library.
Package termbox implements terminal using the nsf/termbox-go library.
terminalapi
Package terminalapi defines the API of all terminal implementations.
Package terminalapi defines the API of all terminal implementations.
Package widgetapi defines the API of a widget on the dashboard.
Package widgetapi defines the API of a widget on the dashboard.
widgets
barchart
Package barchart implements a widget that draws multiple bars displaying values and their relative ratios.
Package barchart implements a widget that draws multiple bars displaying values and their relative ratios.
barchart/barchartdemo
Binary barchartdemo displays a couple of BarChart widgets.
Binary barchartdemo displays a couple of BarChart widgets.
button
Package button implements an interactive widget that can be pressed to activate.
Package button implements an interactive widget that can be pressed to activate.
button/buttondemo
Binary buttondemo shows the functionality of a button widget.
Binary buttondemo shows the functionality of a button widget.
donut
Package donut is a widget that displays the progress of an operation as a partial or full circle.
Package donut is a widget that displays the progress of an operation as a partial or full circle.
donut/donutdemo
Binary donutdemo displays a couple of Donut widgets.
Binary donutdemo displays a couple of Donut widgets.
gauge
Package gauge implements a widget that displays the progress of an operation.
Package gauge implements a widget that displays the progress of an operation.
gauge/gaugedemo
Binary gaugedemo displays a couple of Gauge widgets.
Binary gaugedemo displays a couple of Gauge widgets.
heatmap
Package heatmap contains a widget that displays heat maps.
Package heatmap contains a widget that displays heat maps.
heatmap/heatmapdemo
Binary heatmapdemo displays a heatmap widget.
Binary heatmapdemo displays a heatmap widget.
linechart
Package linechart contains a widget that displays line charts.
Package linechart contains a widget that displays line charts.
linechart/linechartdemo
Binary linechartdemo displays a linechart widget.
Binary linechartdemo displays a linechart widget.
segmentdisplay
Package segmentdisplay is a widget that displays text by simulating a segment display.
Package segmentdisplay is a widget that displays text by simulating a segment display.
segmentdisplay/segmentdisplaydemo
Binary segmentdisplaydemo shows the functionality of a segment display.
Binary segmentdisplaydemo shows the functionality of a segment display.
sparkline
Package sparkline is a widget that draws a graph showing a series of values as vertical bars.
Package sparkline is a widget that draws a graph showing a series of values as vertical bars.
sparkline/sparklinedemo
Binary sparklinedemo displays a couple of SparkLine widgets.
Binary sparklinedemo displays a couple of SparkLine widgets.
text
Package text contains a widget that displays textual data.
Package text contains a widget that displays textual data.
text/textdemo
Binary textdemo displays a couple of Text widgets.
Binary textdemo displays a couple of Text widgets.
textinput
Package textinput implements a widget that accepts text input.
Package textinput implements a widget that accepts text input.
textinput/formdemo
Binary formdemo creates a form that accepts text inputs and supports keyboard navigation.
Binary formdemo creates a form that accepts text inputs and supports keyboard navigation.
textinput/textinputdemo
Binary textinputdemo shows the functionality of a text input field.
Binary textinputdemo shows the functionality of a text input field.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL