doc comments, and update spec (since I can't update docs yet.)

doc/specs/#653 - Quake Mode/#653 - Quake Mode.md

@@ -1,7 +1,7 @@
 ---
 author: Mike Griese @zadjii-msft
 created on: 2021-02-23
-last updated: 2021-04-21
+last updated: 2021-05-13
 issue id: #653
 ---
 
@@ -132,7 +132,7 @@ the window. To try and satisfy all these scenarios, I'm proposing the following
 two arguments to the `globalSummon` action:
 
 ```json
-"monitor": "any"|"toCurrent"|"onCurrent"|int,
+"monitor": "any"|"toCurrent"|"toMouse"|"onCurrent"|int,
 "desktop": "any"|"toCurrent"|"onCurrent"
 ```
 
@@ -141,8 +141,10 @@ The way these settings can be combined is in a table below. As an overview:
 * `monitor`: This controls the monitor that the window will be summoned from/to
   - `"any"`: Summon the MRU window, regardless of which monitor it's currently
     on.
-  - `"toCurrent"`/omitted: (_default_): Summon the MRU window **TO** the current
-    monitor.
+  - `"toCurrent"`/omitted: (_default_): Summon the MRU window **TO** the monitor
+    with the current **foreground** window.
+  - `"toMouse"`: Summon the MRU window **TO** the monitor where the **mouse**
+    cursor is.
   - `"onCurrent"`: Summon the MRU window **ALREADY ON** the current monitor.
   - `int`: Summon the MRU window for the given monitor (as identified by the
     "Identify" displays feature in the OS settings)
@@ -193,16 +195,33 @@ Else:
 </tr>
 <!-- ----------------------------------------------------------------------- -->
 <tr>
-<td><code>"toCurrent"</code><br> Summon the MRU window TO the current monitor</td>
-<td>Go to the desktop the window is on, move to this monitor</td>
-<td>Move the window to this desktop, move to this monitor</td>
+<td><code>"toCurrent"</code><br> Summon the MRU window TO the monitor with the foreground window</td>
+<td>Go to the desktop the window is on, move to the monitor with the foreground window</td>
+<td>Move the window to this desktop, move to the monitor with the foreground window</td>
+<td>
+
+If there isn't one on this desktop:
+* create a new one (on the monitor with the foreground window)
+
+Else:
+* activate the one on this desktop, move to the monitor with the foreground window
+</td>
+</tr>
+<!-- ----------------------------------------------------------------------- -->
+<tr>
+<td>
+  <code>"toMouse"</code>
+  <sup><a href="#footnote-2">[2]</a></sup> <br>
+  Summon the MRU window TO the monitor with the mouse</td>
+<td>Go to the desktop the window is on, move to the monitor with the mouse</td>
+<td>Move the window to this desktop, move to the monitor with the mouse</td>
 <td>
 
 If there isn't one on this desktop:
-* create a new one (on this monitor)
+* create a new one (on the monitor with the mouse)
 
 Else:
-* activate the one on this desktop, move to this window
+* activate the one on this desktop, move to the monitor with the mouse
 </td>
 </tr>
 <!-- ----------------------------------------------------------------------- -->
@@ -673,6 +692,8 @@ aren't already included in this spec.
   ```
   That would allow the user some further customizations on the quake mode
   behaviors.
+  - This was later converted to the idea in [#9992] - Add per-window-name global
+    settings
 * Another proposed idea was a simplification of some of the summoning modes. `{
   "monitor": "any", "desktop": "any" }` is a little long, and maybe not the most
   apparent naming. Perhaps we could add another property like `summonMode` that
@@ -698,9 +719,16 @@ windows. Once [#766] lands, this will give us a chance to persist the state of
 _all_ open windows. This will allow us to re-open with all the user's windows,
 not just the one that happened to be closed last.
 
+<a name="footnote-2"><a>[2]: **Addenda, May 2021**: In the course of
+implementation, it became apparent that there's an important UX differenct
+between summoning _to the monitor with the cursor_ vs _to the monitor with the
+foreground window_. `"monitor": "toMouse"` was added as an option, to allow the
+user to differentiate between the two behaviors.
+
 [#653]: https://github.com/microsoft/terminal/issues/653
 [#766]: https://github.com/microsoft/terminal/issues/766
 [#5727]: https://github.com/microsoft/terminal/issues/5727
+[#9992]: https://github.com/microsoft/terminal/issues/9992
 
 [Process Model 2.0 Spec]: https://github.com/microsoft/terminal/blob/main/doc/specs/%235000%20-%20Process%20Model%202.0/%235000%20-%20Process%20Model%202.0.md
 [Quake 3 sample]: https://youtu.be/ZmR6HQbuHPA?t=27

src/cascadia/TerminalSettingsModel/ActionArgs.h

@@ -1158,7 +1158,7 @@ namespace winrt::Microsoft::Terminal::Settings::Model::implementation
         GlobalSummonArgs() = default;
         WINRT_PROPERTY(winrt::hstring, Name, L"");
         WINRT_PROPERTY(Model::DesktopBehavior, Desktop, Model::DesktopBehavior::ToCurrent);
-        WINRT_PROPERTY(Model::MonitorBehavior, Monitor, Model::MonitorBehavior::ToCurrent);
+        WINRT_PROPERTY(Model::MonitorBehavior, Monitor, Model::MonitorBehavior::ToMouse);
         WINRT_PROPERTY(bool, ToggleVisibility, true);
         WINRT_PROPERTY(uint32_t, DropdownDuration, 0);
 

src/cascadia/WindowsTerminal/IslandWindow.cpp

@@ -1250,6 +1250,12 @@ void IslandWindow::_globalDismissWindow(const uint32_t dropdownDuration)
     }
 }
 
+// Method Description:
+// - Get the monitor the mouse cursor is currently on
+// Arguments:
+// - <none>
+// Return Value:
+// - The MONITORINFO for the monitor the mosue cursor is on
 MONITORINFO IslandWindow::_getMonitorForCursor()
 {
     POINT p{};
@@ -1262,6 +1268,12 @@ MONITORINFO IslandWindow::_getMonitorForCursor()
     return activeMonitor;
 }
 
+// Method Description:
+// - Get the monitor for a given HWND
+// Arguments:
+// - <none>
+// Return Value:
+// - The MONITORINFO for the given HWND
 MONITORINFO IslandWindow::_getMonitorForWindow(HWND foregroundWindow)
 {
     // Get the monitor info for the window's current monitor.
@@ -1271,6 +1283,15 @@ MONITORINFO IslandWindow::_getMonitorForWindow(HWND foregroundWindow)
     return activeMonitor;
 }
 
+// Method Description:
+// - Based on the value in toMonitor, move the window to the monitor of the
+//   given HWND, the monitor of the mouse pointer, or just leave it where it is.
+// Arguments:
+// - oldForegroundWindow: when toMonitor is ToCurrent, we'll move to the monitor
+//   of this HWND. Otherwise, this param is ignored.
+// - toMonitor: Controls which monitor we should move to.
+// Return Value:
+// - <none>
 void IslandWindow::_moveToMonitor(HWND oldForegroundWindow, Remoting::MonitorBehavior toMonitor)
 {
     if (toMonitor == Remoting::MonitorBehavior::ToCurrent)
@@ -1282,16 +1303,38 @@ void IslandWindow::_moveToMonitor(HWND oldForegroundWindow, Remoting::MonitorBeh
         _moveToMonitorOfMouse();
     }
 }
+
+// Method Description:
+// - Move our window to the monitor the mouse is on.
+// Arguments:
+// - <none>
+// Return Value:
+// - <none>
 void IslandWindow::_moveToMonitorOfMouse()
 {
     _moveToMonitor(_getMonitorForCursor());
 }
 
+// Method Description:
+// - Move our window to the monitor that the giben HWND is on.
+// Arguments:
+// - <none>
+// Return Value:
+// - <none>
 void IslandWindow::_moveToMonitorOf(HWND foregroundWindow)
 {
     _moveToMonitor(_getMonitorForWindow(foregroundWindow));
 }
 
+// Method Description:
+// - Move our window to the given monitor. This will do nothing if we're already
+//   on that monitor.
+// - We'll retain the same relative position on the new monitor as we had on the
+//   old monitor.
+// Arguments:
+// - activeMonitor: the monitor to move to.
+// Return Value:
+// - <none>
 void IslandWindow::_moveToMonitor(const MONITORINFO activeMonitor)
 {
     // Get the monitor info for the window's current monitor.