diff options
| -rw-r--r-- | README.md | 193 |
1 files changed, 61 insertions, 132 deletions
@@ -2,35 +2,7 @@ Package gui implements a abstraction layer for Go visual elements. -Definitions: - -```go -* Toolkit: the underlying GUI library (MacOS gui, Windows gui, gtk, qt, etc) -* Node: A binary tree of all the underlying widgets -``` - -Principles: - -```go -* Make code using this package simple to use -* Hide complexity internally here -* Isolate the GUI toolkit -* Widget names should try to match [Wikipedia Graphical widget] -* When in doubt, search upward in the binary tree -* It's ok to guess. Try to do something sensible. -``` - -## Debian Build - -This worked on debian sid (mate-desktop) on 2023/12/03 -I didn't record the dependances needed (gtk-dev) - -```go -export GO111MODULE="off" -make -``` - -Hello World Example +## Hello World Example ```go // This creates a simple hello world window @@ -38,150 +10,107 @@ package main import ( "log" - "go.wit.com/wit/gui/gui" + "go.wit.com/gui" ) var myGui *gui.Node // This is your gui object -// go will sit here until the window exits func main() { - myGui = gui.Init() + myGui = gui.New().Default() + + helloworld() + + // go will sit here until the window exits + // intermittently, it will show toolkit statistics + gui.Watchdog() } // This initializes the first window and 2 tabs func helloworld() { window := myGui.NewWindow() - group := window.NewGroup("foo bar") + group := window.NewGroup("a group of widgets") group.NewButton("hello", func() { log.Println("world") }) } ``` -External Toolkits +## Build + +This will build the simple hello world example above. ```go -* andlabs - [https://github.com/andlabs/ui](https://github.com/andlabs/ui) -* gocui - [https://github.com/awesome-gocui/gocui](https://github.com/awesome-gocui/gocui) +go install go.wit.com/apps/helloworld@latest ``` -The next step is to allow this to work against go-gtk and go-qt. +A more extensive list of applications can be found on [go.wit.com](https://go.wit.com). -TODO: Add Fyne, WASM, native macos & windows, android and -hopefully also things like libSDL, faiface/pixel, slint +### Build Toolkit Plugins -## Bugs - -"The author's idea of friendly may differ to that of many other people." - --- quote from the minimalistic window manager 'evilwm' - -## References - -Useful links and other -external things which might be useful - -* Wikipedia Graphical widget - [https://en.wikipedia.org/wiki/Graphical_widget](https://en.wikipedia.org/wiki/Graphical_widget) -* Github mirror - [https://github.com/wit-go/gui](https://github.com/wit-go/gui) -* Federated git pull - [https://github.com/forgefed/forgefed](https://github.com/forgefed/forgefed) -* GO Style Guide - [https://google.github.io/styleguide/go/index](https://google.github.io/styleguide/go/index) +This is an example of how to build the console based +toolkit plugin built against the gocui package. ```go -* [Wikipedia Graphical widget] -* [Github mirror] -* [Federated git pull] -* [GO Style Guide] +GO111MODULE=off go get go.wit.com/toolkits/gocui +cd ~/go/src/go.wit.com/toolkits/gocui +go build -v -buildmode=plugin -o ~/go/lib/toolkits/gocui.so ``` -## Functions - -### func [DebugWidgetWindow](/debugWidget.go#L52) - -`func DebugWidgetWindow(w *Node)` - -### func [DebugWindow](/debugWindow.go#L21) +## Toolkits -`func DebugWindow()` +The toolkits are compiled as plugins and communicate only over a channel +to your application. This way, the toolkits are isolated and you don't +have to care about what the user uses to display things when you write +your application. Also, that allows the control panels to run in both +a traditional GUI like GTK or in the console like ncurses. -Creates a window helpful for debugging this package +There are two working toolkits. One is written to the andlabs package +which provides a native linux, macos and windows. The second one is +terminal window based using gocui. (There is a 3rd one using STDIN/STDOUT +as a template to create new toolkit plugins.) Also, GO doesn't support +plugins on Windows so the native Windows GUI awaits someone to fix that. -### func [ExampleCatcher](/chan.go#L37) +* andlabs - [github](https://github.com/andlabs/ui) +* gocui - [github](https://github.com/awesome-gocui/gocui) -`func ExampleCatcher(f func())` - -### func [Indent](/debug.go#L124) - -`func Indent(b bool, a ...interface{})` - -### func [SetDebug](/debug.go#L28) - -`func SetDebug(s bool)` - -### func [SetFlag](/debug.go#L50) - -`func SetFlag(s string, b bool)` - -### func [ShowDebugValues](/debug.go#L82) - -`func ShowDebugValues()` - -### func [StandardExit](/main.go#L153) - -`func StandardExit()` - -The window is destroyed and the application exits -TODO: properly exit the plugin since Quit() doesn't do it - -### func [Watchdog](/watchdog.go#L16) - -`func Watchdog()` - -This program sits here. -If you exit here, the whole thing will os.Exit() -TODO: use Ticker - -This goroutine can be used like a watchdog timer - -## Types - -### type [GuiArgs](/structs.go#L29) +The next step is to allow this to work against go-gtk and go-qt. -`type GuiArgs struct { ... }` +Others potential plugins: Fyne, WASM, native macos & windows, android and +hopefully also things like libSDL, faiface/pixel, slint -This struct can be used with the go-arg package +## General Thoughts -#### Variables +Definitions: -```golang -var GuiArg GuiArgs +```go +* Toolkit: the underlying GUI library (MacOS gui, Windows gui, gtk, qt, etc) +* Node: A binary tree of all the underlying widgets ``` -### type [Node](/structs.go#L59) - -`type Node struct { ... }` - -The Node is a binary tree. This is how all GUI elements are stored -simply the name and the size of whatever GUI element exists - -#### func [New](/main.go#L120) - -`func New() *Node` +Principles: -There should only be one of these per application -This is due to restrictions by being cross platform -some toolkit's on some operating systems don't support more than one -Keep things simple. Do the default expected thing whenever possible +```go +* Make code using this package simple to use +* Hide complexity internally here +* Isolate the GUI toolkit +* Widget names should try to match [Wikipedia Graphical widget] +* When in doubt, search upward in the binary tree +* It's ok to guess. Try to do something sensible. +``` -### type [Symbol](/plugin.go#L17) +## Bugs -`type Symbol any` +"The author's idea of friendly may differ to that of many other people." -## Sub Packages +-- quote from the minimalistic window manager 'evilwm' -* [log](./log) +## References -* [toolkit](./toolkit) +Useful links and other +external things which might be useful ---- -Readme created from Go doc with [goreadme](https://github.com/posener/goreadme) +* [A History of the GUI](https://arstechnica.com/features/2005/05/gui/) +* [Wikipedia Graphical widget](https://en.wikipedia.org/wiki/Graphical_widget) +* [Federated git pull](https://github.com/forgefed/forgefed) +* [GO Style Guide](https://google.github.io/styleguide/go/index) |