From a88a2503ae787c379b2320cff256e5558025ac65 Mon Sep 17 00:00:00 2001 From: Chris Bobbe Date: Fri, 6 Oct 2023 19:45:24 -0700 Subject: [PATCH] bottom_sheet: Clarify doc about behavior when useSafeArea is false (#134793) As discussed at https://github.com/flutter/flutter/pull/122225#issuecomment-1690729628, this is a docs change meant to help people in the absence of a fix for #121752, which is being closed as WONTFIX. --- .../flutter/lib/src/material/bottom_sheet.dart | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/packages/flutter/lib/src/material/bottom_sheet.dart b/packages/flutter/lib/src/material/bottom_sheet.dart index 75f8b3e779..6e9c9a523d 100644 --- a/packages/flutter/lib/src/material/bottom_sheet.dart +++ b/packages/flutter/lib/src/material/bottom_sheet.dart @@ -792,8 +792,10 @@ class _ModalBottomSheetState extends State<_ModalBottomSheet> { /// dragged up and down and dismissed by swiping downwards. /// /// The [useSafeArea] parameter specifies whether the sheet will avoid system -/// intrusions on the top, left, and right. If false, no SafeArea is added -/// and the top padding is consumed using [MediaQuery.removePadding]. +/// intrusions on the top, left, and right. If false, no [SafeArea] is added; +/// and [MediaQuery.removePadding] is applied to the top, +/// so that system intrusions at the top will not be avoided by a [SafeArea] +/// inside the bottom sheet either. /// Defaults to false. /// /// The optional [backgroundColor], [elevation], [shape], [clipBehavior], @@ -979,8 +981,14 @@ class ModalBottomSheetRoute extends PopupRoute { /// If true, a [SafeArea] is inserted to keep the bottom sheet away from /// system intrusions at the top, left, and right sides of the screen. /// - /// If false, the bottom sheet isn't exposed to the top padding of the - /// MediaQuery. + /// If false, the bottom sheet will extend through any system intrusions + /// at the top, left, and right. + /// + /// If false, then moreover [MediaQuery.removePadding] will be used + /// to remove top padding, so that a [SafeArea] widget inside the bottom + /// sheet will have no effect at the top edge. If this is undesired, consider + /// setting [useSafeArea] to true. Alternatively, wrap the [SafeArea] in a + /// [MediaQuery] that restates an ambient [MediaQueryData] from outside [builder]. /// /// In either case, the bottom sheet extends all the way to the bottom of /// the screen, including any system intrusions.