termui

README

termui

Go terminal dashboard. Inspired by blessed-contrib, but purely in Go.

Cross-platform, easy to compile, and fully-customizable.

Demo:

Grid layout:(incomplete)

Installation

go get github.com/gizak/termui

Usage

Each component's layout is a bit like HTML block (box model), which has border and padding.

The Border property can be chosen to hide or display (with its border label), when it comes to display, the label takes 1 padding space (i.e. in css: padding: 1;, innerHeight and innerWidth therefore shrunk by 1).

	import ui "github.com/gizak/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.Border.Label = "Text Box"
		p.Border.FgColor = ui.ColorCyan

		g := ui.NewGauge()
		g.Percent = 50
		g.Width = 50
		g.Height = 3
		g.Y = 11
		g.Border.Label = "Gauge"
		g.BarColor = ui.ColorRed
		g.Border.FgColor = ui.ColorWhite
		g.Border.LabelFgColor = ui.ColorCyan

		ui.Render(p, g)

		// 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).

Themes

All colors in all components can be changed at any time, while there provides some predefined color schemes:

// for now there are only two themes: default and helloworld
termui.UseTheme("helloworld")

// create components...

The default theme's settings depend on the user's terminal color scheme, which is saying if your terminal default font color is white and background is white, it will be like:

The helloworld color scheme drops in some colors!

Widgets

Par

demo code

List

demo code

Gauge

demo code

Line Chart

demo code

Bar Chart

demo code

Sparklines

demo code

GoDoc

godoc

TODO

• Grid layout
• Event system

License

This library is under the MIT License

Documentation

Index

• Constants
• Variables
• func Close()
• func Init() error
• func Render(rs ...Bufferer)
• func UseTheme(th string)
• type Attribute
• type BarChart
  • func NewBarChart() *BarChart
  • func (bc *BarChart) Buffer() []Point
• type Block
  • func NewBlock() *Block
  • func (d *Block) Buffer() []Point
  • func (d Block) GetHeight() int
  • func (d Block) GetWidth() int
  • func (d *Block) SetWidth(w int)
  • func (d *Block) SetX(x int)
  • func (d *Block) SetY(y int)
• type Bufferer
• type Col
  • func NewCol(block ColumnBufferer, span, offset int, sticky bool) Col
• type ColumnBufferer
• type Gauge
  • func NewGauge() *Gauge
  • func (g *Gauge) Buffer() []Point
• type LineChart
  • func NewLineChart() *LineChart
  • func (lc *LineChart) Buffer() []Point
• type List
  • func NewList() *List
  • func (l *List) Buffer() []Point
• type Par
  • func NewPar(s string) *Par
  • func (p *Par) Buffer() []Point
• type Point
• type Row
  • func NewRow(cols ...Col) Row
• type Sparkline
  • func NewSparkline() Sparkline
• type Sparklines
  • func NewSparklines(ss ...Sparkline) *Sparklines
  • func (s *Sparklines) Add(sl Sparkline)
  • func (sl *Sparklines) Buffer() []Point

Constants

const BOTTOM_LEFT = '└'

const BOTTOM_RIGHT = '┘'

const HDASH = '┈'

const HORIZONTAL_LINE = '─'

const ORIGIN = '└'

const TOP_LEFT = '┌'

const TOP_RIGHT = '┐'

const VDASH = '┊'

const VERTICAL_LINE = '│'

Variables

var Body container

Functions

func Close

func Close()

func Init

func Init() error

func Render

func Render(rs ...Bufferer)

render all from left to right, right could overlap on left ones

func UseTheme

func UseTheme(th string)

Types

type Attribute

type Attribute uint16

const (
	ColorDefault Attribute = iota
	ColorBlack
	ColorRed
	ColorGreen
	ColorYellow
	ColorBlue
	ColorMagenta
	ColorCyan
	ColorWhite
)

const (
	AttrBold Attribute = 1 << (iota + 9)
	AttrUnderline
	AttrReverse
)

type BarChart

type BarChart struct {
	Block
	BarColor   Attribute
	TextColor  Attribute
	NumColor   Attribute
	Data       []int
	DataLabels []string
	BarWidth   int
	BarGap     int
	// contains filtered or unexported fields
}

func NewBarChart

func NewBarChart() *BarChart

func (*BarChart) Buffer

func (bc *BarChart) Buffer() []Point

type Block

type Block struct {
	X         int
	Y         int
	Border    labeledBorder
	IsDisplay bool
	HasBorder bool
	BgColor   Attribute
	Width     int
	Height    int

	PaddingTop    int
	PaddingBottom int
	PaddingLeft   int
	PaddingRight  int
	// contains filtered or unexported fields
}

basic struct, consider it as css: display:block

func NewBlock

func NewBlock() *Block

func (*Block) Buffer

func (d *Block) Buffer() []Point

func (Block) GetHeight

func (d Block) GetHeight() int

func (Block) GetWidth

func (d Block) GetWidth() int

func (*Block) SetWidth

func (d *Block) SetWidth(w int)

func (*Block) SetX

func (d *Block) SetX(x int)

func (*Block) SetY

func (d *Block) SetY(y int)

type Bufferer

type Bufferer interface {
	Buffer() []Point
}

all renderable components should implement this

type Col

type Col struct {
	ColumnBufferer
	Offset int // 0 ~ 11
	Span   int // 1 ~ 12
	Sticky bool
}

func NewCol

func NewCol(block ColumnBufferer, span, offset int, sticky bool) Col

type ColumnBufferer

type ColumnBufferer interface {
	Bufferer
	GetHeight() int
	GetWidth() int
	SetWidth(int)
	SetX(int)
	SetY(int)
}

type Gauge

type Gauge struct {
	Block
	Percent      int
	BarColor     Attribute
	PercentColor Attribute
}

func NewGauge

func NewGauge() *Gauge

func (*Gauge) Buffer

func (g *Gauge) Buffer() []Point

type LineChart

type LineChart struct {
	Block
	Data       []float64
	DataLabels []string
	Mode       string // braille | dot
	DotStyle   rune
	LineColor  Attribute

	AxesColor Attribute
	// contains filtered or unexported fields
}

func NewLineChart

func NewLineChart() *LineChart

func (*LineChart) Buffer

func (lc *LineChart) Buffer() []Point

type List

type List struct {
	Block
	Items       []string
	Overflow    string
	ItemFgColor Attribute
	ItemBgColor Attribute
}

func NewList

func NewList() *List

func (*List) Buffer

func (l *List) Buffer() []Point

type Par

type Par struct {
	Block
	Text        string
	TextFgColor Attribute
	TextBgColor Attribute
}

func NewPar

func NewPar(s string) *Par

func (*Par) Buffer

func (p *Par) Buffer() []Point

type Point

type Point struct {
	Ch rune
	Bg Attribute
	Fg Attribute
	X  int
	Y  int
}

type Row

type Row []Col

func NewRow

func NewRow(cols ...Col) Row

type Sparkline

type Sparkline struct {
	Data       []int
	Height     int
	Title      string
	TitleColor Attribute
	LineColor  Attribute
	// contains filtered or unexported fields
}

func NewSparkline

func NewSparkline() Sparkline

return unrenderable single sparkline, need to add it into Sparklines

type Sparklines

type Sparklines struct {
	Block
	Lines []Sparkline
	// contains filtered or unexported fields
}

func NewSparklines

func NewSparklines(ss ...Sparkline) *Sparklines

func (*Sparklines) Add

func (s *Sparklines) Add(sl Sparkline)

func (*Sparklines) Buffer

func (sl *Sparklines) Buffer() []Point