From bd1724cf6d5d443510796db2963d9a38015b9d60 Mon Sep 17 00:00:00 2001 From: Jeff Chang Date: Sun, 1 Aug 2021 17:50:33 +0800 Subject: [PATCH] Update the documentation for onResume of Activity onResume is not always an indicator that the activity is visible and start interacting with the user. The case demonstrated activity is in the relaunched process (onCreate() -> onResume()) while the screen is still locked. Update the documentation to prevent developers from being confused. Bug: 187494420 Test: build Change-Id: Id52a02b54218d899a948640049cb627eb98ef2f6 --- core/java/android/app/Activity.java | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/core/java/android/app/Activity.java b/core/java/android/app/Activity.java index 643020a7dbd26..12025f98ada87 100644 --- a/core/java/android/app/Activity.java +++ b/core/java/android/app/Activity.java @@ -1934,10 +1934,14 @@ public class Activity extends ContextThemeWrapper } /** - * Called after {@link #onRestoreInstanceState}, {@link #onRestart}, or - * {@link #onPause}, for your activity to start interacting with the user. This is an indicator - * that the activity became active and ready to receive input. It is on top of an activity stack - * and visible to user. + * Called after {@link #onRestoreInstanceState}, {@link #onRestart}, or {@link #onPause}. This + * is usually a hint for your activity to start interacting with the user, which is a good + * indicator that the activity became active and ready to receive input. This sometimes could + * also be a transit state toward another resting state. For instance, an activity may be + * relaunched to {@link #onPause} due to configuration changes and the activity was visible, + * but wasn’t the top-most activity of an activity task. {@link #onResume} is guaranteed to be + * called before {@link #onPause} in this case which honors the activity lifecycle policy and + * the activity eventually rests in {@link #onPause}. * *

On platform versions prior to {@link android.os.Build.VERSION_CODES#Q} this is also a good * place to try to open exclusive-access devices or to get access to singleton resources.