app

Documentation

Overview

Package app lets you write portable all-Go apps for Android and iOS.

There are typically two ways to use Go on Android and iOS. The first is to write a Go library and use `gomobile bind` to generate language bindings for Java and Objective-C. Building a library does not require the app package. The `gomobile bind` command produces output that you can include in an Android Studio or Xcode project. For more on language bindings, see https://github.com/provpn/mobile/cmd/gobind.

The second way is to write an app entirely in Go. The APIs are limited to those that are portable between both Android and iOS, in particular OpenGL, audio, and other Android NDK-like APIs. An all-Go app should use this app package to initialize the app, manage its lifecycle, and receive events.

Building apps

Apps written entirely in Go have a main function, and can be built with `gomobile build`, which directly produces runnable output for Android and iOS.

The gomobile tool can get installed with go get. For reference, see https://github.com/provpn/mobile/cmd/gomobile.

For detailed instructions and documentation, see https://golang.org/wiki/Mobile.

Event processing in Native Apps

The Go runtime is initialized on Android when NativeActivity onCreate is called, and on iOS when the process starts. In both cases, Go init functions run before the app lifecycle has started.

An app is expected to call the Main function in main.main. When the function exits, the app exits. Inside the func passed to Main, call Filter on every event received, and then switch on its type. Registered filters run when the event is received, not when it is sent, so that filters run in the same goroutine as other code that calls OpenGL.

package main

import (
	"log"

	"github.com/provpn/mobile/app"
	"github.com/provpn/mobile/event/lifecycle"
	"github.com/provpn/mobile/event/paint"
)

func main() {
	app.Main(func(a app.App) {
		for e := range a.Events() {
			switch e := a.Filter(e).(type) {
			case lifecycle.Event:
				// ...
			case paint.Event:
				log.Print("Call OpenGL here.")
				a.Publish()
			}
		}
	})
}

An event is represented by the empty interface type interface{}. Any value can be an event. Commonly used types include Event types defined by the following packages:

• github.com/provpn/mobile/event/lifecycle
• github.com/provpn/mobile/event/mouse
• github.com/provpn/mobile/event/paint
• github.com/provpn/mobile/event/size
• github.com/provpn/mobile/event/touch

For example, touch.Event is the type that represents touch events. Other packages may define their own events, and send them on an app's event channel.

Other packages can also register event filters, e.g. to manage resources in response to lifecycle events. Such packages should call:

app.RegisterFilter(etc)

in an init function inside that package.

Index

• func Main(f func(App))
• type App
• type PublishResult

Functions

func Main

func Main(f func(App))

Main is called by the main.main function to run the mobile application.

It calls f on the App, in a separate goroutine, as some OS-specific libraries require being on 'the main thread'.

Types

type App

type App interface {
	// Events returns the events channel. It carries events from the system to
	// the app. The type of such events include:
	//  - lifecycle.Event
	//  - mouse.Event
	//  - paint.Event
	//  - size.Event
	//  - touch.Event
	// from the github.com/provpn/mobile/event/etc packages. Other packages may
	// define other event types that are carried on this channel.
	Events() <-chan interface{}

	// Send sends an event on the events channel. It does not block.
	Send(event interface{})

	// Publish flushes any pending drawing commands, such as OpenGL calls, and
	// swaps the back buffer to the screen.
	Publish() PublishResult

	// Filter calls each registered event filter function in sequence.
	Filter(event interface{}) interface{}

	// RegisterFilter registers a event filter function to be called by Filter. The
	// function can return a different event, or return nil to consume the event,
	// but the function can also return its argument unchanged, where its purpose
	// is to trigger a side effect rather than modify the event.
	RegisterFilter(f func(interface{}) interface{})
}

App is how a GUI mobile application interacts with the OS.

type PublishResult

type PublishResult struct {
	// BackBufferPreserved is whether the contents of the back buffer was
	// preserved. If false, the contents are undefined.
	BackBufferPreserved bool
}

PublishResult is the result of an App.Publish call.