MenuAcceleratorLabel class

A widget that draws the label text for a menu item (typically a MenuItemButton or SubmenuButton) and renders its child with information about the currently active keyboard accelerator.

On platforms other than macOS and iOS, this widget listens for the Alt key to be pressed, and when it is down, will update the label by calling the builder again with the position of the accelerator in the label string. While the Alt key is pressed, it registers a shortcut with the ShortcutRegistry mapped to a VoidCallbackIntent containing the callback defined by the nearest MenuAcceleratorCallbackBinding.

Because the accelerators are registered with the ShortcutRegistry, any other shortcuts in the widget tree between the primaryFocus and the ShortcutRegistry that define Alt-based shortcuts using the same keys will take precedence over the accelerators.

Because accelerators aren't used on macOS and iOS, the label ignores the Alt key on those platforms, and the builder is always given -1 as an accelerator index. Accelerator labels are still stripped of their accelerator markers.

The built-in menu items MenuItemButton and SubmenuButton already provide the appropriate MenuAcceleratorCallbackBinding, so unless you are creating your own custom menu item type that takes a MenuAcceleratorLabel, it is not necessary to provide one.

This example shows a MenuBar that handles keyboard accelerators using MenuAcceleratorLabel. To use the accelerators, press the Alt key to see which letters are underlined in the menu bar, and then press the appropriate letter. Accelerators are not supported on macOS or iOS since those platforms don't support them natively, so this demo will only show a regular Material menu bar on those platforms.

{@macro material_ui.dartpad_guide}

import 'package:flutter/services.dart';
import 'package:material_ui/material_ui.dart';

/// Flutter code sample for [MenuAcceleratorLabel].

void main() => runApp(const MenuAcceleratorApp());

class MyMenuBar extends StatelessWidget {
  const MyMenuBar({super.key});

  @override
  Widget build(BuildContext context) {
    return Column(
      children: <Widget>[
        Row(
          mainAxisSize: .min,
          children: <Widget>[
            Expanded(
              child: MenuBar(
                children: <Widget>[
                  SubmenuButton(
                    menuChildren: <Widget>[
                      MenuItemButton(
                        onPressed: () {
                          showAboutDialog(
                            context: context,
                            applicationName: 'MenuBar Sample',
                            applicationVersion: '1.0.0',
                          );
                        },
                        child: const MenuAcceleratorLabel('&About'),
                      ),
                      MenuItemButton(
                        onPressed: () {
                          ScaffoldMessenger.of(context).showSnackBar(
                            const SnackBar(content: Text('Saved!')),
                          );
                        },
                        child: const MenuAcceleratorLabel('&Save'),
                      ),
                      MenuItemButton(
                        onPressed: () {
                          ScaffoldMessenger.of(context).showSnackBar(
                            const SnackBar(content: Text('Quit!')),
                          );
                        },
                        child: const MenuAcceleratorLabel('&Quit'),
                      ),
                    ],
                    child: const MenuAcceleratorLabel('&File'),
                  ),
                  SubmenuButton(
                    menuChildren: <Widget>[
                      MenuItemButton(
                        onPressed: () {
                          ScaffoldMessenger.of(context).showSnackBar(
                            const SnackBar(content: Text('Magnify!')),
                          );
                        },
                        child: const MenuAcceleratorLabel('&Magnify'),
                      ),
                      MenuItemButton(
                        onPressed: () {
                          ScaffoldMessenger.of(context).showSnackBar(
                            const SnackBar(content: Text('Minify!')),
                          );
                        },
                        child: const MenuAcceleratorLabel('Mi&nify'),
                      ),
                    ],
                    child: const MenuAcceleratorLabel('&View'),
                  ),
                ],
              ),
            ),
          ],
        ),
        Expanded(
          child: FlutterLogo(
            size: MediaQuery.of(context).size.shortestSide * 0.5,
          ),
        ),
      ],
    );
  }
}

class MenuAcceleratorApp extends StatelessWidget {
  const MenuAcceleratorApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Shortcuts(
        shortcuts: <ShortcutActivator, Intent>{
          const SingleActivator(
            LogicalKeyboardKey.keyT,
            control: true,
          ): VoidCallbackIntent(() {
            debugDumpApp();
          }),
        },
        child: const Scaffold(body: SafeArea(child: MyMenuBar())),
      ),
    );
  }
}
Inheritance

Constructors

Creates a const MenuAcceleratorLabel.
const

Properties

builder → MenuAcceleratorChildBuilder
The optional MenuAcceleratorChildBuilder which is used to build the widget that displays the label itself.
final
displayLabel → String
Returns the label with any accelerator markers removed.
no setter
hasAccelerator → bool
Whether label contains an accelerator definition.
no setter
hashCode → int
The hash code for this object.
no setterinherited
key → Key?
Controls how one widget replaces another widget in the tree.
finalinherited
label → String
The label string that should be displayed.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

createElement() → StatefulElement
Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() → State<MenuAcceleratorLabel>
Creates the mutable state for this widget at a given location in the tree.
override
debugDescribeChildren() → List<DiagnosticsNode>
Returns a list of DiagnosticsNode objects describing this node's children.
inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void
Add additional properties associated with the node.
override
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode
Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String
A string representation of this object.
override
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug, int wrapWidth = 65}) → String
Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String
Returns a one-line detailed description of the object.
inherited
toStringShort() → String
A short, textual description of this widget.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Methods

defaultLabelBuilder(BuildContext context, String label, int index) → Widget
Serves as the default value for builder, rendering the label as a RichText widget with appropriate TextSpans for rendering the label with an underscore under the selected accelerator for the label when the index is non-negative, and a Text widget when the index is negative.
stripAcceleratorMarkers(String label, {void setIndex(int index)?}) → String
Strips out any accelerator markers from the given label, and unescapes any escaped ampersands.