Replace child parameter with builder on showDialog (#15303)

* replace child parameter with builder on showDialog

* change builder parameter to WidgetBuilder

* mark child as deprecated and expand documentation to cover this and how builder should be used

* tidy comments and address some feedback

* phrasing

* move space to prev line and add //ignore comments for deprecated member use

* address comments and fix it's its

* update code samples

* adds semicolon to code snippets

examples/flutter_gallery/lib/demo/cupertino/cupertino_dialog_demo.dart

@@ -18,8 +18,8 @@ class _CupertinoDialogDemoState extends State<CupertinoDialogDemo> {
   void showDemoDialog<T>({ BuildContext context, Widget child }) {
     showDialog<T>(
       context: context,
-      child: child,
       barrierDismissible: false,
+      builder: (BuildContext context) => child,
     )
     .then<Null>((T value) { // The value passed to Navigator.pop() or null.
       if (value != null) {

examples/flutter_gallery/lib/demo/material/dialog_demo.dart

@@ -68,7 +68,7 @@ class DialogDemoState extends State<DialogDemo> {
   void showDemoDialog<T>({ BuildContext context, Widget child }) {
     showDialog<T>(
       context: context,
-      child: child,
+      builder: (BuildContext context) => child,
     )
     .then<Null>((T value) { // The value passed to Navigator.pop() or null.
       if (value != null) {

examples/flutter_gallery/lib/demo/material/drawer_demo.dart

@@ -233,7 +233,8 @@ class _DrawerDemoState extends State<DrawerDemo> with TickerProviderStateMixin {
   void _onOtherAccountsTap(BuildContext context) {
     showDialog<Null>(
       context: context,
-      child: new AlertDialog(
+      builder: (BuildContext context) {
+        return new AlertDialog(
           title: const Text('Account switching not implemented.'),
           actions: <Widget>[
             new FlatButton(
@@ -243,7 +244,8 @@ class _DrawerDemoState extends State<DrawerDemo> with TickerProviderStateMixin {
               },
             ),
           ],
-      ),
+        );
+      },
     );
   }
 }

examples/flutter_gallery/lib/demo/material/full_screen_dialog_demo.dart

@@ -116,7 +116,8 @@ class FullScreenDialogDemoState extends State<FullScreenDialogDemo> {
 
     return await showDialog<bool>(
       context: context,
-      child: new AlertDialog(
+      builder: (BuildContext context) {
+        return new AlertDialog(
           content: new Text(
             'Discard new event?',
             style: dialogTextStyle
@@ -134,8 +135,9 @@ class FullScreenDialogDemoState extends State<FullScreenDialogDemo> {
                 Navigator.of(context).pop(true); // Returning true to _onWillPop will pop again.
               }
             )
-        ]
-      )
+          ],
+        );
+      },
     ) ?? false;
   }
 

examples/flutter_gallery/lib/demo/material/persistent_bottom_sheet_demo.dart

@@ -56,15 +56,19 @@ class _PersistentBottomSheetDemoState extends State<PersistentBottomSheetDemo> {
   void _showMessage() {
     showDialog<Null>(
       context: context,
-      child: new AlertDialog(
+      builder: (BuildContext context) {
+        return new AlertDialog(
           content: const Text('You tapped the floating action button.'),
           actions: <Widget>[
             new FlatButton(
-            onPressed: () { Navigator.pop(context); },
+              onPressed: () {
+                Navigator.pop(context);
+              },
               child: const Text('OK')
             )
-        ]
-      )
+          ],
+        );
+      },
     );
   }
 

examples/flutter_gallery/lib/demo/material/text_form_field_demo.dart

@@ -85,7 +85,8 @@ class TextFormFieldDemoState extends State<TextFormFieldDemo> {
 
     return await showDialog<bool>(
       context: context,
-      child: new AlertDialog(
+      builder: (BuildContext context) {
+        return new AlertDialog(
           title: const Text('This form has errors'),
           content: const Text('Really leave this form?'),
           actions: <Widget> [
@@ -98,7 +99,8 @@ class TextFormFieldDemoState extends State<TextFormFieldDemo> {
               onPressed: () { Navigator.of(context).pop(false); },
             ),
           ],
-      ),
+        );
+      },
     ) ?? false;
   }
 

examples/flutter_gallery/lib/gallery/updates.dart

@@ -41,13 +41,13 @@ class UpdaterState extends State<Updater> {
 
     final String updateUrl = await widget.updateUrlFetcher();
     if (updateUrl != null) {
-      final bool wantsUpdate = await showDialog(context: context, child: _buildDialog());
+      final bool wantsUpdate = await showDialog(context: context, builder: _buildDialog);
       if (wantsUpdate != null && wantsUpdate)
         launch(updateUrl);
     }
   }
 
-  Widget _buildDialog() {
+  Widget _buildDialog(BuildContext _) {
     final ThemeData theme = Theme.of(context);
     final TextStyle dialogTextStyle =
         theme.textTheme.subhead.copyWith(color: theme.textTheme.caption.color);

examples/stocks/lib/stock_home.dart

@@ -95,7 +95,7 @@ class StockHomeState extends State<StockHome> {
       case _StockMenuItem.refresh:
         showDialog<Null>(
           context: context,
-          child: new _NotImplementedDialog()
+          builder: (BuildContext context) => new _NotImplementedDialog(),
         );
         break;
       case _StockMenuItem.speedUp:

examples/stocks/lib/stock_settings.dart

@@ -67,7 +67,8 @@ class StockSettingsState extends State<StockSettings> {
       case StockMode.pessimistic:
         showDialog<bool>(
           context: context,
-          child: new AlertDialog(
+           builder: (BuildContext context) {
+            return new AlertDialog(
               title: const Text('Change mode?'),
               content: const Text('Optimistic mode means everything is awesome. Are you sure you can handle that?'),
               actions: <Widget>[
@@ -83,8 +84,9 @@ class StockSettingsState extends State<StockSettings> {
                     Navigator.pop(context, true);
                   }
                 ),
-            ]
-          )
+              ],
+            );
+          },
         ).then<void>(_handleOptimismChanged);
         break;
     }

packages/flutter/lib/src/material/about.dart

@@ -153,13 +153,15 @@ void showAboutDialog({
 }) {
   showDialog<Null>(
     context: context,
-    child: new AboutDialog(
+    builder: (BuildContext context) {
+      return new AboutDialog(
         applicationName: applicationName,
         applicationVersion: applicationVersion,
         applicationIcon: applicationIcon,
         applicationLegalese: applicationLegalese,
-      children: children
-    )
+        children: children,
+      );
+    }
   );
 }
 

packages/flutter/lib/src/material/date_picker.dart

@@ -1042,6 +1042,6 @@ Future<DateTime> showDatePicker({
 
   return await showDialog<DateTime>(
     context: context,
-    child: child,
+    builder: (BuildContext context) => child,
   );
 }

packages/flutter/lib/src/material/dialog.dart

@@ -96,7 +96,8 @@ class Dialog extends StatelessWidget {
 ///   return showDialog<Null>(
 ///     context: context,
 ///     barrierDismissible: false, // user must tap button!
-///     child: new AlertDialog(
+///     builder: (BuildContext context) {
+///       return new AlertDialog(
 ///         title: new Text('Rewind and remember'),
 ///         content: new SingleChildScrollView(
 ///           child: new ListBody(
@@ -114,7 +115,8 @@ class Dialog extends StatelessWidget {
 ///             },
 ///           ),
 ///         ],
-///     ),
+///       );
+///     },
 ///   );
 /// }
 /// ```
@@ -301,7 +303,8 @@ class SimpleDialogOption extends StatelessWidget {
 /// Future<Null> _askedToLead() async {
 ///   switch (await showDialog<Department>(
 ///     context: context,
-///     child: new SimpleDialog(
+///     builder: (BuildContext context) {
+///       return new SimpleDialog(
 ///         title: const Text('Select assignment'),
 ///         children: <Widget>[
 ///           new SimpleDialogOption(
@@ -313,7 +316,8 @@ class SimpleDialogOption extends StatelessWidget {
 ///             child: const Text('State department'),
 ///           ),
 ///         ],
-///     ),
+///       );
+///     }
 ///   )) {
 ///     case Department.treasury:
 ///       // Let's go.
@@ -457,13 +461,18 @@ class _DialogRoute<T> extends PopupRoute<T> {
 
 /// Displays a dialog above the current contents of the app.
 ///
-/// This function typically receives a [Dialog] widget as its child argument.
-/// Content below the dialog is dimmed with a [ModalBarrier].
+/// This function takes a `builder` which typically builds a [Dialog] widget.
+/// Content below the dialog is dimmed with a [ModalBarrier]. This widget does
+/// not share a context with the location that `showDialog` is originally
+/// called from. Use a [StatefulBuilder] or a custom [StatefulWidget] if the
+/// dialog needs to update dynamically.
 ///
 /// The `context` argument is used to look up the [Navigator] and [Theme] for
 /// the dialog. It is only used when the method is called. Its corresponding
 /// widget can be safely removed from the tree before the dialog is closed.
 ///
+/// The `child` argument is deprecated, and should be replaced with `builder`.
+///
 /// Returns a [Future] that resolves to the value (if any) that was passed to
 /// [Navigator.pop] when the dialog was closed.
 ///
@@ -481,10 +490,16 @@ class _DialogRoute<T> extends PopupRoute<T> {
 Future<T> showDialog<T>({
   @required BuildContext context,
   bool barrierDismissible: true,
-  @required Widget child,
+  @Deprecated(
+    'Instead of using the "child" argument, return the child from a closure '
+    'provided to the "builder" argument. This will ensure that the BuildContext '
+    'is appropriate for widgets built in the dialog.'
+  ) Widget child,
+  WidgetBuilder builder,
 }) {
+  assert(child == null || builder == null); // ignore: deprecated_member_use
   return Navigator.of(context, rootNavigator: true).push(new _DialogRoute<T>(
-    child: child,
+    child: child ?? new Builder(builder: builder), // ignore: deprecated_member_use
     theme: Theme.of(context, shadowThemeOnly: true),
     barrierDismissible: barrierDismissible,
     barrierLabel: MaterialLocalizations.of(context).modalBarrierDismissLabel,

packages/flutter/lib/src/material/time_picker.dart

@@ -1645,7 +1645,7 @@ Future<TimeOfDay> showTimePicker({
 
   return await showDialog<TimeOfDay>(
     context: context,
-    child: new _TimePickerDialog(initialTime: initialTime),
+    builder: (BuildContext context) => new _TimePickerDialog(initialTime: initialTime),
   );
 }
 

packages/flutter/test/cupertino/dialog_test.dart

@@ -19,7 +19,8 @@ void main() {
                 onPressed: () {
                   showDialog<Null>(
                     context: context,
-                    child: new CupertinoAlertDialog(
+                    builder: (BuildContext context) {
+                      return new CupertinoAlertDialog(
                         title: const Text('The title'),
                         content: const Text('The content'),
                         actions: <Widget>[
@@ -35,7 +36,8 @@ void main() {
                             child: const Text('Delete'),
                           ),
                         ],
-                    ),
+                      );
+                    },
                   );
                 },
                 child: const Text('Go'),
@@ -110,7 +112,7 @@ void main() {
               onPressed: () {
                 showDialog<Null>(
                   context: context,
-                  child: new Builder(builder: (BuildContext context) {
+                  builder: (BuildContext context) {
                     return new MediaQuery(
                       data: MediaQuery.of(context).copyWith(textScaleFactor: 3.0),
                       child: new CupertinoAlertDialog(
@@ -128,7 +130,7 @@ void main() {
                         scrollController: scrollController,
                       ),
                     );
-                  }),
+                  },
                 );
               },
               child: const Text('Go'),

packages/flutter/test/material/dialog_test.dart

@@ -23,7 +23,8 @@ void main() {
                   onPressed: () {
                     showDialog<Null>(
                       context: context,
-                      child: new AlertDialog(
+                      builder: (BuildContext context) {
+                        return new AlertDialog(
                           content: new Container(
                             height: 5000.0,
                             width: 300.0,
@@ -36,8 +37,9 @@ void main() {
                               },
                               child: const Text('OK')
                             )
-                        ]
-                      )
+                          ],
+                        );
+                      },
                     );
                   }
                 )
@@ -71,11 +73,13 @@ void main() {
                   onPressed: () {
                     showDialog<Null>(
                       context: context,
-                      child: const AlertDialog(
+                      builder: (BuildContext context) {
+                        return const AlertDialog(
                           title: const Text('Title'),
                           content: const Text('Y'),
                           actions: const <Widget>[ ],
-                      ),
+                        );
+                      },
                     );
                   },
                 ),
@@ -116,7 +120,8 @@ void main() {
 
     final Future<int> result = showDialog(
       context: context,
-      child: new SimpleDialog(
+      builder: (BuildContext context) {
+        return new SimpleDialog(
           title: const Text('Title'),
           children: <Widget>[
             new SimpleDialogOption(
@@ -129,7 +134,8 @@ void main() {
               child: const Text('Second option'),
             ),
           ],
-      ),
+        );
+      },
     );
 
     await tester.pumpAndSettle(const Duration(seconds: 1));
@@ -157,12 +163,14 @@ void main() {
 
     showDialog<Null>(
       context: context,
-      child: new Container(
+      builder: (BuildContext context) {
+        return new Container(
           width: 100.0,
           height: 100.0,
           alignment: Alignment.center,
           child: const Text('Dialog1'),
-      ),
+        );
+      },
     );
 
     await tester.pumpAndSettle(const Duration(seconds: 1));
@@ -177,12 +185,14 @@ void main() {
     showDialog<Null>(
       context: context,
       barrierDismissible: false,
-      child: new Container(
+      builder: (BuildContext context) {
+        return new Container(
           width: 100.0,
           height: 100.0,
           alignment: Alignment.center,
           child: const Text('Dialog2'),
-      ),
+        );
+      },
     );
 
     await tester.pumpAndSettle(const Duration(seconds: 1));
@@ -219,7 +229,9 @@ void main() {
     const String alertText = 'A button in an overlay alert';
     showDialog<Null>(
       context: context,
-      child: const AlertDialog(title: const Text(alertText)),
+      builder: (BuildContext context) {
+        return const AlertDialog(title: const Text(alertText));
+      },
     );
 
     await tester.pumpAndSettle(const Duration(seconds: 1));
@@ -260,12 +272,10 @@ void main() {
     showDialog<Null>(
       context: outerContext,
       barrierDismissible: false,
-      child: new Builder(
       builder: (BuildContext context) {
         dialogContext = context;
         return new Container();
       },
-      ),
     );
 
     await tester.pump();

packages/flutter/test/material/text_field_focus_test.dart

@@ -110,7 +110,7 @@ void main() {
 
     showDialog<Null>(
       context: context,
-      child: const SimpleDialog(title: const Text('Dialog')),
+      builder: (BuildContext context) => const SimpleDialog(title: const Text('Dialog')),
     );
 
     await tester.pump();

packages/flutter/test/material/theme_test.dart

@@ -200,7 +200,7 @@ void main() {
                     onPressed: () {
                       showDialog<Null>(
                         context: context,
-                        child: const Text('dialog'),
+                        builder: (BuildContext context) => const Text('dialog'),
                       );
                     },
                     child: const Text('SHOW'),
@@ -232,12 +232,14 @@ void main() {
                   onTap: () {
                     showDialog<Null>(
                       context: context,
-                      child: const Scaffold(
+                      builder: (BuildContext context) {
+                        return const Scaffold(
                           body: const SizedBox(
                             width: 200.0,
                             height: 200.0,
                           ),
-                      )
+                        );
+                      },
                     );
                   },
                   child: const Text('SHOW'),

packages/flutter/test/material/will_pop_test.dart

@@ -86,7 +86,7 @@ void main() {
                   onPressed: () {
                     showDialog<Null>(
                       context: context,
-                      child: new SamplePage(),
+                      builder: (BuildContext context) => new SamplePage(),
                     );
                   },
                 ),
@@ -185,7 +185,8 @@ void main() {
     Future<bool> showYesNoAlert(BuildContext context) {
       return showDialog<bool>(
         context: context,
-        child: new AlertDialog(
+        builder: (BuildContext context) {
+          return new AlertDialog(
             actions: <Widget> [
               new FlatButton(
                 child: const Text('YES'),
@@ -196,7 +197,8 @@ void main() {
                 onPressed: () { Navigator.of(context).pop(false); },
               ),
             ],
-        ),
+          );
+        },
       );
     }