showArnaMenu<T> function
- required BuildContext context,
- required RelativeRect position,
- required List<
ArnaPopupMenuEntry< items,T> > - T? initialValue,
- String? semanticLabel,
- Color? color,
Show a popup menu that contains the items
at position
.
items
should be non-null and not empty.
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 ArnaPopupMenuEntry.represents method returns true for initialValue
, and then summing the values of
ArnaPopupMenuEntry.height for all the preceding widgets in the list.
The context
argument is used to look up the Navigator 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 useRootNavigator
argument is used to determine whether to push the menu to the Navigator furthest from or
nearest to the given context
. It is false
by default.
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:
- ArnaPopupMenuItem, a popup menu entry for a single value.
- ArnaPopupMenuDivider, a popup menu entry that is just a horizontal line.
- ArnaPopupMenuButton, which provides an ArnaIconButton that shows a menu by calling this method automatically.
- SemanticsConfiguration.namesRoute, for a description of edge triggered semantics.
Implementation
Future<T?> showArnaMenu<T>({
required BuildContext context,
required RelativeRect position,
required List<ArnaPopupMenuEntry<T>> items,
T? initialValue,
String? semanticLabel,
Color? color,
bool useRootNavigator = false,
}) {
assert(items.isNotEmpty);
return Navigator.of(context, rootNavigator: useRootNavigator).push(
_ArnaPopupMenuRoute<T>(
position: position,
items: items,
initialValue: initialValue,
semanticLabel:
semanticLabel ?? MaterialLocalizations.of(context).popupMenuLabel,
barrierLabel: MaterialLocalizations.of(context).modalBarrierDismissLabel,
color: color,
),
);
}