Open topic with navigation
The most common callback sequences for common user actions are listed in the following sub-sections.
As noted previously, while
onResume (and their matching "downward" callbacks
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:
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.|
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.
+-surfaceChanged: 1366, 695
At this point, the application should be rendering, playing its sounds, and accepting input.
An application receives the back button event and has two choices. It can either:
onKeyDown, and returns true ("handled") from its own
onKeyDown. The handling of the event is complete
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.
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).
While the application is stopped, it may be resumed at any time by selecting the app from the list of resident applications.
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.
+-surfaceChanged: 1366, 695
The application is once again ready for rendering, sound, and interaction.
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:
In these cases, the application is visible and can render, but is not focused and cannot receive input.
This is the lightest-weight version of being down-shifted.
When a pending partial-screen UI element on top of your app is dismissed, focus is regained.
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.|
Most commonly, when suspended, the application will be paused and will lose focus.
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.
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.
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.
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).
NVIDIA® GameWorks™ Documentation Rev. 1.0.220830 ©2014-2022. NVIDIA Corporation and affiliates. All Rights Reserved.