@@ -19,6 +19,7 @@ See [Bottom Sheet documentation](BottomSheet.md) for documentation about
19
19
20
20
* [ Using side sheets] ( #using-side-sheets )
21
21
* [ Standard side sheet] ( #standard-side-sheet )
22
+ * [ Modal side sheet] ( #modal-side-sheet )
22
23
* [ Anatomy and key properties] ( #anatomy-and-key-properties )
23
24
* [ Theming] ( #theming-side-sheets )
24
25
@@ -49,8 +50,8 @@ Standard side sheet basic usage:
49
50
50
51
### Setting behavior
51
52
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.
54
55
55
56
Behavior attributes can be applied to standard side sheets in xml by setting
56
57
them on a child ` View ` set to ` app:layout_behavior ` , or programmatically:
@@ -84,6 +85,30 @@ sideSheetBehavior.state = Sheet.STATE_HIDDEN
84
85
85
86
** Note:** ` STATE_SETTLING ` and ` STATE_DRAGGING ` should not be set programmatically.
86
87
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
+
87
112
## Standard side sheet
88
113
89
114
Standard side sheets co-exist with the screen’s main UI region and allow for
@@ -105,9 +130,6 @@ API and source code:
105
130
106
131
### Standard side sheet example
107
132
108
- The following example shows a standard side sheet in its collapsed and
109
- expanded states:
110
-
111
133
` SideSheetBehavior ` works in tandem with ` CoordinatorLayout ` to let you
112
134
display content in a side sheet, perform enter/exit animations, respond to
113
135
dragging/swiping gestures, and more.
@@ -153,9 +175,49 @@ Apply the `SideSheetBehavior` to a direct child `View` of `CoordinatorLayout`:
153
175
154
176
In this example, the side sheet is the ` LinearLayout ` .
155
177
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
+
156
214
## Anatomy and key properties
157
215
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)
159
221
160
222
### Sheet attributes
161
223
@@ -179,28 +241,74 @@ Behavior | Related method(s)
179
241
### Styles
180
242
181
243
** Element** | ** Value**
182
- ------------------------- | -------------------------------------------
244
+ ------------------------- | -----------------------------------------
183
245
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 ` **
184
249
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 ` .
188
255
189
256
See the full list of
190
257
[ 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 ) ,
191
259
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 ) .
193
261
194
262
## Theming side sheets
195
263
196
264
Side sheets support
197
265
[ Material Theming] ( https://material.io/components/sheets-side#theming ) , which
198
- can customize color and shape .
266
+ supports customization of color, shape and more .
199
267
200
268
### Side sheet theming example
201
269
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
+
202
309
API and source code:
203
310
204
311
* ` 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