tui

package module
v0.1.4 Latest Latest
Warning

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

 Go to latest Published: Jan 31, 2021 License: BSD-2-Clause Imports: 8 Imported by: 0

README

GoDoc Build Status

go-tui

Package gen64/go-tui is meant to simplify printing on terminal window by specifying boxes and adding static or dynamic content to it. These boxes here are called panes and they are defined by vertical or horizontal split. Terminal window is main pane which can be split into another panes, and these panes can be split again into next ones, and so on... Just like in another great tool which is tmux.

Pane size can be defined as a percentage or as number of characters. Pane content can be dynamic and coming from an attached function (in sample code below it's called a Widget).

Pane can have a border that can be styled by defining what characters should be used for it (left side, top-left corder, top bar etc.).

Package tui implementation uses ANSI escape codes and so far has been tested on MacOSX and Linux. It won't work on Windows (probably Cygwin as well).

Install

Ensure you have your workspace directory created and run the following:

go get -u github.com/gen64/go-tui
Example

See below sample code and a screenshot of its execution.

package main

import (
    "os"
    "github.com/gen64/go-tui"
)

// TUI has onDraw event and a function can be attached to it. onDraw is
// called when TUI is being drawn, eg. when first started or when
// terminal window is resized.
// getOnTUIDraw returns a func that will later be attached in main().
func getOnTUIDraw(n *NTree) func(*tui.TUI) int {
    // It does nothing actually.
    fn := func(c *tui.TUI) int {
        return 0
    }
    return fn
}

// TUIPane has onDraw event and a function can be attached to it. onDraw
// is called when TUI is being drawn, eg. when first started or when
// terminal window is resized.
// getOnTUIPaneDraw returns a func that will later be attached in main().
func getOnTUIPaneDraw(n *NTree, p *tui.TUIPane) func(*tui.TUIPane) int {
    // Func is defined separate in another struct which is called a Widget.
    // This Widget prints out current time. Check the source for more.
    t := tui.NewTUIWidgetSample()
    t.InitPane(p)
    fn := func(x *tui.TUIPane) int {
        return t.Run(x)
    }
    return fn
}

func main() {
    // Create TUI instance
    myTUI := tui.NewTUI("My Project", "Its description", "Author")
    // Attach func to onDraw event
    myTUI.SetOnDraw(getOnTUIDraw(n))

    // Get main pane which we are going to split
    p0 := myTUI.GetPane()

    // Create new panes by splitting the main pane. Split creates two
    // panes and we have to define size of one of them. If it's the
    // left (vertical) or top (horizontal) one then the value is lower than
    // 0 and if it's right (vertical) or bottom (horizontal) then the value
    // should be highter than 0. It can be a percentage of width/height or
    // number of characters, as it's shown below.
    p01, p02 := p0.SplitVertically(-50, tui.UNIT_PERCENT)
    p021, p022 := p02.SplitVertically(-40, tui.UNIT_CHAR)

    p11, p12 := p01.SplitHorizontally(20, tui.UNIT_CHAR)
    p21, p22 := p021.SplitHorizontally(50, tui.UNIT_PERCENT)
    p31, p32 := p022.SplitHorizontally(-35, tui.UNIT_CHAR)

    // Create style instances which will be attached to certain panes
    s1 := tui.NewTUIPaneStyleFrame()
    s2 := tui.NewTUIPaneStyleMargin()

    // Create custom TUIPaneStyle. Previous ones are predefined and come
    // with the package.
    s3 := &tui.TUIPaneStyle{
        NE: "/", NW: "\\", SE: " ", SW: " ", E: " ", W: " ", N: "_", S: " ",
    }

    // Set pane styles.
    p11.SetStyle(s1)
    p12.SetStyle(s1)
    p21.SetStyle(s2)
    p22.SetStyle(s2)
    p31.SetStyle(s3)
    p32.SetStyle(s1)

    // Attach previously defined func to panes' onDraw event. onDraw
    // handler is called whenever pane is being drawn: on start and
    // on terminal window resize.
    p11.SetOnDraw(getOnTUIPaneDraw(n, p11))
    p12.SetOnDraw(getOnTUIPaneDraw(n, p12))
    p21.SetOnDraw(getOnTUIPaneDraw(n, p21))
    p22.SetOnDraw(getOnTUIPaneDraw(n, p22))
    p31.SetOnDraw(getOnTUIPaneDraw(n, p31))
    p32.SetOnDraw(getOnTUIPaneDraw(n, p32))

    // Attach previously defined func to panes' onIterate event.
    // onIterate handler is called every iteration of TUI's main loop.
    // There is a one second delay between every iteration.
    p11.SetOnIterate(getOnTUIPaneDraw(n, p11))
    p12.SetOnIterate(getOnTUIPaneDraw(n, p12))
    p21.SetOnIterate(getOnTUIPaneDraw(n, p21))
    p22.SetOnIterate(getOnTUIPaneDraw(n, p22))
    p31.SetOnIterate(getOnTUIPaneDraw(n, p31))
    p32.SetOnIterate(getOnTUIPaneDraw(n, p32))

    // Run TUI
    myTUI.Run(os.Stdout, os.Stderr)
}

Example

Documentation

Overview

Package tui is meant to simplify printing on terminal window by specifying boxes and adding static or dynamic content to it. These boxes are called panes and they are defined by vertical or horizontal split. Terminal window is main pane which can be split into another panes, and these panes can be split again into next ones, and so on... Just like in another great tool which is tmux.

Pane size can be defined as a percentage or as number of characters. Pane content can be dynamic and coming from an attached function (in sample code below it's called a Widget).

Pane can have a border that can be styled by defining what characters should be used for it (left side, top-left corner, top bar etc.).

Package tui implementation uses ANSI escape codes and so far has been tested on MacOSX and Linux. It won't work on Windows (probably Cygwin as well).

Install

Ensure you have your workspace directory created and run the following: 

go get -u github.com/gen64/go-tui

Example

See below sample with explanation in comments. 

package main

import (
    "os"
    "github.com/gen64/go-tui"
)

// TUI has onDraw event and a function can be attached to it. onDraw is
// called when TUI is being drawn, eg. when first started or when
// terminal window is resized.
// getOnTUIDraw returns a func that will later be attached in main().
func getOnTUIDraw(n *NTree) func(*tui.TUI) int {
    // It does nothing actually.
    fn := func(c *tui.TUI) int {
        return 0
    }
    return fn
}

// TUIPane has onDraw event and a function can be attached to it. onDraw
// is called when TUI is being drawn, eg. when first started or when
// terminal window is resized.
// getOnTUIPaneDraw returns a func that will later be attached in main().
func getOnTUIPaneDraw(n *NTree, p *tui.TUIPane) func(*tui.TUIPane) int {
    // Func is defined separate in another struct which is called a Widget.
    // This Widget prints out current time. Check the source for more.
    t := tui.NewTUIWidgetSample()
    t.InitPane(p)
    fn := func(x *tui.TUIPane) int {
        return t.Run(x)
    }
    return fn
}

func main() {
    // Create TUI instance
    myTUI := tui.NewTUI("My Project", "Its description", "Author")
    // Attach func to onDraw event
    myTUI.SetOnDraw(getOnTUIDraw(n))

    // Get main pane which we are going to split
    p0 := myTUI.GetPane()

    // Create new panes by splitting the main pane. Split creates two
    // panes and we have to define size of one of them. If it's the
    // left (vertical) or top (horizontal) one then the value is lower than
    // 0 and if it's right (vertical) or bottom (horizontal) then the value
    // should be highter than 0. It can be a percentage of width/height or
    // number of characters, as it's shown below.
    p01, p02 := p0.SplitVertically(-50, tui.UNIT_PERCENT)
    p021, p022 := p02.SplitVertically(-40, tui.UNIT_CHAR)

    p11, p12 := p01.SplitHorizontally(20, tui.UNIT_CHAR)
    p21, p22 := p021.SplitHorizontally(50, tui.UNIT_PERCENT)
    p31, p32 := p022.SplitHorizontally(-35, tui.UNIT_CHAR)

    // Create style instances which will be attached to certain panes
    s1 := tui.NewTUIPaneStyleFrame()
    s2 := tui.NewTUIPaneStyleMargin()

    // Create custom TUIPaneStyle. Previous ones are predefined and come
    // with the package.
    s3 := &tui.TUIPaneStyle{
        NE: "/", NW: "\\", SE: " ", SW: " ", E: " ", W: " ", N: "_", S: " ",
    }

    // Set pane styles.
    p11.SetStyle(s1)
    p12.SetStyle(s1)
    p21.SetStyle(s2)
    p22.SetStyle(s2)
    p31.SetStyle(s3)
    p32.SetStyle(s1)

    // Attach previously defined func to panes' onDraw event. onDraw
    // handler is called whenever pane is being drawn: on start and
    // on terminal window resize.
    p11.SetOnDraw(getOnTUIPaneDraw(n, p11))
    p12.SetOnDraw(getOnTUIPaneDraw(n, p12))
    p21.SetOnDraw(getOnTUIPaneDraw(n, p21))
    p22.SetOnDraw(getOnTUIPaneDraw(n, p22))
    p31.SetOnDraw(getOnTUIPaneDraw(n, p31))
    p32.SetOnDraw(getOnTUIPaneDraw(n, p32))

    // Attach previously defined func to panes' onIterate event.
    // onIterate handler is called every iteration of TUI's main loop.
    // There is a one second delay between every iteration.
    p11.SetOnIterate(getOnTUIPaneDraw(n, p11))
    p12.SetOnIterate(getOnTUIPaneDraw(n, p12))
    p21.SetOnIterate(getOnTUIPaneDraw(n, p21))
    p22.SetOnIterate(getOnTUIPaneDraw(n, p22))
    p31.SetOnIterate(getOnTUIPaneDraw(n, p31))
    p32.SetOnIterate(getOnTUIPaneDraw(n, p32))

    // Run TUI
    myTUI.Run(os.Stdout, os.Stderr)
}

Index

Constants

View Source 
const SPLIT_H = 1
View Source 
const SPLIT_NONE = 0
View Source 
const SPLIT_V = 2
View Source 
const UNIT_CHAR = 2
View Source 
const UNIT_PERCENT = 1
View Source 
const VERSION = "0.1.4"

Variables

This section is empty.

Functions

This section is empty.

Types

type TUI 

type TUI struct {
	// contains filtered or unexported fields
}

TUI is main interface definition. It has a name, description, author (which are not used anywhere yet), current terminal width and height, pointer to main pane, pointer to a function that is triggered when interface is being drawn (that happens when app is started and when terminal size is changed), and finally pointers to standard output and standard error File instances.

func NewTUI 

func NewTUI(n string, d string, a string) *TUI

NewTUI creates new instance of TUI and returns it

func (*TUI) Exit 

func (t *TUI) Exit(i int)

func (*TUI) GetAuthor 

func (t *TUI) GetAuthor() string

GetAuthor returns TUI author

func (*TUI) GetDesc 

func (t *TUI) GetDesc() string

GetDesc returns TUI description

func (*TUI) GetHeight 

func (t *TUI) GetHeight() int

GetHeight returns cached terminal height

func (*TUI) GetLoopSleep 

func (t *TUI) GetLoopSleep() int

GetLoopSleep returns delay between each iteration of main loop

func (*TUI) GetName 

func (t *TUI) GetName() string

GetName returns TUI name

func (*TUI) GetPane 

func (t *TUI) GetPane() *TUIPane

GetPane returns initial/first terminal pane

func (*TUI) GetStderr 

func (t *TUI) GetStderr() *os.File

GetStderr returns stderr property

func (*TUI) GetStdout 

func (t *TUI) GetStdout() *os.File

GetStdout returns stdout property

func (*TUI) GetWidth 

func (t *TUI) GetWidth() int

GetWidth returns cached terminal width

func (*TUI) Run 

func (t *TUI) Run(stdout *os.File, stderr *os.File) int

Run clears the terminal and starts program's main loop

func (*TUI) SetLoopSleep 

func (t *TUI) SetLoopSleep(s int)

SetLoopSleep sets the delay between each iteration of main loop

func (*TUI) SetOnDraw 

func (t *TUI) SetOnDraw(f func(*TUI) int)

SetOnDraw attaches function that will be triggered when interface is being drawn (what happens on initialisation and terminal resize)

func (*TUI) SetOnKeyPress 

func (t *TUI) SetOnKeyPress(f func(*TUI, []byte))

SetOnKeyPress attaches function that will triggered when key is pressed (a byte is sent onto stdio)

func (*TUI) SetPane 

func (t *TUI) SetPane(p *TUIPane)

SetPane sets the main terminal pane

func (*TUI) Write 

func (t *TUI) Write(x int, y int, s string)

Write prints out on the terminal window at a specified position

type TUIPane 

type TUIPane struct {
	// contains filtered or unexported fields
}

TUIPane represent a pane within the terminal interface. It has a name. It can be split horizontally or vertically to create another 2 panes. Split can be described as percentage or fixed characters and only one of the panes created from split can have fixed size. Other one is calculated from total width. Pane also have min width, min height, style and have two events: onDraw and onIterate.

func NewTUIPane 

func NewTUIPane(n string, t *TUI) *TUIPane

NewTUIPane returns new instance of TUIPane

func (*TUIPane) Draw 

func (p *TUIPane) Draw() int

Draw prints the pane on terminal window

func (*TUIPane) GetHeight 

func (p *TUIPane) GetHeight() int

GetHeight returns pane height

func (*TUIPane) GetLeft 

func (p *TUIPane) GetLeft() int

GetLeft returns x position of pane on terminal window (main pane)

func (*TUIPane) GetMinHeight 

func (p *TUIPane) GetMinHeight() int

GetMinHeight returns minimal height necessary for pane content to work

func (*TUIPane) GetMinWidth 

func (p *TUIPane) GetMinWidth() int

GetMinWidth returns minimal width necessary for pane content to work

func (*TUIPane) GetName 

func (p *TUIPane) GetName() string

GetName returns name

func (*TUIPane) GetOnDraw 

func (p *TUIPane) GetOnDraw() func(p *TUIPane) int

GetOnDraw returns onDraw event func

func (*TUIPane) GetOnIterate 

func (p *TUIPane) GetOnIterate() func(p *TUIPane) int

GetOnIterate returns onIterate event func

func (*TUIPane) GetPanes 

func (p *TUIPane) GetPanes() [2]*TUIPane

GetPanes returns pane instances created by split

func (*TUIPane) GetSplit 

func (p *TUIPane) GetSplit() int

GetSplit returns split type (horizontal or vertical)

func (*TUIPane) GetStyle 

func (p *TUIPane) GetStyle() *TUIPaneStyle

GetStyle returns style instance

func (*TUIPane) GetTUI 

func (p *TUIPane) GetTUI() *TUI

GetTUI returns TUI instance that this pane is attached to

func (*TUIPane) GetTop 

func (p *TUIPane) GetTop() int

GetTop returns y position of pane on terminal window (main pane)

func (*TUIPane) GetTotalMinHeight 

func (p *TUIPane) GetTotalMinHeight() int

GetTotalMinHeight returns total minimal height necessary for pane to work It is GetMinHeight + height necessary for style

func (*TUIPane) GetTotalMinWidth 

func (p *TUIPane) GetTotalMinWidth() int

GetTotalMinWidth returns total minimal width necessary for pane to work It is GetMinWidth + width necessary for style

func (*TUIPane) GetWidth 

func (p *TUIPane) GetWidth() int

GetWidth returns pane width

func (*TUIPane) Iterate 

func (p *TUIPane) Iterate() int

Iterate is executed by TUI with every main loop iteration

func (*TUIPane) SetHeight 

func (p *TUIPane) SetHeight(h int)

SetHeight sets height of pane, checks if it's not too small for the content (search for 'minimal height') and calls panes inside to set their height as well.

func (*TUIPane) SetLeft 

func (p *TUIPane) SetLeft(l int)

SetLeft sets the left value (x position on main pane)

func (*TUIPane) SetMinHeight 

func (p *TUIPane) SetMinHeight(h int)

SetMinHeight sets minimal height for pane content (without style)

func (*TUIPane) SetMinWidth 

func (p *TUIPane) SetMinWidth(w int)

SetMinWidth sets minimal width for pane content (without style)

func (*TUIPane) SetOnDraw 

func (p *TUIPane) SetOnDraw(f func(p *TUIPane) int)

SetOnDraw sets onDraw event func

func (*TUIPane) SetOnIterate 

func (p *TUIPane) SetOnIterate(f func(p *TUIPane) int)

SetOnIterate sets onIterate event func

func (*TUIPane) SetStyle 

func (p *TUIPane) SetStyle(s *TUIPaneStyle)

SetStyle sets style

func (*TUIPane) SetTop 

func (p *TUIPane) SetTop(t int)

SetTop sets the top value (y position on main pane)

func (*TUIPane) SetWidth 

func (p *TUIPane) SetWidth(w int)

SetWidth sets width of pane, checks if it's not too small for the content (search for 'minimal width') and calls panes inside to set their width as well.

func (*TUIPane) Split 

func (p *TUIPane) Split(t int, s int, u int) (*TUIPane, *TUIPane)

Split creates new two panes by splitting this pane either horizontally or vertically. Type, size, size unit are func arguments. Function returns pointers to two new panes.

func (*TUIPane) SplitHorizontally 

func (p *TUIPane) SplitHorizontally(s int, u int) (*TUIPane, *TUIPane)

SplitHorizontally splits pane horizontally. It takes size and size unit as arguments. Only one of the two new panes gets the defined size. If the value is < 0 then it's the top one, when the value is > 0 then it is the right one.

func (*TUIPane) SplitVertically 

func (p *TUIPane) SplitVertically(s int, u int) (*TUIPane, *TUIPane)

SplitVertically splits pane vertically. It takes size and size unit as arguments. Only one of the two new panes gets the defined size. If the value is < 0 then it's the left one, when the value is > 0 then it is the right one.

func (*TUIPane) Write 

func (p *TUIPane) Write(x int, y int, s string, overwriteStyleFrame bool)

Write prints string on the pane

type TUIPaneStyle 

type TUIPaneStyle struct {
	NE string
	N  string
	NW string
	W  string
	SW string
	S  string
	SE string
	E  string
}

TUIPaneStyle defined pane style

func NewTUIPaneStyleFrame 

func NewTUIPaneStyleFrame() *TUIPaneStyle

NewTUIPaneStyleFrame returns TUIPaneStyle instance with a nice frame around

func NewTUIPaneStyleMargin 

func NewTUIPaneStyleMargin() *TUIPaneStyle

NewTUIPaneStyleMargin returns TUIPaneStyle instance without a frame but with an internal margin

func NewTUIPaneStyleNone 

func NewTUIPaneStyleNone() *TUIPaneStyle

NewTUIPaneStyleNone returns TUIPaneStyle instance without any frame or margin

func (*TUIPaneStyle) B 

func (s *TUIPaneStyle) B() int

B (bottom) returns height of bottom border

func (*TUIPaneStyle) Draw 

func (s *TUIPaneStyle) Draw(p *TUIPane)

Draw prints border around the pane

func (*TUIPaneStyle) H 

func (s *TUIPaneStyle) H() int

H (horizontal) returns minimal width for borders

func (*TUIPaneStyle) L 

func (s *TUIPaneStyle) L() int

L (left) returns width of left border

func (*TUIPaneStyle) R 

func (s *TUIPaneStyle) R() int

R (right) returns width of right border

func (*TUIPaneStyle) T 

func (s *TUIPaneStyle) T() int

T (top) returns height of top border

func (*TUIPaneStyle) V 

func (s *TUIPaneStyle) V() int

V (vertical) returns minimal height for borders

type TUIWidgetSample 

type TUIWidgetSample struct {
}

func NewTUIWidgetSample 

func NewTUIWidgetSample() *TUIWidgetSample

NewTUIWidgetSample returns instance of TUIWidgetSample struct

func (*TUIWidgetSample) InitPane 

func (w *TUIWidgetSample) InitPane(p *TUIPane)

InitPane sets pane minimal width and height that's necessary for the pane to work.

func (*TUIWidgetSample) Run 

func (w *TUIWidgetSample) Run(p *TUIPane) int

Run is main function which just prints out the current time.

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.