Add desktop param to globalSummon; set _quake = toCurrent (#9954)

This adds support for the `desktop` param to the `globalSummon` action. It accepts 3 values:
* `toCurrent` (default): The window moves to the current desktop when it's summoned
* `any`: We don't care what desktop the window is on. We'll go to the desktop the window is on when we summon it.
* `onCurrent`: We'll only try to summon the MRU window on this desktop when summoning a window. 
  * When combined with `name`, if there's a window matching `name`, we'll move it to this desktop. 
  * If there's not a window on this desktop, and `name` is omitted, then we'll make a new window.

`quakeMode` was also updated to use `toCurrent` behavior by default.

## References
* Original thread: #653
* Spec: #9274 
* megathread: #8888

## PR Checklist
* [x] Checks some boxes in #8888
* [x] closes https://github.com/microsoft/terminal/projects/5#card-59030845
* [x] I work here
* [x] Tests added 
* [n/a] Requires documentation to be updated

## Detailed Description of the Pull Request / Additional comments

S/O to https://github.com/microsoft/PowerToys, who graciously let us use `VirtualDesktopUtils` for figuring out what desktop is the current desktop. Yea, that's all we needed that entire file for. No, there isn't an API for this (_surprised-pikachu.png_)

## Validation Steps Performed

Played with this for a while, and it's amazing.

NOTICE.md

@@ -251,3 +251,33 @@ ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 DEALINGS IN THE SOFTWARE.
 
 ```
+
+## `VirtualDesktopUtils`
+
+**Source**: [https://github.com/microsoft/PowerToys](https://github.com/microsoft/PowerToys)
+
+### License
+
+```
+The MIT License
+
+Copyright (c) Microsoft Corporation. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+```

src/cascadia/Remoting/Microsoft.Terminal.RemotingLib.vcxproj

@@ -28,6 +28,9 @@
     <ClInclude Include="SummonWindowSelectionArgs.h">
       <DependentUpon>Monarch.idl</DependentUpon>
     </ClInclude>
+    <ClInclude Include="SummonWindowBehavior.h">
+      <DependentUpon>Peasant.idl</DependentUpon>
+    </ClInclude>
     <ClInclude Include="RenameRequestArgs.h">
       <DependentUpon>Peasant.idl</DependentUpon>
     </ClInclude>
@@ -60,6 +63,9 @@
     <ClCompile Include="SummonWindowSelectionArgs.cpp">
       <DependentUpon>Monarch.idl</DependentUpon>
     </ClCompile>
+    <ClCompile Include="SummonWindowBehavior.cpp">
+      <DependentUpon>Peasant.idl</DependentUpon>
+    </ClCompile>
     <ClCompile Include="RenameRequestArgs.cpp">
       <DependentUpon>Peasant.idl</DependentUpon>
     </ClCompile>

src/cascadia/Remoting/Monarch.cpp

@@ -711,7 +711,10 @@ namespace winrt::Microsoft::Terminal::Remoting::implementation
             // If no name was provided, then just summon the MRU window.
             if (searchedForName.empty())
             {
-                windowId = _getMostRecentPeasantID(true);
+                // Use the value of the `desktop` arg to determine if we should
+                // limit to the current desktop (desktop:onCurrent) or not
+                // (desktop:any or desktop:toCurrent)
+                windowId = _getMostRecentPeasantID(args.OnCurrentDesktop());
             }
             else
             {
@@ -720,7 +723,7 @@ namespace winrt::Microsoft::Terminal::Remoting::implementation
             }
             if (auto targetPeasant{ _getPeasant(windowId) })
             {
-                targetPeasant.Summon();
+                targetPeasant.Summon(args.SummonBehavior());
                 args.FoundMatch(true);
             }
         }

src/cascadia/Remoting/Monarch.idl

@@ -22,13 +22,15 @@ namespace Microsoft.Terminal.Remoting
         SummonWindowSelectionArgs();
         SummonWindowSelectionArgs(String windowName);
         String WindowName;
+        Boolean OnCurrentDesktop;
         // TODO GH#8888 Other options:
-        // * CurrentDesktop
         // * CurrentMonitor
 
         Boolean FoundMatch;
+        SummonWindowBehavior SummonBehavior;
     }
 
+
     [default_interface] runtimeclass Monarch {
         Monarch();
 

src/cascadia/Remoting/Peasant.cpp

@@ -4,6 +4,7 @@
 #include "pch.h"
 #include "Peasant.h"
 #include "CommandlineArgs.h"
+#include "SummonWindowBehavior.h"
 #include "Peasant.g.cpp"
 #include "../../types/inc/utils.hpp"
 
@@ -126,14 +127,17 @@ namespace winrt::Microsoft::Terminal::Remoting::implementation
     // - <none>
     // Return Value:
     // - <none>
-    void Peasant::Summon()
+    void Peasant::Summon(const Remoting::SummonWindowBehavior& summonBehavior)
     {
-        _SummonRequestedHandlers(*this, nullptr);
+        auto localCopy = winrt::make<implementation::SummonWindowBehavior>(summonBehavior);
 
         TraceLoggingWrite(g_hRemotingProvider,
                           "Peasant_Summon",
                           TraceLoggingUInt64(GetID(), "peasantID", "Our ID"),
+                          TraceLoggingUInt64(localCopy->MoveToCurrentDesktop(), "MoveToCurrentDesktop", "true if we should move to the current desktop"),
                           TraceLoggingLevel(WINEVENT_LEVEL_VERBOSE));
+
+        _SummonRequestedHandlers(*this, localCopy);
     }
 
     // Method Description:

src/cascadia/Remoting/Peasant.h

@@ -24,7 +24,7 @@ namespace winrt::Microsoft::Terminal::Remoting::implementation
         bool ExecuteCommandline(const winrt::Microsoft::Terminal::Remoting::CommandlineArgs& args);
         void ActivateWindow(const winrt::Microsoft::Terminal::Remoting::WindowActivatedArgs& args);
 
-        void Summon();
+        void Summon(const Remoting::SummonWindowBehavior& summonBehavior);
         void RequestIdentifyWindows();
         void DisplayWindowId();
         void RequestRename(const winrt::Microsoft::Terminal::Remoting::RenameRequestArgs& args);
@@ -39,7 +39,7 @@ namespace winrt::Microsoft::Terminal::Remoting::implementation
         TYPED_EVENT(IdentifyWindowsRequested, winrt::Windows::Foundation::IInspectable, winrt::Windows::Foundation::IInspectable);
         TYPED_EVENT(DisplayWindowIdRequested, winrt::Windows::Foundation::IInspectable, winrt::Windows::Foundation::IInspectable);
         TYPED_EVENT(RenameRequested, winrt::Windows::Foundation::IInspectable, winrt::Microsoft::Terminal::Remoting::RenameRequestArgs);
-        TYPED_EVENT(SummonRequested, winrt::Windows::Foundation::IInspectable, winrt::Windows::Foundation::IInspectable);
+        TYPED_EVENT(SummonRequested, winrt::Windows::Foundation::IInspectable, winrt::Microsoft::Terminal::Remoting::SummonWindowBehavior);
 
     private:
         Peasant(const uint64_t testPID);

src/cascadia/Remoting/Peasant.idl

@@ -30,6 +30,13 @@ namespace Microsoft.Terminal.Remoting
         Windows.Foundation.DateTime ActivatedTime { get; };
     };
 
+    [default_interface] runtimeclass SummonWindowBehavior {
+        SummonWindowBehavior();
+        Boolean MoveToCurrentDesktop;
+        // Other options:
+        // * CurrentMonitor
+    }
+
     interface IPeasant
     {
         CommandlineArgs InitialArgs { get; };
@@ -46,14 +53,14 @@ namespace Microsoft.Terminal.Remoting
         String WindowName { get; };
         void RequestIdentifyWindows(); // Tells us to raise a IdentifyWindowsRequested
         void RequestRename(RenameRequestArgs args); // Tells us to raise a RenameRequested
-        void Summon();
+        void Summon(SummonWindowBehavior behavior);
 
         event Windows.Foundation.TypedEventHandler<Object, WindowActivatedArgs> WindowActivated;
         event Windows.Foundation.TypedEventHandler<Object, CommandlineArgs> ExecuteCommandlineRequested;
         event Windows.Foundation.TypedEventHandler<Object, Object> IdentifyWindowsRequested;
         event Windows.Foundation.TypedEventHandler<Object, Object> DisplayWindowIdRequested;
         event Windows.Foundation.TypedEventHandler<Object, RenameRequestArgs> RenameRequested;
-        event Windows.Foundation.TypedEventHandler<Object, Object> SummonRequested;
+        event Windows.Foundation.TypedEventHandler<Object, SummonWindowBehavior> SummonRequested;
     };
 
     [default_interface] runtimeclass Peasant : IPeasant

src/cascadia/Remoting/SummonWindowBehavior.cpp

@@ -0,0 +1,5 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+#include "pch.h"
+#include "SummonWindowBehavior.h"
+#include "SummonWindowBehavior.g.cpp"

src/cascadia/Remoting/SummonWindowBehavior.h

@@ -0,0 +1,35 @@
+/*++
+Copyright (c) Microsoft Corporation
+Licensed under the MIT license.
+
+Class Name:
+- SummonWindowBehavior.h
+
+Abstract:
+- TODO!
+
+--*/
+
+#pragma once
+
+#include "SummonWindowBehavior.g.h"
+#include "../cascadia/inc/cppwinrt_utils.h"
+
+namespace winrt::Microsoft::Terminal::Remoting::implementation
+{
+    struct SummonWindowBehavior : public SummonWindowBehaviorT<SummonWindowBehavior>
+    {
+    public:
+        SummonWindowBehavior() = default;
+        WINRT_PROPERTY(bool, MoveToCurrentDesktop, true);
+
+    public:
+        SummonWindowBehavior(const Remoting::SummonWindowBehavior& other) :
+            _MoveToCurrentDesktop{ other.MoveToCurrentDesktop() } {};
+    };
+}
+
+namespace winrt::Microsoft::Terminal::Remoting::factory_implementation
+{
+    BASIC_FACTORY(SummonWindowBehavior);
+}

src/cascadia/Remoting/SummonWindowSelectionArgs.h

@@ -30,7 +30,10 @@ namespace winrt::Microsoft::Terminal::Remoting::implementation
             _WindowName{ name } {};
 
         WINRT_PROPERTY(winrt::hstring, WindowName);
+
         WINRT_PROPERTY(bool, FoundMatch, false);
+        WINRT_PROPERTY(bool, OnCurrentDesktop, false);
+        WINRT_PROPERTY(SummonWindowBehavior, SummonBehavior);
     };
 }
 

src/cascadia/TerminalSettingsModel/ActionArgs.h

@@ -1044,17 +1044,20 @@ namespace winrt::Microsoft::Terminal::Settings::Model::implementation
     {
         GlobalSummonArgs() = default;
         WINRT_PROPERTY(winrt::hstring, Name, L"");
+        WINRT_PROPERTY(Model::DesktopBehavior, Desktop, Model::DesktopBehavior::ToCurrent);
 
         static constexpr std::string_view NameKey{ "name" };
+        static constexpr std::string_view DesktopKey{ "desktop" };
 
     public:
         hstring GenerateName() const;
 
         bool Equals(const IActionArgs& other)
         {
-            if (auto otherAsUs = other.try_as<GlobalSummonArgs>(); otherAsUs)
+            if (auto otherAsUs = other.try_as<GlobalSummonArgs>())
             {
-                return otherAsUs->_Name == _Name;
+                return otherAsUs->_Name == _Name &&
+                       otherAsUs->_Desktop == _Desktop;
             }
             return false;
         };
@@ -1063,12 +1066,14 @@ namespace winrt::Microsoft::Terminal::Settings::Model::implementation
             // LOAD BEARING: Not using make_self here _will_ break you in the future!
             auto args = winrt::make_self<GlobalSummonArgs>();
             JsonUtils::GetValueForKey(json, NameKey, args->_Name);
+            JsonUtils::GetValueForKey(json, DesktopKey, args->_Desktop);
             return { *args, {} };
         }
         IActionArgs Copy() const
         {
             auto copy{ winrt::make_self<GlobalSummonArgs>() };
             copy->_Name = _Name;
+            copy->_Desktop = _Desktop;
             return *copy;
         }
         // SPECIAL! This deserializer creates a GlobalSummonArgs with the

src/cascadia/TerminalSettingsModel/ActionArgs.idl

@@ -84,6 +84,13 @@ namespace Microsoft.Terminal.Settings.Model
         Disabled,
     };
 
+    enum DesktopBehavior
+    {
+        Any,
+        ToCurrent,
+        OnCurrent,
+    };
+
     [default_interface] runtimeclass NewTerminalArgs {
         NewTerminalArgs();
         NewTerminalArgs(Int32 profileIndex);
@@ -256,5 +263,6 @@ namespace Microsoft.Terminal.Settings.Model
     [default_interface] runtimeclass GlobalSummonArgs : IActionArgs
     {
         String Name { get; };
+        DesktopBehavior Desktop { get; };
     };
 }

src/cascadia/TerminalSettingsModel/TerminalSettingsSerializationHelpers.h

@@ -448,3 +448,12 @@ JSON_ENUM_MAPPER(::winrt::Microsoft::Terminal::Settings::Model::WindowingMode)
         pair_type{ "useExisting", ValueType::UseExisting },
     };
 };
+
+JSON_ENUM_MAPPER(::winrt::Microsoft::Terminal::Settings::Model::DesktopBehavior)
+{
+    JSON_MAPPINGS(3) = {
+        pair_type{ "any", ValueType::Any },
+        pair_type{ "toCurrent", ValueType::ToCurrent },
+        pair_type{ "onCurrent", ValueType::OnCurrent },
+    };
+};