Updated Widget API (markdown)

Widget-API.md

@@ -18,7 +18,7 @@ The widget can request the infrastructure to ensure that the canvas provided to
 
 E.g. if the widget returns:
 
-```
+```go
 Options{
   Ratio: image.Point{4, 3},
 }
@@ -34,7 +34,7 @@ To specify a minimum size of 10 columns and 5 rows, the widget can return the fo
 
 ```go
 Options{
-  Ratio: image.Point{10, 5},
+  MinimumSize: image.Point{10, 5},
 }
 ```
 
@@ -44,6 +44,59 @@ The left container in the following diagram resulted in a canvas smaller than th
 
 ### Maximum size
 
+When the terminal size changes, the infrastructure recalculates sizes of all containers according to the configured terminal layout (the container splits). See [[Terminal layout|terminal-layout]] for more details.
+
+Widgets placed in containers are automatically stretched to fill the full space available in the container. Widgets can specify an option to limit the canvas size to a maximum in which case the infrastructure never stretches a widget above this limit.
+
+To specify a maximum size of 10 columns and 5 rows, the widget can return the following options:
+
+```go
+Options{
+  MaximumSize: image.Point{10, 5},
+}
+```
+
 ### Keyboard events
 
-### Mouse events
+Widgets can choose whether they want to subscribe to keyboard events. Unless this is specifically requested, the widget won't receive any keyboard events, so its **widgetapi.Keyboard** method won't be called.
+
+Widgets can request keyboard events by specifying the **WantKeyboard** option:
+
+```go
+Options{
+  WantKeyboard: KeyScopeFocused,
+}
+```
+
+Widgets can request to receive keyboard events at different scopes.
+
+#### [widgetapi.KeyScope](https://godoc.org/github.com/mum4k/termdash/widgetapi#KeyScope)
+
+This type is used by the widget to specify the scope at which it wants to receive keyboard events. The following scopes are available:
+
+1. **KeyScopeNone** is the default scope and indicates the widget doesn't want any keyboard events.
+1. **KeyScopeFocused** indicates that the widget wants to receive keyboard events when its container is focused. See [[Keyboard focus|keyboard-focus]] for more details.
+1. **KeyScopeGlobal** indicates that the widget wants to receive all keyboard events, even if its container isn't focused.
+
+### Mouse events
+
+Widgets can choose whether they want to subscribe to mouse events. Unless this is specifically requested, the widget won't receive any mouse events, so its **widgetapi.Mouse** method won't be called.
+
+Widgets can request mouse events by specifying the **WantMouse** option:
+
+```go
+Options{
+  WantMouse: MouseScopeWidget,
+}
+```
+
+Widgets can request to receive mouse events at different scopes.
+
+#### [widgetapi.MouseScope](https://godoc.org/github.com/mum4k/termdash/widgetapi#MouseScope)
+
+This type is used by the widget to specify the scope at which it wants to receive mouse events. The following scopes are available:
+
+1. **MouseScopeNone** is the default scope and indicates the widget doesn't want any mouse events.
+1. **MouseScopeWidget** indicates that the widget wants to receive mouse events as long as they fall on the area of its canvas.
+1. **MouseScopeContainer** indicates that the widget wants to receive mouse events as long as they fall on the area of its container including its padding and border.
+1. **MouseScopeGlobal** indicates that the widget wants to receive all mouse events, regardless where on the terminal they fall on.