blob: 9a5f54ed113c842d3c7de8e1c34f77bdcc053dd8 [file] [log] [blame]
// Copyright 2015 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
// Package lifecycle defines an event for an app's lifecycle.
//
// The app lifecycle consists of moving back and forth between an ordered
// sequence of stages. For example, being at a stage greater than or equal to
// StageVisible means that the app is visible on the screen.
//
// A lifecycle event is a change from one stage to another, which crosses every
// intermediate stage. For example, changing from StageAlive to StageFocused
// implicitly crosses StageVisible.
//
// Crosses can be in a positive or negative direction. A positive crossing of
// StageFocused means that the app has gained the focus. A negative crossing
// means it has lost the focus.
//
// See the golang.org/x/mobile/app package for details on the event model.
package lifecycle // import "golang.org/x/mobile/event/lifecycle"
import (
"fmt"
)
// Cross is whether a lifecycle stage was crossed.
type Cross uint32
func (c Cross) String() string {
switch c {
case CrossOn:
return "on"
case CrossOff:
return "off"
}
return "none"
}
const (
CrossNone Cross = 0
CrossOn Cross = 1
CrossOff Cross = 2
)
// Event is a lifecycle change from an old stage to a new stage.
type Event struct {
From, To Stage
// DrawContext is the state used for painting, if any is valid.
//
// For OpenGL apps, a non-nil DrawContext is a gl.Context.
//
// TODO: make this an App method if we move away from an event channel?
DrawContext interface{}
}
func (e Event) String() string {
return fmt.Sprintf("lifecycle.Event{From:%v, To:%v, DrawContext:%v}", e.From, e.To, e.DrawContext)
}
// Crosses reports whether the transition from From to To crosses the stage s:
// - It returns CrossOn if it does, and the lifecycle change is positive.
// - It returns CrossOff if it does, and the lifecycle change is negative.
// - Otherwise, it returns CrossNone.
// See the documentation for Stage for more discussion of positive and negative
// crosses.
func (e Event) Crosses(s Stage) Cross {
switch {
case e.From < s && e.To >= s:
return CrossOn
case e.From >= s && e.To < s:
return CrossOff
}
return CrossNone
}
// Stage is a stage in the app's lifecycle. The values are ordered, so that a
// lifecycle change from stage From to stage To implicitly crosses every stage
// in the range (min, max], exclusive on the low end and inclusive on the high
// end, where min is the minimum of From and To, and max is the maximum.
//
// The documentation for individual stages talk about positive and negative
// crosses. A positive lifecycle change is one where its From stage is less
// than its To stage. Similarly, a negative lifecycle change is one where From
// is greater than To. Thus, a positive lifecycle change crosses every stage in
// the range (From, To] in increasing order, and a negative lifecycle change
// crosses every stage in the range (To, From] in decreasing order.
type Stage uint32
// TODO: how does iOS map to these stages? What do cross-platform mobile
// abstractions do?
const (
// StageDead is the zero stage. No lifecycle change crosses this stage,
// but:
// - A positive change from this stage is the very first lifecycle change.
// - A negative change to this stage is the very last lifecycle change.
StageDead Stage = iota
// StageAlive means that the app is alive.
// - A positive cross means that the app has been created.
// - A negative cross means that the app is being destroyed.
// Each cross, either from or to StageDead, will occur only once.
// On Android, these correspond to onCreate and onDestroy.
StageAlive
// StageVisible means that the app window is visible.
// - A positive cross means that the app window has become visible.
// - A negative cross means that the app window has become invisible.
// On Android, these correspond to onStart and onStop.
// On Desktop, an app window can become invisible if e.g. it is minimized,
// unmapped, or not on a visible workspace.
StageVisible
// StageFocused means that the app window has the focus.
// - A positive cross means that the app window has gained the focus.
// - A negative cross means that the app window has lost the focus.
// On Android, these correspond to onResume and onFreeze.
StageFocused
)
func (s Stage) String() string {
switch s {
case StageDead:
return "StageDead"
case StageAlive:
return "StageAlive"
case StageVisible:
return "StageVisible"
case StageFocused:
return "StageFocused"
default:
return fmt.Sprintf("lifecycle.Stage(%d)", s)
}
}