PopupMenuButton should lazily build menu items

Previously, the client of PopupMenuButton needed to build all the menu times

when building the PopupMenuButton. This can get expensive if, for example, each
item in a scrollable list has a popup menu associated with it.

Now the client passes a builder function to the PopupMenuButton that gets
invoked only when its time to show the menu items.

dev/benchmarks/complex_layout/lib/main.dart

@@ -101,7 +101,7 @@ class TopBarMenu extends StatelessWidget {
   Widget build(BuildContext context) {
     return new PopupMenuButton<String>(
       onSelected: (String value) { print("Selected: $value"); },
-      items: <PopupMenuItem<String>>[
+      itemBuilder: (BuildContext context) => <PopupMenuItem<String>>[
         new PopupMenuItem<String>(
           value: "Friends",
           child: new MenuItemWithIcon(Icons.people, "Friends", "5 new")

examples/material_gallery/lib/demo/flexible_space_demo.dart

@@ -110,7 +110,7 @@ class FlexibleSpaceDemoState extends State<FlexibleSpaceDemo> {
                   _appBarBehavior = value;
                 });
               },
-              items: <PopupMenuItem<AppBarBehavior>>[
+              itemBuilder: (BuildContext context) => <PopupMenuItem<AppBarBehavior>>[
                 new PopupMenuItem<AppBarBehavior>(
                   value: AppBarBehavior.scroll,
                   child: new Text('AppBar scrolls away')

examples/material_gallery/lib/demo/leave_behind_demo.dart

@@ -134,7 +134,7 @@ class LeaveBehindDemoState extends State<LeaveBehindDemo> {
         actions: <Widget>[
           new PopupMenuButton<LeaveBehindDemoAction>(
             onSelected: handleDemoAction,
-            items: <PopupMenuEntry<LeaveBehindDemoAction>>[
+            itemBuilder: (BuildContext context) => <PopupMenuEntry<LeaveBehindDemoAction>>[
               new PopupMenuItem<LeaveBehindDemoAction>(
                 value: LeaveBehindDemoAction.reset,
                 child: new Text('Reset the list')

examples/material_gallery/lib/demo/menu_demo.dart

@@ -64,7 +64,7 @@ class MenuDemoState extends State<MenuDemo> {
         actions: <Widget>[
           new PopupMenuButton<String>(
             onSelected: showMenuSelection,
-            items: <PopupMenuItem<String>>[
+            itemBuilder: (BuildContext context) => <PopupMenuItem<String>>[
               new PopupMenuItem<String>(
                 value: 'AppBar Menu',
                 child: new Text('AppBar Menu')
@@ -91,7 +91,7 @@ class MenuDemoState extends State<MenuDemo> {
             title: new Text('An item with a context menu button'),
             trailing: new PopupMenuButton<String>(
               onSelected: showMenuSelection,
-              items: <PopupMenuItem<String>>[
+              itemBuilder: (BuildContext context) => <PopupMenuItem<String>>[
                 new PopupMenuItem<String>(
                   value: _simpleValue1,
                   child: new Text('Context menu item one')
@@ -114,7 +114,7 @@ class MenuDemoState extends State<MenuDemo> {
             title: new Text('An item with a sectioned menu'),
             trailing: new PopupMenuButton<String>(
               onSelected: showMenuSelection,
-              items: <PopupMenuEntry<String>>[
+              itemBuilder: (BuildContext context) => <PopupMenuEntry<String>>[
                 new PopupMenuItem<String>(
                   value: 'Preview',
                   child: new ListItem(
@@ -157,7 +157,7 @@ class MenuDemoState extends State<MenuDemo> {
               title: new Text('An item with a simple menu'),
               subtitle: new Text(_simpleValue)
             ),
-            items: <PopupMenuItem<String>>[
+            itemBuilder: (BuildContext context) => <PopupMenuItem<String>>[
               new PopupMenuItem<String>(
                 value: _simpleValue1,
                 child: new Text(_simpleValue1)
@@ -178,7 +178,7 @@ class MenuDemoState extends State<MenuDemo> {
             title: new Text('An item with a checklist menu'),
             trailing: new PopupMenuButton<String>(
               onSelected: showCheckedMenuSelections,
-              items: <PopupMenuItem<String>>[
+              itemBuilder: (BuildContext context) => <PopupMenuItem<String>>[
                 new CheckedPopupMenuItem<String>(
                   value: _checkedValue1,
                   checked: isChecked(_checkedValue1),

examples/material_gallery/lib/demo/scrollable_tabs_demo.dart

@@ -53,7 +53,7 @@ class ScrollableTabsDemoState extends State<ScrollableTabsDemo> {
           actions: <Widget>[
             new PopupMenuButton<TabsDemoStyle>(
               onSelected: changeDemoStyle,
-              items: <PopupMenuItem<TabsDemoStyle>>[
+              itemBuilder: (BuildContext context) => <PopupMenuItem<TabsDemoStyle>>[
                 new PopupMenuItem<TabsDemoStyle>(
                   value: TabsDemoStyle.iconsAndText,
                   child: new Text('Icons and Text')

examples/stocks/lib/stock_home.dart

@@ -220,7 +220,7 @@ class StockHomeState extends State<StockHome> {
         ),
         new PopupMenuButton<_StockMenuItem>(
           onSelected: (_StockMenuItem value) { _handleStockMenu(context, value); },
-          items: <PopupMenuItem<_StockMenuItem>>[
+          itemBuilder: (BuildContext context) => <PopupMenuItem<_StockMenuItem>>[
             new CheckedPopupMenuItem<_StockMenuItem>(
               value: _StockMenuItem.autorefresh,
               checked: _autorefresh,

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

@@ -380,6 +380,9 @@ Future<dynamic/*=T*/> showMenu/*<T>*/({
 /// its menu to be dismissed.
 typedef void PopupMenuItemSelected<T>(T value);
 
+/// Signature used by [PopupMenuButton] to lazily construct the items shown when the button is pressed.
+typedef List<PopupMenuEntry<T>> PopupMenuItemBuilder<T>(BuildContext context);
+
 /// Displays a menu when pressed and calls [onSelected] when the menu is dismissed
 /// because an item was selected. The value passed to [onSelected] is the value of
 /// the selected menu item. If child is null then a standard 'navigation/more_vert'
@@ -387,15 +390,18 @@ typedef void PopupMenuItemSelected<T>(T value);
 class PopupMenuButton<T> extends StatefulWidget {
   PopupMenuButton({
     Key key,
-    this.items,
+    this.itemBuilder,
     this.initialValue,
     this.onSelected,
     this.tooltip: 'Show menu',
     this.elevation: 8,
     this.child
-  }) : super(key: key);
+  }) : super(key: key) {
+    assert(itemBuilder != null);
+  }
 
-  final List<PopupMenuEntry<T>> items;
+  /// Called when the button is pressed to create the items to show in the menu.
+  final PopupMenuItemBuilder<T> itemBuilder;
 
   final T initialValue;
 
@@ -420,7 +426,7 @@ class _PopupMenuButtonState<T> extends State<PopupMenuButton<T>> {
     showMenu/*<T>*/(
       context: context,
       elevation: config.elevation,
-      items: config.items,
+      items: config.itemBuilder(context),
       initialValue: config.initialValue,
       position: new ModalPosition(
         left: topLeft.x,