gioui.org: gioui.org/app Index | Files | Directories

package app

import "gioui.org/app"

Package app provides a platform-independent interface to operating system functionality for running graphical user interfaces.

See https://gioui.org for instructions to set up and run Gio programs.

Windows

Create a new Window by calling NewWindow. 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 FrameEvent that prompts an update of the window contents and state.

For example:

import "gioui.org/unit"

w := app.NewWindow()
for e := range w.Events() {
	if e, ok := e.(app.FrameEvent); ok {
		ops.Reset()
		// Add operations to ops.
		...
		// Completely replace the window contents and state.
		e.Frame(ops)
	}
}

A program must keep receiving events from the event channel until DestroyEvent is received.

Main

The Main function must be called from a program's 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/app"

func main() {
	go func() {
		w := app.NewWindow()
		for range w.Events() {
		}
	}()
	app.Main()
}

Event queue

A Window's Queue method returns an event.Queue implementation that distributes incoming events to the event handlers declared in the latest frame. See the gioui.org/io/event package for more information about event handlers.

Permissions

The packages under gioui.org/app/permission should be imported by a Gio program or by one of its dependencies to indicate that specific operating-system permissions are required. For example, if a Gio program requires access to a device's Bluetooth interface, it should import "gioui.org/app/permission/bluetooth" as follows:

package main

import (
	"gioui.org/app"
	_ "gioui.org/app/permission/bluetooth"
)

func main() {
	...
}

Since there are no exported identifiers in the app/permission/bluetooth package, the import uses the anonymous identifier (_) as the imported package name.

As a special case, the gogio tool detects when a program directly or indirectly depends on the "net" package from the Go standard library as an indication that the program requires network access permissions. If a program requires network permissions but does not directly or indirectly import "net", it will be necessary to add the following code somewhere in the program's source code:

import (
	...
	_ "net"
)

Index

Package Files

app.go datadir.go doc.go window.go

func DataDir Uses

func DataDir() (string, error)

DataDir returns a path to use for application-specific configuration data. On desktop systems, DataDir use os.UserConfigDir. On iOS NSDocumentDirectory is queried. For Android Context.getFilesDir is used.

BUG: DataDir blocks on Android until init functions have completed.

func Main Uses

func Main()

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 windows.

type Handle Uses

type Handle window.Handle

func PlatformHandle Uses

func PlatformHandle() *Handle

PlatformHandle returns the platform specific Handle.

type Option Uses

type Option func(opts *window.Options)

WindowOption configures a Window.

func Size Uses

func Size(w, h unit.Value) Option

Size sets the size of the window.

func Title Uses

func Title(t string) Option

Title sets the title of the window.

type Queue Uses

type Queue struct {
    // contains filtered or unexported fields
}

Queue is an event.Queue implementation that distributes system events to the input handlers declared in the most recent frame.

func (*Queue) Events Uses

func (q *Queue) Events(k event.Key) []event.Event

type Window Uses

type Window struct {
    // contains filtered or unexported fields
}

Window represents an operating system window.

func NewWindow Uses

func NewWindow(options ...Option) *Window

NewWindow creates a new window for a set of window options. The options are hints; the platform is free to ignore or adjust them.

If opts are nil, a set of sensible defaults are used.

If the current program is running on iOS and Android, NewWindow returns the window previously created by the platform.

BUG: Calling NewWindow more than once is not yet supported.

func (*Window) Events Uses

func (w *Window) Events() <-chan event.Event

Events returns the channel where events are delivered.

func (*Window) Invalidate Uses

func (w *Window) Invalidate()

Invalidate the window such that a FrameEvent will be generated immediately. If the window is inactive, the event is sent when the window becomes active. Invalidate is safe for concurrent use.

func (*Window) Queue Uses

func (w *Window) Queue() *Queue

Queue returns the Window's event queue. The queue contains the events received since the last frame.

Directories

PathSynopsis
internal/gl
internal/gpu
internal/input
internal/logPackage points standard output, standard error and the standard library package log to the platform logger.
internal/windowPackage window implements platform specific windows and GPU contexts.
internal/xkbPackage xkb implements a Go interface for the X Keyboard Extension library.
permission/bluetooth
permission/bluetooth_le

Package app imports 16 packages (graph) and is imported by 3 packages. Updated 2019-11-12. Refresh now. Tools for package owners.