DEV/material-components_material-components-android
1
0
Fork 0
mirror of https://github.com/material-components/material-components-android.git synced 2026-02-04 13:53:16 +08:00
Code Issues Packages Projects Releases Wiki Activity

[Predictive Back] Minor dev doc edits

Browse Source 
PiperOrigin-RevId: 534176825
This commit is contained in:
dsn5ft 2023-05-22 21:06:31 +00:00 committed by Avigail F
parent 47c307d889
commit 82a91c8455
5 changed files with 98 additions and 118 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

76
docs/components/BottomSheet.md
View File

@ -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:
And then add and enable the back callback as follows:
```java
getOnBackPressedDispatcher().addCallback(this, bottomSheetBackCallback);
```kt
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:
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

12
docs/components/NavigationDrawer.md
View File

@ -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

11
docs/components/Search.md
View File

@ -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

77
docs/components/SideSheet.md
View File

@ -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:
And then add and enable the back callback as follows:
```java
getOnBackPressedDispatcher().addCallback(this, sideSheetBackCallback);
```kt
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;
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

40
docs/foundations/PredictiveBack.md
View File

@ -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)