What does “visibility” refer to in the Activity Lifecycle? onPause vs onStop?

Question

The Activity Lifecycle is giving me headaches. The documentation at http://developer.android.com/reference/android/app/Activity.html is so darn ambiguous when it describes the concept of visibility, that I can't figure out when onStop() is called vs onPause().

Compare the following two statements from the documentation:

(taken from right beneath the lifecycle diagram)

The onStart() and onStop() methods can be called multiple times, as the activity becomes visible and hidden to the user.

vs

(further down in the blue table with the "killable" columns)

onPause() Called when the system is about to start resuming a previous activity.

What I'd understand from the first quote, is that onStop() is called on activity A when A is "hidden". "Hidden" I'd guess is referring to when another activity B has been resumed and is completely covering actvity A. But the second quote then states that onPause() is called when another activity is about to start resuming. Wouldn't that completely hide activity A as well? Both cases seem to imply that that activity A becomes "hidden", no? According to my likely faulty interpretation, onPause() and onStop() are called in identical situations.

The documentation also seems to differ between being hidden (onStop() gets called) and being partial visibility (onPause() gets called). But when is an activity still partially visible? Do they mean literally? Or can an activity still be deemed "partially visible" when it has started up a new activity (activity calls startActivityForResult and starts a date picker activity) that covers the entire screen? Surely the activity is not going get onStop invoked? Its supposed to receive a result any moment!

So I'm trying to figure out what I'm not getting. I understand that a call to onPause is guaranteed. That would be when activity A loses focus (device enters sleep mode, screenlock, etc), a different activity B takes the foreground (where activity B may or may not have been initiated by activity A). But at which point is the onStop() invoked on activity A?

Is it matter of how many activities have been piled ontop of activity A on the activity stack? Are there two different definitions of "visiblity" at play?

Sorry about the wall of text, but I'm really frustrated :S

So the question stands: Precisely in which situations is an activity deemed "hidden" such that onStop() is called on it?

EDIT:

I inserted Toast notifications in each onX method, and discovered some additional weirdness:

1. Pressing the Home button will always call onStop(). But starting up the application won't call onRestart(). Instead it calls onCreate(). This seems strange to me, but ok...
2. When the "USB Mass Storage" activity is started on top of the main activity, onStop() is called. And when exiting the usb storage activity, returning to the main activity, onRestart() is called, instead of onCreate().
3. When the device goes into Sleep mode and is waken up, the activity only goes through the onPause() and onResume() cycle.

The last point was expected (although I can't get it to fit in the lifecycle diagram). But whats up with 1. and 2. ?

In the first point, I was expecting a call to onRestart() when starting the activity again. Why did it deallocate the activity and call onCreate() instead?

And take a look at point nr 2: According to the documentation: when "another activity comes in front of the activity", onPaused() should be called. Isn't that what happened when the USB Storage activity came up? It didn't call onPause(), it went through the onStop() - OnRestart() cycle! Obviously, the documentation doesn't consider that a case where "another activity comes in front of the activity". So what really happened?

Answer 1

Ok, I think I've got this now.

1.

The key to the first point was this link:

http://code.google.com/p/android/issues/detail?id=2373

Its a bug. Theres some code in the link that has completely solved the problem with new root activity instances being created, instead of just restarting the last active activity (before the home button was pressed).

I put the code at the top of the onCreate method, just below the super.onCreate call:

if (!isTaskRoot()) {
    final Intent intent = getIntent();
    final String intentAction = intent.getAction();
    if (intent.hasCategory(Intent.CATEGORY_LAUNCHER) &&
            intentAction != null && intentAction.equals(Intent.ACTION_MAIN)) {
        finish(); return;
    }
}

Note that I added the return statement after finish so the rest of the onCreate method doesn't run in the case that the bug is detected.

2.& 3.

The key to the second and third points was these two links:

http://answers.oreilly.com/topic/2692-android-programming-understanding-the-activity-life-cycle/

How to make Activity, not covering full screen

It turns out that "visibility" really is literally! So when the documentation says "another activity comes in front of the activity", the activity behind the bumped activity is still partially visible. This means that the Android Activity manager must check whether the bumped Activity is a full-screen activity or not: If it is, onStop() is called on the previous activity. If not, then onPaused() is called on the previous activity instead.

This trivially explains why the USB Storage manager caused the onStop() to be called.

This also means that when device goes into sleep mode, the Activity Manager considers it a non-fullscreen activity, even though technically the main activity is completely hidden behind it.

(See the second link on how to make non-fullscreen activities )

Interestingly, the pull-down window (with the notifications) doesn't call onPause() (nor does it call onStop()), even though it would have made sense as a non-fullscreen activity. This must be some kind of exception that I'll be investigating on my own.

This also means that the onStop()-onRestart() cycle is probably more common than the onPause()-onResume() cycle (although both must still be accounted for), since activities probably more often than not are full-screen activities (personally, I thought the documentation indicated the opposite: that onPause-onResume was more commmon, but maybe thats just me).

Additionally, this must mean that when the main activity starts a new fullscreen activity for a result, the main activity will be first stopped and later restarted when the result-retrieveing activity is done.

So the only question now is how to best deal with a paused activity (meaning, it is covered by a non-fullscreen activity) that gets deallocated (although this case would be rare). What challenges may there be?

But thats outside the scope of this question.

Answer 2

Finally tracked this down: you can detect the status bar pulldown using onWindowFocusChanged()

how to use OnWindowFocusChanged method