Skip to content

Commit 2e9b39f

Browse files
afohrmanleticiarossi
authored andcommitted
[Adaptive][Side Sheet] Added modal side sheet documentation.
PiperOrigin-RevId: 494729494
1 parent 88a05f3 commit 2e9b39f

File tree

1 file changed

+122
-14
lines changed

1 file changed

+122
-14
lines changed

docs/components/SideSheet.md

Lines changed: 122 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ See [Bottom Sheet documentation](BottomSheet.md) for documentation about
1919

2020
* [Using side sheets](#using-side-sheets)
2121
* [Standard side sheet](#standard-side-sheet)
22+
* [Modal side sheet](#modal-side-sheet)
2223
* [Anatomy and key properties](#anatomy-and-key-properties)
2324
* [Theming](#theming-side-sheets)
2425

@@ -49,8 +50,8 @@ Standard side sheet basic usage:
4950

5051
### Setting behavior
5152

52-
There are several attributes that can be used to adjust the behavior of
53-
standard side sheets.
53+
There are several attributes that can be used to adjust the behavior of standard
54+
and modal side sheets.
5455

5556
Behavior attributes can be applied to standard side sheets in xml by setting
5657
them on a child `View` set to `app:layout_behavior`, or programmatically:
@@ -84,6 +85,30 @@ sideSheetBehavior.state = Sheet.STATE_HIDDEN
8485

8586
**Note:** `STATE_SETTLING` and `STATE_DRAGGING` should not be set programmatically.
8687

88+
### Listening to state and slide changes
89+
90+
`SideSheetCallback`s can be added to a `SideSheetBehavior` to listen for state
91+
and slide changes:
92+
93+
```kt
94+
val sideSheetCallback = object : SideSheetBehavior.SideSheetCallback() {
95+
96+
override fun onStateChanged(sideSheet: View, newState: Int) {
97+
// Do something for new state.
98+
}
99+
100+
override fun onSlide(sideSheet: View, slideOffset: Float) {
101+
// Do something for slide offset.
102+
}
103+
}
104+
105+
// To add a callback:
106+
sideSheetBehavior.addCallback(sideSheetCallback)
107+
108+
// To remove a callback:
109+
sideSheetBehavior.removeCallback(sideSheetCallback)
110+
```
111+
87112
## Standard side sheet
88113

89114
Standard side sheets co-exist with the screen’s main UI region and allow for
@@ -105,9 +130,6 @@ API and source code:
105130

106131
### Standard side sheet example
107132

108-
The following example shows a standard side sheet in its collapsed and
109-
expanded states:
110-
111133
`SideSheetBehavior` works in tandem with `CoordinatorLayout` to let you
112134
display content in a side sheet, perform enter/exit animations, respond to
113135
dragging/swiping gestures, and more.
@@ -153,9 +175,49 @@ Apply the `SideSheetBehavior` to a direct child `View` of `CoordinatorLayout`:
153175

154176
In this example, the side sheet is the `LinearLayout`.
155177

178+
## Modal side sheet
179+
180+
Modal side sheets present the sheet while blocking interaction with the rest of
181+
the screen. They are an alternative to inline menus and simple dialogs on mobile
182+
devices, providing additional room for content, iconography, and actions.
183+
184+
Modal side sheets render a scrim on the non-side sheet content, to indicate that
185+
they are modal and block interaction with the rest of the screen. If the content
186+
outside of the dialog is tapped, the side sheet is dismissed. Modal side sheets
187+
can be dragged horizontally and dismissed by sliding them off of the screen.
188+
189+
API and source code:
190+
191+
* `SideSheetDialog`
192+
* [Class definition](https://developer.android.com/reference/com/google/android/material/sidesheet/SideSheetDialog.java)
193+
* [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/sidesheet/BottomSheetDialogFragment.java)
194+
195+
### Modal side sheet example
196+
197+
To show a modal side sheet, instantiate a `SideSheetDialog` with the desired
198+
`context`:
199+
200+
```kt
201+
val sideSheetDialog = new SideSheetDialog(requireContext());
202+
```
203+
204+
Then, you can set the content view of the `SideSheetDialog`:
205+
206+
```kt
207+
sideSheetDialog.setContentView(R.layout.side_sheet_content_layout)
208+
```
209+
210+
You can then show the side sheet with `sideSheetDialog.show()` and dismiss it
211+
with `sideSheetDialog.hide()`. `SideSheetDialog` has built in functionality to
212+
automatically cancel the dialog after it is swiped off the screen.
213+
156214
## Anatomy and key properties
157215

158-
Side sheets have a sheet and content.
216+
Side sheets have a sheet, content, and, if modal, a scrim.
217+
218+
1. Sheet
219+
2. Content
220+
3. Scrim (in modal side sheets)
159221

160222
### Sheet attributes
161223

@@ -179,28 +241,74 @@ Behavior | Related method(s)
179241
### Styles
180242

181243
**Element** | **Value**
182-
------------------------- | -------------------------------------------
244+
------------------------- | -----------------------------------------
183245
Standard side sheet style | `@style/Widget.Material3.SideSheet`
246+
Modal side sheet style | `@style/Widget.Material3.SideSheet.Modal`
247+
248+
**Default style theme attribute:`?attr/sideSheetModalStyle`**
184249

185-
Note: There is no default style theme attribute for standard
186-
side sheets, because `SideSheetBehavior`s don't have a designated associated
187-
`View`.
250+
Note: There is no default style theme attribute for standard side sheets,
251+
because `SideSheetBehavior`s don't have a designated associated `View`. Modal
252+
side sheets use `?attr/sideSheetModalStyle` as the default style, but there is
253+
no need to set `?attr/sideSheetModalStyle` on your modal side sheet layout
254+
because the style is automatically applied to the parent `SideSheetDialog`.
188255

189256
See the full list of
190257
[styles](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/sidesheet/res/values/styles.xml),
258+
[attributes](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/sidesheet/res/values/attrs.xml),
191259
and
192-
[attributes](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/sidesheet/res/values/attrs.xml).
260+
[themes and theme overlays](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/sidesheet/res/values/themes.xml).
193261

194262
## Theming side sheets
195263

196264
Side sheets support
197265
[Material Theming](https://material.io/components/sheets-side#theming), which
198-
can customize color and shape.
266+
supports customization of color, shape and more.
199267

200268
### Side sheet theming example
201269

270+
Setting the theme attribute `sideSheetDialogTheme` to your custom `ThemeOverlay`
271+
will affect all side sheets.
272+
273+
In `res/values/themes.xml`:
274+
275+
```xml
276+
<style name="Theme.App" parent="Theme.Material3.*">
277+
...
278+
<item name="sideSheetDialogTheme">@style/ThemeOverlay.App.SideSheetDialog</item>
279+
</style>
280+
281+
<style name="ThemeOverlay.App.SideSheetDialog" parent="ThemeOverlay.Material3.SideSheetDialog">
282+
<item name="sideSheetModalStyle">@style/Widget.App.SideSheet.Modal</item>
283+
</style>
284+
```
285+
286+
In `res/values/styles.xml`:
287+
288+
```xml
289+
<style name="Widget.App.SideSheet.Modal" parent="Widget.Material3.SideSheet.Modal">
290+
<item name="backgroundTint">@color/shrine_pink_light</item>
291+
<item name="shapeAppearance">@style/ShapeAppearance.App.LargeComponent</item>
292+
</style>
293+
294+
<style name="ShapeAppearance.App.LargeComponent" parent="ShapeAppearance.Material3.LargeComponent">
295+
<item name="cornerFamily">cut</item>
296+
<item name="cornerSize">24dp</item>
297+
</style>
298+
```
299+
300+
**Note:** The benefit of using a custom `ThemeOverlay` is that any changes to
301+
your main theme, such as updated colors, will be reflected in the side sheet, as
302+
long as they're not overridden in your custom theme overlay. If you use a custom
303+
`Theme` instead, by extending from one of the
304+
`Theme.Material3.*.SideSheetDialog` variants, you will have more control over
305+
exactly what attributes are included in each, but it also means you'll have to
306+
duplicate any changes that you've made in your main theme into your custom
307+
theme.
308+
202309
API and source code:
203310

204311
* `SideSheetBehavior`
205-
* [Class definition](https://developer.android.com/reference/com/google/android/material/sidesheet/SideSheetBehavior)
206-
* [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/sidesheet/SideSheetBehavior.java)
312+
* [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/sidesheet/SideSheetBehavior.java)
313+
* `SideSheetDialog`
314+
* [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/sidesheet/SideSheetDialog.java)

0 commit comments

Comments
 (0)