Update deprecation documentation for onBackPressed

Add some detail about migrating to OnBackInvokedDispatcher and the
reason behing the deprecation of onBackPressed methods.

Fixes: 227563202
Test: Documentation change only
Change-Id: Ifc2dd88cb9600efae84cd353549811e7b07ae4bc

2 files changed, 38 insertions, 2 deletions

diff --git a/core/java/android/app/Activity.java b/core/java/android/app/Activity.java
index acdab1b97599..ae16e01b7788 100644
--- a/core/java/android/app/Activity.java
+++ b/core/java/android/app/Activity.java
@@ -3925,15 +3925,32 @@ public class Activity extends ContextThemeWrapper
      *         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
+     *      <li><p>If you target version {@link android.os.Build.VERSION_CODES#S} and
+     *         override this method, we strongly recommend to call through to the superclass
      *         implementation after you finish handling navigation within the app.
+     *
+     *      <li><p>If you target version {@link android.os.Build.VERSION_CODES#TIRAMISU} or later,
+     *          you should not use this method but register an {@link OnBackInvokedCallback} on an
+     *          {@link OnBackInvokedDispatcher} that you can retrieve using
+     *          {@link #getOnBackInvokedDispatcher()}. You should also set
+     *          {@code android:enableOnBackInvokedCallback="true"} in the application manifest.
+     *          <p>Alternatively, you can use
+     *          {@code  androidx.activity.ComponentActivity#getOnBackPressedDispatcher()}
+     *          for backward compatibility.
      * </ul>
      *
      * @see #moveTaskToBack(boolean)
      *
      * @deprecated Use {@link OnBackInvokedCallback} or
      * {@code androidx.activity.OnBackPressedCallback} to handle back navigation instead.
+     * <p>
+     * Starting from Android 13 (API level 33), back event handling is
+     * moving to an ahead-of-time model and {@link Activity#onBackPressed()} and
+     * {@link KeyEvent#KEYCODE_BACK} should not be used to handle back events (back gesture or
+     * back button click). Instead, an {@link OnBackInvokedCallback} should be registered using
+     * {@link Activity#getOnBackInvokedDispatcher()}
+     * {@link OnBackInvokedDispatcher#registerOnBackInvokedCallback(int, OnBackInvokedCallback)
+     * .registerOnBackInvokedCallback(priority, callback)}.
      */
     @Deprecated
     public void onBackPressed() {
diff --git a/core/java/android/app/Dialog.java b/core/java/android/app/Dialog.java
index f0af9bad2864..33cf71256d51 100644
--- a/core/java/android/app/Dialog.java
+++ b/core/java/android/app/Dialog.java
@@ -720,8 +720,27 @@ public class Dialog implements DialogInterface, Window.Callback,
      * key.  The default implementation simply cancels the dialog (only if
      * it is cancelable), but you can override this to do whatever you want.
      *
+     * <p>
+     * If you target version {@link android.os.Build.VERSION_CODES#TIRAMISU} or later, you
+     * should not use this method but register an {@link OnBackInvokedCallback} on an
+     * {@link OnBackInvokedDispatcher} that you can retrieve using
+     * {@link #getOnBackInvokedDispatcher()}. You should also set
+     * {@code android:enableOnBackInvokedCallback="true"} in the application manifest.
+     *
+     * <p>Alternatively, you
+     * can use {@code androidx.activity.ComponentDialog#getOnBackPressedDispatcher()}
+     * for backward compatibility.
+     *
      * @deprecated Use {@link OnBackInvokedCallback} or
      * {@code androidx.activity.OnBackPressedCallback} to handle back navigation instead.
+     * <p>
+     * Starting from Android 13 (API level 33), back event handling is
+     * moving to an ahead-of-time model and {@link #onBackPressed()} and
+     * {@link KeyEvent#KEYCODE_BACK} should not be used to handle back events (back gesture or
+     * back button click). Instead, an {@link OnBackInvokedCallback} should be registered using
+     * {@link Dialog#getOnBackInvokedDispatcher()}
+     * {@link OnBackInvokedDispatcher#registerOnBackInvokedCallback(int, OnBackInvokedCallback)
+     * .registerOnBackInvokedCallback(priority, callback)}.
      */
     @Deprecated
     public void onBackPressed() {