Documentation

Overview

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.(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 range w.Events() {
		}
	}()
	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

Constants

View Source
const (
	// Windowed is the normal window mode with OS specific window decorations.
	Windowed = wm.Windowed
	// Fullscreen is the full screen window mode.
	Fullscreen = wm.Fullscreen
)

Variables

This section is empty.

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 Option

      type Option func(opts *wm.Options)

        WindowOption configures a wm.

        func MaxSize

        func MaxSize(w, h unit.Value) Option

          MaxSize sets the maximum size of the wm.

          func MinSize

          func MinSize(w, h unit.Value) Option

            MinSize sets the minimum size of the wm.

            func Size

            func Size(w, h unit.Value) Option

              Size sets the size of the wm.

              func Title

              func Title(t string) Option

                Title sets the title of the wm.

                func WindowMode

                func WindowMode(mode wm.WindowMode) Option

                  WindowMode sets the window mode.

                  Supported platforms are macOS, X11 and Windows.

                  type Window

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

                    Window represents an operating system wm.

                    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 and Android, NewWindow returns the window previously created by the platform.

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

                      func (*Window) Close

                      func (w *Window) Close()

                        Close the wm. The window's event loop should exit when it receives system.DestroyEvent.

                        Currently, only macOS, Windows and X11 drivers implement this functionality, all others are stubbed.

                        func (*Window) Events

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

                          Events returns the channel where events are delivered.

                          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) Option

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

                              Option applies the options to the window.

                              func (*Window) ReadClipboard

                              func (w *Window) ReadClipboard()

                                ReadClipboard initiates a read of the clipboard in the form of a clipboard.Event. Multiple reads may be coalesced to a single event.

                                func (*Window) SetCursorName

                                func (w *Window) SetCursorName(name pointer.CursorName)

                                  SetCursorName changes the current window cursor to name.

                                  func (*Window) WriteClipboard

                                  func (w *Window) WriteClipboard(s string)

                                    WriteClipboard writes a string to the clipboard.

                                    Directories

                                    Path Synopsis
                                    Package permission includes sub-packages that should be imported by a Gio program or by one of its dependencies to indicate that specific operating-system permissions are required.
                                    Package permission includes sub-packages that should be imported by a Gio program or by one of its dependencies to indicate that specific operating-system permissions are required.
                                    bluetooth
                                    Package bluetooth implements permissions to access Bluetooth and Bluetooth Low Energy hardware, including the ability to discover and pair devices.
                                    Package bluetooth implements permissions to access Bluetooth and Bluetooth Low Energy hardware, including the ability to discover and pair devices.
                                    camera
                                    Package camera implements permissions to access camera hardware.
                                    Package camera implements permissions to access camera hardware.
                                    networkstate
                                    Package networkstate implements permissions to access network connectivity information.
                                    Package networkstate implements permissions to access network connectivity information.
                                    storage
                                    Package storage implements read and write storage permissions on mobile devices.
                                    Package storage implements read and write storage permissions on mobile devices.
                                    internal
                                    log
                                    Package points standard output, standard error and the standard library package log to the platform logger.
                                    Package points standard output, standard error and the standard library package log to the platform logger.
                                    wm
                                    package wm implements platform specific windows and GPU contexts.
                                    package wm implements platform specific windows and GPU contexts.
                                    xkb
                                    Package xkb implements a Go interface for the X Keyboard Extension library.
                                    Package xkb implements a Go interface for the X Keyboard Extension library.