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