diff options
Diffstat (limited to 'Godeps/_workspace/src/github.com/gizak/termui/README.md')
| -rw-r--r-- | Godeps/_workspace/src/github.com/gizak/termui/README.md | 169 |
1 files changed, 79 insertions, 90 deletions
diff --git a/Godeps/_workspace/src/github.com/gizak/termui/README.md b/Godeps/_workspace/src/github.com/gizak/termui/README.md index b9bc3024d..0e1d41b08 100644 --- a/Godeps/_workspace/src/github.com/gizak/termui/README.md +++ b/Godeps/_workspace/src/github.com/gizak/termui/README.md @@ -1,55 +1,30 @@ # termui [](https://travis-ci.org/gizak/termui) [](https://godoc.org/github.com/gizak/termui) -## Update 23/06/2015 -Pull requests and master branch are freezing, waiting for merging from `refactoring` branch. +<img src="./_example/dashboard.gif" alt="demo cast under osx 10.10; Terminal.app; Menlo Regular 12pt.)" width="80%"> -## Notice -termui comes with ABSOLUTELY NO WARRANTY, and there is a breaking change coming up (see refactoring branch) which will change the `Bufferer` interface and many others. These changes reduce calculation overhead and introduce a new drawing buffer with better capacibilities. We will step into the next stage (call it beta) after merging these changes. +`termui` is a cross-platform, easy-to-compile, and fully-customizable terminal dashboard. It is inspired by [blessed-contrib](https://github.com/yaronn/blessed-contrib), but purely in Go. -## Introduction -Go terminal dashboard. Inspired by [blessed-contrib](https://github.com/yaronn/blessed-contrib), but purely in Go. +Now version v2 has arrived! It brings new event system, new theme system, new `Buffer` interface and specific colour text rendering. (some docs are missing, but it will be completed soon!) -Cross-platform, easy to compile, and fully-customizable. - -__Demo:__ (cast under osx 10.10; Terminal.app; Menlo Regular 12pt.) +## Installation -<img src="./example/dashboard.gif" alt="demo" width="600"> +`master` mirrors v2 branch, to install: -__Grid layout:__ + go get -u github.com/gizak/termui -Expressive syntax, using [12 columns grid system](http://www.w3schools.com/bootstrap/bootstrap_grid_system.asp) -```go - import ui "github.com/gizak/termui" - // init and create widgets... +For the compatible reason, you can choose to install the legacy version of `termui`: - // 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))) + go get gopkg.in/gizak/termui.v1 - // calculate layout - ui.Body.Align() - - ui.Render(ui.Body) -``` -[demo code:](https://github.com/gizak/termui/blob/master/example/grid.go) - -<img src="./example/grid.gif" alt="grid" width="500"> - -## Installation +## Usage - go get github.com/gizak/termui +### Layout -## Usage +To use `termui`, the very first thing you may want to know is how to manage layout. `termui` offers two ways of doing this, known as absolute layout and grid layout. -Each component's layout is a bit like HTML block (box model), which has border and padding. +__Absolute layout__ -The `Border` property can be chosen to hide or display (with its border label), when it comes to display, the label takes 1 padding space (i.e. in css: `padding: 1;`, innerHeight and innerWidth therefore shrunk by 1). +Each widget has an underlying block structure which basically is a box model. It has border, label and padding properties. A border of a widget can be chosen to hide or display (with its border label), you can pick a different front/back colour for the border as well. To display such a widget at a specific location in terminal window, you need to assign `.X`, `.Y`, `.Height`, `.Width` values for each widget before send it to `.Render`. Let's demonstrate these by a code snippet: `````go import ui "github.com/gizak/termui" // <- ui shortcut, optional @@ -65,20 +40,20 @@ The `Border` property can be chosen to hide or display (with its border label), p.Height = 3 p.Width = 50 p.TextFgColor = ui.ColorWhite - p.Border.Label = "Text Box" - p.Border.FgColor = ui.ColorCyan + p.BorderLabel = "Text Box" + p.BorderFg = ui.ColorCyan g := ui.NewGauge() g.Percent = 50 g.Width = 50 g.Height = 3 g.Y = 11 - g.Border.Label = "Gauge" + g.BorderLabel = "Gauge" g.BarColor = ui.ColorRed - g.Border.FgColor = ui.ColorWhite - g.Border.LabelFgColor = ui.ColorCyan + g.BorderFg = ui.ColorWhite + g.BorderLabelFg = ui.ColorCyan - ui.Render(p, g) + ui.Render(p, g) // feel free to call Render, it's async and non-block // event handler... } @@ -86,62 +61,74 @@ The `Border` property can be chosen to hide or display (with its border label), Note that components can be overlapped (I'd rather call this a feature...), `Render(rs ...Renderer)` renders its args from left to right (i.e. each component's weight is arising from left to right). -## Themes - -_All_ colors in _all_ components can be changed at _any_ time, while there provides some predefined color schemes: - -```go -// for now there are only two themes: default and helloworld -termui.UseTheme("helloworld") - -// create components... -``` -The `default ` theme's settings depend on the user's terminal color scheme, which is saying if your terminal default font color is white and background is white, it will be like: - -<img src="./example/themedefault.png" alt="default" type="image/png" width="600"> - -The `helloworld` color scheme drops in some colors! - -<img src="./example/themehelloworld.png" alt="helloworld" type="image/png" width="600"> - -## Widgets - -#### Par - -[demo code](https://github.com/gizak/termui/blob/master/example/par.go) - -<img src="./example/par.png" alt="par" type="image/png" width="300"> +__Grid layout:__ -#### List -[demo code](https://github.com/gizak/termui/blob/master/example/list.go) +<img src="./_example/grid.gif" alt="grid" width="60%"> -<img src="./example/list.png" alt="list" type="image/png" width="200"> +Grid layout uses [12 columns grid system](http://www.w3schools.com/bootstrap/bootstrap_grid_system.asp) with expressive syntax. To use `Grid`, all we need to do is build a widget tree consisting of `Row`s and Cols (Actually a Col is also a `Row` but with a widget endpoint attached). -#### Gauge -[demo code](https://github.com/gizak/termui/blob/master/example/gauge.go) +```go + import ui "github.com/gizak/termui" + // init and create widgets... -<img src="./example/gauge.png" alt="gauge" type="image/png" width="350"> + // 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))) -#### Line Chart -[demo code](https://github.com/gizak/termui/blob/master/example/linechart.go) + // calculate layout + ui.Body.Align() -<img src="./example/linechart.png" alt="linechart" type="image/png" width="450"> + ui.Render(ui.Body) +``` -#### Bar Chart -[demo code](https://github.com/gizak/termui/blob/master/example/barchart.go) +### Events -<img src="./example/barchart.png" alt="barchart" type="image/png" width="150"> +`termui` ships with a http-like event mux handling system. All events are channeled up from different sources (typing, click, windows resize, custom event) and then encoded as universal `Event` object. `Event.Path` indicates the event type and `Event.Data` stores the event data struct. Add a handler to a certain event is easy as below: -#### Mult-Bar / Stacked-Bar Chart -[demo code](https://github.com/gizak/termui/blob/master/example/mbarchart.go) +```go + // handle key q pressing + ui.Handle("/sys/kbd/q", func(ui.Event) { + // press q to quit + ui.StopLoop() + }) + + ui.Handle("/sys/kbd/C-x", func(ui.Event) { + // handle Ctrl + x combination + }) + + ui.Handle("/sys/kbd", func(ui.Event) { + // handle all other key pressing + }) + + // handle a 1s timer + ui.Handle("/timer/1s", func(e ui.Event) { + t := e.Data.(ui.EvtTimer) + // t is a EvtTimer + if t.Count%2 ==0 { + // do something + } + }) -<img src="./example/mbarchart.png" alt="barchart" type="image/png" width="150"> + ui.Loop() // block until StopLoop is called +``` -#### Sparklines -[demo code](https://github.com/gizak/termui/blob/master/example/sparklines.go) +### Widgets -<img src="./example/sparklines.png" alt="sparklines" type="image/png" width="350"> +Click image to see the corresponding demo codes. +[<img src="./_example/par.png" alt="par" type="image/png" width="45%">](https://github.com/gizak/termui/blob/master/_example/par.go) +[<img src="./_example/list.png" alt="list" type="image/png" width="45%">](https://github.com/gizak/termui/blob/master/_example/list.go) +[<img src="./_example/gauge.png" alt="gauge" type="image/png" width="45%">](https://github.com/gizak/termui/blob/master/_example/gauge.go) +[<img src="./_example/linechart.png" alt="linechart" type="image/png" width="45%">](https://github.com/gizak/termui/blob/master/_example/linechart.go) +[<img src="./_example/barchart.png" alt="barchart" type="image/png" width="45%">](https://github.com/gizak/termui/blob/master/_example/barchart.go) +[<img src="./_example/mbarchart.png" alt="barchart" type="image/png" width="45%">](https://github.com/gizak/termui/blob/master/_example/mbarchart.go) +[<img src="./_example/sparklines.png" alt="sparklines" type="image/png" width="45%">](https://github.com/gizak/termui/blob/master/_example/sparklines.go) ## GoDoc @@ -150,10 +137,12 @@ The `helloworld` color scheme drops in some colors! ## TODO - [x] Grid layout -- [ ] Event system -- [ ] Canvas widget -- [ ] Refine APIs +- [x] Event system +- [x] Canvas widget +- [x] Refine APIs - [ ] Focusable widgets +## Changelog + ## License This library is under the [MIT License](http://opensource.org/licenses/MIT) |