diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 174 |
1 files changed, 62 insertions, 112 deletions
@@ -1,29 +1,22 @@ # gui -Package gui implements a abstraction layer for Go visual elements in -a cross platform and library independent way. (hopefully this is will work) - -A quick overview of the features, some general design guidelines -and principles for how this package should generally work: +Package gui implements a abstraction layer for Go visual elements. Definitions: -* Toolkit: the underlying library (MacOS gui, Windows gui, gtk, qt, etc) -* Node: A binary tree of all the underlying GUI toolkit elements +* Toolkit: the underlying GUI library (MacOS gui, Windows gui, gtk, qt, etc) +* Node: A binary tree of all the underlying widgets Principles: * Make code using this package simple to use -* When in doubt, search upward in the binary tree -* It's ok to guess. We will return something close. * Hide complexity internally here * Isolate the GUI toolkit -* Try to use [Wikipedia Graphical widget] names - -## Quick Start +* 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. -This section demonstrates how to quickly get started with spew. See the -sections below for further details on formatting and configuration options. +Quick Start ```go // This creates a simple hello world window @@ -38,6 +31,7 @@ var window *gui.Node // This is the beginning of the binary tree of widgets // go will sit here until the window exits func main() { + gui.Init() gui.Main(helloworld) } @@ -74,34 +68,21 @@ GO111MODULE="off" go build -v -x [./helloworld](./helloworld) ``` -## Toolkits +Toolkits -The goal is to design something that will work with more than one. +* andlabs - [https://github.com/andlabs/ui](https://github.com/andlabs/ui) +* gocui - [https://github.com/awesome-gocui/gocui](https://github.com/awesome-gocui/gocui) -Right now, this abstraction is built on top of the go package 'andlabs/ui' -which does the cross platform support. -The next step is to intent is to allow this to work directly against GTK and QT. +The next step is to allow this to work against go-gtk and go-qt. -It should be able to add Fyne, WASM, native macos & windows, android and +TODO: Add Fyne, WASM, native macos & windows, android and hopefully also things like libSDL, faiface/pixel, slint -## Errors - -Since it is possible for custom Stringer/error interfaces to panic, spew -detects them and handles them internally by printing the panic information -inline with the output. Since spew is intended to provide deep pretty printing -capabilities on structures, it intentionally does not return any errors. - -## Debugging - -To dump variables with full newlines, indentation, type, and pointer -information this uses spew.Dump() - ## Bugs "The author's idea of friendly may differ to that of many other people." --- manpage quote from the excellent minimalistic window manager 'evilwm' +-- quote from the minimalistic window manager 'evilwm' ## References @@ -111,56 +92,37 @@ which might be useful * [Wikipedia Graphical widget](https://en.wikipedia.org/wiki/Graphical_widget) * [Github mirror](https://github.com/witorg/gui) +* [Federated git pull](https://github.com/forgefed/forgefed) ## Functions -### func [DebugTab](/window-debug.go#L26) - -`func DebugTab()` - -this function is used by the examples to add a tab -dynamically to the bugWin node -TODO: make this smarter once this uses toolkit/ - -### func [DebugWindow](/window-debug.go#L14) - -`func DebugWindow()` - -Creates a window helpful for debugging this package +### func [GetDebug](/structs.go#L25) -### func [DemoToolkitWindow](/window-demo-toolkit.go#L24) +`func GetDebug() bool` -`func DemoToolkitWindow()` +### func [GetDebugToolkit](/structs.go#L37) -This creates a window that shows how the toolkit works -internally using it's raw unchanged code for the toolkit itself - -This is a way to test and see if the toolkit is working at all -right now it shows the andlabs/ui/DemoNumbersPage() - -### func [DemoWindow](/window-demo.go#L10) - -`func DemoWindow()` +`func GetDebugToolkit() bool` -This creates a window that shows how this package works +### func [IndentPrintln](/structs.go#L188) -### func [GetDebugToolkit](/structs.go#L28) +`func IndentPrintln(a ...interface{})` -`func GetDebugToolkit() bool` +### func [Init](/main.go#L41) -### func [GolangDebugWindow](/window-golang-debug.go#L20) +`func Init()` -`func GolangDebugWindow()` +### func [LoadToolkit](/plugin.go#L37) -### func [IndentPrintln](/structs.go#L199) +`func LoadToolkit(name string)` -`func IndentPrintln(a ...interface{})` +loads and initializes a toolkit (andlabs/ui, gocui, etc) -### func [Main](/main.go#L31) +### func [Main](/main.go#L56) `func Main(f func())` -### func [Queue](/main.go#L42) +### func [Queue](/main.go#L77) `func Queue(f func())` @@ -171,21 +133,42 @@ other goroutines. This is due to the nature of how Linux, MacOS and Windows work (they all work differently. suprise. surprise.) For example: gui.Queue(NewWindow()) -### func [SetDebugToolkit](/structs.go#L24) +### func [SetDebug](/structs.go#L29) + +`func SetDebug(s bool)` + +### func [SetDebugToolkit](/structs.go#L41) `func SetDebugToolkit(s bool)` -### func [ShowDebugValues](/structs.go#L32) +### func [ShowDebugValues](/structs.go#L45) `func ShowDebugValues()` -### func [StandardClose](/window-golang-debug.go#L12) +### func [StandardClose](/main.go#L83) `func StandardClose(n *Node)` +The window is destroyed but the application does not quit + +### func [StandardExit](/main.go#L90) + +`func StandardExit(n *Node)` + +The window is destroyed but the application does not quit + +### func [Watchdog](/watchdog.go#L16) + +`func Watchdog()` + +This program sits here. +If you exit here, the whole thing will os.Exit() + +This goroutine can be used like a watchdog timer + ## Types -### type [GuiConfig](/structs.go#L56) +### type [GuiConfig](/structs.go#L68) `type GuiConfig struct { ... }` @@ -195,20 +178,18 @@ For example: gui.Queue(NewWindow()) var Config GuiConfig ``` -### type [GuiOptions](/structs.go#L44) +### type [GuiOptions](/structs.go#L56) `type GuiOptions struct { ... }` -### type [Node](/structs.go#L104) +This struct can be used with go-arg + +### type [Node](/structs.go#L87) `type Node struct { ... }` The Node is simply the name and the size of whatever GUI element exists -#### func [NewStandardWindow](/window-demo-toolkit.go#L7) - -`func NewStandardWindow(title string) *Node` - #### func [NewWindow](/window.go#L15) `func NewWindow() *Node` @@ -220,46 +201,15 @@ it can be passed via the 'andlabs/ui' queue which, because it is cross platform, must pass UI changes into the OS threads (that is my guess). -This example demonstrates how to create a NewWindow() - -Interacting with a GUI in a cross platform fashion adds some -unusual problems. To obvuscate those, andlabs/ui starts a -goroutine that interacts with the native gui toolkits -on the Linux, MacOS, Windows, etc. - -Because of this oddity, to initialize a new window, the -function is not passed any arguements and instead passes -the information via the Config type. - -```golang -package main - -import ( - "git.wit.org/wit/gui" -) +### type [Symbol](/plugin.go#L17) -func main() { - // Define the name and size - gui.Config.Title = "WIT GUI Window 1" - gui.Config.Width = 640 - gui.Config.Height = 480 - - // Create the Window - gui.NewWindow() +`type Symbol any` -} - -``` - - Output: - -``` -You get a window -``` +## Sub Packages -### type [Widget](/structs.go#L74) +* [need-to-redo](./need-to-redo) -`type Widget int` +* [toolkit](./toolkit) --- Readme created from Go doc with [goreadme](https://github.com/posener/goreadme) |