PlatformMenuBar class

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 PlatformMenuItems, which 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. It is only part of the widget tree to provide a convenient refresh mechanism for the menu data.

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 PlatformMenuItems, not a tree of widgets.

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.

link

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';

/// Flutter code sample for [PlatformMenuBar].

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

enum MenuSelection {
  about,
  showMessage,
}

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

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

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

  @override
  State<PlatformMenuBarExample> createState() => _PlatformMenuBarExampleState();
}

class _PlatformMenuBarExampleState extends State<PlatformMenuBarExample> {
  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',
        );
      case MenuSelection.showMessage:
        setState(() {
          _showMessage = !_showMessage;
        });
    }
  }

  @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: <PlatformMenuItem>[
        PlatformMenu(
          label: 'Flutter API Sample',
          menus: <PlatformMenuItem>[
            PlatformMenuItemGroup(
              members: <PlatformMenuItem>[
                PlatformMenuItem(
                  label: 'About',
                  onSelected: () {
                    _handleMenuSelection(MenuSelection.about);
                  },
                ),
              ],
            ),
            PlatformMenuItemGroup(
              members: <PlatformMenuItem>[
                PlatformMenuItem(
                  onSelected: () {
                    _handleMenuSelection(MenuSelection.showMessage);
                  },
                  shortcut: const CharacterActivator('m'),
                  label: _showMessage ? 'Hide Message' : 'Show Message',
                ),
                PlatformMenu(
                  label: 'Messages',
                  menus: <PlatformMenuItem>[
                    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.'),
      ),
    );
  }
}

The menus could just as effectively be managed without using the widget tree by using the following code, but mixing this usage with PlatformMenuBar is not recommended, since it will overwrite the menu configuration when it is rebuilt:

List<PlatformMenuItem> menus = <PlatformMenuItem>[ /* Define menus... */ ];
WidgetsBinding.instance.platformMenuDelegate.setMenus(menus);
Inheritance
Mixed-in types

Constructors

PlatformMenuBar({Key? key, required List<PlatformMenuItem> menus, Widget? child})
Creates a const PlatformMenuBar.
const

Properties

child Widget?
The widget below this widget in the tree.
final
hashCode int
The hash code for this object.
no setterinherited
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.
no setterinherited

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 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.
inherited
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 brief description of this object, usually just the runtimeType and the hashCode.
inherited

Operators

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