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 | |
5 | import 'framework.dart'; |
6 | import 'inherited_theme.dart'; |
7 | import 'navigator.dart'; |
8 | import '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. |
27 | class 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 | |