Fixes gui-cs#3691 - Adds ViewArrangement.Popover (gui-cs#3852)

* Added Applicaton.Popover.
Refactored FindDeepestView

* Popover prototype

* Testing highlight

* Fixed click outside issue

* Fixed DialogTests

* Fixed click outside issue (agbain)

* Enabled mouse wheel in Bar

* Enabled mouse wheel in Bar

* Progress. Broke arrangement

* Added popover tests.
Fixed a bunch more CM issues related ot unreliable unit tests.
Updated config.json to include Glyphs.

* Can't set ForceDriver to empty in Resources/config.json.

* added BUGBUG

* Made Position/ScreenPosition clear

* Added View.IsInHierarchy tests

* Added Contextmenuv2 scenario.

* Implemented CM2 in TextView

* Removed unneeded CM stuff from testhelpers

* Shortcut API docs

* Fixed keybinding unit tests

* Fixed mouse handling

* Fighting with CM related unit test failures

* Unit tests pass. I think.

* Shortcut code cleanup

* TextView uses new CM2

* Starting on OnSelect etc...

* Starting on OnSelect etc...

* Fixed ContextMenuv2

* ContextMenu is working again.

* Ugh. ANd fixed button api docs

* Fixed DrawHorizontalShadowTransparent (vertical was already fixed).

* Made Scenarios compatible with #nullable enable

* Undid some keybinding stuff

* Fixed stuff

* Sped up unit tests

* Sped up unit tests 2

* Sped up unit tests 3

* Messing with menus

* merged latest v2_develop

* Added more Popover unit tests

* Added more Popover unit tests2

* Fixed positioning bug

* Fixed mouse bug

* Fixed Bar draw issue

* WIP

* merge v2_develop

* CM2 sorta works

* Enabled Bar subclasses to have IDesignable

* Added ViewportSettings.Transparent

* Region -> nullable enable

* Added ViewportSettigs Editor

* merged v2_develop part 2

* merged v2_develop part 3

* WIP: GetViewsUnderMouse

* WIP: More GetViewsUnderMouse work

* Bars works again

* Added unit tests

* CM now works

* MenuItemv2 POC

* SubMenu POC

* CommandNotBound

* More POC

* Optimize Margin to not defer draw if there's no shadow

* Logger cleanup

* Reverted Generic

* Cascading mostly working

* fixed layout bug

* API docs

* API docs

* Fixed cascade

* Events basically work

* code cleanup

* Fixed IsDefault bug;

* Enabled hotkey support

* Made context-menu-like

* Improved usability

* Refactored ApplicationPopover again

* Cleanup

* Menuv2 POC basically complete

* Code Cleanup

* Made menu API simpler

* Fixed Strings bugs

* Got old ContextMenu scenario mostly working

* ContextMenu scenario now works

* ContextMenu fixes

* ContextMenu fixes

* Tons of menu cleanup

* ContextMenu works in TextView

* Fixed unit tes

* Added unit tests

* Fixed tests

* code cleanup

* More code cleanup

* Deep dive

* scenario

* typos

* Demo colorpicker in a Menu

* Added Region tests proving Region is broken in some Union cases

* fixed v2win/net

Author: tig

Terminal.Gui/Application/Application.Initialization.cs

@@ -83,6 +83,7 @@ internal static void InternalInit (
         }
 
         Navigation = new ();
+        Popover = new ();
 
         // For UnitTests
         if (driver is { })
@@ -162,6 +163,12 @@ internal static void InternalInit (
 
         SynchronizationContext.SetSynchronizationContext (new MainLoopSyncContext ());
 
+        // TODO: This is probably not needed
+        if (Popover.GetActivePopover () is View popover)
+        {
+            popover.Visible = false;
+        }
+
         MainThreadId = Thread.CurrentThread.ManagedThreadId;
         bool init = Initialized = true;
         InitializedChanged?.Invoke (null, new (init));
@@ -265,6 +272,6 @@ internal static void UnsubscribeDriverEvents ()
     /// </summary>
     internal static void OnInitializedChanged (object sender, EventArgs<bool> e)
     {
-        Application.InitializedChanged?.Invoke (sender,e);
+        Application.InitializedChanged?.Invoke (sender, e);
     }
 }

Terminal.Gui/Application/Application.Keyboard.cs

@@ -13,13 +13,19 @@ public static partial class Application // Keyboard handling
     /// <returns><see langword="true"/> if the key was handled.</returns>
     public static bool RaiseKeyDownEvent (Key key)
     {
+        // TODO: This should match standard event patterns
         KeyDown?.Invoke (null, key);
 
         if (key.Handled)
         {
             return true;
         }
 
+        if (Popover?.DispatchKeyDown (key) is true)
+        {
+            return true;
+        }
+
         if (Top is null)
         {
             foreach (Toplevel topLevel in TopLevels.ToList ())
@@ -43,6 +49,27 @@ public static bool RaiseKeyDownEvent (Key key)
             }
         }
 
+        bool? commandHandled = InvokeCommandsBoundToKey (key);
+        if(commandHandled is true)
+        {
+            return true;
+        }
+
+        return false;
+    }
+
+    /// <summary>
+    ///     Invokes any commands bound at the Application-level to <paramref name="key"/>.
+    /// </summary>
+    /// <param name="key"></param>
+    /// <returns>
+    ///     <see langword="null"/> if no command was found; input processing should continue.
+    ///     <see langword="false"/> if the command was invoked and was not handled (or cancelled); input processing should continue.
+    ///     <see langword="true"/> if the command was invoked the command was handled (or cancelled); input processing should stop.
+    /// </returns>
+    public static bool? InvokeCommandsBoundToKey (Key key)
+    {
+        bool? handled = null;
         // Invoke any Application-scoped KeyBindings.
         // The first view that handles the key will stop the loop.
         // foreach (KeyValuePair<Key, KeyBinding> binding in KeyBindings.GetBindings (key))
@@ -52,22 +79,17 @@ public static bool RaiseKeyDownEvent (Key key)
             {
                 if (!binding.Target.Enabled)
                 {
-                    return false;
+                    return null;
                 }
 
-                bool? handled = binding.Target?.InvokeCommands (binding.Commands, binding);
-
-                if (handled != null && (bool)handled)
-                {
-                    return true;
-                }
+                handled = binding.Target?.InvokeCommands (binding.Commands, binding);
             }
             else
             {
                 // BUGBUG: this seems unneeded.
                 if (!KeyBindings.TryGet (key, out KeyBinding keybinding))
                 {
-                    return false;
+                    return null;
                 }
 
                 bool? toReturn = null;
@@ -77,30 +99,42 @@ public static bool RaiseKeyDownEvent (Key key)
                     toReturn = InvokeCommand (command, key, keybinding);
                 }
 
-                return toReturn ?? true;
+                handled = toReturn ?? true;
             }
         }
 
-        return false;
+        return handled;
+    }
 
-        static bool? InvokeCommand (Command command, Key key, KeyBinding binding)
+    /// <summary>
+    ///     Invokes an Application-bound commmand.
+    /// </summary>
+    /// <param name="command">The Command to invoke</param>
+    /// <param name="key">The Application-bound Key that was pressed.</param>
+    /// <param name="binding">Describes the binding.</param>
+    /// <returns>
+    ///     <see langword="null"/> if no command was found; input processing should continue.
+    ///     <see langword="false"/> if the command was invoked and was not handled (or cancelled); input processing should continue.
+    ///     <see langword="true"/> if the command was invoked the command was handled (or cancelled); input processing should stop.
+    /// </returns>
+    /// <exception cref="NotSupportedException"></exception>
+    public static bool? InvokeCommand (Command command, Key key, KeyBinding binding)
+    {
+        if (!_commandImplementations!.ContainsKey (command))
         {
-            if (!_commandImplementations!.ContainsKey (command))
-            {
-                throw new NotSupportedException (
-                                                 @$"A KeyBinding was set up for the command {command} ({key}) but that command is not supported by Application."
-                                                );
-            }
-
-            if (_commandImplementations.TryGetValue (command, out View.CommandImplementation? implementation))
-            {
-                CommandContext<KeyBinding> context = new (command, binding); // Create the context here
+            throw new NotSupportedException (
+                                             @$"A KeyBinding was set up for the command {command} ({key}) but that command is not supported by Application."
+                                            );
+        }
 
-                return implementation (context);
-            }
+        if (_commandImplementations.TryGetValue (command, out View.CommandImplementation? implementation))
+        {
+            CommandContext<KeyBinding> context = new (command, null, binding); // Create the context here
 
-            return false;
+            return implementation (context);
         }
+
+        return null;
     }
 
     /// <summary>
@@ -167,7 +201,7 @@ internal static void AddKeyBindings ()
     {
         _commandImplementations.Clear ();
 
-        // Things this view knows how to do
+        // Things Application knows how to do
         AddCommand (
                     Command.Quit,
                     static () =>
@@ -213,7 +247,7 @@ internal static void AddKeyBindings ()
                    );
 
         AddCommand (
-                    Command.Edit,
+                    Command.Arrange,
                     static () =>
                     {
                         View? viewToArrange = Navigation?.GetFocused ();
@@ -249,7 +283,7 @@ internal static void AddKeyBindings ()
         KeyBindings.Add (PrevTabKey, Command.PreviousTabStop);
         KeyBindings.Add (NextTabGroupKey, Command.NextTabGroup);
         KeyBindings.Add (PrevTabGroupKey, Command.PreviousTabGroup);
-        KeyBindings.Add (ArrangeKey, Command.Edit);
+        KeyBindings.Add (ArrangeKey, Command.Arrange);
 
         KeyBindings.Add (Key.CursorRight, Command.NextTabStop);
         KeyBindings.Add (Key.CursorDown, Command.NextTabStop);

Terminal.Gui/Application/Application.Mouse.cs

@@ -1,5 +1,6 @@
 #nullable enable
 using System.ComponentModel;
+using System.Diagnostics;
 
 namespace Terminal.Gui;
 
@@ -168,6 +169,20 @@ internal static void RaiseMouseEvent (MouseEventArgs mouseEvent)
             return;
         }
 
+        // Dismiss the Popover if the user presses mouse outside of it
+        if (mouseEvent.IsPressed
+            && Popover?.GetActivePopover () as View is { Visible: true } visiblePopover
+            && View.IsInHierarchy (visiblePopover, deepestViewUnderMouse, includeAdornments: true) is false)
+        {
+
+            visiblePopover.Visible = false;
+
+            // Recurse once so the event can be handled below the popover
+            RaiseMouseEvent (mouseEvent);
+
+            return;
+        }
+
         if (HandleMouseGrab (deepestViewUnderMouse, mouseEvent))
         {
             return;
@@ -216,6 +231,7 @@ internal static void RaiseMouseEvent (MouseEventArgs mouseEvent)
         else
         {
             // The mouse was outside any View's Viewport.
+            //Debug.Fail ("this should not happen.");
 
             // Debug.Fail ("This should never happen. If it does please file an Issue!!");
 

Terminal.Gui/Application/Application.Popover.cs

@@ -0,0 +1,9 @@
+#nullable enable
+
+namespace Terminal.Gui;
+
+public static partial class Application // Popover handling
+{
+    /// <summary>Gets the Application <see cref="Popover"/> manager.</summary>
+    public static ApplicationPopover? Popover { get; internal set; }
+}

Terminal.Gui/Application/Application.Run.cs

@@ -337,7 +337,7 @@ public static Toplevel Run (Func<Exception, bool>? errorHandler = null, IConsole
     [RequiresUnreferencedCode ("AOT")]
     [RequiresDynamicCode ("AOT")]
     public static T Run<T> (Func<Exception, bool>? errorHandler = null, IConsoleDriver? driver = null)
-        where T : Toplevel, new ()
+        where T : Toplevel, new()
     {
         return ApplicationImpl.Instance.Run<T> (errorHandler, driver);
     }
@@ -426,7 +426,16 @@ public static T Run<T> (Func<Exception, bool>? errorHandler = null, IConsoleDriv
 
     internal static void LayoutAndDrawImpl (bool forceDraw = false)
     {
-        bool neededLayout = View.Layout (TopLevels.Reverse (), Screen.Size);
+        List<View> tops = [..TopLevels];
+
+        if (Popover?.GetActivePopover () as View is { Visible: true } visiblePopover)
+        {
+            visiblePopover.SetNeedsDraw ();
+            visiblePopover.SetNeedsLayout ();
+            tops.Insert (0, visiblePopover);
+        }
+
+        bool neededLayout = View.Layout (tops.ToArray ().Reverse (), Screen.Size);
 
         if (ClearScreenNextIteration)
         {
@@ -440,7 +449,7 @@ internal static void LayoutAndDrawImpl (bool forceDraw = false)
         }
 
         View.SetClipToScreen ();
-        View.Draw (TopLevels, neededLayout || forceDraw);
+        View.Draw (tops, neededLayout || forceDraw);
         View.SetClipToScreen ();
         Driver?.Refresh ();
     }
@@ -555,6 +564,8 @@ public static void End (RunState runState)
     {
         ArgumentNullException.ThrowIfNull (runState);
 
+        Popover?.HidePopover (Popover?.GetActivePopover ());
+
         runState.Toplevel.OnUnloaded ();
 
         // End the RunState.Toplevel

Terminal.Gui/Application/Application.cs

@@ -103,6 +103,7 @@ internal static List<CultureInfo> GetAvailableCulturesFromEmbeddedResources ()
                        .ToList ();
     }
 
+    // BUGBUG: This does not return en-US even though it's supported by default
     internal static List<CultureInfo> GetSupportedCultures ()
     {
         CultureInfo [] cultures = CultureInfo.GetCultures (CultureTypes.AllCultures);
@@ -148,6 +149,12 @@ internal static void ResetState (bool ignoreDisposed = false)
             t!.Running = false;
         }
 
+        if (Popover?.GetActivePopover () is View popover)
+        {
+            popover.Visible = false;
+        }
+        Popover = null;
+
         TopLevels.Clear ();
 #if DEBUG_IDISPOSABLE
 
@@ -197,7 +204,9 @@ internal static void ResetState (bool ignoreDisposed = false)
         Initialized = false;
 
         // Mouse
-        _lastMousePosition = null;
+        // Do not clear _lastMousePosition; Popover's require it to stay set with
+        // last mouse pos.
+        //_lastMousePosition = null;
         _cachedViewsUnderMouse.Clear ();
         WantContinuousButtonPressedView = null;
         MouseEvent = null;

Terminal.Gui/Application/ApplicationNavigation.cs

@@ -104,6 +104,10 @@ internal void SetFocused (View? value)
     /// </returns>
     public bool AdvanceFocus (NavigationDirection direction, TabBehavior? behavior)
     {
+        if (Application.Popover?.GetActivePopover () as View is { Visible: true } visiblePopover)
+        {
+            return visiblePopover.AdvanceFocus (direction, behavior);
+        }
         return Application.Top is { } && Application.Top.AdvanceFocus (direction, behavior);
     }
 }