Documentation
¶
Overview ¶
Retort is a reactive terminal user interface framework for golang.
Inspired by React, the API is somewhat similar, but due to langauge differences they are not the same thing.
Components ¶
An app built with retort is composed of components.
Hooks ¶
Retort uses hooks to provide the functionality to make your Components interactive and responsive to user input and data.
There are a few built in hooks, which can also be used to create custom hooks.
UseState: use this to keep track of, and change state that is local to a component
UseEffect: use this to do something (like setState) in a goroutine, for example fetch data
UseScreen: use this to access the screen object directly. You probably wont need this, but it's there if you do for example if you want to create a new ScreenElement.
UseQuit: use this to exit the application.
Why ¶
As stated by the inspiration for this package "Declarative views make your code more predictable and easier to debug.Log". The original author (Owen Kelly) has years of experience building complex websites with React, and wanted a similar reactive/declarative tool for terminal user interfaces in golang.
The biggest reason though, is state management.
When you build an interactive user interface, the biggest challenge is always state management. The model that a reactive framework like retort (and React before it) allows, is one of the simplest ways to solve the state management problem. Much moreso than an imperitive user interface library.
About the Name ¶
retort: to answer, or react to, an argument by a counter argument
Terminals usually have arguments, often with their user.
Don't think about it too much.
Examples ¶
Below are some simple examples of how to use retort
Example (App) ¶
package main import ( // import tcell to get access to colors and event types "github.com/gdamore/tcell" "retort.dev/components/box" example "retort.dev/example/components" "retort.dev/r" ) var exampleVarToMakeGoDocPrintTheWholeFile bool func main() { // Call the main function on retort to start the app, // when you call this, retort will take over the screen. r.Retort( // Root Element r.CreateElement( example.ClickableBox, r.Properties{ box.Properties{ Width: 100, // Make the root element fill the screen Height: 100, // Make the root element fill the screen Border: box.Border{ Style: box.BorderStyleSingle, Foreground: tcell.ColorWhite, }, }, }, r.Children{ // First Child r.CreateElement( example.ClickableBox, r.Properties{ box.Properties{ Border: box.Border{ Style: box.BorderStyleSingle, Foreground: tcell.ColorWhite, }, }, }, nil, // Pass nil as the third argument if there are no children ), // Second Child r.CreateElement( example.ClickableBox, r.Properties{ box.Properties{ Border: box.Border{ Style: box.BorderStyleSingle, Foreground: tcell.ColorWhite, }, }, }, nil, ), }, ), // Pass in optional configuration r.RetortConfiguration{}, ) }
Output:
Directories
¶
Path | Synopsis |
---|---|
How to create custom Components By convention if a Component (lets call it Box) needs Properties the package should have a struct called BoxProps.
|
How to create custom Components By convention if a Component (lets call it Box) needs Properties the package should have a struct called BoxProps. |
box
package box contains Box a highly configurable building block for retort apps.
|
package box contains Box a highly configurable building block for retort apps. |
package example shows how a retort app can be made
|
package example shows how a retort app can be made |
package r is the core retort package TODO: Explain how this all works.
|
package r is the core retort package TODO: Explain how this all works. |
internal/quadtree
Via https://github.com/JamesLMilner/quadtree-go Converted to ints for our use case
|
Via https://github.com/JamesLMilner/quadtree-go Converted to ints for our use case |