[Predictive Back] Minor dev doc edits

PiperOrigin-RevId: 534176825
material-components · May 24, 2023 · 82a91c8 · 82a91c8
1 parent 47c307d
commit 82a91c8
Show file tree

Hide file tree

Showing 5 changed files with 102 additions and 122 deletions.
diff --git a/docs/components/BottomSheet.md b/docs/components/BottomSheet.md
@@ -471,77 +471,65 @@ and
 
 ## Predictive Back
 
-The modal `BottomSheetDialogFragment` and `BottomSheetDialog` components
-automatically support [Predictive Back](../foundations/PredictiveBack.md) by
-default.
+### Modal Bottom Sheets
 
-No further integration is required on the app side other than the general
+The modal `BottomSheetDialogFragment` and `BottomSheetDialog` components
+automatically support [Predictive Back](../foundations/PredictiveBack.md). No
+further integration is required on the app side other than the general
 Predictive Back prerequisites and migration steps mentioned
 [here](../foundations/PredictiveBack.md#usage).
 
 Visit the
 [Predictive Back design guidelines](https://m3.material.io/components/bottom-sheets/guidelines#3d7735e2-73ea-4f3e-bd42-e70161fc1085)
-to see how the component will behave when a user swipes back.
+to see how the component behaves when a user swipes back.
+
+### Standard (Non-Modal) Bottom Sheets
 
 To set up Predictive Back for standard (non-modal) bottom sheets using
-`BottomSheetBehavior`, you can create an AndroidX back callback that forwards
-the system `BackEvent` objects to your `BottomSheetBehavior`:
+`BottomSheetBehavior`, create an AndroidX back callback that forwards the system
+`BackEvent` objects to your `BottomSheetBehavior`:
 
-```java
-OnBackPressedCallback bottomSheetBackCallback = new OnBackPressedCallback(/* enabled= */ false) {
+```kt
+val bottomSheetBackCallback = object : OnBackPressedCallback(/* enabled= */false) {
   @RequiresApi(VERSION_CODES.UPSIDE_DOWN_CAKE)
-  @Override
-  public void handleOnBackStarted(@NonNull BackEvent backEvent) {
-    bottomSheetBehavior.startBackProgress(backEvent);
+  override fun handleOnBackStarted(backEvent: BackEvent) {
+    bottomSheetBehavior.startBackProgress(backEvent)
   }
 
   @RequiresApi(VERSION_CODES.UPSIDE_DOWN_CAKE)
-  @Override
-  public void handleOnBackProgressed(@NonNull BackEvent backEvent) {
-    bottomSheetBehavior.updateBackProgress(backEvent);
+  override fun handleOnBackProgressed(backEvent: BackEvent) {
+    bottomSheetBehavior.updateBackProgress(backEvent)
   }
 
-  @Override
-  public void handleOnBackPressed() {
-    bottomSheetBehavior.handleBackInvoked();
+  override fun handleOnBackPressed() {
+    bottomSheetBehavior.handleBackInvoked()
   }
 
   @RequiresApi(VERSION_CODES.UPSIDE_DOWN_CAKE)
-  @Override
-  public void handleOnBackCancelled() {
-    bottomSheetBehavior.cancelBackProgress();
+  override fun handleOnBackCancelled() {
+    bottomSheetBehavior.cancelBackProgress()
   }
-};
+}
 ```
 
-And then you can add and enable the back callback as follows:
-
-```java
-getOnBackPressedDispatcher().addCallback(this, bottomSheetBackCallback);
-
-bottomSheetBehavior.addBottomSheetCallback(new BottomSheetCallback() {
-  @Override
-  public void onStateChanged(@NonNull View bottomSheet, int newState) {
-    switch (newState) {
-      case BottomSheetBehavior.STATE_EXPANDED:
-      case BottomSheetBehavior.STATE_HALF_EXPANDED:
-        bottomSheetBackCallback.setEnabled(true);
-        break;
-      case BottomSheetBehavior.STATE_COLLAPSED:
-      case BottomSheetBehavior.STATE_HIDDEN:
-        bottomSheetBackCallback.setEnabled(false);
-        break;
-      case BottomSheetBehavior.STATE_DRAGGING:
-      case BottomSheetBehavior.STATE_SETTLING:
-      default:
+And then add and enable the back callback as follows:
+
+```kt
+getOnBackPressedDispatcher().addCallback(this, bottomSheetBackCallback)
+
+bottomSheetBehavior.addBottomSheetCallback(object : BottomSheetCallback() {
+  override fun onStateChanged(bottomSheet: View, newState: Int) {
+    when (newState) {
+      STATE_EXPANDED, STATE_HALF_EXPANDED -> bottomSheetBackCallback.setEnabled(true)
+      STATE_COLLAPSED, STATE_HIDDEN -> bottomSheetBackCallback.setEnabled(false)
+      else -> {
         // Do nothing, only change callback enabled for "stable" states.
-        break;
+      }
     }
   }
 
-  @Override
-  public void onSlide(@NonNull View bottomSheet, float slideOffset) {}
-});
+  override fun onSlide(bottomSheet: View, slideOffset: Float) {}
+})
 ```
 
 ## Theming bottom sheets

diff --git a/docs/components/NavigationDrawer.md b/docs/components/NavigationDrawer.md
@@ -601,16 +601,14 @@ For more information on bottom app bars see the
 ## Predictive Back
 
 The `NavigationView` component automatically supports
-[Predictive Back](../foundations/PredictiveBack.md) by default when it is set up
-within a `DrawerLayout`, as mentioned in the sections above.
-
-No further integration is required on the app side other than the general
-Predictive Back prerequisites and migration steps mentioned
-[here](../foundations/PredictiveBack.md#usage).
+[Predictive Back](../foundations/PredictiveBack.md) when it is set up within a
+`DrawerLayout`, as mentioned in the sections above. No further integration is
+required on the app side other than the general Predictive Back prerequisites
+and migration steps mentioned [here](../foundations/PredictiveBack.md#usage).
 
 Visit the
 [Predictive Back design guidelines](https://m3.material.io/components/side-sheets/guidelines#d77245e3-1013-48f8-a9d7-76f484e1be13)
-to see how the component will behave when a user swipes back.
+to see how the component behaves when a user swipes back.
 
 ## Theming
 

diff --git a/docs/components/Search.md b/docs/components/Search.md
@@ -354,16 +354,15 @@ method to achieve the same result.
 ## Predictive Back
 
 The `SearchView` component automatically supports
-[Predictive Back](../foundations/PredictiveBack.md) by default when it is set up
-with and connected to a `SearchBar`, as mentioned in the sections above.
-
-No further integration is required on the app side other than the general
-Predictive Back prerequisites and migration steps mentioned
+[Predictive Back](../foundations/PredictiveBack.md) when it is set up with and
+connected to a `SearchBar`, as mentioned in the sections above. No further
+integration is required on the app side other than the general Predictive Back
+prerequisites and migration steps mentioned
 [here](../foundations/PredictiveBack.md#usage).
 
 Visit the
 [Predictive Back design guidelines](https://m3.material.io/components/search/guidelines#3f2d4e47-2cf5-4c33-b6e1-5368ceaade55)
-to see how the component will behave when a user swipes back.
+to see how the component behaves when a user swipes back.
 
 ## API and source code
 

diff --git a/docs/components/SideSheet.md b/docs/components/SideSheet.md
@@ -299,73 +299,64 @@ and
 
 ## Predictive Back
 
-The modal `SideSheetDialog` component automatically supports
-[Predictive Back](../foundations/PredictiveBack.md) by default.
+### Modal Side Sheets
 
-No further integration is required on the app side other than the general
-Predictive Back prerequisites and migration steps mentioned
-[here](../foundations/PredictiveBack.md#usage).
+The modal `SideSheetDialog` component automatically supports
+[Predictive Back](../foundations/PredictiveBack.md). No further integration is
+required on the app side other than the general Predictive Back prerequisites
+and migration steps mentioned [here](../foundations/PredictiveBack.md#usage).
 
 Visit the
 [Predictive Back design guidelines](https://m3.material.io/components/side-sheets/guidelines#d77245e3-1013-48f8-a9d7-76f484e1be13)
-to see how the component will behave when a user swipes back.
+to see how the component behaves when a user swipes back.
+
+### Standard and Coplanar (Non-Modal) Side Sheets
 
 To set up Predictive Back for standard or coplanar (non-modal) side sheets using
-`SideSheetBehavior`, you can create an AndroidX back callback that forwards
-the system `BackEvent` objects to your `SideSheetBehavior`:
+`SideSheetBehavior`, create an AndroidX back callback that forwards the system
+`BackEvent` objects to your `SideSheetBehavior`:
 
-```java
-OnBackPressedCallback sideSheetBackCallback = new OnBackPressedCallback(/* enabled= */ false) {
+```kt
+val sideSheetBackCallback = object : OnBackPressedCallback(/* enabled= */false) {
   @RequiresApi(VERSION_CODES.UPSIDE_DOWN_CAKE)
-  @Override
-  public void handleOnBackStarted(@NonNull BackEvent backEvent) {
-    sideSheetBehavior.startBackProgress(backEvent);
+  override fun handleOnBackStarted(backEvent: BackEvent) {
+    sideSheetBehavior.startBackProgress(backEvent)
   }
 
   @RequiresApi(VERSION_CODES.UPSIDE_DOWN_CAKE)
-  @Override
-  public void handleOnBackProgressed(@NonNull BackEvent backEvent) {
-    sideSheetBehavior.updateBackProgress(backEvent);
+  override fun handleOnBackProgressed(backEvent: BackEvent) {
+    sideSheetBehavior.updateBackProgress(backEvent)
   }
 
-  @Override
-  public void handleOnBackPressed() {
-    sideSheetBehavior.handleBackInvoked();
+  override fun handleOnBackPressed() {
+    sideSheetBehavior.handleBackInvoked()
   }
 
   @RequiresApi(VERSION_CODES.UPSIDE_DOWN_CAKE)
-  @Override
-  public void handleOnBackCancelled() {
-    sideSheetBehavior.cancelBackProgress();
+  override fun handleOnBackCancelled() {
+    sideSheetBehavior.cancelBackProgress()
   }
-};
+}
 ```
 
-And then you can add and enable the back callback as follows:
-
-```java
-getOnBackPressedDispatcher().addCallback(this, sideSheetBackCallback);
-
-sideSheetBehavior.addCallback(new SideSheetCallback() {
-  @Override
-  public void onStateChanged(@NonNull View sideSheet, int newState) {
-    switch (newState) {
-      case SideSheetBehavior.STATE_EXPANDED:
-      case SideSheetBehavior.STATE_SETTLING:
-        sideSheetBackCallback.setEnabled(true);
-        break;
-      case SideSheetBehavior.STATE_HIDDEN:
-        sideSheetBackCallback.setEnabled(false);
-        break;
-      case SideSheetBehavior.STATE_DRAGGING:
-      default:
-        break;
+And then add and enable the back callback as follows:
+
+```kt
+getOnBackPressedDispatcher().addCallback(this, sideSheetBackCallback)
+
+sideSheetBehavior.addCallback(object : SideSheetCallback() {
+  override fun onStateChanged(sideSheet: View, newState: Int) {
+    when (newState) {
+      STATE_EXPANDED, STATE_SETTLING -> sideSheetBackCallback.setEnabled(true)
+      STATE_HIDDEN -> sideSheetBackCallback.setEnabled(false)
+      else -> {
+        // Do nothing, only change callback enabled for above states.
+      }
     }
   }
 
-  @Override
-  public void onSlide(@NonNull View sideSheet, float slideOffset) {}
-});
+  override fun onSlide(sideSheet: View, slideOffset: Float) {}
+})
 ```
 
 ## Theming side sheets

diff --git a/docs/foundations/PredictiveBack.md b/docs/foundations/PredictiveBack.md
@@ -14,12 +14,13 @@ the user a glimpse of where swiping back will bring them. Before completing a
 swipe, the user can decide to continue to the previous view or stay in the
 current view.
 
-In Android T (13), the OS introduced support for predictive back-to-home, which
-shows the user a preview of the home screen when swiping back to exit an app.
+In Android 13 (T / API level 33), the OS introduced support for predictive
+back-to-home, which shows the user a preview of the home screen when swiping
+back to exit an app.
 
-With Android U (14), the OS adds support for in-app predictive back, which apps
-can take advantage of to show the user previous destinations when swiping back
-within the app itself.
+With Android 14 (U / API level 34), the OS adds support for in-app predictive
+back, which apps can take advantage of to show the user previous destinations
+when swiping back within the app itself.
 
 ## Design & API documentation
 
@@ -28,17 +29,6 @@ within the app itself.
 -   [Framework & AndroidX Predictive Back developer guide](https://developer.android.com/guide/navigation/predictive-back-gesture)
 -   [Android 14 Predictive Back developer guide](https://developer.android.com/about/versions/14/features/predictive-back)
 
-## Talks
-
--   [What's New in Android (Google I/O 2023)](https://youtu.be/qXhjN66O7Bk?t=1193)
--   [What's New in Material Design (Google I/O 2023)](https://youtu.be/vnDhq8W98O4?t=156)
--   [Building for the Future of Android (Google I/O 2023)](https://www.youtube.com/watch?v=WMMPXayjP8g&t=333s)
-
-## Blog Posts
-
--   [Second Beta of Android 14](https://android-developers.googleblog.com/2023/05/android-14-beta-2.html)
--   [Google I/O 2023: What's new in Jetpack](https://android-developers.googleblog.com/2023/05/whats-new-in-jetpack-io-2023.html)
-
 ## Usage
 
 To opt in to predictive back, apps must:
@@ -67,5 +57,19 @@ animations:
 - [Bottom sheet](../components/BottomSheet.md#predictive-back) (automatically for modal, standard requires integration)
 - [Side sheet](../components/SideSheet.md#predictive-back) (automatically for modal, standard and coplanar require integration)
 - [Navigation drawer](../components/NavigationDrawer.md#predictive-back) (automatically for `NavigationView` within `DrawerLayout`)
-- Navigation bar / Bottom navigation view (support coming soon)
-- Navigation rail (support coming soon)
+
+Future predictive back support is planned for the following Material Components:
+
+- Navigation bar / Bottom navigation view
+- Navigation rail
+
+## Talks
+
+-   [What's New in Android (Google I/O 2023)](https://youtu.be/qXhjN66O7Bk?t=1193)
+-   [What's New in Material Design (Google I/O 2023)](https://youtu.be/vnDhq8W98O4?t=156)
+-   [Building for the Future of Android (Google I/O 2023)](https://www.youtube.com/watch?v=WMMPXayjP8g&t=333s)
+
+## Blog Posts
+
+-   [Second Beta of Android 14](https://android-developers.googleblog.com/2023/05/android-14-beta-2.html)
+-   [Google I/O 2023: What's new in Jetpack](https://android-developers.googleblog.com/2023/05/whats-new-in-jetpack-io-2023.html)