README.md
1# Terminal User Interface Widgets in Go
2
3Gowid provides widgets and a framework for making terminal user interfaces. It's written in Go and inspired by [urwid](http://urwid.org).
4
5Widgets out-of-the-box include:
6
7 - input components like button, checkbox and an editable text field with support for passwords
8 - layout components for arranging widgets in columns, rows and a grid
9 - structured components - a tree, an infinite list and a table
10 - pre-canned widgets - a progress bar, a modal dialog, a bar graph and a menu
11 - a VT220-compatible terminal widget, heavily cribbed from urwid :smiley:
12
13All widgets support interaction with the mouse when the terminal allows.
14
15Gowid is built on top of the fantastic [tcell](https://github.com/gdamore/tcell) package.
16
17There are many alternatives to gowid - see [Similar Projects](#similar-projects)
18
19The most developed gowid application is currently [termshark](https://termshark.io), a terminal UI for tshark.
20## Installation
21
22```bash
23go get github.com/gcla/gowid/...
24```
25## Examples
26
27Make sure `$GOPATH/bin` is in your PATH (or `~/go/bin` if `GOPATH` isn't set), then tab complete "gowid-" e.g.
28
29```bash
30gowid-fib
31```
32
33Here is a port of urwid's [palette](https://github.com/urwid/urwid/blob/master/examples/palette_test.py) example:
34
35<a href="https://drive.google.com/uc?export=view&id=1wENPAEOOdPp6eeHvpH0TvYOYnl4Gmy9Q"><img src="https://drive.google.com/uc?export=view&id=1wENPAEOOdPp6eeHvpH0TvYOYnl4Gmy9Q" style="width: 50px; max-width: 10%; height: auto" title="Click for the larger version." /></a>
36
37Here is urwid's [graph](https://github.com/urwid/urwid/blob/master/examples/graph.py) example:
38
39<a href="https://drive.google.com/uc?export=view&id=16p1NFrc3X3ReD-wz7bPXeYF8pCap3U-y"><img src="https://drive.google.com/uc?export=view&id=16p1NFrc3X3ReD-wz7bPXeYF8pCap3U-y" style="width: 50px; max-width: 10%; height: auto" title="Click for the larger version." /></a>
40
41And urwid's [fibonacci](https://github.com/urwid/urwid/blob/master/examples/fib.py) example:
42
43<a href="https://drive.google.com/uc?export=view&id=1fPVYOWt7EMUP18ZQL78OFY7IXwmeeqUO"><img src="https://drive.google.com/uc?export=view&id=1fPVYOWt7EMUP18ZQL78OFY7IXwmeeqUO" style="width: 500px; max-width: 100%; height: auto" title="Click for the larger version." /></a>
44
45A demonstration of gowid's terminal widget, a port of urwid's [terminal widget](https://github.com/urwid/urwid/blob/master/examples/terminal.py):
46
47<a href="https://drive.google.com/uc?export=view&id=1bRtgHoXcy0UESmKZK6JID8FIlkf5T7aL"><img src="https://drive.google.com/uc?export=view&id=1bRtgHoXcy0UESmKZK6JID8FIlkf5T7aL" style="width: 500px; max-width: 100%; height: auto" title="Click for the larger version." /></a>
48
49Finally, here is an animation of termshark in action:
50
51<a href="https://drive.google.com/uc?export=view&id=1vDecxjqwJrtMGJjOObL-LLvi-1pBVByt"><img src="https://drive.google.com/uc?export=view&id=1vDecxjqwJrtMGJjOObL-LLvi-1pBVByt" style="width: 500px; max-width: 100%; height: auto" title="Click for the larger version." /></a>
52
53## Hello World
54
55This example is an attempt to mimic urwid's ["Hello World"](http://urwid.org/tutorial/index.html) example.
56
57```go
58package main
59
60import (
61 "github.com/gcla/gowid"
62 "github.com/gcla/gowid/widgets/divider"
63 "github.com/gcla/gowid/widgets/pile"
64 "github.com/gcla/gowid/widgets/styled"
65 "github.com/gcla/gowid/widgets/text"
66 "github.com/gcla/gowid/widgets/vpadding"
67)
68
69//======================================================================
70
71func main() {
72
73 palette := gowid.Palette{
74 "banner": gowid.MakePaletteEntry(gowid.ColorWhite, gowid.MakeRGBColor("#60d")),
75 "streak": gowid.MakePaletteEntry(gowid.ColorNone, gowid.MakeRGBColor("#60a")),
76 "inside": gowid.MakePaletteEntry(gowid.ColorNone, gowid.MakeRGBColor("#808")),
77 "outside": gowid.MakePaletteEntry(gowid.ColorNone, gowid.MakeRGBColor("#a06")),
78 "bg": gowid.MakePaletteEntry(gowid.ColorNone, gowid.MakeRGBColor("#d06")),
79 }
80
81 div := divider.NewBlank()
82 outside := styled.New(div, gowid.MakePaletteRef("outside"))
83 inside := styled.New(div, gowid.MakePaletteRef("inside"))
84
85 helloworld := styled.New(
86 text.NewFromContentExt(
87 text.NewContent([]text.ContentSegment{
88 text.StyledContent("Hello World", gowid.MakePaletteRef("banner")),
89 }),
90 text.Options{
91 Align: gowid.HAlignMiddle{},
92 },
93 ),
94 gowid.MakePaletteRef("streak"),
95 )
96
97 f := gowid.RenderFlow{}
98
99 view := styled.New(
100 vpadding.New(
101 pile.New([]gowid.IContainerWidget{
102 &gowid.ContainerWidget{IWidget: outside, D: f},
103 &gowid.ContainerWidget{IWidget: inside, D: f},
104 &gowid.ContainerWidget{IWidget: helloworld, D: f},
105 &gowid.ContainerWidget{IWidget: inside, D: f},
106 &gowid.ContainerWidget{IWidget: outside, D: f},
107 }),
108 gowid.VAlignMiddle{},
109 f),
110 gowid.MakePaletteRef("bg"),
111 )
112
113 app, _ := gowid.NewApp(gowid.AppArgs{
114 View: view,
115 Palette: &palette,
116 })
117
118 app.SimpleMainLoop()
119}
120```
121
122Running the example above displays this:
123
124<a href="https://drive.google.com/uc?export=view&id=1P2kjWagHJmhtWLV0hPQti0fXKidr_WMB"><img src="https://drive.google.com/uc?export=view&id=1P2kjWagHJmhtWLV0hPQti0fXKidr_WMB" style="width: 500px; max-width: 100%; height: auto" title="Click for the larger version." /></a>
125
126## Documentation
127
128 - The beginnings of a [tutorial](docs/Tutorial.md)
129 - A list of most of the [widgets](docs/Widgets.md)
130 - Some [FAQs](docs/FAQ.md) (which I guessed at...)
131 - Some gowid [programming tricks](docs/Debugging.md)
132
133## Similar Projects
134
135Gowid is late to the TUI party. There are many options from which to choose - please read https://appliedgo.net/tui/ for a nice summary for the Go language. Here is a selection:
136
137 - [urwid](http://urwid.org/) - one of the oldest, for those working in python
138 - [tview](https://github.com/rivo/tview) - active, polished, concise, lots of widgets, Go
139 - [termui](https://github.com/gizak/termui) - focus on graphing and dataviz, Go
140 - [gocui](https://github.com/jroimartin/gocui) - focus on layout, good input options, mouse support, Go
141 - [clui](https://github.com/VladimirMarkelov/clui) - active, many widgets, mouse support, Go
142 - [tui-go](https://github.com/marcusolsson/tui-go) - QT-inspired, experimental, nice examples, Go
143
144## Dependencies
145
146Gowid depends on these great open-source packages:
147
148- [urwid](http://urwid.org) - not a Go-dependency, but the model for most of gowid's design
149- [tcell](https://github.com/gdamore/tcell) - a cell based view for text terminals, like xterm, inspired by termbox
150- [asciigraph](https://github.com/guptarohit/asciigraph) - lightweight ASCII line-graphs for Go
151- [logrus](https://github.com/sirupsen/logrus) - structured pluggable logging for Go
152- [testify](github.com/stretchr/testify) - tools for testifying that your code will behave as you intend
153
154## Contact
155
156- The author - Graham Clark (grclark@gmail.com)
157
158## License
159
160[](https://opensource.org/licenses/MIT)
161
162
){kind=link}