Add Material 3 `Dialog` examples and update existing `Dialog` examples (#101508)

examples/api/lib/material/dialog/alert_dialog.0.dart

+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+// Flutter code sample for AlertDialog
+
+import 'package:flutter/material.dart';
+
+void main() => runApp(const MyApp());
+
+class MyApp extends StatelessWidget {
+  const MyApp({Key? key}) : super(key: key);
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      home: Scaffold(
+        appBar: AppBar(title: const Text('AlertDialog Sample')),
+        body: const Center(
+          child: DialogExample(),
+        ),
+      ),
+    );
+  }
+}
+
+class DialogExample extends StatelessWidget {
+  const DialogExample({Key? key}) : super(key: key);
+
+  @override
+  Widget build(BuildContext context) {
+    return TextButton(
+      onPressed: () => showDialog<String>(
+        context: context,
+        builder: (BuildContext context) => AlertDialog(
+          title: const Text('AlertDialog Title'),
+          content: const Text('AlertDialog description'),
+          actions: <Widget>[
+            TextButton(
+              onPressed: () => Navigator.pop(context, 'Cancel'),
+              child: const Text('Cancel'),
+            ),
+            TextButton(
+              onPressed: () => Navigator.pop(context, 'OK'),
+              child: const Text('OK'),
+            ),
+          ],
+        ),
+      ),
+      child: const Text('Show Dialog'),
+    );
+  }
+}

examples/api/lib/material/dialog/alert_dialog.1.dart

@@ -11,24 +11,22 @@ void main() => runApp(const MyApp());
 class MyApp extends StatelessWidget {
   const MyApp({Key? key}) : super(key: key);
 
-  static const String _title = 'Flutter Code Sample';
-
   @override
   Widget build(BuildContext context) {
     return MaterialApp(
-      title: _title,
+      theme: ThemeData(colorSchemeSeed: const Color(0xff6750a4), useMaterial3: true),
       home: Scaffold(
-        appBar: AppBar(title: const Text(_title)),
+        appBar: AppBar(title: const Text('AlertDialog Sample')),
         body: const Center(
-          child: MyStatelessWidget(),
+          child: DialogExample(),
         ),
       ),
     );
   }
 }
 
-class MyStatelessWidget extends StatelessWidget {
-  const MyStatelessWidget({Key? key}) : super(key: key);
+class DialogExample extends StatelessWidget {
+  const DialogExample({Key? key}) : super(key: key);
 
   @override
   Widget build(BuildContext context) {

examples/api/lib/material/dialog/show_dialog.0.dart

@@ -11,41 +11,63 @@ void main() => runApp(const MyApp());
 class MyApp extends StatelessWidget {
   const MyApp({Key? key}) : super(key: key);
 
-  static const String _title = 'Flutter Code Sample';
-
   @override
   Widget build(BuildContext context) {
     return const MaterialApp(
-      restorationScopeId: 'app',
-      title: _title,
-      home: MyStatelessWidget(),
+      home: DialogExample(),
     );
   }
 }
 
-class MyStatelessWidget extends StatelessWidget {
-  const MyStatelessWidget({Key? key}) : super(key: key);
+class DialogExample extends StatelessWidget {
+  const DialogExample({Key? key}) : super(key: key);
 
   @override
   Widget build(BuildContext context) {
     return Scaffold(
+      appBar: AppBar(title: const Text('showDialog Sample')),
       body: Center(
         child: OutlinedButton(
-          onPressed: () {
-            Navigator.of(context).restorablePush(_dialogBuilder);
-          },
+          onPressed: () => _dialogBuilder(context),
           child: const Text('Open Dialog'),
         ),
       ),
     );
   }
 
-  static Route<Object?> _dialogBuilder(
-      BuildContext context, Object? arguments) {
-    return DialogRoute<void>(
+  Future<void> _dialogBuilder(BuildContext context) {
+    return showDialog<void>(
       context: context,
-      builder: (BuildContext context) =>
-          const AlertDialog(title: Text('Material Alert!')),
+      builder: (BuildContext context) {
+        return AlertDialog(
+          title: const Text('Basic dialog title'),
+          content: const Text(
+              'A dialog is a type of modal window that\n'
+              'appears in front of app content to\n'
+              'provide critical information, or prompt\n'
+              'for a decision to be made.'),
+          actions: <Widget>[
+            TextButton(
+              style: TextButton.styleFrom(
+                textStyle: Theme.of(context).textTheme.labelLarge,
+              ),
+              child: const Text('Disable'),
+              onPressed: () {
+                Navigator.of(context).pop();
+              },
+            ),
+            TextButton(
+              style: TextButton.styleFrom(
+                textStyle: Theme.of(context).textTheme.labelLarge,
+              ),
+              child: const Text('Enable'),
+              onPressed: () {
+                Navigator.of(context).pop();
+              },
+            ),
+          ],
+        );
+      },
     );
   }
 }

examples/api/lib/material/dialog/show_dialog.1.dart

+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+// Flutter code sample for showDialog
+
+import 'package:flutter/material.dart';
+
+void main() => runApp(const MyApp());
+
+class MyApp extends StatelessWidget {
+  const MyApp({Key? key}) : super(key: key);
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      theme: ThemeData(colorSchemeSeed: const Color(0xff6750a4), useMaterial3: true),
+      home: const DialogExample(),
+    );
+  }
+}
+
+class DialogExample extends StatelessWidget {
+  const DialogExample({Key? key}) : super(key: key);
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(title: const Text('showDialog Sample')),
+      body: Center(
+        child: OutlinedButton(
+          onPressed: () => _dialogBuilder(context),
+          child: const Text('Open Dialog'),
+        ),
+      ),
+    );
+  }
+
+  Future<void> _dialogBuilder(BuildContext context) {
+    return showDialog<void>(
+      context: context,
+      builder: (BuildContext context) {
+        return AlertDialog(
+          title: const Text('Basic dialog title'),
+          content: const Text(
+              'A dialog is a type of modal window that\n'
+              'appears in front of app content to\n'
+              'provide critical information, or prompt\n'
+              'for a decision to be made.'),
+          actions: <Widget>[
+            TextButton(
+              style: TextButton.styleFrom(
+                textStyle: Theme.of(context).textTheme.labelLarge,
+              ),
+              child: const Text('Disable'),
+              onPressed: () {
+                Navigator.of(context).pop();
+              },
+            ),
+            TextButton(
+              style: TextButton.styleFrom(
+                textStyle: Theme.of(context).textTheme.labelLarge,
+              ),
+              child: const Text('Enable'),
+              onPressed: () {
+                Navigator.of(context).pop();
+              },
+            ),
+          ],
+        );
+      },
+    );
+  }
+}

examples/api/lib/material/dialog/show_dialog.2.dart

+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+// Flutter code sample for showDialog
+
+import 'package:flutter/material.dart';
+
+void main() => runApp(const MyApp());
+
+class MyApp extends StatelessWidget {
+  const MyApp({Key? key}) : super(key: key);
+
+  @override
+  Widget build(BuildContext context) {
+    return const MaterialApp(
+      restorationScopeId: 'app',
+      home: DialogExample(),
+    );
+  }
+}
+
+class DialogExample extends StatelessWidget {
+  const DialogExample({Key? key}) : super(key: key);
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(title: const Text('AlertDialog Sample')),
+      body: Center(
+        child: OutlinedButton(
+          onPressed: () {
+            Navigator.of(context).restorablePush(_dialogBuilder);
+          },
+          child: const Text('Open Dialog'),
+        ),
+      ),
+    );
+  }
+
+  static Route<Object?> _dialogBuilder(
+      BuildContext context, Object? arguments) {
+    return DialogRoute<void>(
+      context: context,
+      builder: (BuildContext context) {
+        return AlertDialog(
+          title: const Text('Basic dialog title'),
+          content: const Text(
+              'A dialog is a type of modal window that\n'
+              'appears in front of app content to\n'
+              'provide critical information, or prompt\n'
+              'for a decision to be made.'),
+          actions: <Widget>[
+            TextButton(
+              style: TextButton.styleFrom(
+                textStyle: Theme.of(context).textTheme.labelLarge,
+              ),
+              child: const Text('Disable'),
+              onPressed: () {
+                Navigator.of(context).pop();
+              },
+            ),
+            TextButton(
+              style: TextButton.styleFrom(
+                textStyle: Theme.of(context).textTheme.labelLarge,
+              ),
+              child: const Text('Enable'),
+              onPressed: () {
+                Navigator.of(context).pop();
+              },
+            ),
+          ],
+        );
+      },
+    );
+  }
+}

examples/api/test/material/dialog/alert_dialog.0_test.dart

+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'package:flutter/material.dart';
+import 'package:flutter_api_samples/material/dialog/alert_dialog.0.dart' as example;
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  testWidgets('Show Alert dialog', (WidgetTester tester) async {
+    const String dialogTitle = 'AlertDialog Title';
+    await tester.pumpWidget(
+      const MaterialApp(
+        home: Scaffold(
+          body: example.MyApp(),
+        ),
+      ),
+    );
+
+    expect(find.text(dialogTitle), findsNothing);
+
+    await tester.tap(find.widgetWithText(TextButton, 'Show Dialog'));
+    await tester.pumpAndSettle();
+    expect(find.text(dialogTitle), findsOneWidget);
+
+    await tester.tap(find.text('OK'));
+    await tester.pumpAndSettle();
+    expect(find.text(dialogTitle), findsNothing);
+  });
+}

examples/api/test/material/dialog/alert_dialog.1_test.dart

+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'package:flutter/material.dart';
+import 'package:flutter_api_samples/material/dialog/alert_dialog.1.dart' as example;
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  testWidgets('Show Alert dialog', (WidgetTester tester) async {
+    const String dialogTitle = 'AlertDialog Title';
+    await tester.pumpWidget(
+      const MaterialApp(
+        home: Scaffold(
+          body: example.MyApp(),
+        ),
+      ),
+    );
+
+    expect(find.text(dialogTitle), findsNothing);
+
+    await tester.tap(find.widgetWithText(TextButton, 'Show Dialog'));
+    await tester.pumpAndSettle();
+    expect(find.text(dialogTitle), findsOneWidget);
+
+    await tester.tap(find.text('OK'));
+    await tester.pumpAndSettle();
+    expect(find.text(dialogTitle), findsNothing);
+  });
+}

examples/api/test/material/dialog/show_dialog.0_test.dart

+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'package:flutter/material.dart';
+import 'package:flutter_api_samples/material/dialog/show_dialog.0.dart' as example;
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  testWidgets('Show dialog', (WidgetTester tester) async {
+    const String dialogTitle = 'Basic dialog title';
+    await tester.pumpWidget(
+      const MaterialApp(
+        home: Scaffold(
+          body: example.MyApp(),
+        ),
+      ),
+    );
+
+    expect(find.text(dialogTitle), findsNothing);
+
+    await tester.tap(find.widgetWithText(OutlinedButton, 'Open Dialog'));
+    await tester.pumpAndSettle();
+    expect(find.text(dialogTitle), findsOneWidget);
+
+    await tester.tap(find.text('Enable'));
+    await tester.pumpAndSettle();
+    expect(find.text(dialogTitle), findsNothing);
+  });
+}

examples/api/test/material/dialog/show_dialog.1_test.dart

+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'package:flutter/material.dart';
+import 'package:flutter_api_samples/material/dialog/show_dialog.1.dart' as example;
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  testWidgets('Show dialog', (WidgetTester tester) async {
+    const String dialogTitle = 'Basic dialog title';
+    await tester.pumpWidget(
+      const MaterialApp(
+        home: Scaffold(
+          body: example.MyApp(),
+        ),
+      ),
+    );
+
+    expect(find.text(dialogTitle), findsNothing);
+
+    await tester.tap(find.widgetWithText(OutlinedButton, 'Open Dialog'));
+    await tester.pumpAndSettle();
+    expect(find.text(dialogTitle), findsOneWidget);
+
+    await tester.tap(find.text('Enable'));
+    await tester.pumpAndSettle();
+    expect(find.text(dialogTitle), findsNothing);
+  });
+}

examples/api/test/material/dialog/show_dialog.2_test.dart

+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'package:flutter/material.dart';
+import 'package:flutter_api_samples/material/dialog/show_dialog.2.dart' as example;
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  testWidgets('Show dialog', (WidgetTester tester) async {
+    const String dialogTitle = 'Basic dialog title';
+    await tester.pumpWidget(
+      const MaterialApp(
+        home: Scaffold(
+          body: example.MyApp(),
+        ),
+      ),
+    );
+
+    expect(find.text(dialogTitle), findsNothing);
+
+    await tester.tap(find.widgetWithText(OutlinedButton, 'Open Dialog'));
+    await tester.pumpAndSettle();
+    expect(find.text(dialogTitle), findsOneWidget);
+
+    await tester.tap(find.text('Enable'));
+    await tester.pumpAndSettle();
+    expect(find.text(dialogTitle), findsNothing);
+  });
+}

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

@@ -233,6 +233,13 @@ class Dialog extends StatelessWidget {
 /// displays a Material dialog above the current contents of the app and returns
 /// a [Future] that completes when the dialog is dismissed.
 ///
+/// ** See code in examples/api/lib/material/dialog/alert_dialog.0.dart **
+/// {@end-tool}
+///
+/// {@tool dartpad}
+/// This sample shows the creation of [AlertDialog], as described in:
+/// https://m3.material.io/components/dialogs/overview
+///
 /// ** See code in examples/api/lib/material/dialog/alert_dialog.1.dart **
 /// {@end-tool}
 ///
@@ -1013,6 +1020,19 @@ Widget _buildMaterialDialogTransitions(BuildContext context, Animation<double> a
 /// Returns a [Future] that resolves to the value (if any) that was passed to
 /// [Navigator.pop] when the dialog was closed.
 ///
+/// {@tool dartpad}
+/// This sample demonstrates how to use [showDialog] to display a dialog box.
+///
+/// ** See code in examples/api/lib/material/dialog/show_dialog.0.dart **
+/// {@end-tool}
+///
+/// {@tool dartpad}
+/// This sample shows the creation of [showDialog], as described in:
+/// https://m3.material.io/components/dialogs/overview
+///
+/// ** See code in examples/api/lib/material/dialog/show_dialog.1.dart **
+/// {@end-tool}
+///
 /// ### State Restoration in Dialogs
 ///
 /// Using this method will not enable state restoration for the dialog. In order
@@ -1021,7 +1041,7 @@ Widget _buildMaterialDialogTransitions(BuildContext context, Animation<double> a
 ///
 /// For more information about state restoration, see [RestorationManager].
 ///
-/// {@tool sample}
+/// {@tool dartpad}
 /// This sample demonstrates how to create a restorable Material dialog. This is
 /// accomplished by enabling state restoration by specifying
 /// [MaterialApp.restorationScopeId] and using [Navigator.restorablePush] to
@@ -1029,7 +1049,7 @@ Widget _buildMaterialDialogTransitions(BuildContext context, Animation<double> a
 ///
 /// {@macro flutter.widgets.RestorationManager}
 ///
-/// ** See code in examples/api/lib/material/dialog/show_dialog.0.dart **
+/// ** See code in examples/api/lib/material/dialog/show_dialog.2.dart **
 /// {@end-tool}
 ///
 /// See also: