github.com/c-darwin/mobile@v0.0.0-20160313183840-ff625c46f7c9/event/lifecycle/lifecycle.go (about)

     1  // Copyright 2015 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  // Package lifecycle defines an event for an app's lifecycle.
     6  //
     7  // The app lifecycle consists of moving back and forth between an ordered
     8  // sequence of stages. For example, being at a stage greater than or equal to
     9  // StageVisible means that the app is visible on the screen.
    10  //
    11  // A lifecycle event is a change from one stage to another, which crosses every
    12  // intermediate stage. For example, changing from StageAlive to StageFocused
    13  // implicitly crosses StageVisible.
    14  //
    15  // Crosses can be in a positive or negative direction. A positive crossing of
    16  // StageFocused means that the app has gained the focus. A negative crossing
    17  // means it has lost the focus.
    18  //
    19  // See the github.com/c-darwin/mobile/app package for details on the event model.
    20  package lifecycle // import "github.com/c-darwin/mobile/event/lifecycle"
    21  
    22  import (
    23  	"fmt"
    24  )
    25  
    26  // Cross is whether a lifecycle stage was crossed.
    27  type Cross uint32
    28  
    29  func (c Cross) String() string {
    30  	switch c {
    31  	case CrossOn:
    32  		return "on"
    33  	case CrossOff:
    34  		return "off"
    35  	}
    36  	return "none"
    37  }
    38  
    39  const (
    40  	CrossNone Cross = 0
    41  	CrossOn   Cross = 1
    42  	CrossOff  Cross = 2
    43  )
    44  
    45  // Event is a lifecycle change from an old stage to a new stage.
    46  type Event struct {
    47  	From, To Stage
    48  }
    49  
    50  // Crosses returns whether the transition from From to To crosses the stage s:
    51  // 	- It returns CrossOn if it does, and the lifecycle change is positive.
    52  // 	- It returns CrossOff if it does, and the lifecycle change is negative.
    53  //	- Otherwise, it returns CrossNone.
    54  // See the documentation for Stage for more discussion of positive and negative
    55  // crosses.
    56  func (e Event) Crosses(s Stage) Cross {
    57  	switch {
    58  	case e.From < s && e.To >= s:
    59  		return CrossOn
    60  	case e.From >= s && e.To < s:
    61  		return CrossOff
    62  	}
    63  	return CrossNone
    64  }
    65  
    66  // Stage is a stage in the app's lifecycle. The values are ordered, so that a
    67  // lifecycle change from stage From to stage To implicitly crosses every stage
    68  // in the range (min, max], exclusive on the low end and inclusive on the high
    69  // end, where min is the minimum of From and To, and max is the maximum.
    70  //
    71  // The documentation for individual stages talk about positive and negative
    72  // crosses. A positive lifecycle change is one where its From stage is less
    73  // than its To stage. Similarly, a negative lifecycle change is one where From
    74  // is greater than To. Thus, a positive lifecycle change crosses every stage in
    75  // the range (From, To] in increasing order, and a negative lifecycle change
    76  // crosses every stage in the range (To, From] in decreasing order.
    77  type Stage uint32
    78  
    79  // TODO: how does iOS map to these stages? What do cross-platform mobile
    80  // abstractions do?
    81  
    82  const (
    83  	// StageDead is the zero stage. No lifecycle change crosses this stage,
    84  	// but:
    85  	//	- A positive change from this stage is the very first lifecycle change.
    86  	//	- A negative change to this stage is the very last lifecycle change.
    87  	StageDead Stage = iota
    88  
    89  	// StageAlive means that the app is alive.
    90  	//	- A positive cross means that the app has been created.
    91  	//	- A negative cross means that the app is being destroyed.
    92  	// Each cross, either from or to StageDead, will occur only once.
    93  	// On Android, these correspond to onCreate and onDestroy.
    94  	StageAlive
    95  
    96  	// StageVisible means that the app window is visible.
    97  	//	- A positive cross means that the app window has become visible.
    98  	//	- A negative cross means that the app window has become invisible.
    99  	// On Android, these correspond to onStart and onStop.
   100  	// On Desktop, an app window can become invisible if e.g. it is minimized,
   101  	// unmapped, or not on a visible workspace.
   102  	StageVisible
   103  
   104  	// StageFocused means that the app window has the focus.
   105  	//	- A positive cross means that the app window has gained the focus.
   106  	//	- A negative cross means that the app window has lost the focus.
   107  	// On Android, these correspond to onResume and onFreeze.
   108  	StageFocused
   109  )
   110  
   111  func (s Stage) String() string {
   112  	switch s {
   113  	case StageDead:
   114  		return "StageDead"
   115  	case StageAlive:
   116  		return "StageAlive"
   117  	case StageVisible:
   118  		return "StageVisible"
   119  	case StageFocused:
   120  		return "StageFocused"
   121  	default:
   122  		return fmt.Sprintf("lifecycle.Stage(%d)", s)
   123  	}
   124  }