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

Directories

Path Synopsis

Jump to

Keyboard shortcuts

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