doc.go (3004B)
1 // Copyright 2014 The Go Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style 3 // license that can be found in the LICENSE file. 4 5 /* 6 Package app lets you write portable all-Go apps for Android and iOS. 7 8 There are typically two ways to use Go on Android and iOS. The first 9 is to write a Go library and use `gomobile bind` to generate language 10 bindings for Java and Objective-C. Building a library does not 11 require the app package. The `gomobile bind` command produces output 12 that you can include in an Android Studio or Xcode project. For more 13 on language bindings, see https://golang.org/x/mobile/cmd/gobind. 14 15 The second way is to write an app entirely in Go. The APIs are limited 16 to those that are portable between both Android and iOS, in particular 17 OpenGL, audio, and other Android NDK-like APIs. An all-Go app should 18 use this app package to initialize the app, manage its lifecycle, and 19 receive events. 20 21 Building apps 22 23 Apps written entirely in Go have a main function, and can be built 24 with `gomobile build`, which directly produces runnable output for 25 Android and iOS. 26 27 The gomobile tool can get installed with go get. For reference, see 28 https://golang.org/x/mobile/cmd/gomobile. 29 30 For detailed instructions and documentation, see 31 https://golang.org/wiki/Mobile. 32 33 Event processing in Native Apps 34 35 The Go runtime is initialized on Android when NativeActivity onCreate is 36 called, and on iOS when the process starts. In both cases, Go init functions 37 run before the app lifecycle has started. 38 39 An app is expected to call the Main function in main.main. When the function 40 exits, the app exits. Inside the func passed to Main, call Filter on every 41 event received, and then switch on its type. Registered filters run when the 42 event is received, not when it is sent, so that filters run in the same 43 goroutine as other code that calls OpenGL. 44 45 package main 46 47 import ( 48 "log" 49 50 "golang.org/x/mobile/app" 51 "golang.org/x/mobile/event/lifecycle" 52 "golang.org/x/mobile/event/paint" 53 ) 54 55 func main() { 56 app.Main(func(a app.App) { 57 for e := range a.Events() { 58 switch e := a.Filter(e).(type) { 59 case lifecycle.Event: 60 // ... 61 case paint.Event: 62 log.Print("Call OpenGL here.") 63 a.Publish() 64 } 65 } 66 }) 67 } 68 69 An event is represented by the empty interface type interface{}. Any value can 70 be an event. Commonly used types include Event types defined by the following 71 packages: 72 - golang.org/x/mobile/event/lifecycle 73 - golang.org/x/mobile/event/mouse 74 - golang.org/x/mobile/event/paint 75 - golang.org/x/mobile/event/size 76 - golang.org/x/mobile/event/touch 77 For example, touch.Event is the type that represents touch events. Other 78 packages may define their own events, and send them on an app's event channel. 79 80 Other packages can also register event filters, e.g. to manage resources in 81 response to lifecycle events. Such packages should call: 82 app.RegisterFilter(etc) 83 in an init function inside that package. 84 */ 85 package app // import "golang.org/x/mobile/app"