OrgGo
/
termdash
mirror of https://github.com/mum4k/termdash.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Updated Widget API (markdown)

Jakub Sobon 2019-03-04 00:23:23 -05:00
parent 2f3b6d62fb
commit 6c88bdcea3
1 changed files with 40 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
Widget-API.md

@ -7,3 +7,43 @@ This documentation introduces the Widget's API and the surrounding types. See al
## [widgetapi.Widget](https://godoc.org/github.com/mum4k/termdash/widgetapi#Widget)
The **widgetapi.Widget** is the interface implemented by all widgets. The infrastructure calls the **widgetapi.Draw** method on every screen redraw. See the [[Termdash API|termdash-api]] for details about screen redraw. Each call to the **widgetapi.Draw** method os preceded by a call to the **widgetapi.Options** method. This is how the infrastructure asks the widget for its preferences regarding canvas size and events. The **widgetapi.Keyboard** and **widgetapi.Mouse** methods are how the infrastructure delivers keyboard and mouse events to the widget.
## [widgetapi.Options](https://godoc.org/github.com/mum4k/termdash/widgetapi#Options)
The widget uses the **widgetapi.Options** type to specify its preferences to the infrastructure.
### Aspect ratio
The widget can request the infrastructure to ensure that the canvas provided to **widgetapi.Draw** will have a specific aspect ratio. A zero value point **image.ZP** indicates that widget doesn't have any preferences regarding aspect ratio. Specifying any other value guarantees the requested aspect ratio.
E.g. if the widget returns:
```
Options{
Ratio: image.Point{4, 3},
}
```
All canvases delivered to the widget will have the specified aspect ratio **4:3** of **columns** : **rows**. If the actual ratio of the outer container is different, the infrastructure decreases the size of the canvas to the next smaller size that meets this ratio requirement.
### Minimum size
Widgets can specify the smallest canvas size they are willing to accept. This protects the widget's **widgetapi.Draw** method. The infrastructure guarantees not to call this method if the canvas would be smaller than the specified size. If this happens, the infrastructure draws a unicode rune '⇄' indicating that the size is too small.
To specify a minimum size of 10 columns and 5 rows, the widget can return the following options:
```go
Options{
Ratio: image.Point{10, 5},
}
```
The left container in the following diagram resulted in a canvas smaller than the widget's minimum size:
[[/images/widget-api/resize_needed.png|resize_needed]]
### Maximum size
### Keyboard events
### Mouse events