From c257fb9ee120c51867eb953dd59c9d0edcf322d1 Mon Sep 17 00:00:00 2001
From: Prabir Pradhan <prabirmsp@google.com>
Date: Tue, 8 Jun 2021 14:26:21 -0700
Subject: [PATCH] Update docs for onBackPressed

After changing the default behavior of the back button in S, we should
update the javadocs to reflect the change.

We also make a recommendation for developers to call through to the
super implementation to maintain consistency in navigation patterns
throughout the platform, especially for things like splash screens.

Bug: 186142540
Bug: 188832670
Test: None
Change-Id: I1c71250b26bec743be15f4ac95965ef046dcf4f3
---
 core/java/android/app/Activity.java | 23 ++++++++++++++++++++---
 1 file changed, 20 insertions(+), 3 deletions(-)

diff --git a/core/java/android/app/Activity.java b/core/java/android/app/Activity.java
index 854c9f2a5b3ab..db5dcc5c264bd 100644
--- a/core/java/android/app/Activity.java
+++ b/core/java/android/app/Activity.java
@@ -3866,9 +3866,26 @@ public class Activity extends ContextThemeWrapper
     }
 
     /**
-     * Called when the activity has detected the user's press of the back
-     * key.  The default implementation simply finishes the current activity,
-     * but you can override this to do whatever you want.
+     * Called when the activity has detected the user's press of the back key. The default
+     * implementation depends on the platform version:
+     *
+     * <ul>
+     *     <li>On platform versions prior to {@link android.os.Build.VERSION_CODES#S}, it
+     *         finishes the current activity, but you can override this to do whatever you want.
+     *
+     *     <li><p>Starting with platform version {@link android.os.Build.VERSION_CODES#S}, for
+     *         activities that are the root activity of the task and also declare an
+     *         {@link android.content.IntentFilter} with {@link Intent#ACTION_MAIN} and
+     *         {@link Intent#CATEGORY_LAUNCHER} in the manifest, the current activity and its
+     *         task will be moved to the back of the activity stack instead of being finished.
+     *         Other activities will simply be finished.
+     *
+     *         <p>If you target version {@link android.os.Build.VERSION_CODES#S} or later and
+     *         override this method, it is strongly recommended to call through to the superclass
+     *         implementation after you finish handling navigation within the app.
+     * </ul>
+     *
+     * @see #moveTaskToBack(boolean)
      */
     public void onBackPressed() {
         if (mActionBar != null && mActionBar.collapseActionView()) {