doc.go raw

   1  // SPDX-License-Identifier: Unlicense OR MIT
   2  
   3  /*
   4  Package app provides a platform-independent interface to operating system
   5  functionality for running graphical user interfaces.
   6  
   7  See https://github.com/p9c/p9/pkg/gel/gio for instructions to set up and run Gio programs.
   8  
   9  Windows
  10  
  11  Create a new Window by calling NewWindow. On mobile platforms or when Gio
  12  is embedded in another project, NewWindow merely connects with a previously
  13  created window.
  14  
  15  A Window is run by receiving events from its Events channel. The most
  16  important event is FrameEvent that prompts an update of the window
  17  contents and state.
  18  
  19  For example:
  20  
  21  	import "github.com/p9c/p9/pkg/gel/gio/unit"
  22  
  23  	w := app.NewWindow()
  24  	for e := range w.Events() {
  25  		if e, ok := e.(system.FrameEvent); ok {
  26  			ops.Reset()
  27  			// Add operations to ops.
  28  			...
  29  			// Completely replace the window contents and state.
  30  			e.Frame(ops)
  31  		}
  32  	}
  33  
  34  A program must keep receiving events from the event channel until
  35  DestroyEvent is received.
  36  
  37  Main
  38  
  39  The Main function must be called from a program's main function, to hand over
  40  control of the main thread to operating systems that need it.
  41  
  42  Because Main is also blocking on some platforms, the event loop of a Window must run in a goroutine.
  43  
  44  For example, to display a blank but otherwise functional window:
  45  
  46  	package main
  47  
  48  	import "github.com/p9c/p9/pkg/gel/gio/app"
  49  
  50  	func main() {
  51  		go func() {
  52  			w := app.NewWindow()
  53  			for range w.Events() {
  54  			}
  55  		}()
  56  		app.Main()
  57  	}
  58  
  59  
  60  Event queue
  61  
  62  A FrameEvent's Queue method returns an event.Queue implementation that distributes
  63  incoming events to the event handlers declared in the last frame.
  64  See the github.com/p9c/p9/pkg/gel/gio/io/event package for more information about event handlers.
  65  
  66  Permissions
  67  
  68  The packages under github.com/p9c/p9/pkg/gel/gio/app/permission should be imported
  69  by a Gio program or by one of its dependencies to indicate that specific
  70  operating-system permissions are required.  Please see documentation for
  71  package github.com/p9c/p9/pkg/gel/gio/app/permission for more information.
  72  */
  73  package app
  74