1// Copyright 2014 The Flutter Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5import 'framework.dart';
6import 'inherited_theme.dart';
7import 'navigator.dart';
8import 'overlay.dart';
9
10/// Builds and manages a context menu at a given location.
11///
12/// There can only ever be one context menu shown at a given time in the entire
13/// app. Calling [show] on one instance of this class will hide any other
14/// shown instances.
15///
16/// {@tool dartpad}
17/// This example shows how to use a GestureDetector to show a context menu
18/// anywhere in a widget subtree that receives a right click or long press.
19///
20/// ** See code in examples/api/lib/material/context_menu/context_menu_controller.0.dart **
21/// {@end-tool}
22///
23/// See also:
24///
25/// * [BrowserContextMenu], which allows the browser's context menu on web to
26/// be disabled and Flutter-rendered context menus to appear.
27class ContextMenuController {
28 /// Creates a context menu that can be shown with [show].
29 ContextMenuController({
30 this.onRemove,
31 });
32
33 /// Called when this menu is removed.
34 final VoidCallback? onRemove;
35
36 /// The currently shown instance, if any.
37 static ContextMenuController? _shownInstance;
38
39 // The OverlayEntry is static because only one context menu can be displayed
40 // at one time.
41 static OverlayEntry? _menuOverlayEntry;
42
43 /// Shows the given context menu.
44 ///
45 /// Since there can only be one shown context menu at a time, calling this
46 /// will also remove any other context menu that is visible.
47 void show({
48 required BuildContext context,
49 required WidgetBuilder contextMenuBuilder,
50 Widget? debugRequiredFor,
51 }) {
52 removeAny();
53 final OverlayState overlayState = Overlay.of(
54 context,
55 rootOverlay: true,
56 debugRequiredFor: debugRequiredFor,
57 );
58 final CapturedThemes capturedThemes = InheritedTheme.capture(
59 from: context,
60 to: Navigator.maybeOf(context)?.context,
61 );
62
63 _menuOverlayEntry = OverlayEntry(
64 builder: (BuildContext context) {
65 return capturedThemes.wrap(contextMenuBuilder(context));
66 },
67 );
68 overlayState.insert(_menuOverlayEntry!);
69 _shownInstance = this;
70 }
71
72 /// Remove the currently shown context menu from the UI.
73 ///
74 /// Does nothing if no context menu is currently shown.
75 ///
76 /// If a menu is removed, and that menu provided an [onRemove] callback when
77 /// it was created, then that callback will be called.
78 ///
79 /// See also:
80 ///
81 /// * [remove], which removes only the current instance.
82 static void removeAny() {
83 _menuOverlayEntry?.remove();
84 _menuOverlayEntry?.dispose();
85 _menuOverlayEntry = null;
86 if (_shownInstance != null) {
87 _shownInstance!.onRemove?.call();
88 _shownInstance = null;
89 }
90 }
91
92 /// True if and only if this menu is currently being shown.
93 bool get isShown => _shownInstance == this;
94
95 /// Cause the underlying [OverlayEntry] to rebuild during the next pipeline
96 /// flush.
97 ///
98 /// It's necessary to call this function if the output of [contextMenuBuilder]
99 /// has changed.
100 ///
101 /// Errors if the context menu is not currently shown.
102 ///
103 /// See also:
104 ///
105 /// * [OverlayEntry.markNeedsBuild]
106 void markNeedsBuild() {
107 assert(isShown);
108 _menuOverlayEntry?.markNeedsBuild();
109 }
110
111 /// Remove this menu from the UI.
112 ///
113 /// Does nothing if this instance is not currently shown. In other words, if
114 /// another context menu is currently shown, that menu will not be removed.
115 ///
116 /// This method should only be called once. The instance cannot be shown again
117 /// after removing. Create a new instance.
118 ///
119 /// If an [onRemove] method was given to this instance, it will be called.
120 ///
121 /// See also:
122 ///
123 /// * [removeAny], which removes any shown instance of the context menu.
124 void remove() {
125 if (!isShown) {
126 return;
127 }
128 removeAny();
129 }
130}
131