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 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';
/// 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
-
- Object
- DiagnosticableTree
- Widget
- StatefulWidget
- PlatformMenuBar
- Mixed in types
Constructors
- PlatformMenuBar({Key? key, 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}) → 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