PlatformMenuBar class Null safety

A menu bar that uses the platform's native APIs to construct and render a menu described by a PlatformMenu/PlatformMenuItem hierarchy.

This widget is especially useful on macOS, where a system menu is a required part of every application. Flutter only includes support for macOS out of the box, but support for other platforms may be provided via plugins that set WidgetsBinding.platformMenuDelegate in their initialization.

The menus member contains MenuItems. They will not be part of the widget tree, since they are not required to be widgets (even if they happen to be widgets that implement MenuItem, they still won't be part of the widget tree). They are provided to configure the properties of the menus on the platform menu bar.

As far as Flutter is concerned, this widget has no visual representation, and intercepts no events: it just returns the child from its build function. This is because all of the rendering, shortcuts, and event handling for the menu is handled by the plugin on the host platform.

There can only be one PlatformMenuBar at a time using the same PlatformMenuDelegate. It will assert if more than one is detected.

When calling toStringDeep on this widget, it will give a tree of MenuItems, not a tree of widgets.

link
This example shows a PlatformMenuBar that contains a single top level menu, containing three items for "About", a toggleable menu item for showing a message, a cascading submenu with message choices, and "Quit".

This example will only work on macOS.

To create a local project with this code sample, run:
flutter create --sample=widgets.PlatformMenuBar.1 mysample 
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';

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

enum MenuSelection {
  about,
  showMessage,
}

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

  @override
  Widget build(BuildContext context) {
    return const MaterialApp(
      home: Scaffold(body: MyMenuBarApp()),
    );
  }
}

class MyMenuBarApp extends StatefulWidget {
  const MyMenuBarApp({super.key});

  @override
  State<MyMenuBarApp> createState() => _MyMenuBarAppState();
}

class _MyMenuBarAppState extends State<MyMenuBarApp> {
  String _message = 'Hello';
  bool _showMessage = false;

  void _handleMenuSelection(MenuSelection value) {
    switch (value) {
      case MenuSelection.about:
        showAboutDialog(
          context: context,
          applicationName: 'MenuBar Sample',
          applicationVersion: '1.0.0',
        );
        break;
      case MenuSelection.showMessage:
        setState(() {
          _showMessage = !_showMessage;
        });
        break;
    }
  }

  @override
  Widget build(BuildContext context) {
    ////////////////////////////////////
    // THIS SAMPLE ONLY WORKS ON MACOS.
    ////////////////////////////////////

    // This builds a menu hierarchy that looks like this:
    // Flutter API Sample
    //  ├ About
    //  ├ ────────  (group divider)
    //  ├ Hide/Show Message
    //  ├ Messages
    //  │  ├ I am not throwing away my shot.
    //  │  └ There's a million things I haven't done, but just you wait.
    //  └ Quit
    return PlatformMenuBar(
      menus: <MenuItem>[
        PlatformMenu(
          label: 'Flutter API Sample',
          menus: <MenuItem>[
            PlatformMenuItemGroup(
              members: <MenuItem>[
                PlatformMenuItem(
                  label: 'About',
                  onSelected: () {
                    _handleMenuSelection(MenuSelection.about);
                  },
                ),
              ],
            ),
            PlatformMenuItemGroup(
              members: <MenuItem>[
                PlatformMenuItem(
                  onSelected: () {
                    _handleMenuSelection(MenuSelection.showMessage);
                  },
                  shortcut: const CharacterActivator('m'),
                  label: _showMessage ? 'Hide Message' : 'Show Message',
                ),
                PlatformMenu(
                  label: 'Messages',
                  menus: <MenuItem>[
                    PlatformMenuItem(
                      label: 'I am not throwing away my shot.',
                      shortcut: const SingleActivator(LogicalKeyboardKey.digit1,
                          meta: true),
                      onSelected: () {
                        setState(() {
                          _message = 'I am not throwing away my shot.';
                        });
                      },
                    ),
                    PlatformMenuItem(
                      label:
                          "There's a million things I haven't done, but just you wait.",
                      shortcut: const SingleActivator(LogicalKeyboardKey.digit2,
                          meta: true),
                      onSelected: () {
                        setState(() {
                          _message =
                              "There's a million things I haven't done, but just you wait.";
                        });
                      },
                    ),
                  ],
                ),
              ],
            ),
            if (PlatformProvidedMenuItem.hasMenu(
                PlatformProvidedMenuItemType.quit))
              const PlatformProvidedMenuItem(
                  type: PlatformProvidedMenuItemType.quit),
          ],
        ),
      ],
      child: Center(
        child: Text(_showMessage
            ? _message
            : 'This space intentionally left blank.\n'
                'Show a message here using the menu.'),
      ),
    );
  }
}

Inheritance
Mixed in types

Constructors

PlatformMenuBar({Key? key, required List<MenuItem> menus, Widget? child, @Deprecated('Use the child attribute instead. ' 'This feature was deprecated after v3.1.0-0.0.pre.') Widget? body})
Creates a const PlatformMenuBar.
const

Properties

body → Widget?
The widget below this widget in the tree.
Deprecated('Use the child attribute instead. ' 'This feature was deprecated after v3.1.0-0.0.pre.')">@Deprecated('Use the child attribute instead. ' 'This feature was deprecated after v3.1.0-0.0.pre.')final
child → Widget?
The widget below this widget in the tree.
final
hashCode → int
The hash code for this object.
nonVirtual">@nonVirtualread-onlyinherited
key → Key?
Controls how one widget replaces another widget in the tree.
finalinherited
The list of menu items that are the top level children of the PlatformMenuBar.
final
runtimeType → Type
A representation of the runtime type of the object.
read-onlyinherited

Methods

createElement() → StatefulElement
Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() → State<PlatformMenuBar>
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.
override
debugFillProperties(DiagnosticPropertiesBuilder properties) → void
Add additional properties associated with the node.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a non-existent 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.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug}) → 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 brief description of this object, usually just the runtimeType and the hashCode.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
nonVirtual">@nonVirtualinherited