Update README
This commit is contained in:
gizak
parent
ad8b8b432b
commit
3bf132c51f
210
README.md
210
README.md
@ -1,23 +1,70 @@
|
||||
# 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.
|
||||
|
||||
Cross-platform, easy to compile, and fully-customizable.
|
||||
## Installation
|
||||
|
||||
__Demo:__ (cast under osx 10.10; Terminal.app; Menlo Regular 12pt.)
|
||||
`master` mirrors v2 branch, to install:
|
||||
|
||||
<img src="./example/dashboard.gif" alt="demo" width="600">
|
||||
go get -u github.com/gizak/termui
|
||||
|
||||
For the compatible reason, you can choose to install the legacy version of `termui`:
|
||||
|
||||
go get gopkg.in/gizak/termui.v1
|
||||
|
||||
## Usage
|
||||
|
||||
### Layout
|
||||
|
||||
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.
|
||||
|
||||
__Absolute layout__
|
||||
|
||||
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
|
||||
|
||||
func main() {
|
||||
err := ui.Init()
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
defer ui.Close()
|
||||
|
||||
p := ui.NewPar(":PRESS q TO QUIT DEMO")
|
||||
p.Height = 3
|
||||
p.Width = 50
|
||||
p.TextFgColor = ui.ColorWhite
|
||||
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.BarColor = ui.ColorRed
|
||||
g.BorderFg = ui.ColorWhite
|
||||
g.BorderLabelFg = ui.ColorCyan
|
||||
|
||||
ui.Render(p, g) // feel free to call Render, it's async and non-block
|
||||
|
||||
// event handler...
|
||||
}
|
||||
`````
|
||||
|
||||
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).
|
||||
|
||||
__Grid layout:__
|
||||
|
||||
Expressive syntax, using [12 columns grid system](http://www.w3schools.com/bootstrap/bootstrap_grid_system.asp)
|
||||
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).
|
||||
|
||||
```go
|
||||
import ui "github.com/gizak/termui"
|
||||
// init and create widgets...
|
||||
@ -37,116 +84,49 @@ Expressive syntax, using [12 columns grid system](http://www.w3schools.com/boots
|
||||
|
||||
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">
|
||||
### Events
|
||||
|
||||
## Installation
|
||||
|
||||
go get -u github.com/gizak/termui
|
||||
|
||||
## Usage
|
||||
|
||||
Each component's layout is a bit like HTML block (box model), which has border and padding.
|
||||
|
||||
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).
|
||||
|
||||
`````go
|
||||
import ui "github.com/gizak/termui" // <- ui shortcut, optional
|
||||
|
||||
func main() {
|
||||
err := ui.Init()
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
defer ui.Close()
|
||||
|
||||
p := ui.NewPar(":PRESS q TO QUIT DEMO")
|
||||
p.Height = 3
|
||||
p.Width = 50
|
||||
p.TextFgColor = ui.ColorWhite
|
||||
p.Border.Label = "Text Box"
|
||||
p.Border.FgColor = ui.ColorCyan
|
||||
|
||||
g := ui.NewGauge()
|
||||
g.Percent = 50
|
||||
g.Width = 50
|
||||
g.Height = 3
|
||||
g.Y = 11
|
||||
g.Border.Label = "Gauge"
|
||||
g.BarColor = ui.ColorRed
|
||||
g.Border.FgColor = ui.ColorWhite
|
||||
g.Border.LabelFgColor = ui.ColorCyan
|
||||
|
||||
ui.Render(p, g)
|
||||
|
||||
// event handler...
|
||||
}
|
||||
`````
|
||||
|
||||
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:
|
||||
`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:
|
||||
|
||||
```go
|
||||
// for now there are only two themes: default and helloworld
|
||||
termui.UseTheme("helloworld")
|
||||
// handle key q pressing
|
||||
termui.Handle("/sys/kbd/q", func(termui.Event) {
|
||||
// press q to quit
|
||||
termui.StopLoop()
|
||||
})
|
||||
|
||||
// create components...
|
||||
termui.Handle("/sys/kbd/C-x", func(termui.Event) {
|
||||
// handle Ctrl + x combination
|
||||
})
|
||||
|
||||
termui.Handle("/sys/kbd", func(termui.Event) {
|
||||
// handle all other key pressing
|
||||
})
|
||||
|
||||
// handle a 1s timer
|
||||
termui.Handle("/timer/1s", func(e ui.Event) {
|
||||
t := e.Data.(termui.EvtTimer)
|
||||
// t is a EvtTimer
|
||||
if t.Count%2 ==0 {
|
||||
// do something
|
||||
}
|
||||
})
|
||||
|
||||
ui.Loop() // block until StopLoop is called
|
||||
```
|
||||
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">
|
||||
### Widgets
|
||||
|
||||
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">
|
||||
|
||||
#### List
|
||||
[demo code](https://github.com/gizak/termui/blob/master/example/list.go)
|
||||
|
||||
<img src="./example/list.png" alt="list" type="image/png" width="200">
|
||||
|
||||
#### Colored List
|
||||
[demo code](https://github.com/gizak/termui/blob/master/example/coloredList.go)
|
||||
|
||||
TODO: Image (let's wait until the implementation is finished).
|
||||
|
||||
#### Gauge
|
||||
[demo code](https://github.com/gizak/termui/blob/master/example/gauge.go)
|
||||
|
||||
<img src="./example/gauge.png" alt="gauge" type="image/png" width="350">
|
||||
|
||||
#### Line Chart
|
||||
[demo code](https://github.com/gizak/termui/blob/master/example/linechart.go)
|
||||
|
||||
<img src="./example/linechart.png" alt="linechart" type="image/png" width="450">
|
||||
|
||||
#### Bar Chart
|
||||
[demo code](https://github.com/gizak/termui/blob/master/example/barchart.go)
|
||||
|
||||
<img src="./example/barchart.png" alt="barchart" type="image/png" width="150">
|
||||
|
||||
#### Mult-Bar / Stacked-Bar Chart
|
||||
[demo code](https://github.com/gizak/termui/blob/master/example/mbarchart.go)
|
||||
|
||||
<img src="./example/mbarchart.png" alt="barchart" type="image/png" width="150">
|
||||
|
||||
#### Sparklines
|
||||
[demo code](https://github.com/gizak/termui/blob/master/example/sparklines.go)
|
||||
|
||||
<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
|
||||
|
||||
@ -155,10 +135,12 @@ TODO: Image (let's wait until the implementation is finished).
|
||||
## 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)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user