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
- func Close()
- func ColorSubsequencesToMap(sequences []ColorSubsequence) map[int]Attribute
- func EventCh() <-chan Event
- func Init() error
- func Render(rs ...Bufferer)
- func SetTheme(newTheme ColorScheme)
- func TermHeight() int
- func TermWidth() int
- func TrimStr2Runes(s string, w int) []rune
- func TrimStrIfAppropriate(s string, w int) string
- func UseTheme(th string)
- type Align
- type Attribute
- type BarChart
- type Block
- type Bufferer
- type Canvas
- type ColorScheme
- type ColorSubsequence
- type EscapeCode
- type EscapeCodeRenderer
- type EscapeCodeRendererFactory
- type Event
- type EventType
- type Gauge
- type Grid
- type GridBufferer
- type Key
- type LineChart
- type List
- type MBarChart
- type MarkdownTextRenderer
- type MarkdownTextRendererFactory
- type Modifier
- type Par
- type PlainRenderer
- type PlainRendererFactory
- type Point
- type RenderedSequence
- type Row
- type Sparkline
- type Sparklines
- type TextRenderer
- type TextRendererFactory
Constants ¶
const BOTTOM_LEFT = '└'
const BOTTOM_RIGHT = '┘'
const HDASH = '┈'
const HORIZONTAL_LINE = '─'
const MarkdownRegex = `(?:\[([^]]+)\])\(([a-z\s,]+)\)`
MarkdownRegex is used by MarkdownTextRenderer to determine how to format the text.
const NumberofColors = 8 //Have a constant that defines number of colors
const ORIGIN = '└'
const TOP_LEFT = '┌'
const TOP_RIGHT = '┐'
const VDASH = '┊'
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 ColorSubsequencesToMap ¶
func ColorSubsequencesToMap(sequences []ColorSubsequence) map[int]Attribute
ColorSubsequencesToMap creates a map with all colors that from the subsequences.
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 TrimStr2Runes ¶
TrimStr2Runes trims string to w[-1 rune], appends …, and returns the runes of that string if string is grather then n. If string is small then w, return the runes.
func TrimStrIfAppropriate ¶
TrimStrIfAppropriate trim string to "s[:-1] + …" if string > width otherwise return string
Types ¶
type Attribute ¶
type Attribute uint16
Attribute is printable cell's color and style.
func StringToAttribute ¶
StringToAttribute converts text to a termui attribute. You may specifiy more then one attribute like that: "BLACK, BOLD, ...". All whitespaces are ignored.
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.
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) InnerBounds ¶
InnerBounds returns the internal bounds of the block after aligning and calculating the padding and border, if any.
type Bufferer ¶
type Bufferer interface {
Buffer() []Point
}
Bufferer should be implemented by all renderable components.
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.
type ColorSubsequence ¶
A ColorSubsequence represents a color for the given text span.
type EscapeCode ¶
type EscapeCode string
An EscapeCode is a unix ASCII Escape code.
func (EscapeCode) Color ¶
func (e EscapeCode) Color() (Attribute, error)
Color converts the escape code to an `Attribute` (color). The EscapeCode must be formatted like this:
- ASCII-Escape chacter (\033) + [ + Number + (;Number...) + m
The second number is optimal. The semicolon (;) is used to seperate the colors. For example: `\033[1;31m` means: the following text is red and bold.
func (EscapeCode) IsValid ¶
func (e EscapeCode) IsValid() bool
IsValid returns whether or not the syntax of the escape code is valid and the code is supported.
func (EscapeCode) MakeSafe ¶
func (e EscapeCode) MakeSafe() string
MakeSafe replace the invisible escape code chacacter (\0333) with \\0333 so that it will not mess up the terminal when an error is shown.
func (EscapeCode) Raw ¶
func (e EscapeCode) Raw() string
Raw returns the raw value of the escape code. Alias to string(EscapeCode)
type EscapeCodeRenderer ¶
type EscapeCodeRenderer struct {
Text string
}
A EscapeCodeRenderer does not render the text at all.
func (EscapeCodeRenderer) NormalizedText ¶
func (r EscapeCodeRenderer) NormalizedText() string
NormalizedText strips all escape code outs (even the unkown/unsupported) ones.
func (EscapeCodeRenderer) Render ¶
func (r EscapeCodeRenderer) Render(lastColor, background Attribute) RenderedSequence
Render just like RenderSequence
func (EscapeCodeRenderer) RenderSequence ¶
func (r EscapeCodeRenderer) RenderSequence(start, end int, lastColor, background Attribute) RenderedSequence
RenderSequence renders the text just like Render but the start and end may be set. If end is -1, the end of the string will be used.
type EscapeCodeRendererFactory ¶
type EscapeCodeRendererFactory struct{}
EscapeCodeRendererFactory is a TextRendererFactory for the EscapeCodeRenderer.
func (EscapeCodeRendererFactory) TextRenderer ¶
func (f EscapeCodeRendererFactory) TextRenderer(text string) TextRenderer
TextRenderer returns a EscapeCodeRenderer instance.
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 Gauge ¶
type Grid ¶
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.
type GridBufferer ¶
GridBufferer introduces a Bufferer that can be manipulated by Grid.
type Key ¶
type Key uint16
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.
type List ¶
type List struct { Block Items []string Overflow string ItemFgColor Attribute ItemBgColor Attribute RendererFactory TextRendererFactory }
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
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.
type MarkdownTextRenderer ¶
type MarkdownTextRenderer struct {
Text string
}
MarkdownTextRenderer is used for rendering the text with colors using markdown-like syntax. See: https://github.com/gizak/termui/issues/4#issuecomment-87270635
func (MarkdownTextRenderer) NormalizedText ¶
func (r MarkdownTextRenderer) NormalizedText() string
NormalizedText returns the text the user will see (without colors). It strips out all formatting option and only preserves plain text.
func (MarkdownTextRenderer) Render ¶
func (r MarkdownTextRenderer) Render(lastColor, background Attribute) RenderedSequence
Render renders the sequence `text` using a markdown-like syntax: `[hello](red) world` will become: `hello world` where hello is red.
You may also specify other attributes such as bold text: `[foo](YELLOW, BOLD)` will become `foo` in yellow, bold text.
For all available combinations, colors, and attribute, see: `StringToAttribute`.
This method returns a RenderedSequence
func (MarkdownTextRenderer) RenderSequence ¶
func (r MarkdownTextRenderer) RenderSequence(start, end int, lastColor, background Attribute) RenderedSequence
RenderSequence renders the text just like Render but the start and end can be specified.
type MarkdownTextRendererFactory ¶
type MarkdownTextRendererFactory struct{}
MarkdownTextRendererFactory is a TextRendererFactory for the MarkdownTextRenderer.
func (MarkdownTextRendererFactory) TextRenderer ¶
func (f MarkdownTextRendererFactory) TextRenderer(text string) TextRenderer
TextRenderer returns a MarkdownTextRenderer instance.
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 RendererFactory TextRendererFactory }
Par displays a paragraph.
par := termui.NewPar("Simple Text") par.Height = 3 par.Width = 17 par.Border.Label = "Label"
type PlainRenderer ¶
type PlainRenderer struct {
Text string
}
A PlainRenderer does not render the text at all.
func (PlainRenderer) NormalizedText ¶
func (r PlainRenderer) NormalizedText() string
NormalizedText returns the text given in
func (PlainRenderer) Render ¶
func (r PlainRenderer) Render(lastColor, background Attribute) RenderedSequence
Render just like RenderSequence
func (PlainRenderer) RenderSequence ¶
func (r PlainRenderer) RenderSequence(start, end int, lastColor, background Attribute) RenderedSequence
RenderSequence returns a RenderedSequence that does not have any color sequences.
type PlainRendererFactory ¶
type PlainRendererFactory struct{}
PlainRendererFactory is a TextRendererFactory for the PlainRenderer.
func (PlainRendererFactory) TextRenderer ¶
func (f PlainRendererFactory) TextRenderer(text string) TextRenderer
TextRenderer returns a PlainRenderer instance.
type RenderedSequence ¶
type RenderedSequence struct { NormalizedText string LastColor Attribute BackgroundColor Attribute Sequences []ColorSubsequence // contains filtered or unexported fields }
RenderedSequence is a string sequence that is capable of returning the Buffer used by termui for displaying the colorful string.
func (*RenderedSequence) Buffer ¶
func (s *RenderedSequence) Buffer(x, y int) ([]Point, Attribute)
Buffer returns the colorful formatted buffer and the last color that was used.
func (*RenderedSequence) PointAt ¶
func (s *RenderedSequence) PointAt(n, x, y int) (Point, int)
PointAt returns the point at the position of n. The x, and y coordinates are used for placing the point at the right position. Since some charaters are wider (like `一`), this method also returns the width the point actually took. This is important for increasing the x property properly.
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.
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 ¶
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.
type TextRenderer ¶
type TextRenderer interface { NormalizedText() string Render(lastColor, background Attribute) RenderedSequence RenderSequence(start, end int, lastColor, background Attribute) RenderedSequence }
TextRenderer adds common methods for rendering a text on screeen.
type TextRendererFactory ¶
type TextRendererFactory interface {
TextRenderer(text string) TextRenderer
}
TextRendererFactory is factory for creating text renderers.