Add snap-layouts support to the Terminal (microsoft#11680)

Adds snap layout support to the Terminal's maximize button. This PR is
full of BODGY, so brace yourselves.

Big thanks to Chris Swan in microsoft#11134 for building the prototype.
I don't believe this solves microsoft#8795, because XAML islands can't get
nchittest messages

- The window procedure for the drag bar forwards clicks on its client
  area to its parent as non-client clicks.
- BODGY: It also _manually_ handles the caption buttons. They exist in
  the titlebar, and work reasonably well with just XAML, if the drag bar
  isn't covering them.
- However, to get snap layout support, we need to actually return
  `HTMAXBUTTON` where the maximize button is. If the drag bar doesn't
  cover the caption buttons, then the core input site (which takes up
  the entirety of the XAML island) will steal the `WM_NCHITTEST` before
  we get a chance to handle it.
- So, the drag bar covers the caption buttons, and manually handles
  hovering and pressing them when needed. This gives the impression that
  they're getting input as they normally would, even if they're not
  _really_ getting input via XAML.
- We also need to manually display the button tooltips now, because XAML
  doesn't know when they've been hovered for long enough. Hence, the
  `_displayToolTip` `ThrottledFuncTrailing`

## Validation
Minimized, maximized, restored down, hovered the buttons slowly, moved
the mouse over them quickly, they feel the same as before. But now with
snap layouts appearing.

## TODO!
* [x] I'm working on getting the ToolTips on the caption buttons back. Alas, I needed a demo of this _today_, so I'll fix that tomorrow morning.
* [x] mild concern: I should probably test Win 10 to make sure there wasn't weird changes to the message loop in win11 that means this is broken on win10.
* [x] I think I used the wrong issue number for tons of my comments throughout this PR. Double check that. Should be microsoft#9443, not microsoft#9447. 

Closes microsoft#9443
I thought this took care of microsoft#8587 ~as a bonus, because I was here, and the fix is _now_ trivial~, but looking at the latest commit that regressed.

Co-authored-by: Chris Swan <chswan@microsoft.com>

.github/actions/spelling/allow/apis.txt

@@ -43,12 +43,14 @@ fullkbd
 futex
 GETDESKWALLPAPER
 GETHIGHCONTRAST
+GETMOUSEHOVERTIME
 Hashtable
 HIGHCONTRASTON
 HIGHCONTRASTW
 hotkeys
 href
 hrgn
+HTCLOSE
 IActivation
 IApp
 IAppearance
@@ -93,11 +95,14 @@ MENUINFO
 MENUITEMINFOW
 memicmp
 mptt
+MOUSELEAVE
 mov
 msappx
 MULTIPLEUSE
 NCHITTEST
 NCLBUTTONDBLCLK
+NCMOUSELEAVE
+NCMOUSEMOVE
 NCRBUTTONDBLCLK
 NIF
 NIN
@@ -163,9 +168,11 @@ TASKBARCREATED
 TBPF
 THEMECHANGED
 tlg
+TME
 tmp
 tolower
 toupper
+TRACKMOUSEEVENT
 TTask
 TVal
 UChar

src/cascadia/TerminalApp/MinMaxCloseControl.cpp

@@ -1,25 +1,67 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
-//
-// MinMaxCloseControl.xaml.cpp
-// Implementation of the MinMaxCloseControl class
-//
 
 #include "pch.h"
 
 #include "MinMaxCloseControl.h"
-
 #include "MinMaxCloseControl.g.cpp"
-
 #include <LibraryResources.h>
 
 using namespace winrt::Windows::UI::Xaml;
 
 namespace winrt::TerminalApp::implementation
 {
+    static void closeToolTipForButton(const Controls::Button& button)
+    {
+        if (auto tt{ Controls::ToolTipService::GetToolTip(button) })
+        {
+            if (auto tooltip{ tt.try_as<Controls::ToolTip>() })
+            {
+                tooltip.IsOpen(false);
+            }
+        }
+    }
+
     MinMaxCloseControl::MinMaxCloseControl()
     {
+        // Get our dispatcher. This will get us the same dispatcher as
+        // Dispatcher(), but it's a DispatcherQueue, so we can use it with
+        // ThrottledFunc
+        auto dispatcher = winrt::Windows::System::DispatcherQueue::GetForCurrentThread();
+
         InitializeComponent();
+
+        // Get the tooltip hover time from the system, or default to 400ms
+        // (which should be the default, see:
+        // https://docs.microsoft.com/en-us/windows/win32/api/winuser/ns-winuser-trackmouseevent#remarks)
+        unsigned int hoverTimeoutMillis{ 400 };
+        LOG_IF_WIN32_BOOL_FALSE(SystemParametersInfoW(SPI_GETMOUSEHOVERTIME, 0, &hoverTimeoutMillis, 0));
+        const auto toolTipInterval = std::chrono::milliseconds(hoverTimeoutMillis);
+
+        // Create a ThrottledFunc for opening the tooltip after the hover
+        // timeout. If we hover another button, we should make sure to call
+        // Run() with the new button. Calling `_displayToolTip.Run(nullptr)`,
+        // which will cause us to not display a tooltip, which is used when we
+        // leave the control entirely.
+        _displayToolTip = std::make_shared<ThrottledFuncTrailing<Controls::Button>>(
+            dispatcher,
+            toolTipInterval,
+            [weakThis = get_weak()](Controls::Button button) {
+                // If we provide a button, then open the tooltip on that button.
+                // We can "dismiss" this throttled func by calling it with null,
+                // which will cause us to do nothing at the end of the timeout
+                // instead.
+                if (button)
+                {
+                    if (auto tt{ Controls::ToolTipService::GetToolTip(button) })
+                    {
+                        if (auto tooltip{ tt.try_as<Controls::ToolTip>() })
+                        {
+                            tooltip.IsOpen(true);
+                        }
+                    }
+                }
+            });
     }
 
     // These event handlers simply forward each buttons click events up to the
@@ -95,4 +137,104 @@ namespace winrt::TerminalApp::implementation
             break;
         }
     }
+
+    // Method Description:
+    // - Called when the mouse hovers a button.
+    //   - Transition that button to `PointerOver`
+    //   - run the throttled func with this button, to display the tooltip after
+    //     a timeout
+    //   - dismiss any open tooltips on other buttons.
+    // Arguments:
+    // - button: the button that was hovered
+    void MinMaxCloseControl::HoverButton(CaptionButton button)
+    {
+        // Keep track of the button that's been pressed. we get a mouse move
+        // message when we open the tooltip. If we move the mouse on top of this
+        // button, that we've already pressed, then no need to move to the
+        // "hovered" state, we should stay in the pressed state.
+        if (_lastPressedButton && _lastPressedButton.value() == button)
+        {
+            return;
+        }
+
+        switch (button)
+        {
+            // Make sure to use true for the useTransitions parameter, to
+            // animate the fade in/out transition between colors.
+        case CaptionButton::Minimize:
+            VisualStateManager::GoToState(MinimizeButton(), L"PointerOver", true);
+            VisualStateManager::GoToState(MaximizeButton(), L"Normal", true);
+            VisualStateManager::GoToState(CloseButton(), L"Normal", true);
+
+            _displayToolTip->Run(MinimizeButton());
+            closeToolTipForButton(MaximizeButton());
+            closeToolTipForButton(CloseButton());
+            break;
+        case CaptionButton::Maximize:
+            VisualStateManager::GoToState(MinimizeButton(), L"Normal", true);
+            VisualStateManager::GoToState(MaximizeButton(), L"PointerOver", true);
+            VisualStateManager::GoToState(CloseButton(), L"Normal", true);
+
+            closeToolTipForButton(MinimizeButton());
+            _displayToolTip->Run(MaximizeButton());
+            closeToolTipForButton(CloseButton());
+            break;
+        case CaptionButton::Close:
+            VisualStateManager::GoToState(MinimizeButton(), L"Normal", true);
+            VisualStateManager::GoToState(MaximizeButton(), L"Normal", true);
+            VisualStateManager::GoToState(CloseButton(), L"PointerOver", true);
+
+            closeToolTipForButton(MinimizeButton());
+            closeToolTipForButton(MaximizeButton());
+            _displayToolTip->Run(CloseButton());
+            break;
+        }
+    }
+
+    // Method Description:
+    // - Called when the mouse presses down on a button. NOT when it is
+    //   released. That's handled one level above, in
+    //   TitleBarControl::ReleaseButtons
+    //   - Transition that button to `Pressed`
+    // Arguments:
+    // - button: the button that was pressed
+    void MinMaxCloseControl::PressButton(CaptionButton button)
+    {
+        switch (button)
+        {
+        case CaptionButton::Minimize:
+            VisualStateManager::GoToState(MinimizeButton(), L"Pressed", true);
+            VisualStateManager::GoToState(MaximizeButton(), L"Normal", true);
+            VisualStateManager::GoToState(CloseButton(), L"Normal", true);
+            break;
+        case CaptionButton::Maximize:
+            VisualStateManager::GoToState(MinimizeButton(), L"Normal", true);
+            VisualStateManager::GoToState(MaximizeButton(), L"Pressed", true);
+            VisualStateManager::GoToState(CloseButton(), L"Normal", true);
+            break;
+        case CaptionButton::Close:
+            VisualStateManager::GoToState(MinimizeButton(), L"Normal", true);
+            VisualStateManager::GoToState(MaximizeButton(), L"Normal", true);
+            VisualStateManager::GoToState(CloseButton(), L"Pressed", true);
+            break;
+        }
+        _lastPressedButton = button;
+    }
+
+    // Method Description:
+    // - Called when buttons are no longer hovered or pressed. Return them all
+    //   to the normal state, and dismiss the tooltips.
+    void MinMaxCloseControl::ReleaseButtons()
+    {
+        _displayToolTip->Run(nullptr);
+        VisualStateManager::GoToState(MinimizeButton(), L"Normal", true);
+        VisualStateManager::GoToState(MaximizeButton(), L"Normal", true);
+        VisualStateManager::GoToState(CloseButton(), L"Normal", true);
+
+        closeToolTipForButton(MinimizeButton());
+        closeToolTipForButton(MaximizeButton());
+        closeToolTipForButton(CloseButton());
+
+        _lastPressedButton = std::nullopt;
+    }
 }

src/cascadia/TerminalApp/MinMaxCloseControl.h

@@ -6,11 +6,9 @@
 
 #pragma once
 
-#include "winrt/Windows.UI.Xaml.h"
-#include "winrt/Windows.UI.Xaml.Markup.h"
-#include "winrt/Windows.UI.Xaml.Interop.h"
 #include "MinMaxCloseControl.g.h"
 #include "../../cascadia/inc/cppwinrt_utils.h"
+#include <ThrottledFunc.h>
 
 namespace winrt::TerminalApp::implementation
 {
@@ -20,6 +18,10 @@ namespace winrt::TerminalApp::implementation
 
         void SetWindowVisualState(WindowVisualState visualState);
 
+        void HoverButton(CaptionButton button);
+        void PressButton(CaptionButton button);
+        void ReleaseButtons();
+
         void _MinimizeClick(winrt::Windows::Foundation::IInspectable const& sender,
                             winrt::Windows::UI::Xaml::RoutedEventArgs const& e);
         void _MaximizeClick(winrt::Windows::Foundation::IInspectable const& sender,
@@ -30,6 +32,9 @@ namespace winrt::TerminalApp::implementation
         TYPED_EVENT(MinimizeClick, TerminalApp::MinMaxCloseControl, winrt::Windows::UI::Xaml::RoutedEventArgs);
         TYPED_EVENT(MaximizeClick, TerminalApp::MinMaxCloseControl, winrt::Windows::UI::Xaml::RoutedEventArgs);
         TYPED_EVENT(CloseClick, TerminalApp::MinMaxCloseControl, winrt::Windows::UI::Xaml::RoutedEventArgs);
+
+        std::shared_ptr<ThrottledFuncTrailing<winrt::Windows::UI::Xaml::Controls::Button>> _displayToolTip{ nullptr };
+        std::optional<CaptionButton> _lastPressedButton{ std::nullopt };
     };
 }
 

src/cascadia/TerminalApp/MinMaxCloseControl.idl

@@ -11,6 +11,10 @@ namespace TerminalApp
 
         void SetWindowVisualState(WindowVisualState visualState);
 
+        void HoverButton(CaptionButton button);
+        void PressButton(CaptionButton button);
+        void ReleaseButtons();
+
         event Windows.Foundation.TypedEventHandler<MinMaxCloseControl, Windows.UI.Xaml.RoutedEventArgs> MinimizeClick;
         event Windows.Foundation.TypedEventHandler<MinMaxCloseControl, Windows.UI.Xaml.RoutedEventArgs> MaximizeClick;
         event Windows.Foundation.TypedEventHandler<MinMaxCloseControl, Windows.UI.Xaml.RoutedEventArgs> CloseClick;

src/cascadia/TerminalApp/MinMaxCloseControl.xaml

@@ -220,7 +220,7 @@
     </StackPanel.Resources>
 
     <Button x:Name="MinimizeButton"
-            x:Uid="WindowMinimizeButton"
+            x:Uid="MinimizeButton"
             Width="46.0"
             Height="{StaticResource CaptionButtonHeightWindowed}"
             MinWidth="46.0"
@@ -232,9 +232,14 @@
                 <x:String x:Key="CaptionButtonPath">M 0 0 H 10</x:String>
             </ResourceDictionary>
         </Button.Resources>
+        <ToolTipService.ToolTip>
+            <ToolTip>
+                <TextBlock x:Uid="WindowMinimizeButtonToolTip" />
+            </ToolTip>
+        </ToolTipService.ToolTip>
     </Button>
     <Button x:Name="MaximizeButton"
-            x:Uid="WindowMaximizeButton"
+            x:Uid="MaximizeButton"
             Width="46.0"
             Height="{StaticResource CaptionButtonHeightWindowed}"
             MinWidth="46.0"
@@ -256,7 +261,7 @@
         </ToolTipService.ToolTip>
     </Button>
     <Button x:Name="CloseButton"
-            x:Uid="WindowCloseButton"
+            x:Uid="CloseButton"
             Width="46.0"
             Height="{StaticResource CaptionButtonHeightWindowed}"
             MinWidth="46.0"
@@ -309,5 +314,10 @@
                 <x:String x:Key="CaptionButtonPath">M 0 0 L 10 10 M 10 0 L 0 10</x:String>
             </ResourceDictionary>
         </Button.Resources>
+        <ToolTipService.ToolTip>
+            <ToolTip>
+                <TextBlock x:Uid="WindowCloseButtonToolTip" />
+            </ToolTip>
+        </ToolTipService.ToolTip>
     </Button>
 </StackPanel>

src/cascadia/TerminalApp/Resources/en-US/Resources.resw

@@ -411,6 +411,9 @@
   <data name="WindowCloseButton.[using:Windows.UI.Xaml.Controls]ToolTipService.ToolTip" xml:space="preserve">
     <value>Close</value>
   </data>
+  <data name="WindowCloseButtonToolTip.Text" xml:space="preserve">
+    <value>Close</value>
+  </data>
   <data name="WindowMaximizeButton.[using:Windows.UI.Xaml.Automation]AutomationProperties.Name" xml:space="preserve">
     <value>Maximize</value>
   </data>
@@ -420,6 +423,9 @@
   <data name="WindowMinimizeButton.[using:Windows.UI.Xaml.Controls]ToolTipService.ToolTip" xml:space="preserve">
     <value>Minimize</value>
   </data>
+  <data name="WindowMinimizeButtonToolTip.Text" xml:space="preserve">
+    <value>Minimize</value>
+  </data>
   <data name="AboutDialog.Title" xml:space="preserve">
     <value>About</value>
   </data>