Merge pull request #75 from mum4k/release-0.4

Release 0.4

.travis.yml

@@ -1,8 +1,8 @@
 language: go
 go:
-        - 1.8.x
         - 1.9.x
         - 1.10.x
+        - 1.11.x
         - stable
 script:
         - go get -t ./...

README.md

@@ -6,105 +6,132 @@
 
 # termdash
 
-This project implements a terminal based dashboard. The feature set is inspired
-by the [gizak/termui](http://github.com/gizak/termui) project, which in turn
-was inspired by a javascript based
-[yaronn/blessed-contrib](http://github.com/yaronn/blessed-contrib). Why the
-rewrite you ask?
+[<img src="./images/termdashdemo.gif" alt="termdashdemo" type="image/gif">](termdashdemo/termdashdemo.go)
 
-1. The above mentioned [gizak/termui](http://github.com/gizak/termui) is
-   abandoned and isn't maintained anymore.
-1. The project doesn't follow the design goals outlined below.
+This project implements a cross-platform customizable terminal based dashboard.
+The feature set is inspired by the
+[gizak/termui](http://github.com/gizak/termui) project, which in turn was
+inspired by a javascript based
+[yaronn/blessed-contrib](http://github.com/yaronn/blessed-contrib).
 
-# Design goals
+This rewrite focuses on code readability, maintainability and testability, see
+the [design goals](doc/design_goals.md). It aims to achieve the following
+[requirements](doc/requirements.md). See the [high-level design](doc/hld.md)
+for more details.
 
-This effort is focused on good software design and maintainability. By good
-design I mean:
+# Current feature set
 
-1. Write readable, well documented code.
-1. Only beautiful, simple APIs, no exposed concurrency, channels, internals, etc.
-1. Follow [Effective Go](http://golang.org/doc/effective_go.html).
-1. Provide an infrastructure that allows development of individual dashboard
-   components in separation.
-1. The infrastructure must enforce consistency in how the dashboard components
-   are implemented.
-1. Focus on maintainability, the infrastructure and dashboard components must
-   have good test coverage, the repository must have CI/CD enabled.
+- Full support for terminal window resizing throughout the infrastructure.
+- Customizable layout, widget placement, borders, colors, etc.
+- Focusable containers and widgets.
+- Processing of keyboard and mouse events.
+- Periodic and event driven screen redraw.
+- A library of widgets, see below.
+- UTF-8 for all text elements.
+- Drawing primitives (Go functions) for widget development with character and
+  sub-character resolution.
 
-On top of that - let's have fun, learn something and become better developers
-together.
+# Installation
 
-# Requirements
+To install this library, run the following:
 
-1. Native support of the UTF-8 encoding.
-1. Simple container management to position the widgets and set their size.
-1. Mouse and keyboard input.
-1. Cross-platform terminal based output.
-1. Unit testing framework for simple and readable tests of dashboard elements.
-1. Tooling to streamline addition of new widgets.
-1. Apache-2.0 licence for the project.
+```
+go get -u github.com/mum4k/termdash
 
-# High-Level design
+```
 
-See the [design document](doc/hld.md).
+# Usage
 
-# Contributing
+The usage of most of these elements is demonstrated in
+[termdashdemo.go](termdashdemo/termdashdemo.go). To execute the demo:
 
-If you are willing to contribute, improve the infrastructure or develop a
-widget, first of all Thank You! Your help is appreciated.
 
-Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for guidelines related
-to the Google's CLA, and code review requirements.
+```
+go run github.com/mum4k/termdash/termdashdemo/termdashdemo.go
+```
 
-As stated above the primary goal of this project is to develop readable, well
-designed code, the functionality and efficiency come second. This is achieved
-through detailed code reviews, design discussions and following of the [design
-guidelines](doc/design_guidelines.md). Please familiarize yourself with these
-before contributing.
+# Documentation
 
-## Contributing widgets
+Code documentation can be viewed in
+[godoc](https://godoc.org/github.com/mum4k/termdash).
 
-If you're developing a new widget, please see the [widget
-development](doc/widget_development.md) section.
+Project documentation is available in the [doc](doc/) directory.
 
 ## Implemented Widgets
 
 ### The Gauge
 
 Displays the progress of an operation. Run the
-[gaugedemo](widgets/gauge/demo/gaugedemo.go).
+[gaugedemo](widgets/gauge/gaugedemo/gaugedemo.go).
+
+```go
+go run github.com/mum4k/termdash/widgets/gauge/gaugedemo/gaugedemo.go
+```
 
-[<img src="./images/gaugedemo.gif" alt="gaugedemo" type="image/gif">](widgets/gauge/demo/gaugedemo.go)
+[<img src="./images/gaugedemo.gif" alt="gaugedemo" type="image/gif">](widgets/gauge/gaugedemo/gaugedemo.go)
 
 ### The Text
 
 Displays text content, supports trimming and scrolling of content. Run the
-[textdemo](widgets/text/demo/textdemo.go).
+[textdemo](widgets/text/textdemo/textdemo.go).
 
-[<img src="./images/textdemo.gif" alt="textdemo" type="image/gif">](widgets/gauge/demo/gaugedemo.go)
+```go
+go run github.com/mum4k/termdash/widgets/text/textdemo/textdemo.go
+```
+
+[<img src="./images/textdemo.gif" alt="textdemo" type="image/gif">](widgets/text/textdemo/textdemo.go)
 
 ### The SparkLine
 
 Draws a graph showing a series of values as vertical bars. The bars can have
 sub-cell height. Run the
 [sparklinedemo](widgets/sparkline/sparklinedemo/sparklinedemo.go).
 
+```go
+go run github.com/mum4k/termdash/widgets/sparkline/sparklinedemo/sparklinedemo.go
+```
+
 [<img src="./images/sparklinedemo.gif" alt="sparklinedemo" type="image/gif">](widgets/sparkline/sparklinedemo/sparklinedemo.go)
 
 ### The BarChart
 
 Displays multiple bars showing relative ratios of values. Run the
 [barchartdemo](widgets/barchart/barchartdemo/barchartdemo.go).
 
+```go
+go run github.com/mum4k/termdash/widgets/barchart/barchartdemo/barchartdemo.go
+```
+
 [<img src="./images/barchartdemo.gif" alt="barchartdemo" type="image/gif">](widgets/barchart/barchartdemo/barchartdemo.go)
 
 ### The LineChart
 
-Displays series of values as line charts. Run the
+Displays series of values on a line chart. Run the
 [linechartdemo](widgets/linechart/linechartdemo/linechartdemo.go).
 
+```go
+go run github.com/mum4k/termdash/widgets/linechart/linechartdemo/linechartdemo.go
+```
+
 [<img src="./images/linechartdemo.gif" alt="linechartdemo" type="image/gif">](widgets/linechart/linechartdemo/linechartdemo.go)
 
+# Contributing
+
+If you are willing to contribute, improve the infrastructure or develop a
+widget, first of all Thank You! Your help is appreciated.
+
+Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for guidelines related
+to the Google's CLA, and code review requirements.
+
+As stated above the primary goal of this project is to develop readable, well
+designed code, the functionality and efficiency come second. This is achieved
+through detailed code reviews, design discussions and following of the [design
+guidelines](doc/design_guidelines.md). Please familiarize yourself with these
+before contributing.
+
+If you're developing a new widget, please see the [widget
+development](doc/widget_development.md) section.
+
 
 ## Disclaimer
 

area/area.go

@@ -36,26 +36,44 @@ func FromSize(size image.Point) (image.Rectangle, error) {
 	return image.Rect(0, 0, size.X, size.Y), nil
 }
 
-// HSplit returns two new areas created by splitting the provided area in the
-// middle along the horizontal axis. Can return zero size areas.
-func HSplit(area image.Rectangle) (image.Rectangle, image.Rectangle) {
-	height := area.Dy() / 2
-	if height == 0 {
-		return image.ZR, image.ZR
-	}
-	return image.Rect(area.Min.X, area.Min.Y, area.Max.X, area.Min.Y+height),
-		image.Rect(area.Min.X, area.Min.Y+height, area.Max.X, area.Max.Y)
+// HSplit returns two new areas created by splitting the provided area at the
+// specified percentage of its width. The percentage must be in the range
+// 0 <= heightPerc <= 100.
+// Can return zero size areas.
+func HSplit(area image.Rectangle, heightPerc int) (top image.Rectangle, bottom image.Rectangle, err error) {
+	if min, max := 0, 100; heightPerc < min || heightPerc > max {
+		return image.ZR, image.ZR, fmt.Errorf("invalid heightPerc %d, must be in range %d <= heightPerc <= %d", heightPerc, min, max)
+	}
+	height := area.Dy() * heightPerc / 100
+	top = image.Rect(area.Min.X, area.Min.Y, area.Max.X, area.Min.Y+height)
+	if top.Dy() == 0 {
+		top = image.ZR
+	}
+	bottom = image.Rect(area.Min.X, area.Min.Y+height, area.Max.X, area.Max.Y)
+	if bottom.Dy() == 0 {
+		bottom = image.ZR
+	}
+	return top, bottom, nil
 }
 
-// VSplit returns two new areas created by splitting the provided area in the
-// middle along the vertical axis. Can return zero size areas.
-func VSplit(area image.Rectangle) (image.Rectangle, image.Rectangle) {
-	width := area.Dx() / 2
-	if width == 0 {
-		return image.ZR, image.ZR
-	}
-	return image.Rect(area.Min.X, area.Min.Y, area.Min.X+width, area.Max.Y),
-		image.Rect(area.Min.X+width, area.Min.Y, area.Max.X, area.Max.Y)
+// VSplit returns two new areas created by splitting the provided area at the
+// specified percentage of its width. The percentage must be in the range
+// 0 <= widthPerc <= 100.
+// Can return zero size areas.
+func VSplit(area image.Rectangle, widthPerc int) (left image.Rectangle, right image.Rectangle, err error) {
+	if min, max := 0, 100; widthPerc < min || widthPerc > max {
+		return image.ZR, image.ZR, fmt.Errorf("invalid widthPerc %d, must be in range %d <= widthPerc <= %d", widthPerc, min, max)
+	}
+	width := area.Dx() * widthPerc / 100
+	left = image.Rect(area.Min.X, area.Min.Y, area.Min.X+width, area.Max.Y)
+	if left.Dx() == 0 {
+		left = image.ZR
+	}
+	right = image.Rect(area.Min.X+width, area.Min.Y, area.Max.X, area.Max.Y)
+	if right.Dx() == 0 {
+		right = image.ZR
+	}
+	return left, right, nil
 }
 
 // abs returns the absolute value of x.