README
¶
termdash
This project implements a terminal based dashboard. The feature set is inspired by the gizak/termui project, which in turn was inspired by a javascript based yaronn/blessed-contrib. Why the rewrite you ask?
- The above mentioned gizak/termui is abandoned and isn't maintained anymore.
- The project doesn't follow the design goals outlined below.
Design goals
This effort is focused on good software design and maintainability. By good design I mean:
- Write readable, well documented code.
- Only beautiful, simple APIs, no exposed concurrency, channels, internals, etc.
- Follow Effective Go.
- Provide an infrastructure that allows development of individual dashboard components in separation.
- The infrastructure must enforce consistency in how the dashboard components are implemented.
- Focus on maintainability, the infrastructure and dashboard components must have good test coverage, the repository must have CI/CD enabled.
On top of that - let's have fun, learn something and become better developers together.
Requirements
- Native support of the UTF-8 encoding.
- Simple container management to position the widgets and set their size.
- Mouse and keyboard input.
- Cross-platform terminal based output.
- Unit testing framework for simple and readable tests of dashboard elements.
- Tooling to streamline addition of new widgets.
- Apache-2.0 licence for the project.
High-Level design
See the design document.
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.
Contributing widgets
If you're developing a new widget, please see the widget development section.
Implemented Widgets
The Gauge
Displays the progress of an operation. Run the gaugedemo.
The Text
Displays text content, supports trimming and scrolling of content. Run the textdemo.
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.
// Create the terminal.
t, err := termbox.New()
if err != nil {
panic(err)
}
defer t.Close()
wOpts := widgetapi.Options{
MinimumSize: fakewidget.MinimumSize,
WantKeyboard: true,
WantMouse: true,
}
// Create the container with two fake widgets.
c := container.New(
t,
container.SplitVertical(
container.Left(
container.PlaceWidget(fakewidget.New(wOpts)),
),
container.Right(
container.PlaceWidget(fakewidget.New(wOpts)),
),
),
)
// 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)
}
Index ¶
Examples ¶
Constants ¶
const DefaultRedrawInterval = 250 * time.Millisecond
DefaultRedrawInterval is the default for the RedrawInterval option.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Option ¶
type Option interface {
// contains filtered or unexported methods
}
Option is used to provide options.
func ErrorHandler ¶
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.
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 non-blocking, ideally just storing the value and returning as termdash blocks on each subscriber.
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 non-blocking, ideally just storing the value and returning as termdash blocks on each subscriber.
func RedrawInterval ¶
RedrawInterval sets how often termdash redraws the container and all the widgets. Defaults to DefaultRedrawInterval.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package align defines constants representing types of alignment.
|
Package align defines constants representing types of alignment. |
|
Package area provides functions working with image areas.
|
Package area provides functions working with image areas. |
|
Package canvas defines the canvas that the widgets draw on.
|
Package canvas defines the canvas that the widgets draw on. |
|
testcanvas
Package testcanvas provides helpers for tests that use the canvas package.
|
Package testcanvas provides helpers for tests that use the canvas package. |
|
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. |
|
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. |
|
testdraw
Package testdraw provides helpers for tests that use the draw package.
|
Package testdraw provides helpers for tests that use the draw package. |
|
Package eventqueue provides an unboud FIFO queue of events.
|
Package eventqueue provides an unboud FIFO queue of events. |
|
Package keyboard defines well known keyboard keys and shortcuts.
|
Package keyboard defines well known keyboard keys and shortcuts. |
|
Package mouse defines known mouse buttons.
|
Package mouse defines known mouse buttons. |
|
terminal
|
|
|
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. |
|
termbox
Package termbox implements terminal using the nsf/termbox-go library.
|
Package termbox implements terminal using the nsf/termbox-go library. |
|
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
|
|
|
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. |
|
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/demo
command
Binary gaugedemo displays a couple of Gauge widgets.
|
Binary gaugedemo displays a couple of Gauge widgets. |
|
text
Package text contains a widget that displays textual data.
|
Package text contains a widget that displays textual data. |
|
text/demo
command
Binary textdemo displays a couple of Text widgets.
|
Binary textdemo displays a couple of Text widgets. |