User Actions and Callback Sequences

You are here:

User Actions and Callback Sequences

The most common callback sequences for common user actions are listed in the following sub-sections.

Sequencing Differences

As noted previously, while onCreate, onStart, and onResume (and their matching "downward" callbacks onDestroy, onStop and onPause) are defined by specification to happen in a nested ordering, focus events, and window created/update/destroy events are not specified to fall in definite locations in these sequences. You should be prepared to see such differences as:

The window can gain focus before or after the surface is created.
The window can lose focus before or after the surface is destroyed.
These cases do not imply each other (i.e., all four possible outcomes have been seen in practice).

Thus, it is important to flag all of these changes and have an update function that is called on each change to check the current state flags and act when the combinations of important state are entered.

Note: these are merely common examples. Some devices may produce slightly different results, as we will document in the section Surprising Application Lifecycle Events and how to Handle Them.

Launching a New Application

When a new instance of an application is launched, the Java class for the Activity is created (the process itself may actually have still be resident from an earlier run of the app), and the full system is brought up, including a valid, visible, focused window.

+-onCreate 
+-onStart
+-onResume
+-surfaceCreated
+-surfaceChanged: 1366, 695
+-onWindowFocusChanged (TRUE)

At this point, the application should be rendering, playing its sounds, and accepting input.

Pressing the Back Button

An application receives the back button event and has two choices. It can either:

"Eat" the event, handling it internally by stepping backwards in its UI structure. It then does not pass the event to the super-class’s onKeyDown, and returns true ("handled") from its own onKeyDown. The handling of the event is complete
Allow Android to process the event, in which case it will pop the application off the UI stack and destroy the application’s Activity, essentially quitting the application (although the app’s process will likely keep running).

+-onPause
+-onWindowFocusChanged (FALSE)
+-surfaceDestroyed
+-onStop
+-onDestroy

This is quite a heavyweight case. For this reason, most applications will "eat" the Back event internally, and provide dialogs for the user to confirm before quitting actually happens.

Pressing the Home Button

The Home button sends the app down in the UI stack. The application’s Activity still exists, but is completely hidden and may be killed at any time. Additionally, it loses its rendering surface (which is not an issue, since it is not visible in any case).

+-onPause
+-onWindowFocusChanged (FALSE)
+-surfaceDestroyed
+-onStop

While the application is stopped, it may be resumed at any time by selecting the app from the list of resident applications.

Resuming a "Home’d" Application

If an application sent further down the UI stack by a Home event is selected from the list of running applications before Android chooses to kill it, the app is "restarted," which calls not only start but also a special onRestart callback that differentiates between a newly-launched instance and a resumed one.

+-onRestart
+-onStart
+-onResume
+-surfaceCreated
+-surfaceChanged: 1366, 695
+-onWindowFocusChanged (TRUE)

The application is once again ready for rendering, sound, and interaction.

Opening a Status Icon Pop-up

Pulling down a pull-down status bar or tapping on a status icon causes some UI items to be composited on top of the application. These include:

Pulling down a pull-down status bar
Tapping on a status icon
Showing the task-switch interface in Honeycomb or Ice Cream Sandwich
Alarm indications

In these cases, the application is visible and can render, but is not focused and cannot receive input.

+-onWindowFocusChanged (FALSE)

This is the lightest-weight version of being down-shifted.

Closing a Status Icon Pop-up

When a pending partial-screen UI element on top of your app is dismissed, focus is regained.

+-onWindowFocusChanged (TRUE)

Suspend/Resume

Suspend and resume happen in a three-step sequence, and thus are best discussed together.

When the device is suspended with the power button or the screen-saver timeout expires, the device suspends. If the power button is pressed again, it resumes to the lock-screen. At this point, if the user unlocks the device, the application is resumed. If the user waits several seconds without unlocking the lock screen, the device will suspend again.

Note: Suspend/Resume is the most variable of all of the cases. See the later section Surprising Application Lifecycle Events and How to Handle Them for practical details on handling this case.

Suspending the Device

Most commonly, when suspended, the application will be paused and will lose focus.

+-onPause
+-onWindowFocusChanged (FALSE)

Since this is explicitly a low-power state, the application should have stopped all rendering and sound, and likely any background processing that isn’t 100% required to keep the app alive.

Resuming the Device

When the device is resumed with the power button, the application is also resumed. However, the lock screen covers the application’s window. No focus change is returned to the application. The application should not play sound or render at this point. Within a few seconds, it may be paused again if the lock screen times out.

+-onResume

Unlocking the Lock Screen

Once the lock screen is unlocked, the application is focused again. Since it is now resumed and focused, the application should consider itself signaled to begin rendering, playing sound and accepting input.

+-onWindowFocusChanged (TRUE)

Alternative Sequence

Note that in some cases, only the onPause is received on suspend, in which case, the focus lost callback actually comes when the device is resumed to the lock screen. In other words, resuming sends an indication that you have been resumed (onResume) and then an indication that you are hidden (focus lost). And the unlock case remains unchanged (focus regained).