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 calling NextEvent in a loop. The most important event is FrameEvent that prompts an update of the window contents.

For example:

import "gioui.org/unit"

w := app.NewWindow()
for {
	e := w.NextEvent()
	if e, ok := e.(system.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 on some platforms, 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 {
			w.NextEvent()
		}
	}()
	app.Main()
}

Event queue

A FrameEvent's Queue method returns an event.Queue implementation that distributes incoming events to the event handlers declared in the last 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. Please see documentation for package gioui.org/app/permission for more information.

Index ¶

• Variables
• func DataDir() (string, error)
• func Main()
• type Config
• type ConfigEvent
• func (ConfigEvent) ImplementsEvent()
• type Option
• func CustomRenderer(custom bool) Option
• func Decorated(enabled bool) Option
• func MaxSize(w, h unit.Dp) Option
• func MinSize(w, h unit.Dp) Option
• func NavigationColor(color color.NRGBA) Option
• func Size(w, h unit.Dp) Option
• func StatusColor(color color.NRGBA) Option
• func Title(t string) Option
• type Orientation
• func (o Orientation) Option() Option
• func (o Orientation) String() string
• type ViewEvent
• func (_ ViewEvent) ImplementsEvent()
• type Window
• func NewWindow(options ...Option) *Window
• func (w *Window) Invalidate()
• func (w *Window) NextEvent() event.Event
• func (w *Window) Option(opts ...Option)
• func (w *Window) Perform(actions system.Action)
• func (w *Window) Run(f func())
• func (w *Window) WriteClipboard(s string)
• type WindowMode
• func (m WindowMode) Option() Option
• func (m WindowMode) String() string

Variables ¶

var ID = ""

ID is the app id exposed to the platform.

On Android ID is the package property of AndroidManifest.xml, on iOS ID is the CFBundleIdentifier of the app Info.plist, on Wayland it is the toplevel app_id, on X11 it is the X11 XClassHint

ID is set by the gogio tool or manually with the -X linker flag. For example,

go build -ldflags="-X 'gioui.org/app.ID=org.gioui.example.Kitchen'" .

Note that ID is treated as a constant, and that changing it at runtime is not supported. Default value of ID is filepath.Base(os.Args[0]).

Functions ¶

func DataDir ¶

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 ¶

func Main()

Main must be called last from the program main function. On most platforms Main blocks forever, for Android and iOS it returns immediately to give control of the main thread back to the system.

Calling Main is necessary because some operating systems require control of the main thread of the program for running windows.

Types ¶

type Config ¶

type Config struct {
	// Size is the window dimensions (Width, Height).
	Size image.Point
	// MaxSize is the window maximum allowed dimensions.
	MaxSize image.Point
	// MinSize is the window minimum allowed dimensions.
	MinSize image.Point
	// Title is the window title displayed in its decoration bar.
	Title string
	// WindowMode is the window mode.
	Mode WindowMode
	// StatusColor is the color of the Android status bar.
	StatusColor color.NRGBA
	// NavigationColor is the color of the navigation bar
	// on Android, or the address bar in browsers.
	NavigationColor color.NRGBA
	// Orientation is the current window orientation.
	Orientation Orientation
	// CustomRenderer is true when the window content is rendered by the
	// client.
	CustomRenderer bool
	// Decorated reports whether window decorations are provided automatically.
	Decorated bool
	// contains filtered or unexported fields
}

Config describes a Window configuration.

type ConfigEvent ¶

type ConfigEvent struct {
	Config Config
}

ConfigEvent is sent whenever the configuration of a Window changes.

func (ConfigEvent) ImplementsEvent ¶

func (ConfigEvent) ImplementsEvent()

type Option ¶

type Option func(unit.Metric, *Config)

Option configures a window.

func CustomRenderer ¶

func CustomRenderer(custom bool) Option

CustomRenderer controls whether the window contents is rendered by the client. If true, no GPU context is created.

Caller must assume responsibility for rendering which includes initializing the render backend, swapping the framebuffer and handling frame pacing.

func Decorated ¶

func Decorated(enabled bool) Option

Decorated controls whether Gio and/or the platform are responsible for drawing window decorations. Providing false indicates that the application will either be undecorated or will draw its own decorations.

func MaxSize ¶

func MaxSize(w, h unit.Dp) Option

MaxSize sets the maximum size of the window.

func MinSize ¶

func MinSize(w, h unit.Dp) Option

MinSize sets the minimum size of the window.

func NavigationColor ¶

func NavigationColor(color color.NRGBA) Option

NavigationColor sets the color of the navigation bar on Android, or the address bar in browsers.

func Size ¶

func Size(w, h unit.Dp) Option

Size sets the size of the window. The mode will be changed to Windowed.

func StatusColor ¶

func StatusColor(color color.NRGBA) Option

StatusColor sets the color of the Android status bar.

func Title ¶

func Title(t string) Option

Title sets the title of the window.

type Orientation ¶

type Orientation uint8

Orientation is the orientation of the app (Orientation.Option sets it).

Supported platforms are Android and JS.

const (
	// AnyOrientation allows the window to be freely orientated.
	AnyOrientation Orientation = iota
	// LandscapeOrientation constrains the window to landscape orientations.
	LandscapeOrientation
	// PortraitOrientation constrains the window to portrait orientations.
	PortraitOrientation
)

func (Orientation) Option ¶

func (o Orientation) Option() Option

func (Orientation) String ¶

func (o Orientation) String() string

type ViewEvent ¶

type ViewEvent struct {
	HWND uintptr
}

func (ViewEvent) ImplementsEvent ¶

func (_ ViewEvent) ImplementsEvent()

type Window ¶

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

Window represents an operating system window.

func NewWindow ¶

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 the current program is running on iOS or Android, NewWindow returns the window previously created by the platform.

Calling NewWindow more than once is not supported on iOS, Android, WebAssembly.

func (*Window) Invalidate ¶

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.

Note that Invalidate is intended for externally triggered updates, such as a response from a network request. InvalidateOp is more efficient for animation and similar internal updates.

Invalidate is safe for concurrent use.

func (*Window) NextEvent ¶

func (w *Window) NextEvent() event.Event

NextEvent blocks until an event is received from the window, such as io/system.FrameEvent. It blocks forever if called after io/system.DestroyEvent has been returned.

func (*Window) Option ¶

func (w *Window) Option(opts ...Option)

Option applies the options to the window.

func (*Window) Perform ¶

func (w *Window) Perform(actions system.Action)

Perform the actions on the window.

func (*Window) Run ¶

func (w *Window) Run(f func())

Run f in the same thread as the native window event loop, and wait for f to return or the window to close. Run is guaranteed not to deadlock if it is invoked during the handling of a ViewEvent, system.FrameEvent, system.StageEvent; call Run in a separate goroutine to avoid deadlock in all other cases.

Note that most programs should not call Run; configuring a Window with CustomRenderer is a notable exception.

func (*Window) WriteClipboard ¶

func (w *Window) WriteClipboard(s string)

WriteClipboard writes a string to the clipboard.

type WindowMode ¶

type WindowMode uint8

WindowMode is the window mode (WindowMode.Option sets it). Note that mode can be changed programatically as well as by the user clicking on the minimize/maximize buttons on the window's title bar.

const (
	// Windowed is the normal window mode with OS specific window decorations.
	Windowed WindowMode = iota
	// Fullscreen is the full screen window mode.
	Fullscreen
	// Minimized is for systems where the window can be minimized to an icon.
	Minimized
	// Maximized is for systems where the window can be made to fill the available monitor area.
	Maximized
)

func (WindowMode) Option ¶

func (m WindowMode) Option() Option

Option changes the mode of a Window.

func (WindowMode) String ¶

func (m WindowMode) String() string

String returns the mode name.

Source Files ¶

app.go d3d11_windows.go datadir.go doc.go egl_windows.go os.go os_windows.go window.go

Directories ¶