diff --git a/Termdash-API.md b/Termdash-API.md index 1a50083..7d58633 100644 --- a/Termdash-API.md +++ b/Termdash-API.md @@ -111,7 +111,7 @@ if err := ctrl.Redraw(); err != nil { ## [termdash.ErrorHandler](https://github.com/mum4k/termdash/blob/1c6947618b08ae236959763efd07278be5f03211/termdash.go#L64-L71): -The **termdash.ErrorHandler** function is used to provide a custom error handler. If not provided, the application will panic on all runtime errors. An error handler is a function that receives the error and decides what to do. This function must be thread-safe, since Termdash delivers events concurrently. +The **termdash.ErrorHandler** function is used to provide a custom error handler. If not provided, the application will panic on all runtime errors. An error handler is a function (a callback) that receives the error and decides what to do. This function must be thread-safe, since Termdash delivers events concurrently. The following example shows initialisation of Termdash with an error handler that just logs the error message: @@ -135,4 +135,28 @@ if err != nil { } defer ctrl.Close() ``` -## [termdash.ErrorHandler](https://github.com/mum4k/termdash/blob/1c6947618b08ae236959763efd07278be5f03211/termdash.go#L64-L71): \ No newline at end of file +## [termdash.KeyboardSubscriber](https://github.com/mum4k/termdash/blob/275d95ad418b6ecca8817de4b013b440fc9abbe6/termdash.go#L74-L81): + +The **termdash.KeyboardSubscriber** function can be used by the developer to provide an additional subscriber to keyboard events. A keyboard subscriber is a function (a callback) that processes keyboard events. This function must be thread-safe, since Termdash delivers events concurrently. Providing an additional keyboard subscriber is completely optional and doesn't affect any of Termdash functionalities. + +The following example shows initialisation of Termdash with a keyboard subscriber that terminates the application when the letter 'q' or 'Q' is pressed on the keyboard. + +```go +// Create terminal t and container c as in the examples above. + +// Context for Termdash, the application quits when this expires. +// Since the context has no deadline, it will only expire when cancel() is called. +ctx, cancel := context.WithCancel(context.Background()) + +// A keyboard subscriber that terminates the application by cancelling the context. +quitter := func(k *terminalapi.Keyboard) { + if k.Key == 'q' || k.Key == 'Q' { + cancel() + } +} + +// Termdash will run until one of the two letters is pressed. +if err := termdash.Run(ctx, t, c, termdash.KeyboardSubscriber(quitter)); err != nil { + return fmt.Errorf("termdash.Run => %v", err) +} +``` \ No newline at end of file