termui

package module
v0.0.0-...-2d8fd3e Latest Latest
Warning

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

 Go to latest Published: Mar 26, 2015 License: MIT Imports: 6 Imported by: 0

README

termui Build Status Doc Status

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

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

Demo:

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

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) 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
}

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

func Theme 

func Theme() ColorScheme

Theme returns the currently used theme.

type Gauge 

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

Gauge is a progress bar like widget. A simple example: 

g := termui.NewGauge()
g.Percent = 40
g.Width = 50
g.Height = 3
g.Border.Label = "Slim Gauge"
g.BarColor = termui.ColorRed
g.PercentColor = termui.ColorBlue

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