termui

package
v1.0.3 Latest Latest
Warning

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

Go to latest
Published: Sep 1, 2015 License: GPL-3.0, MIT Imports: 6 Imported by: 0

README

termui Build Status Doc Status

Update 23/06/2015

Pull requests and master branch are freezing, waiting for merging from refactoring branch.

Notice

termui comes with ABSOLUTELY NO WARRANTY, and there is a breaking change coming up (see refactoring branch) which will change the Bufferer interface and many others. These changes reduce calculation overhead and introduce a new drawing buffer with better capacibilities. We will step into the next stage (call it beta) after merging these changes.

Introduction

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

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

Demo: (cast under osx 10.10; Terminal.app; Menlo Regular 12pt.)

demo

Grid layout:

Expressive syntax, using 12 columns grid system

	import ui "github.com/gizak/termui"
	// init and create widgets...

	// build
	ui.Body.AddRows(
		ui.NewRow(
			ui.NewCol(6, 0, widget0),
			ui.NewCol(6, 0, widget1)),
		ui.NewRow(
			ui.NewCol(3, 0, widget2),
			ui.NewCol(3, 0, widget30, widget31, widget32),
			ui.NewCol(6, 0, widget4)))

	// calculate layout
	ui.Body.Align()

	ui.Render(ui.Body)

demo code:

grid

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:

default

The helloworld color scheme drops in some colors!

helloworld

Widgets

Par

demo code

par
List

demo code

list
Gauge

demo code

gauge
Line Chart

demo code

linechart
Bar Chart

demo code

barchart
Mult-Bar / Stacked-Bar Chart

demo code

barchart
Sparklines

demo code

sparklines

GoDoc

godoc

TODO

  • Grid layout
  • Event system
  • Canvas widget
  • Refine APIs
  • Focusable widgets

License

This library is under the MIT License

Documentation

Overview

Package termui is a library designed for creating command line UI. For more info, goto http://github.com/gizak/termui

A simplest example:

package main

import ui "github.com/gizak/termui"

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

    g := ui.NewGauge()
    g.Percent = 50
    g.Width = 50
    g.Border.Label = "Gauge"

    ui.Render(g)
}

Index

Constants

View Source
const BOTTOM_LEFT = '└'
View Source
const BOTTOM_RIGHT = '┘'
View Source
const HDASH = '┈'
View Source
const HORIZONTAL_LINE = '─'
View Source
const NumberofColors = 8 //Have a constant that defines number of colors
View Source
const ORIGIN = '└'
View Source
const TOP_LEFT = '┌'
View Source
const TOP_RIGHT = '┐'
View Source
const VDASH = '┊'
View Source
const VERTICAL_LINE = '│'

Variables

This section is empty.

Functions

func Close

func Close()

Close finalizes termui library, should be called after successful initialization when termui's functionality isn't required anymore.

func EventCh

func EventCh() <-chan Event

EventCh returns an output-only event channel. This function can be called many times (multiplexer).

func Init

func Init() error

Init initializes termui library. This function should be called before any others. After initialization, the library must be finalized by 'Close' function.

func Render

func Render(rs ...Bufferer)

Render renders all Bufferer in the given order from left to right, right could overlap on left ones.

func SetTheme

func SetTheme(newTheme ColorScheme)

SetTheme sets a new, custom theme.

func TermHeight

func TermHeight() int

TermHeight returns the current terminal's height.

func TermWidth

func TermWidth() int

TermWidth returns the current terminal's width.

func UseTheme

func UseTheme(th string)

UseTheme sets a predefined scheme. Currently available: "hello-world" and "black-and-white".

Types

type Align

type Align int

Align is the position of the gauge's label.

const (
	AlignLeft Align = iota
	AlignCenter
	AlignRight
)

All supported positions.

type Attribute

type Attribute uint16

Attribute is printable cell's color and style.

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
}

BarChart creates multiple bars in a widget:

bc := termui.NewBarChart()
data := []int{3, 2, 5, 3, 9, 5}
bclabels := []string{"S0", "S1", "S2", "S3", "S4", "S5"}
bc.Border.Label = "Bar Chart"
bc.Data = data
bc.Width = 26
bc.Height = 10
bc.DataLabels = bclabels
bc.TextColor = termui.ColorGreen
bc.BarColor = termui.ColorRed
bc.NumColor = termui.ColorYellow

func NewBarChart

func NewBarChart() *BarChart

NewBarChart returns a new *BarChart with current theme.

func (*BarChart) Buffer

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

Buffer implements Bufferer interface.

func (*BarChart) SetMax

func (bc *BarChart) SetMax(max int)

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
}

Block is a base struct for all other upper level widgets, consider it as css: display:block. Normally you do not need to create it manually.

func NewBlock

func NewBlock() *Block

NewBlock returns a *Block which inherits styles from current theme.

func (*Block) Buffer

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

Buffer implements Bufferer interface. Draw background and border (if any).

func (Block) GetHeight

func (d Block) GetHeight() int

GetHeight implements GridBufferer. It returns current height of the block.

func (*Block) InnerBounds

func (d *Block) InnerBounds() (x, y, width, height int)

InnerBounds returns the internal bounds of the block after aligning and calculating the padding and border, if any.

func (*Block) SetWidth

func (d *Block) SetWidth(w int)

SetWidth implements GridBuffer interface, it sets block's width.

func (*Block) SetX

func (d *Block) SetX(x int)

SetX implements GridBufferer interface, which sets block's x position.

func (*Block) SetY

func (d *Block) SetY(y int)

SetY implements GridBufferer interface, it sets y position for block.

type Bufferer

type Bufferer interface {
	Buffer() []Point
}

Bufferer should be implemented by all renderable components.

type Canvas

type Canvas map[[2]int]rune

Canvas contains drawing map: i,j -> rune

func NewCanvas

func NewCanvas() Canvas

NewCanvas returns an empty Canvas

func (Canvas) Buffer

func (c Canvas) Buffer() []Point

Buffer returns un-styled points

func (Canvas) Set

func (c Canvas) Set(x, y int)

Set sets a point (x,y) in the virtual coordinate

func (Canvas) Unset

func (c Canvas) Unset(x, y int)

Unset removes point (x,y)

type ColorScheme

type ColorScheme struct {
	BodyBg            Attribute
	BlockBg           Attribute
	HasBorder         bool
	BorderFg          Attribute
	BorderBg          Attribute
	BorderLabelTextFg Attribute
	BorderLabelTextBg Attribute
	ParTextFg         Attribute
	ParTextBg         Attribute
	SparklineLine     Attribute
	SparklineTitle    Attribute
	GaugeBar          Attribute
	GaugePercent      Attribute
	LineChartLine     Attribute
	LineChartAxes     Attribute
	ListItemFg        Attribute
	ListItemBg        Attribute
	BarChartBar       Attribute
	BarChartText      Attribute
	BarChartNum       Attribute
	MBarChartBar      Attribute
	MBarChartText     Attribute
	MBarChartNum      Attribute
}

A ColorScheme represents the current look-and-feel of the dashboard.

func Theme

func Theme() ColorScheme

Theme returns the currently used theme.

type Event

type Event struct {
	Type   EventType // one of Event* constants
	Mod    Modifier  // one of Mod* constants or 0
	Key    Key       // one of Key* constants, invalid if 'Ch' is not 0
	Ch     rune      // a unicode character
	Width  int       // width of the screen
	Height int       // height of the screen
	Err    error     // error in case if input failed
	MouseX int       // x coord of mouse
	MouseY int       // y coord of mouse
	N      int       // number of bytes written when getting a raw event
}

This type represents a termbox event. The 'Mod', 'Key' and 'Ch' fields are valid if 'Type' is EventKey. The 'Width' and 'Height' fields are valid if 'Type' is EventResize. The 'Err' field is valid if 'Type' is EventError.

type EventType

type EventType uint8
const (
	EventKey EventType = iota
	EventResize
	EventMouse
	EventError
	EventInterrupt
	EventRaw
	EventNone
)

Event type. See Event.Type field.

type Gauge

type Gauge struct {
	Block
	Percent      int
	BarColor     Attribute
	PercentColor Attribute
	Label        string
	LabelAlign   Align
}

func NewGauge

func NewGauge() *Gauge

NewGauge return a new gauge with current theme.

func (*Gauge) Buffer

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

Buffer implements Bufferer interface.

type Grid

type Grid struct {
	Rows    []*Row
	Width   int
	X       int
	Y       int
	BgColor Attribute
}

Grid implements 12 columns system. A simple example:

import ui "github.com/gizak/termui"
// init and create widgets...

// build
ui.Body.AddRows(
    ui.NewRow(
        ui.NewCol(6, 0, widget0),
        ui.NewCol(6, 0, widget1)),
    ui.NewRow(
        ui.NewCol(3, 0, widget2),
        ui.NewCol(3, 0, widget30, widget31, widget32),
        ui.NewCol(6, 0, widget4)))

// calculate layout
ui.Body.Align()

ui.Render(ui.Body)
var Body *Grid

Body corresponds to the entire terminal display region.

func NewGrid

func NewGrid(rows ...*Row) *Grid

NewGrid returns *Grid with given rows.

func (*Grid) AddRows

func (g *Grid) AddRows(rs ...*Row)

AddRows appends given rows to Grid.

func (*Grid) Align

func (g *Grid) Align()

Align calculate each rows' layout.

func (Grid) Buffer

func (g Grid) Buffer() []Point

Buffer implments Bufferer interface.

type GridBufferer

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

GridBufferer introduces a Bufferer that can be manipulated by Grid.

type Key

type Key uint16
const (
	KeyF1 Key = 0xFFFF - iota
	KeyF2
	KeyF3
	KeyF4
	KeyF5
	KeyF6
	KeyF7
	KeyF8
	KeyF9
	KeyF10
	KeyF11
	KeyF12
	KeyInsert
	KeyDelete
	KeyHome
	KeyEnd
	KeyPgup
	KeyPgdn
	KeyArrowUp
	KeyArrowDown
	KeyArrowLeft
	KeyArrowRight

	MouseLeft
	MouseMiddle
	MouseRight
)
const (
	KeyCtrlTilde      Key = 0x00
	KeyCtrl2          Key = 0x00
	KeyCtrlSpace      Key = 0x00
	KeyCtrlA          Key = 0x01
	KeyCtrlB          Key = 0x02
	KeyCtrlC          Key = 0x03
	KeyCtrlD          Key = 0x04
	KeyCtrlE          Key = 0x05
	KeyCtrlF          Key = 0x06
	KeyCtrlG          Key = 0x07
	KeyBackspace      Key = 0x08
	KeyCtrlH          Key = 0x08
	KeyTab            Key = 0x09
	KeyCtrlI          Key = 0x09
	KeyCtrlJ          Key = 0x0A
	KeyCtrlK          Key = 0x0B
	KeyCtrlL          Key = 0x0C
	KeyEnter          Key = 0x0D
	KeyCtrlM          Key = 0x0D
	KeyCtrlN          Key = 0x0E
	KeyCtrlO          Key = 0x0F
	KeyCtrlP          Key = 0x10
	KeyCtrlQ          Key = 0x11
	KeyCtrlR          Key = 0x12
	KeyCtrlS          Key = 0x13
	KeyCtrlT          Key = 0x14
	KeyCtrlU          Key = 0x15
	KeyCtrlV          Key = 0x16
	KeyCtrlW          Key = 0x17
	KeyCtrlX          Key = 0x18
	KeyCtrlY          Key = 0x19
	KeyCtrlZ          Key = 0x1A
	KeyEsc            Key = 0x1B
	KeyCtrlLsqBracket Key = 0x1B
	KeyCtrl3          Key = 0x1B
	KeyCtrl4          Key = 0x1C
	KeyCtrlBackslash  Key = 0x1C
	KeyCtrl5          Key = 0x1D
	KeyCtrlRsqBracket Key = 0x1D
	KeyCtrl6          Key = 0x1E
	KeyCtrl7          Key = 0x1F
	KeyCtrlSlash      Key = 0x1F
	KeyCtrlUnderscore Key = 0x1F
	KeySpace          Key = 0x20
	KeyBackspace2     Key = 0x7F
	KeyCtrl8          Key = 0x7F
)

type LineChart

type LineChart struct {
	Block
	Data       []float64
	DataLabels []string // if unset, the data indices will be used
	Mode       string   // braille | dot
	DotStyle   rune
	LineColor  Attribute

	AxesColor Attribute
	// contains filtered or unexported fields
}

LineChart has two modes: braille(default) and dot. Using braille gives 2x capicity as dot mode, because one braille char can represent two data points.

lc := termui.NewLineChart()
lc.Border.Label = "braille-mode Line Chart"
lc.Data = [1.2, 1.3, 1.5, 1.7, 1.5, 1.6, 1.8, 2.0]
lc.Width = 50
lc.Height = 12
lc.AxesColor = termui.ColorWhite
lc.LineColor = termui.ColorGreen | termui.AttrBold
// termui.Render(lc)...

func NewLineChart

func NewLineChart() *LineChart

NewLineChart returns a new LineChart with current theme.

func (*LineChart) Buffer

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

Buffer implements Bufferer interface.

type List

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

List displays []string as its items, it has a Overflow option (default is "hidden"), when set to "hidden", the item exceeding List's width is truncated, but when set to "wrap", the overflowed text breaks into next line.

  strs := []string{
		"[0] github.com/gizak/termui",
		"[1] editbox.go",
		"[2] iterrupt.go",
		"[3] keyboard.go",
		"[4] output.go",
		"[5] random_out.go",
		"[6] dashboard.go",
		"[7] nsf/termbox-go"}

  ls := termui.NewList()
  ls.Items = strs
  ls.ItemFgColor = termui.ColorYellow
  ls.Border.Label = "List"
  ls.Height = 7
  ls.Width = 25
  ls.Y = 0

func NewList

func NewList() *List

NewList returns a new *List with current theme.

func (*List) Buffer

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

Buffer implements Bufferer interface.

type MBarChart

type MBarChart struct {
	Block
	BarColor   [NumberofColors]Attribute
	TextColor  Attribute
	NumColor   [NumberofColors]Attribute
	Data       [NumberofColors][]int
	DataLabels []string
	BarWidth   int
	BarGap     int

	ShowScale bool
	// contains filtered or unexported fields
}

This is the implemetation of multi-colored or stacked bar graph. This is different from default barGraph which is implemented in bar.go Multi-Colored-BarChart creates multiple bars in a widget:

bc := termui.NewMBarChart()
data := make([][]int, 2)
data[0] := []int{3, 2, 5, 7, 9, 4}
data[1] := []int{7, 8, 5, 3, 1, 6}
bclabels := []string{"S0", "S1", "S2", "S3", "S4", "S5"}
bc.Border.Label = "Bar Chart"
bc.Data = data
bc.Width = 26
bc.Height = 10
bc.DataLabels = bclabels
bc.TextColor = termui.ColorGreen
bc.BarColor = termui.ColorRed
bc.NumColor = termui.ColorYellow

func NewMBarChart

func NewMBarChart() *MBarChart

NewBarChart returns a new *BarChart with current theme.

func (*MBarChart) Buffer

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

Buffer implements Bufferer interface.

func (*MBarChart) SetMax

func (bc *MBarChart) SetMax(max int)

type Modifier

type Modifier uint8
const (
	ModAlt Modifier = 0x01
)

Alt modifier constant, see Event.Mod field and SetInputMode function.

type Par

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

Par displays a paragraph.

par := termui.NewPar("Simple Text")
par.Height = 3
par.Width = 17
par.Border.Label = "Label"

func NewPar

func NewPar(s string) *Par

NewPar returns a new *Par with given text as its content.

func (*Par) Buffer

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

Buffer implements Bufferer interface.

type Point

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

Point stands for a single cell in terminal.

type Row

type Row struct {
	Cols   []*Row       //children
	Widget GridBufferer // root
	X      int
	Y      int
	Width  int
	Height int
	Span   int
	Offset int
}

Row builds a layout tree

func NewCol

func NewCol(span, offset int, widgets ...GridBufferer) *Row

NewCol accepts: widgets are LayoutBufferer or widgets is A NewRow. Note that if multiple widgets are provided, they will stack up in the col.

func NewRow

func NewRow(cols ...*Row) *Row

NewRow creates a new row out of given columns.

func (*Row) Buffer

func (r *Row) Buffer() []Point

Buffer implements Bufferer interface, recursively merge all widgets buffer

func (Row) GetHeight

func (r Row) GetHeight() int

GetHeight implements GridBufferer interface.

func (*Row) SetWidth

func (r *Row) SetWidth(w int)

SetWidth implements GridBufferer interface.

func (*Row) SetX

func (r *Row) SetX(x int)

SetX implements GridBufferer interface.

func (*Row) SetY

func (r *Row) SetY(y int)

SetY implements GridBufferer interface.

type Sparkline

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

Sparkline is like: ▅▆▂▂▅▇▂▂▃▆▆▆▅▃

data := []int{4, 2, 1, 6, 3, 9, 1, 4, 2, 15, 14, 9, 8, 6, 10, 13, 15, 12, 10, 5, 3, 6, 1}
spl := termui.NewSparkline()
spl.Data = data
spl.Title = "Sparkline 0"
spl.LineColor = termui.ColorGreen

func NewSparkline

func NewSparkline() Sparkline

NewSparkline returns a unrenderable single sparkline that intended to be added into Sparklines.

type Sparklines

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

Sparklines is a renderable widget which groups together the given sparklines.

spls := termui.NewSparklines(spl0,spl1,spl2) //...
spls.Height = 2
spls.Width = 20

func NewSparklines

func NewSparklines(ss ...Sparkline) *Sparklines

NewSparklines return a new *Spaklines with given Sparkline(s), you can always add a new Sparkline later.

func (*Sparklines) Add

func (s *Sparklines) Add(sl Sparkline)

Add appends a given Sparkline to s *Sparklines.

func (*Sparklines) Buffer

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

Buffer implements Bufferer interface.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL