termui

package module
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: May 4, 2021 License: MIT Imports: 10 Imported by: 0

README

termui

termui is a cross-platform and fully-customizable terminal dashboard and widget library built on top of termbox-go. It is inspired by blessed-contrib and tui-rs and written purely in Go.

Features

  • Several premade widgets for common use cases
  • Easily create custom widgets
  • Position widgets either in a relative grid or with absolute coordinates
  • Keyboard, mouse, and terminal resizing events
  • Colors and styling

Installation

Go modules

It is not necessary to go get termui, since Go will automatically manage any imported dependencies for you. Do note that you have to include /v3 in the import statements as shown in the 'Hello World' example below.

Dep

Add with dep ensure -add github.com/gizak/termui. With Dep, /v3 should not be included in the import statements.

Hello World

package main

import (
	"log"

	ui "github.com/johnjones4/termui"
	"github.com/johnjones4/termui/widgets"
)

func main() {
	if err := ui.Init(); err != nil {
		log.Fatalf("failed to initialize termui: %v", err)
	}
	defer ui.Close()

	p := widgets.NewParagraph()
	p.Text = "Hello World!"
	p.SetRect(0, 0, 25, 5)

	ui.Render(p)

	for e := range ui.PollEvents() {
		if e.Type == ui.KeyboardEvent {
			break
		}
	}
}

Widgets

Run an example with go run _examples/{example}.go or run each example consecutively with make run-examples.

Documentation

Uses

License

MIT

Documentation

Overview

Package termui is a library for creating terminal user interfaces (TUIs) using widgets.

Index

Constants

View Source 
const (
	DOT      = '•'
	ELLIPSES = '…'

	UP_ARROW   = '▲'
	DOWN_ARROW = '▼'

	COLLAPSED = '+'
	EXPANDED  = '−'
)
View Source 
const (
	TOP_LEFT     = '┌'
	TOP_RIGHT    = '┐'
	BOTTOM_LEFT  = '└'
	BOTTOM_RIGHT = '┘'

	VERTICAL_LINE   = '│'
	HORIZONTAL_LINE = '─'

	VERTICAL_LEFT   = '┤'
	VERTICAL_RIGHT  = '├'
	HORIZONTAL_UP   = '┴'
	HORIZONTAL_DOWN = '┬'

	QUOTA_LEFT  = '«'
	QUOTA_RIGHT = '»'

	VERTICAL_DASH   = '┊'
	HORIZONTAL_DASH = '┈'
)

Variables

View Source 
var (
	BARS = [...]rune{' ', '▁', '▂', '▃', '▄', '▅', '▆', '▇', '█'}

	SHADED_BLOCKS = [...]rune{' ', '░', '▒', '▓', '█'}

	IRREGULAR_BLOCKS = [...]rune{
		' ', '▘', '▝', '▀', '▖', '▌', '▞', '▛',
		'▗', '▚', '▐', '▜', '▄', '▙', '▟', '█',
	}

	BRAILLE_OFFSET = '\u2800'
	BRAILLE        = [4][2]rune{
		{'\u0001', '\u0008'},
		{'\u0002', '\u0010'},
		{'\u0004', '\u0020'},
		{'\u0040', '\u0080'},
	}

	DOUBLE_BRAILLE = map[[2]int]rune{
		[2]int{0, 0}: '⣀',
		[2]int{0, 1}: '⡠',
		[2]int{0, 2}: '⡐',
		[2]int{0, 3}: '⡈',

		[2]int{1, 0}: '⢄',
		[2]int{1, 1}: '⠤',
		[2]int{1, 2}: '⠔',
		[2]int{1, 3}: '⠌',

		[2]int{2, 0}: '⢂',
		[2]int{2, 1}: '⠢',
		[2]int{2, 2}: '⠒',
		[2]int{2, 3}: '⠊',

		[2]int{3, 0}: '⢁',
		[2]int{3, 1}: '⠡',
		[2]int{3, 2}: '⠑',
		[2]int{3, 3}: '⠉',
	}

	SINGLE_BRAILLE_LEFT  = [4]rune{'\u2840', '⠄', '⠂', '⠁'}
	SINGLE_BRAILLE_RIGHT = [4]rune{'\u2880', '⠠', '⠐', '⠈'}
)
View Source 
var CellClear = Cell{
	Rune:  ' ',
	Style: StyleClear,
}
View Source 
var StandardColors = []Color{
	ColorRed,
	ColorGreen,
	ColorYellow,
	ColorBlue,
	ColorMagenta,
	ColorCyan,
	ColorWhite,
}
View Source 
var StandardStyles = []Style{
	NewStyle(ColorRed),
	NewStyle(ColorGreen),
	NewStyle(ColorYellow),
	NewStyle(ColorBlue),
	NewStyle(ColorMagenta),
	NewStyle(ColorCyan),
	NewStyle(ColorWhite),
}
View Source 
var StyleClear = Style{
	Fg:       ColorClear,
	Bg:       ColorClear,
	Modifier: ModifierClear,
}

StyleClear represents a default Style, with no colors or modifiers

View Source 
var StyleParserColorMap = map[string]Color{
	"red":     ColorRed,
	"blue":    ColorBlue,
	"black":   ColorBlack,
	"cyan":    ColorCyan,
	"yellow":  ColorYellow,
	"white":   ColorWhite,
	"clear":   ColorClear,
	"green":   ColorGreen,
	"magenta": ColorMagenta,
}

StyleParserColorMap can be modified to add custom color parsing to text

View Source 
var Theme = RootTheme{
	Default: NewStyle(ColorWhite),

	Block: BlockTheme{
		Title:  NewStyle(ColorWhite),
		Border: NewStyle(ColorWhite),
	},

	BarChart: BarChartTheme{
		Bars:   StandardColors,
		Nums:   StandardStyles,
		Labels: StandardStyles,
	},

	Paragraph: ParagraphTheme{
		Text: NewStyle(ColorWhite),
	},

	PieChart: PieChartTheme{
		Slices: StandardColors,
	},

	List: ListTheme{
		Text: NewStyle(ColorWhite),
	},

	Tree: TreeTheme{
		Text:      NewStyle(ColorWhite),
		Collapsed: COLLAPSED,
		Expanded:  EXPANDED,
	},

	StackedBarChart: StackedBarChartTheme{
		Bars:   StandardColors,
		Nums:   StandardStyles,
		Labels: StandardStyles,
	},

	Gauge: GaugeTheme{
		Bar:   ColorWhite,
		Label: NewStyle(ColorWhite),
	},

	Sparkline: SparklineTheme{
		Title: NewStyle(ColorWhite),
		Line:  ColorWhite,
	},

	Plot: PlotTheme{
		Lines: StandardColors,
		Axes:  ColorWhite,
	},

	Table: TableTheme{
		Text: NewStyle(ColorWhite),
	},

	Tab: TabTheme{
		Active:   NewStyle(ColorRed),
		Inactive: NewStyle(ColorWhite),
	},
}

Theme holds the default Styles and Colors for all widgets. You can set default widget Styles by modifying the Theme before creating the widgets.

Functions

func AbsInt 

func AbsInt(x int) int

func CellsToString 

func CellsToString(cells []Cell) string

func Clear 

func Clear()

func Close 

func Close()

Close closes termbox-go.

func FloorFloat64 

func FloorFloat64(x float64) float64

func GetMaxFloat64From2dSlice 

func GetMaxFloat64From2dSlice(slices [][]float64) (float64, error)

func GetMaxFloat64FromSlice 

func GetMaxFloat64FromSlice(slice []float64) (float64, error)

func GetMaxIntFromSlice 

func GetMaxIntFromSlice(slice []int) (int, error)

func GetMinFloat64From2dSlice 

func GetMinFloat64From2dSlice(slices [][]float64) (float64, error)

func Init 

func Init() error

Init initializes termbox-go and is required to render anything. After initialization, the library must be finalized with `Close`.

func InterfaceSlice 

func InterfaceSlice(slice interface{}) []interface{}

InterfaceSlice takes an []interface{} represented as an interface{} and converts it https://stackoverflow.com/questions/12753805/type-converting-slices-of-interfaces-in-go

func MaxFloat64 

func MaxFloat64(x, y float64) float64

func MaxInt 

func MaxInt(x, y int) int

func MinFloat64 

func MinFloat64(x, y float64) float64

func MinInt 

func MinInt(x, y int) int

func PollEvents 

func PollEvents() <-chan Event

PollEvents gets events from termbox, converts them, then sends them to each of its channels.

func Render 

func Render(items ...Drawable)

func RoundFloat64 

func RoundFloat64(x float64) float64

func SplitCells 

func SplitCells(cells []Cell, r rune) [][]Cell

func SumFloat64Slice 

func SumFloat64Slice(data []float64) float64

func SumIntSlice 

func SumIntSlice(slice []int) int

func TerminalDimensions 

func TerminalDimensions() (int, int)

func TrimString 

func TrimString(s string, w int) string

TrimString trims a string to a max length and adds '…' to the end if it was trimmed.

Types

type Alignment 

type Alignment uint
const (
	AlignLeft Alignment = iota
	AlignCenter
	AlignRight
)

type BarChartTheme 

type BarChartTheme struct {
	Bars   []Color
	Nums   []Style
	Labels []Style
}

type Block 

type Block struct {
	Border      bool
	BorderStyle Style

	BorderLeft, BorderRight, BorderTop, BorderBottom bool

	PaddingLeft, PaddingRight, PaddingTop, PaddingBottom int

	image.Rectangle
	Inner image.Rectangle

	Title      string
	TitleStyle Style

	sync.Mutex
}

Block is the base struct inherited by most widgets. Block manages size, position, border, and title. It implements all 3 of the methods needed for the `Drawable` interface. Custom widgets will override the Draw method.

func NewBlock 

func NewBlock() *Block

func (*Block) Draw 

func (self *Block) Draw(buf *Buffer)

Draw implements the Drawable interface.

func (*Block) GetRect 

func (self *Block) GetRect() image.Rectangle

GetRect implements the Drawable interface.

func (*Block) SetRect 

func (self *Block) SetRect(x1, y1, x2, y2 int)

SetRect implements the Drawable interface.

type BlockTheme 

type BlockTheme struct {
	Title  Style
	Border Style
}

type Buffer 

type Buffer struct {
	image.Rectangle
	CellMap map[image.Point]Cell
}

Buffer represents a section of a terminal and is a renderable rectangle of cells.

func NewBuffer 

func NewBuffer(r image.Rectangle) *Buffer

func (*Buffer) Fill 

func (self *Buffer) Fill(c Cell, rect image.Rectangle)

func (*Buffer) GetCell 

func (self *Buffer) GetCell(p image.Point) Cell

func (*Buffer) SetCell 

func (self *Buffer) SetCell(c Cell, p image.Point)

func (*Buffer) SetString 

func (self *Buffer) SetString(s string, style Style, p image.Point)

type Canvas 

type Canvas struct {
	Block
	drawille.Canvas
}

func NewCanvas 

func NewCanvas() *Canvas

func (*Canvas) Draw 

func (self *Canvas) Draw(buf *Buffer)

func (*Canvas) SetLine 

func (self *Canvas) SetLine(p0, p1 image.Point, color Color)

func (*Canvas) SetPoint 

func (self *Canvas) SetPoint(p image.Point, color Color)

type Cell 

type Cell struct {
	Rune  rune
	Style Style
}

Cell represents a viewable terminal cell

func NewCell 

func NewCell(rune rune, args ...interface{}) Cell

NewCell takes 1 to 2 arguments 1st argument = rune 2nd argument = optional style

func ParseStyles 

func ParseStyles(s string, defaultStyle Style) []Cell

ParseStyles parses a string for embedded Styles and returns []Cell with the correct styling. Uses defaultStyle for any text without an embedded style. Syntax is of the form [text](fg:<color>,mod:<attribute>,bg:<color>). Ordering does not matter. All fields are optional.

func RunesToStyledCells 

func RunesToStyledCells(runes []rune, style Style) []Cell

func TrimCells 

func TrimCells(cells []Cell, w int) []Cell

func WrapCells 

func WrapCells(cells []Cell, width uint) []Cell

WrapCells takes []Cell and inserts Cells containing '\n' wherever a linebreak should go.

type CellWithX 

type CellWithX struct {
	X    int
	Cell Cell
}

func BuildCellWithXArray 

func BuildCellWithXArray(cells []Cell) []CellWithX

type Color 

type Color int

Color is an integer from -1 to 255 -1 = ColorClear 0-255 = Xterm colors 

const (
	ColorBlack   Color = 0
	ColorRed     Color = 1
	ColorGreen   Color = 2
	ColorYellow  Color = 3
	ColorBlue    Color = 4
	ColorMagenta Color = 5
	ColorCyan    Color = 6
	ColorWhite   Color = 7
)

Basic terminal colors 

const ColorClear Color = -1

ColorClear clears the Fg or Bg color of a Style

func SelectColor 

func SelectColor(colors []Color, index int) Color

type Drawable 

type Drawable interface {
	GetRect() image.Rectangle
	SetRect(int, int, int, int)
	Draw(*Buffer)
	sync.Locker
}

type Event 

type Event struct {
	Type    EventType
	ID      string
	Payload interface{}
}

type EventType 

type EventType uint
const (
	KeyboardEvent EventType = iota
	MouseEvent
	ResizeEvent
)

type GaugeTheme 

type GaugeTheme struct {
	Bar   Color
	Label Style
}

type Grid 

type Grid struct {
	Block
	Items []*GridItem
}

func NewGrid 

func NewGrid() *Grid

func (*Grid) Draw 

func (self *Grid) Draw(buf *Buffer)

func (*Grid) Set 

func (self *Grid) Set(entries ...interface{})

Set is used to add Columns and Rows to the grid. It recursively searches the GridItems, adding leaves to the grid and calculating the dimensions of the leaves.

type GridItem 

type GridItem struct {
	Type        gridItemType
	XRatio      float64
	YRatio      float64
	WidthRatio  float64
	HeightRatio float64
	Entry       interface{} // Entry.type == GridBufferer if IsLeaf else []GridItem
	IsLeaf      bool
	// contains filtered or unexported fields
}

GridItem represents either a Row or Column in a grid. Holds sizing information and either an []GridItems or a widget.

func NewCol 

func NewCol(ratio float64, i ...interface{}) GridItem

NewCol takes a height percentage and either a widget or a Row or Column

func NewRow 

func NewRow(ratio float64, i ...interface{}) GridItem

NewRow takes a width percentage and either a widget or a Row or Column

type ListTheme 

type ListTheme struct {
	Text Style
}

type Modifier 

type Modifier uint
const (
	// ModifierClear clears any modifiers
	ModifierClear     Modifier = 0
	ModifierBold      Modifier = 1 << 9
	ModifierUnderline Modifier = 1 << 10
	ModifierReverse   Modifier = 1 << 11
)

type Mouse 

type Mouse struct {
	Drag bool
	X    int
	Y    int
}

Mouse payload.

type ParagraphTheme 

type ParagraphTheme struct {
	Text Style
}

type PieChartTheme 

type PieChartTheme struct {
	Slices []Color
}

type PlotTheme 

type PlotTheme struct {
	Lines []Color
	Axes  Color
}

type Resize 

type Resize struct {
	Width  int
	Height int
}

Resize payload.

type RootTheme 

type RootTheme struct {
	Default Style

	Block BlockTheme

	BarChart        BarChartTheme
	Gauge           GaugeTheme
	Plot            PlotTheme
	List            ListTheme
	Tree            TreeTheme
	Paragraph       ParagraphTheme
	PieChart        PieChartTheme
	Sparkline       SparklineTheme
	StackedBarChart StackedBarChartTheme
	Tab             TabTheme
	Table           TableTheme
}

type SparklineTheme 

type SparklineTheme struct {
	Title Style
	Line  Color
}

type StackedBarChartTheme 

type StackedBarChartTheme struct {
	Bars   []Color
	Nums   []Style
	Labels []Style
}

type Style 

type Style struct {
	Fg       Color
	Bg       Color
	Modifier Modifier
}

Style represents the style of one terminal cell

func NewStyle 

func NewStyle(fg Color, args ...interface{}) Style

NewStyle takes 1 to 3 arguments 1st argument = Fg 2nd argument = optional Bg 3rd argument = optional Modifier

func SelectStyle 

func SelectStyle(styles []Style, index int) Style

type TabTheme 

type TabTheme struct {
	Active   Style
	Inactive Style
}

type TableTheme 

type TableTheme struct {
	Text Style
}

type TreeTheme 

type TreeTheme struct {
	Text      Style
	Collapsed rune
	Expanded  rune
}

Source Files

View all Source files

Directories

Path Synopsis

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.