github.com/cybriq/giocore@v0.0.7-0.20210703034601-cfb9cb5f3900/app/doc.go (about)

     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/cybriq/giocore 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/cybriq/giocore/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/cybriq/giocore/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/cybriq/giocore/io/event package for more information about event handlers.
    65  
    66  Permissions
    67  
    68  The packages under github.com/cybriq/giocore/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/cybriq/giocore/app/permission for more information.
    72  */
    73  package app