diff --git a/Termdash-API.md b/Termdash-API.md index 169e087..0eac961 100644 --- a/Termdash-API.md +++ b/Termdash-API.md @@ -24,26 +24,60 @@ The public API surface of this package consists of the following: The **Run** function provides the simplest way to run a Termdash based application. Run blocks until the provided context expires, therefore we need a trigger to close the context, e.g. a keyboard shortcut or a timeout. When Termdash is started using this function, the screen is redrawn periodically. -The following code snippet starts Termdash with an empty container and no widgets. Termdash will quit after 5 seconds when the context expires. +The following code snippet starts Termdash with an empty container and no widgets. Termdash will quit after five seconds when the context expires. ```go // Create the terminal. t, err := termbox.New() if err != nil { - fmt.Errorf("termbox.New => %v", err) + return fmt.Errorf("termbox.New => %v", err) } defer t.Close() // Create the container without widgets. c, err := container.New(t) if err != nil { - fmt.Errorf("termbox.New => %v", err) + return fmt.Errorf("container.New => %v", err) } // Termdash runs until the context expires. ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) defer cancel() -if err := Run(ctx, t, c); err != nil { - panic(err) +if err := termdash.Run(ctx, t, c); err != nil { + return fmt.Errorf("termdash.Run => %v", err) +} +``` + +## [termdash.NewController](https://github.com/mum4k/termdash/blob/ffbf88caeddb1735dcf2a5f735eec80dc9cf9fe7/termdash.go#L113-L130): + +The **NewController** function creates a new **Controller** instance which allows the user to manually trigger a screen redraw. Periodic redraws are disabled in this mode. Termdash will still redraw the screen each time an input event happens, e.g. a keyboard, a mouse event or a terminal resize. + +The following code snippet starts Termdash with an empty container and no widgets and redraws the screen once. As opposed to **Run**, the following code isn't blocking so the user remains in control of the main goroutine. + +```go +// Create the terminal. +t, err := termbox.New() +if err != nil { + return fmt.Errorf("termbox.New => %v", err) +} +defer t.Close() + +// Create the container without widgets. +c, err := container.New(t) +if err != nil { + return fmt.Errorf("container.New => %v", err) +} + +// Create the controller. +ctrl, err := termdash.NewController(t, c) +if err != nil { + return fmt.Errorf("termdash.NewController => %v", err) +} +// Close the controller and termdash once it isn't required anymore. +defer ctrl.Close() + +// Redraw the screen manually. +if err := ctrl.Redraw(); err != nil { + return fmt.Errorf("ctrl.Redraw => %v", err) } ``` \ No newline at end of file