Index | Files | Directories

package app

import ""

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


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 UpdateEvent that prompts an update of the window contents and state.

For example:

import ""

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

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


The Main function must be called from a programs 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 ""

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

Event queue

A Window's Queue method returns an input.Queue implementation that distributes incoming events to the input handlers declared in the latest call to Update. See the package for more information about input handlers.


Package Files

app.go datadir_go112.go doc.go egl.go egl_linux.go egl_wayland.go os_wayland.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 CommandEvent Uses

type CommandEvent struct {
    Type CommandType
    // Suppress the default action of the command.
    Cancel bool

CommandEvent is a system event.

func (*CommandEvent) ImplementsEvent Uses

func (_ *CommandEvent) ImplementsEvent()

type CommandType Uses

type CommandType uint8

CommandType is the type of a CommandEvent.

const (
    // CommandBack is the command for a back action
    // such as the Android back button.
    CommandBack CommandType = iota

type Config Uses

type Config struct {
    // contains filtered or unexported fields

Config implements the ui.Config interface.

func (*Config) Now Uses

func (c *Config) Now() time.Time

func (*Config) Px Uses

func (c *Config) Px(v ui.Value) int

type DestroyEvent Uses

type DestroyEvent struct {
    // Err is nil for normal window closures. If a
    // window is prematurely closed, Err is the cause.
    Err error

DestroyEvent is the last event sent through a window event channel.

func (DestroyEvent) ImplementsEvent Uses

func (_ DestroyEvent) ImplementsEvent()

type Insets Uses

type Insets struct {
    Top, Bottom, Left, Right ui.Value

Insets is the space taken up by system decoration such as translucent system bars and software keyboards.

type Queue Uses

type Queue struct {
    // contains filtered or unexported fields

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

func (*Queue) Next Uses

func (q *Queue) Next(k input.Key) (input.Event, bool)

type Stage Uses

type Stage uint8

Stage of a Window.

const (
    // StagePaused is the Stage for inactive Windows.
    // Inactive Windows don't receive UpdateEvents.
    StagePaused Stage = iota
    // StateRunning is for active Windows.

func (Stage) String Uses

func (l Stage) String() string

type StageEvent Uses

type StageEvent struct {
    Stage Stage

A StageEvent is generated whenever the stage of a Window changes.

func (StageEvent) ImplementsEvent Uses

func (_ StageEvent) ImplementsEvent()

type UpdateEvent Uses

type UpdateEvent struct {
    Config Config
    // Size is the dimensions of the window.
    Size image.Point
    // Insets is the insets to apply.
    Insets Insets
    // contains filtered or unexported fields

An UpdateEvent is generated when a Window's Update method must be called.

func (UpdateEvent) ImplementsEvent Uses

func (_ UpdateEvent) ImplementsEvent()

type Window Uses

type Window struct {
    // contains filtered or unexported fields

Window represents an operating system window.

func NewWindow Uses

func NewWindow(options ...WindowOption) *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 input.Event

Events returns the channel where events are delivered.

func (*Window) Invalidate Uses

func (w *Window) Invalidate()

Invalidate the window such that a UpdateEvent will be generated immediately. If the window is inactive, the event is sent when the window becomes active.

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

func (*Window) Update Uses

func (w *Window) Update(frame *ui.Ops)

Update updates the Window. Paint operations updates the window contents, input operations declare input handlers, and so on. The supplied operations list completely replaces the window state from previous calls.

type WindowOption Uses

type WindowOption struct {
    // contains filtered or unexported fields

WindowOption configures a Window.

func WithHeight Uses

func WithHeight(h ui.Value) WindowOption

WithHeight returns an option that sets the window height.

func WithTitle Uses

func WithTitle(t string) WindowOption

WithTitle returns an option that sets the window title.

func WithWidth Uses

func WithWidth(w ui.Value) WindowOption

WithWidth returns an option that sets the window width.



Package app imports 26 packages (graph) and is imported by 3 packages. Updated 2019-08-22. Refresh now. Tools for package owners.