Add support for "Always on top" mode (#6903)

This PR adds support for always on top mode, via two mechanisms:
* The global setting `alwaysOnTop`. When set to true, the window will be
  created in the "topmost" group of windows.  Changing this value will
  hot-reload whether the window is in the topmost group.
* The action `toggleAlwaysOnTop`, which will toggle the `alwaysOnTop`
  property at runtime.

## Detailed Description of the Pull Request / Additional comments

All "topmost" windows maintain an internal z-ordering relative to one
another, but they're all always above all other "non-topmost" windows.
So multiple Windows Terminal windows which are both `alwaysOnTop` will
maintain a z-order relative to one another, but they'll all be on top of
all other windows.

## Validation Steps Performed

Toggled always on top mode, both in the settings and also at runtime,
and verified that it largely did what I expected.

Closes #3038

.github/actions/spell-check/expect/expect.txt

@@ -1530,6 +1530,7 @@ nothrow
 NOTICKS
 NOTIMPL
 notin
+NOTOPMOST
 NOTNULL
 NOTRACK
 NOTSUPPORTED

doc/cascadia/profiles.schema.json

@@ -56,6 +56,7 @@
         "switchToTab",
         "toggleFocusMode",
         "toggleFullscreen",
+        "toggleAlwaysOnTop",
         "toggleRetroEffect",
         "find",
         "setTabColor",
@@ -324,6 +325,11 @@
       "additionalProperties": true,
       "description": "Properties that affect the entire window, regardless of the profile settings.",
       "properties": {
+        "alwaysOnTop": {
+          "default": false,
+          "description": "When set to true, the window is created on top of all other windows. If multiple windows are all \"always on top\", the most recently focused one will be the topmost",
+          "type": "boolean"
+        },
         "alwaysShowTabs": {
           "default": true,
           "description": "When set to true, tabs are always displayed. When set to false and \"showTabsInTitlebar\" is set to false, tabs only appear after opening a new tab.",

src/cascadia/TerminalApp/ActionAndArgs.cpp

@@ -31,6 +31,7 @@ static constexpr std::string_view FindKey{ "find" };
 static constexpr std::string_view ToggleRetroEffectKey{ "toggleRetroEffect" };
 static constexpr std::string_view ToggleFocusModeKey{ "toggleFocusMode" };
 static constexpr std::string_view ToggleFullscreenKey{ "toggleFullscreen" };
+static constexpr std::string_view ToggleAlwaysOnTopKey{ "toggleAlwaysOnTop" };
 static constexpr std::string_view SetTabColorKey{ "setTabColor" };
 static constexpr std::string_view OpenTabColorPickerKey{ "openTabColorPicker" };
 static constexpr std::string_view RenameTabKey{ "renameTab" };
@@ -76,6 +77,7 @@ namespace winrt::TerminalApp::implementation
         { ToggleRetroEffectKey, ShortcutAction::ToggleRetroEffect },
         { ToggleFocusModeKey, ShortcutAction::ToggleFocusMode },
         { ToggleFullscreenKey, ShortcutAction::ToggleFullscreen },
+        { ToggleAlwaysOnTopKey, ShortcutAction::ToggleAlwaysOnTop },
         { SplitPaneKey, ShortcutAction::SplitPane },
         { SetTabColorKey, ShortcutAction::SetTabColor },
         { OpenTabColorPickerKey, ShortcutAction::OpenTabColorPicker },
@@ -256,6 +258,7 @@ namespace winrt::TerminalApp::implementation
                 { ShortcutAction::ToggleRetroEffect, RS_(L"ToggleRetroEffectCommandKey") },
                 { ShortcutAction::ToggleFocusMode, RS_(L"ToggleFocusModeCommandKey") },
                 { ShortcutAction::ToggleFullscreen, RS_(L"ToggleFullscreenCommandKey") },
+                { ShortcutAction::ToggleAlwaysOnTop, RS_(L"ToggleAlwaysOnTopCommandKey") },
                 { ShortcutAction::SplitPane, RS_(L"SplitPaneCommandKey") },
                 { ShortcutAction::Invalid, L"" },
                 { ShortcutAction::Find, RS_(L"FindCommandKey") },

src/cascadia/TerminalApp/AppActionHandlers.cpp

@@ -253,6 +253,13 @@ namespace winrt::TerminalApp::implementation
         args.Handled(true);
     }
 
+    void TerminalPage::_HandleToggleAlwaysOnTop(const IInspectable& /*sender*/,
+                                                const TerminalApp::ActionEventArgs& args)
+    {
+        ToggleAlwaysOnTop();
+        args.Handled(true);
+    }
+
     void TerminalPage::_HandleToggleCommandPalette(const IInspectable& /*sender*/,
                                                    const TerminalApp::ActionEventArgs& args)
     {

src/cascadia/TerminalApp/AppLogic.cpp

@@ -1121,6 +1121,21 @@ namespace winrt::TerminalApp::implementation
         return RS_(L"ApplicationVersionUnknown");
     }
 
+    bool AppLogic::FocusMode() const
+    {
+        return _root ? _root->FocusMode() : false;
+    }
+
+    bool AppLogic::Fullscreen() const
+    {
+        return _root ? _root->Fullscreen() : false;
+    }
+
+    bool AppLogic::AlwaysOnTop() const
+    {
+        return _root ? _root->AlwaysOnTop() : false;
+    }
+
     // -------------------------------- WinRT Events ---------------------------------
     // Winrt events need a method for adding a callback to the event and removing the callback.
     // These macros will define them both for you.

src/cascadia/TerminalApp/AppLogic.h

@@ -33,6 +33,9 @@ namespace winrt::TerminalApp::implementation
 
         winrt::hstring ApplicationDisplayName() const;
         winrt::hstring ApplicationVersion() const;
+        bool FocusMode() const;
+        bool Fullscreen() const;
+        bool AlwaysOnTop() const;
 
         Windows::Foundation::Point GetLaunchDimensions(uint32_t dpi);
         winrt::Windows::Foundation::Point GetLaunchInitialPositions(int32_t defaultInitialX, int32_t defaultInitialY);
@@ -104,8 +107,9 @@ namespace winrt::TerminalApp::implementation
         FORWARDED_TYPED_EVENT(SetTitleBarContent, winrt::Windows::Foundation::IInspectable, winrt::Windows::UI::Xaml::UIElement, _root, SetTitleBarContent);
         FORWARDED_TYPED_EVENT(TitleChanged, winrt::Windows::Foundation::IInspectable, winrt::hstring, _root, TitleChanged);
         FORWARDED_TYPED_EVENT(LastTabClosed, winrt::Windows::Foundation::IInspectable, winrt::TerminalApp::LastTabClosedEventArgs, _root, LastTabClosed);
-        FORWARDED_TYPED_EVENT(ToggleFocusMode, winrt::Windows::Foundation::IInspectable, winrt::TerminalApp::ToggleFocusModeEventArgs, _root, ToggleFocusMode);
-        FORWARDED_TYPED_EVENT(ToggleFullscreen, winrt::Windows::Foundation::IInspectable, winrt::TerminalApp::ToggleFullscreenEventArgs, _root, ToggleFullscreen);
+        FORWARDED_TYPED_EVENT(FocusModeChanged, winrt::Windows::Foundation::IInspectable, winrt::Windows::Foundation::IInspectable, _root, FocusModeChanged);
+        FORWARDED_TYPED_EVENT(FullscreenChanged, winrt::Windows::Foundation::IInspectable, winrt::Windows::Foundation::IInspectable, _root, FullscreenChanged);
+        FORWARDED_TYPED_EVENT(AlwaysOnTopChanged, winrt::Windows::Foundation::IInspectable, winrt::Windows::Foundation::IInspectable, _root, AlwaysOnTopChanged);
     };
 }
 

src/cascadia/TerminalApp/AppLogic.idl

@@ -41,6 +41,10 @@ namespace TerminalApp
         String ApplicationDisplayName { get; };
         String ApplicationVersion { get; };
 
+        Boolean FocusMode { get; };
+        Boolean Fullscreen { get; };
+        Boolean AlwaysOnTop { get; };
+
         Windows.Foundation.Point GetLaunchDimensions(UInt32 dpi);
         Windows.Foundation.Point GetLaunchInitialPositions(Int32 defaultInitialX, Int32 defaultInitialY);
         Windows.UI.Xaml.ElementTheme GetRequestedTheme();
@@ -58,7 +62,8 @@ namespace TerminalApp
         event Windows.Foundation.TypedEventHandler<Object, String> TitleChanged;
         event Windows.Foundation.TypedEventHandler<Object, LastTabClosedEventArgs> LastTabClosed;
         event Windows.Foundation.TypedEventHandler<Object, Windows.UI.Xaml.ElementTheme> RequestedThemeChanged;
-        event Windows.Foundation.TypedEventHandler<Object, ToggleFullscreenEventArgs> ToggleFullscreen;
-        event Windows.Foundation.TypedEventHandler<Object, ToggleFocusModeEventArgs> ToggleFocusMode;
+        event Windows.Foundation.TypedEventHandler<Object, Object> FocusModeChanged;
+        event Windows.Foundation.TypedEventHandler<Object, Object> FullscreenChanged;
+        event Windows.Foundation.TypedEventHandler<Object, Object> AlwaysOnTopChanged;
     }
 }

src/cascadia/TerminalApp/GlobalAppSettings.cpp

@@ -36,6 +36,7 @@ static constexpr std::string_view LaunchModeKey{ "launchMode" };
 static constexpr std::string_view ConfirmCloseAllKey{ "confirmCloseAllTabs" };
 static constexpr std::string_view SnapToGridOnResizeKey{ "snapToGridOnResize" };
 static constexpr std::string_view EnableStartupTaskKey{ "startOnUserLogin" };
+static constexpr std::string_view AlwaysOnTopKey{ "alwaysOnTop" };
 
 static constexpr std::string_view DebugFeaturesKey{ "debugFeatures" };
 
@@ -207,6 +208,8 @@ void GlobalAppSettings::LayerJson(const Json::Value& json)
 
     JsonUtils::GetBool(json, EnableStartupTaskKey, _StartOnUserLogin);
 
+    JsonUtils::GetBool(json, AlwaysOnTopKey, _AlwaysOnTop);
+
     // This is a helper lambda to get the keybindings and commands out of both
     // and array of objects. We'll use this twice, once on the legacy
     // `keybindings` key, and again on the newer `bindings` key.

src/cascadia/TerminalApp/GlobalAppSettings.h

@@ -84,6 +84,7 @@ class TerminalApp::GlobalAppSettings final
     GETSET_PROPERTY(bool, ForceVTInput, false);
     GETSET_PROPERTY(bool, DebugFeaturesEnabled); // default value set in constructor
     GETSET_PROPERTY(bool, StartOnUserLogin, false);
+    GETSET_PROPERTY(bool, AlwaysOnTop, false);
 
 private:
     std::optional<std::wstring> _unparsedDefaultProfile;

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

@@ -399,6 +399,9 @@
   <data name="ToggleFullscreenCommandKey" xml:space="preserve">
     <value>Toggle fullscreen</value>
   </data>
+  <data name="ToggleAlwaysOnTopCommandKey" xml:space="preserve">
+    <value>Toggle always on top mode</value>
+  </data>
   <data name="OpenNewTabDropdownCommandKey" xml:space="preserve">
     <value>Open new tab dropdown</value>
   </data>

src/cascadia/TerminalApp/ShortcutActionDispatch.cpp

@@ -169,6 +169,11 @@ namespace winrt::TerminalApp::implementation
             _ToggleFullscreenHandlers(*this, *eventArgs);
             break;
         }
+        case ShortcutAction::ToggleAlwaysOnTop:
+        {
+            _ToggleAlwaysOnTopHandlers(*this, *eventArgs);
+            break;
+        }
         case ShortcutAction::ToggleCommandPalette:
         {
             _ToggleCommandPaletteHandlers(*this, *eventArgs);

src/cascadia/TerminalApp/ShortcutActionDispatch.h

@@ -49,6 +49,7 @@ namespace winrt::TerminalApp::implementation
         TYPED_EVENT(ToggleRetroEffect,    TerminalApp::ShortcutActionDispatch, TerminalApp::ActionEventArgs);
         TYPED_EVENT(ToggleFocusMode,      TerminalApp::ShortcutActionDispatch, TerminalApp::ActionEventArgs);
         TYPED_EVENT(ToggleFullscreen,     TerminalApp::ShortcutActionDispatch, TerminalApp::ActionEventArgs);
+        TYPED_EVENT(ToggleAlwaysOnTop,    TerminalApp::ShortcutActionDispatch, TerminalApp::ActionEventArgs);
         TYPED_EVENT(ToggleCommandPalette, TerminalApp::ShortcutActionDispatch, TerminalApp::ActionEventArgs);
         TYPED_EVENT(SetTabColor,          TerminalApp::ShortcutActionDispatch, TerminalApp::ActionEventArgs);
         TYPED_EVENT(OpenTabColorPicker,   TerminalApp::ShortcutActionDispatch, TerminalApp::ActionEventArgs);

src/cascadia/TerminalApp/ShortcutActionDispatch.idl

@@ -34,6 +34,7 @@ namespace TerminalApp
         ToggleRetroEffect,
         ToggleFocusMode,
         ToggleFullscreen,
+        ToggleAlwaysOnTop,
         SetTabColor,
         OpenTabColorPicker,
         OpenSettings,
@@ -78,6 +79,7 @@ namespace TerminalApp
         event Windows.Foundation.TypedEventHandler<ShortcutActionDispatch, ActionEventArgs> ToggleRetroEffect;
         event Windows.Foundation.TypedEventHandler<ShortcutActionDispatch, ActionEventArgs> ToggleFocusMode;
         event Windows.Foundation.TypedEventHandler<ShortcutActionDispatch, ActionEventArgs> ToggleFullscreen;
+        event Windows.Foundation.TypedEventHandler<ShortcutActionDispatch, ActionEventArgs> ToggleAlwaysOnTop;
         event Windows.Foundation.TypedEventHandler<ShortcutActionDispatch, ActionEventArgs> ToggleCommandPalette;
         event Windows.Foundation.TypedEventHandler<ShortcutActionDispatch, ActionEventArgs> SetTabColor;
         event Windows.Foundation.TypedEventHandler<ShortcutActionDispatch, ActionEventArgs> OpenTabColorPicker;

src/cascadia/TerminalApp/TerminalPage.cpp

@@ -852,6 +852,7 @@ namespace winrt::TerminalApp::implementation
         _actionDispatch->ToggleRetroEffect({ this, &TerminalPage::_HandleToggleRetroEffect });
         _actionDispatch->ToggleFocusMode({ this, &TerminalPage::_HandleToggleFocusMode });
         _actionDispatch->ToggleFullscreen({ this, &TerminalPage::_HandleToggleFullscreen });
+        _actionDispatch->ToggleAlwaysOnTop({ this, &TerminalPage::_HandleToggleAlwaysOnTop });
         _actionDispatch->ToggleCommandPalette({ this, &TerminalPage::_HandleToggleCommandPalette });
         _actionDispatch->SetTabColor({ this, &TerminalPage::_HandleSetTabColor });
         _actionDispatch->OpenTabColorPicker({ this, &TerminalPage::_HandleOpenTabColorPicker });
@@ -1913,6 +1914,12 @@ namespace winrt::TerminalApp::implementation
             _UpdateTabWidthMode();
             _CreateNewTabFlyout();
         }
+
+        // Reload the current value of alwaysOnTop from the settings file. This
+        // will let the user hot-reload this setting, but any runtime changes to
+        // the alwaysOnTop setting will be lost.
+        _isAlwaysOnTop = _settings->GlobalSettings().AlwaysOnTop();
+        _alwaysOnTopChangedHandlers(*this, nullptr);
     }
 
     // Method Description:
@@ -1969,34 +1976,42 @@ namespace winrt::TerminalApp::implementation
 
     // Method Description:
     // - Toggles borderless mode. Hides the tab row, and raises our
-    //   ToggleFocusMode event.
+    //   FocusModeChanged event.
     // Arguments:
     // - <none>
     // Return Value:
     // - <none>
     void TerminalPage::ToggleFocusMode()
     {
-        _toggleFocusModeHandlers(*this, nullptr);
-
         _isInFocusMode = !_isInFocusMode;
-
         _UpdateTabView();
+        _focusModeChangedHandlers(*this, nullptr);
     }
 
     // Method Description:
     // - Toggles fullscreen mode. Hides the tab row, and raises our
-    //   ToggleFullscreen event.
+    //   FullscreenChanged event.
     // Arguments:
     // - <none>
     // Return Value:
     // - <none>
     void TerminalPage::ToggleFullscreen()
     {
-        _toggleFullscreenHandlers(*this, nullptr);
-
         _isFullscreen = !_isFullscreen;
-
         _UpdateTabView();
+        _fullscreenChangedHandlers(*this, nullptr);
+    }
+
+    // Method Description:
+    // - Toggles always on top mode. Raises our AlwaysOnTopChanged event.
+    // Arguments:
+    // - <none>
+    // Return Value:
+    // - <none>
+    void TerminalPage::ToggleAlwaysOnTop()
+    {
+        _isAlwaysOnTop = !_isAlwaysOnTop;
+        _alwaysOnTopChangedHandlers(*this, nullptr);
     }
 
     // Method Description:
@@ -2187,12 +2202,36 @@ namespace winrt::TerminalApp::implementation
         }
     }
 
+    bool TerminalPage::FocusMode() const
+    {
+        return _isInFocusMode;
+    }
+
+    bool TerminalPage::Fullscreen() const
+    {
+        return _isFullscreen;
+    }
+    // Method Description:
+    // - Returns true if we're currently in "Always on top" mode. When we're in
+    //   always on top mode, the window should be on top of all other windows.
+    //   If multiple windows are all "always on top", they'll maintain their own
+    //   z-order, with all the windows on top of all other non-topmost windows.
+    // Arguments:
+    // - <none>
+    // Return Value:
+    // - true if we should be in "always on top" mode
+    bool TerminalPage::AlwaysOnTop() const
+    {
+        return _isAlwaysOnTop;
+    }
+
     // -------------------------------- WinRT Events ---------------------------------
     // Winrt events need a method for adding a callback to the event and removing the callback.
     // These macros will define them both for you.
     DEFINE_EVENT_WITH_TYPED_EVENT_HANDLER(TerminalPage, TitleChanged, _titleChangeHandlers, winrt::Windows::Foundation::IInspectable, winrt::hstring);
     DEFINE_EVENT_WITH_TYPED_EVENT_HANDLER(TerminalPage, LastTabClosed, _lastTabClosedHandlers, winrt::Windows::Foundation::IInspectable, winrt::TerminalApp::LastTabClosedEventArgs);
     DEFINE_EVENT_WITH_TYPED_EVENT_HANDLER(TerminalPage, SetTitleBarContent, _setTitleBarContentHandlers, winrt::Windows::Foundation::IInspectable, UIElement);
-    DEFINE_EVENT_WITH_TYPED_EVENT_HANDLER(TerminalPage, ToggleFocusMode, _toggleFocusModeHandlers, winrt::Windows::Foundation::IInspectable, winrt::TerminalApp::ToggleFocusModeEventArgs);
-    DEFINE_EVENT_WITH_TYPED_EVENT_HANDLER(TerminalPage, ToggleFullscreen, _toggleFullscreenHandlers, winrt::Windows::Foundation::IInspectable, winrt::TerminalApp::ToggleFullscreenEventArgs);
+    DEFINE_EVENT_WITH_TYPED_EVENT_HANDLER(TerminalPage, FocusModeChanged, _focusModeChangedHandlers, winrt::Windows::Foundation::IInspectable, winrt::Windows::Foundation::IInspectable);
+    DEFINE_EVENT_WITH_TYPED_EVENT_HANDLER(TerminalPage, FullscreenChanged, _fullscreenChangedHandlers, winrt::Windows::Foundation::IInspectable, winrt::Windows::Foundation::IInspectable);
+    DEFINE_EVENT_WITH_TYPED_EVENT_HANDLER(TerminalPage, AlwaysOnTopChanged, _alwaysOnTopChangedHandlers, winrt::Windows::Foundation::IInspectable, winrt::Windows::Foundation::IInspectable);
 }

src/cascadia/TerminalApp/TerminalPage.h

@@ -51,6 +51,10 @@ namespace winrt::TerminalApp::implementation
 
         void ToggleFocusMode();
         void ToggleFullscreen();
+        void ToggleAlwaysOnTop();
+        bool FocusMode() const;
+        bool Fullscreen() const;
+        bool AlwaysOnTop() const;
 
         void SetStartupActions(std::deque<winrt::TerminalApp::ActionAndArgs>& actions);
 
@@ -61,8 +65,9 @@ namespace winrt::TerminalApp::implementation
         DECLARE_EVENT_WITH_TYPED_EVENT_HANDLER(TitleChanged, _titleChangeHandlers, winrt::Windows::Foundation::IInspectable, winrt::hstring);
         DECLARE_EVENT_WITH_TYPED_EVENT_HANDLER(LastTabClosed, _lastTabClosedHandlers, winrt::Windows::Foundation::IInspectable, winrt::TerminalApp::LastTabClosedEventArgs);
         DECLARE_EVENT_WITH_TYPED_EVENT_HANDLER(SetTitleBarContent, _setTitleBarContentHandlers, winrt::Windows::Foundation::IInspectable, winrt::Windows::UI::Xaml::UIElement);
-        DECLARE_EVENT_WITH_TYPED_EVENT_HANDLER(ToggleFocusMode, _toggleFocusModeHandlers, winrt::Windows::Foundation::IInspectable, winrt::TerminalApp::ToggleFocusModeEventArgs);
-        DECLARE_EVENT_WITH_TYPED_EVENT_HANDLER(ToggleFullscreen, _toggleFullscreenHandlers, winrt::Windows::Foundation::IInspectable, winrt::TerminalApp::ToggleFullscreenEventArgs);
+        DECLARE_EVENT_WITH_TYPED_EVENT_HANDLER(FocusModeChanged, _focusModeChangedHandlers, winrt::Windows::Foundation::IInspectable, winrt::Windows::Foundation::IInspectable);
+        DECLARE_EVENT_WITH_TYPED_EVENT_HANDLER(FullscreenChanged, _fullscreenChangedHandlers, winrt::Windows::Foundation::IInspectable, winrt::Windows::Foundation::IInspectable);
+        DECLARE_EVENT_WITH_TYPED_EVENT_HANDLER(AlwaysOnTopChanged, _alwaysOnTopChangedHandlers, winrt::Windows::Foundation::IInspectable, winrt::Windows::Foundation::IInspectable);
         TYPED_EVENT(Initialized, winrt::Windows::Foundation::IInspectable, winrt::Windows::UI::Xaml::RoutedEventArgs);
 
     private:
@@ -87,6 +92,7 @@ namespace winrt::TerminalApp::implementation
 
         bool _isInFocusMode{ false };
         bool _isFullscreen{ false };
+        bool _isAlwaysOnTop{ false };
 
         bool _rearranging;
         std::optional<int> _rearrangeFrom;
@@ -211,6 +217,7 @@ namespace winrt::TerminalApp::implementation
         void _HandleToggleRetroEffect(const IInspectable& sender, const TerminalApp::ActionEventArgs& args);
         void _HandleToggleFocusMode(const IInspectable& sender, const TerminalApp::ActionEventArgs& args);
         void _HandleToggleFullscreen(const IInspectable& sender, const TerminalApp::ActionEventArgs& args);
+        void _HandleToggleAlwaysOnTop(const IInspectable& sender, const TerminalApp::ActionEventArgs& args);
         void _HandleSetTabColor(const IInspectable& sender, const TerminalApp::ActionEventArgs& args);
         void _HandleOpenTabColorPicker(const IInspectable& sender, const TerminalApp::ActionEventArgs& args);
         void _HandleRenameTab(const IInspectable& sender, const TerminalApp::ActionEventArgs& args);