Update `PopupMenuButton` example (#96681)

examples/api/lib/material/popupmenu/popupmenu.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 PopupMenuButton
+
+import 'package:flutter/material.dart';
+
+// This is the type used by the popup menu below.
+enum Menu { itemOne, itemTwo, itemThree, itemFour }
+
+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(
+      title: _title,
+      home: MyStatefulWidget(),
+    );
+  }
+}
+
+class MyStatefulWidget extends StatefulWidget {
+  const MyStatefulWidget({Key? key}) : super(key: key);
+
+  @override
+  State<MyStatefulWidget> createState() => _MyStatefulWidgetState();
+}
+
+class _MyStatefulWidgetState extends State<MyStatefulWidget> {
+  String _selectedMenu = '';
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(
+        actions: <Widget>[
+          // This button presents popup menu items.
+          PopupMenuButton<Menu>(
+          // Callback that sets the selected popup menu item.
+          onSelected: (Menu item) {
+            setState(() {
+              _selectedMenu = item.name;
+            });
+          },
+          itemBuilder: (BuildContext context) => <PopupMenuEntry<Menu>>[
+            const PopupMenuItem<Menu>(
+              value: Menu.itemOne,
+              child: Text('Item 1'),
+            ),
+            const PopupMenuItem<Menu>(
+              value: Menu.itemTwo,
+              child: Text('Item 2'),
+            ),
+            const PopupMenuItem<Menu>(
+              value: Menu.itemThree,
+              child: Text('Item 3'),
+            ),
+            const PopupMenuItem<Menu>(
+              value: Menu.itemFour,
+              child: Text('Item 4'),
+            ),
+          ])
+        ],
+      ),
+      body: Center(
+        child: Text('_selectedMenu: $_selectedMenu'),
+      ),
+    );
+  }
+}

examples/api/test/material/popupmenu/popupmenu.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/popupmenu/popupmenu.0.dart' as example;
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  testWidgets('Can select a menu item', (WidgetTester tester) async {
+    final Key popupButtonKey = UniqueKey();
+    await tester.pumpWidget(
+      MaterialApp(
+        home: Scaffold(
+          body: example.MyStatefulWidget(
+            key: popupButtonKey,
+          ),
+        ),
+      ),
+    );
+
+    await tester.tap(find.byKey(popupButtonKey));
+    await tester.pump();
+    await tester.pump(const Duration(seconds: 1)); // finish the menu animation
+    await tester.tapAt(const Offset(1.0, 1.0));
+    await tester.pumpAndSettle();
+    expect(find.text('_selectedMenu: itemOne'), findsNothing);
+  });
+}

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

@@ -26,6 +26,7 @@ import 'tooltip.dart';
 // late dynamic _selection;
 // late BuildContext context;
 // void setState(VoidCallback fn) { }
+// enum Menu { itemOne, itemTwo, itemThree, itemFour }
 
 const Duration _kMenuDuration = Duration(milliseconds: 300);
 const double _kMenuCloseIntervalEnd = 2.0 / 3.0;
@@ -186,13 +187,13 @@ class _RenderMenuItem extends RenderShiftedBox {
 ///
 /// {@tool snippet}
 ///
-/// Here, a [Text] widget is used with a popup menu item. The `WhyFarther` type
+/// Here, a [Text] widget is used with a popup menu item. The `Menu` type
 /// is an enum, not shown here.
 ///
 /// ```dart
-/// const PopupMenuItem<WhyFarther>(
-///   value: WhyFarther.harder,
-///   child: Text('Working a lot harder'),
+/// const PopupMenuItem<Menu>(
+///   value: Menu.itemOne,
+///   child: Text('Item 1'),
 /// )
 /// ```
 /// {@end-tool}
@@ -933,36 +934,9 @@ typedef PopupMenuItemBuilder<T> = List<PopupMenuEntry<T>> Function(BuildContext
 /// {@tool snippet}
 ///
 /// This example shows a menu with four items, selecting between an enum's
-/// values and setting a `_selection` field based on the selection.
+/// values and setting a `_selectedMenu` field based on the selection
 ///
-/// ```dart
-/// // This is the type used by the popup menu below.
-/// enum WhyFarther { harder, smarter, selfStarter, tradingCharter }
-///
-/// // This menu button widget updates a _selection field (of type WhyFarther,
-/// // not shown here).
-/// PopupMenuButton<WhyFarther>(
-///   onSelected: (WhyFarther result) { setState(() { _selection = result; }); },
-///   itemBuilder: (BuildContext context) => <PopupMenuEntry<WhyFarther>>[
-///     const PopupMenuItem<WhyFarther>(
-///       value: WhyFarther.harder,
-///       child: Text('Working a lot harder'),
-///     ),
-///     const PopupMenuItem<WhyFarther>(
-///       value: WhyFarther.smarter,
-///       child: Text('Being a lot smarter'),
-///     ),
-///     const PopupMenuItem<WhyFarther>(
-///       value: WhyFarther.selfStarter,
-///       child: Text('Being a self-starter'),
-///     ),
-///     const PopupMenuItem<WhyFarther>(
-///       value: WhyFarther.tradingCharter,
-///       child: Text('Placed in charge of trading charter'),
-///     ),
-///   ],
-/// )
-/// ```
+/// ** See code in examples/api/lib/material/popupmenu/popupmenu.0.dart **
 /// {@end-tool}
 ///
 /// See also: