a8f42cd567a4703aed100e89e348685ea3bee1de — Elias Naur a month ago 657c40e
ui/app: expand package documentation

Signed-off-by: Elias Naur <mail@eliasnaur.com>
2 files changed, 55 insertions(+), 2 deletions(-)

M ui/app/app.go
M ui/app/doc.go
M ui/app/app.go => ui/app/app.go +4 -2
@@ 134,10 134,12 @@ return dataDir()
  }
  
- // Main must be called from the a program's main function.
+ // Main must be called from the a program's main function. It
+ // blocks until there are no more windows active.
+ //
  // Calling Main is necessary because some operating systems
  // require control of the main thread of the program for
- // running user interfaces.
+ // running windows.
  func Main() {
  	main()
  }

M ui/app/doc.go => ui/app/doc.go +51 -0
@@ 4,5 4,56 @@ Package app provides a platform-independent interface to operating system
  functionality for running graphical user interfaces.
  
+ Windows
+ 
+ Create a new Window by callingNewWindow. On mobile platforms or when Gio
+ is embedded in another project, NewWindow merely connects with a previously
+ created window.
+ 
+ A Window is run by receiving events from its Events channel. The most
+ important event is UpdateEvent that prompts an update of the window
+ contents and state.
+ 
+ For example:
+ 
+ 	import "gioui.org/ui"
+ 
+ 	w := app.NewWindow(nil)
+ 	for e := range w.Events() {
+ 		if e, ok := e.(app.UpdateEvent); ok {
+ 			ops.Reset()
+ 			// Add operations to ops.
+ 			...
+ 			// Completely replace the window contents and state.
+ 			w.Update(ops)
+ 		}
+ 	}
+ 
+ A program must keep receiving events from the event channel until
+ DestroyEvent is received.
+ 
+ Main
+ 
+ The Main function must be called from a programs main function, to hand over
+ control of the main thread to operating systems that need it.
+ 
+ Because Main is also blocking, the event loop of a Window must run in a goroutine.
+ 
+ For example, to display a blank but otherwise functional window:
+ 
+ 	package main
+ 
+ 	import "gioui.org/ui/app"
+ 
+ 	func main() {
+ 		go func() {
+ 			w := app.NewWindow(nil)
+ 			for range w.Events() {
+ 			}
+ 		}()
+ 		app.Main()
+ 	}
+ 
+ 
  */
  package app