showMenu<T> function

Future<T> showMenu <T>({@required BuildContext context, RelativeRect position, @required List<PopupMenuEntry<T>> items, T initialValue, double elevation: 8.0, String semanticLabel })

Show a popup menu that contains the items at position.

If initialValue is specified then the first item with a matching value will be highlighted and the value of position gives the rectangle whose vertical center will be aligned with the vertical center of the highlighted item (when possible).

If initialValue is not specified then the top of the menu will be aligned with the top of the position rectangle.

In both cases, the menu position will be adjusted if necessary to fit on the screen.

Horizontally, the menu is positioned so that it grows in the direction that has the most room. For example, if the position describes a rectangle on the left edge of the screen, then the left edge of the menu is aligned with the left edge of the position, and the menu grows to the right. If both edges of the position are equidistant from the opposite edge of the screen, then the ambient Directionality is used as a tie-breaker, preferring to grow in the reading direction.

The positioning of the initialValue at the position is implemented by iterating over the items to find the first whose PopupMenuEntry.represents method returns true for initialValue, and then summing the values of PopupMenuEntry.height for all the preceding widgets in the list.

The elevation argument specifies the z-coordinate at which to place the menu. The elevation defaults to 8, the appropriate elevation for popup menus.

The context argument is used to look up the Navigator and Theme for the menu. It is only used when the method is called. Its corresponding widget can be safely removed from the tree before the popup menu is closed.

The semanticLabel argument is used by accessibility frameworks to announce screen transitions when the menu is opened and closed. If this label is not provided, it will default to MaterialLocalizations.popupMenuLabel.

See also:

Implementation 

Future<T> showMenu<T>({
  @required BuildContext context,
  RelativeRect position,
  @required List<PopupMenuEntry<T>> items,
  T initialValue,
  double elevation = 8.0,
  String semanticLabel,
}) {
  assert(context != null);
  assert(items != null && items.isNotEmpty);
  assert(debugCheckHasMaterialLocalizations(context));
  String label = semanticLabel;
  switch (defaultTargetPlatform) {
    case TargetPlatform.iOS:
      label = semanticLabel;
      break;
    case TargetPlatform.android:
    case TargetPlatform.fuchsia:
      label = semanticLabel ?? MaterialLocalizations.of(context)?.popupMenuLabel;
  }

  return Navigator.push(context, _PopupMenuRoute<T>(
    position: position,
    items: items,
    initialValue: initialValue,
    elevation: elevation,
    semanticLabel: label,
    theme: Theme.of(context, shadowThemeOnly: true),
    barrierLabel: MaterialLocalizations.of(context).modalBarrierDismissLabel,
  ));
}