termui

package
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Jul 29, 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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.