Dim the caption buttons for unfocused windows (#19668)

Aliremu · DHowett · commit d14747ff2db6 · 2026-01-21T18:24:38.000-06:00
This PR closes #12632 by dimming the caption controls in the titlebar when unfocused. Leaves them intact when in high contrast mode. The color used is borrowed from PowerToys' unfocused color. ## Validation Steps Performed Tested by hovering and unhovering in focused and unfocused states, as well as in high contrast mode. States are consistent and applied correctly. I did notice that clicking on the titlebar wouldn't put it into focus unless I also moved my mouse though, but that is also present in the release branch. Closes #12632 (cherry picked from commit 8d94edd) Service-Card-Id: PVTI_lADOAF3p4s4AxadtzgkC_KQ Service-Version: 1.23
diff --git a/.github/actions/spelling/expect/expect.txt b/.github/actions/spelling/expect/expect.txt
@@ -1121,6 +1121,7 @@ Mypair
 Myval
 NAMELENGTH
 namestream
+NCACTIVATE
 NCCALCSIZE
 NCCREATE
 NCLBUTTONDOWN
diff --git a/src/cascadia/TerminalApp/MinMaxCloseControl.cpp b/src/cascadia/TerminalApp/MinMaxCloseControl.cpp
@@ -89,6 +89,18 @@ namespace winrt::TerminalApp::implementation
         CloseClick.raise(*this, e);
     }
 
+    bool MinMaxCloseControl::Focused() const
+    {
+        return _focused;
+    }
+
+    void MinMaxCloseControl::Focused(bool focused)
+    {
+        _focused = focused;
+
+        ReleaseButtons();
+    }
+
     void MinMaxCloseControl::SetWindowVisualState(WindowVisualState visualState)
     {
         // Look up the heights we should use for the caption buttons from our
@@ -170,25 +182,25 @@ namespace winrt::TerminalApp::implementation
             // 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);
+            VisualStateManager::GoToState(MaximizeButton(), _normalState(), true);
+            VisualStateManager::GoToState(CloseButton(), _normalState(), true);
 
             _displayToolTip->Run(MinimizeButton());
             closeToolTipForButton(MaximizeButton());
             closeToolTipForButton(CloseButton());
             break;
         case CaptionButton::Maximize:
-            VisualStateManager::GoToState(MinimizeButton(), L"Normal", true);
+            VisualStateManager::GoToState(MinimizeButton(), _normalState(), true);
             VisualStateManager::GoToState(MaximizeButton(), L"PointerOver", true);
-            VisualStateManager::GoToState(CloseButton(), L"Normal", true);
+            VisualStateManager::GoToState(CloseButton(), _normalState(), 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(MinimizeButton(), _normalState(), true);
+            VisualStateManager::GoToState(MaximizeButton(), _normalState(), true);
             VisualStateManager::GoToState(CloseButton(), L"PointerOver", true);
 
             closeToolTipForButton(MinimizeButton());
@@ -211,17 +223,17 @@ namespace winrt::TerminalApp::implementation
         {
         case CaptionButton::Minimize:
             VisualStateManager::GoToState(MinimizeButton(), L"Pressed", true);
-            VisualStateManager::GoToState(MaximizeButton(), L"Normal", true);
-            VisualStateManager::GoToState(CloseButton(), L"Normal", true);
+            VisualStateManager::GoToState(MaximizeButton(), _normalState(), true);
+            VisualStateManager::GoToState(CloseButton(), _normalState(), true);
             break;
         case CaptionButton::Maximize:
-            VisualStateManager::GoToState(MinimizeButton(), L"Normal", true);
+            VisualStateManager::GoToState(MinimizeButton(), _normalState(), true);
             VisualStateManager::GoToState(MaximizeButton(), L"Pressed", true);
-            VisualStateManager::GoToState(CloseButton(), L"Normal", true);
+            VisualStateManager::GoToState(CloseButton(), _normalState(), true);
             break;
         case CaptionButton::Close:
-            VisualStateManager::GoToState(MinimizeButton(), L"Normal", true);
-            VisualStateManager::GoToState(MaximizeButton(), L"Normal", true);
+            VisualStateManager::GoToState(MinimizeButton(), _normalState(), true);
+            VisualStateManager::GoToState(MaximizeButton(), _normalState(), true);
             VisualStateManager::GoToState(CloseButton(), L"Pressed", true);
             break;
         }
@@ -234,14 +246,21 @@ namespace winrt::TerminalApp::implementation
     void MinMaxCloseControl::ReleaseButtons()
     {
         _displayToolTip->Run(nullptr);
-        VisualStateManager::GoToState(MinimizeButton(), L"Normal", true);
-        VisualStateManager::GoToState(MaximizeButton(), L"Normal", true);
-        VisualStateManager::GoToState(CloseButton(), L"Normal", true);
+        VisualStateManager::GoToState(MinimizeButton(), _normalState(), true);
+        VisualStateManager::GoToState(MaximizeButton(), _normalState(), true);
+        VisualStateManager::GoToState(CloseButton(), _normalState(), true);
 
         closeToolTipForButton(MinimizeButton());
         closeToolTipForButton(MaximizeButton());
         closeToolTipForButton(CloseButton());
 
         _lastPressedButton = std::nullopt;
     }
+
+    const winrt::param::hstring& MinMaxCloseControl::_normalState() const
+    {
+        static const winrt::param::hstring normal = L"Normal";
+        static const winrt::param::hstring unfocused = L"Unfocused";
+        return (_focused ? normal : unfocused);
+    }
 }
diff --git a/src/cascadia/TerminalApp/MinMaxCloseControl.h b/src/cascadia/TerminalApp/MinMaxCloseControl.h
@@ -21,6 +21,9 @@ namespace winrt::TerminalApp::implementation
         void PressButton(CaptionButton button);
         void ReleaseButtons();
 
+        bool Focused() const;
+        void Focused(bool focused);
+
         void _MinimizeClick(const winrt::Windows::Foundation::IInspectable& sender,
                             const winrt::Windows::UI::Xaml::RoutedEventArgs& e);
         void _MaximizeClick(const winrt::Windows::Foundation::IInspectable& sender,
@@ -32,8 +35,12 @@ namespace winrt::TerminalApp::implementation
         til::typed_event<TerminalApp::MinMaxCloseControl, winrt::Windows::UI::Xaml::RoutedEventArgs> MaximizeClick;
         til::typed_event<TerminalApp::MinMaxCloseControl, winrt::Windows::UI::Xaml::RoutedEventArgs> CloseClick;
 
+        bool _focused{ false };
         std::shared_ptr<ThrottledFunc<winrt::Windows::UI::Xaml::Controls::Button>> _displayToolTip{ nullptr };
         std::optional<CaptionButton> _lastPressedButton{ std::nullopt };
+
+    private:
+        const winrt::param::hstring& _normalState() const;
     };
 }
 
diff --git a/src/cascadia/TerminalApp/MinMaxCloseControl.idl b/src/cascadia/TerminalApp/MinMaxCloseControl.idl
@@ -14,6 +14,7 @@ namespace TerminalApp
         void HoverButton(CaptionButton button);
         void PressButton(CaptionButton button);
         void ReleaseButtons();
+        Boolean Focused { get; set; };
 
         event Windows.Foundation.TypedEventHandler<MinMaxCloseControl, Windows.UI.Xaml.RoutedEventArgs> MinimizeClick;
         event Windows.Foundation.TypedEventHandler<MinMaxCloseControl, Windows.UI.Xaml.RoutedEventArgs> MaximizeClick;
diff --git a/src/cascadia/TerminalApp/MinMaxCloseControl.xaml b/src/cascadia/TerminalApp/MinMaxCloseControl.xaml
@@ -32,6 +32,10 @@
                                     ResourceKey="SystemControlForegroundBaseHighBrush" />
                     <StaticResource x:Key="CaptionButtonForegroundPressed"
                                     ResourceKey="SystemControlForegroundBaseHighBrush" />
+                    <StaticResource x:Key="CaptionButtonForegroundUnfocusedColor"
+                                    ResourceKey="TextFillColorDisabled" />
+                    <SolidColorBrush x:Key="CaptionButtonForegroundUnfocused"
+                                     Color="{ThemeResource CaptionButtonForegroundUnfocusedColor}" />
                     <SolidColorBrush x:Key="CaptionButtonBackground"
                                      Color="Transparent" />
                     <Color x:Key="CaptionButtonBackgroundColor">Transparent</Color>
@@ -66,6 +70,10 @@
                                     ResourceKey="SystemControlForegroundBaseHighBrush" />
                     <StaticResource x:Key="CaptionButtonForegroundPressed"
                                     ResourceKey="SystemControlForegroundBaseHighBrush" />
+                    <StaticResource x:Key="CaptionButtonForegroundUnfocusedColor"
+                                    ResourceKey="TextFillColorDisabled" />
+                    <SolidColorBrush x:Key="CaptionButtonForegroundUnfocused"
+                                     Color="{ThemeResource CaptionButtonForegroundUnfocusedColor}" />
                     <SolidColorBrush x:Key="CaptionButtonBackground"
                                      Color="Transparent" />
                     <Color x:Key="CaptionButtonBackgroundColor">Transparent</Color>
@@ -103,6 +111,10 @@
                                      Color="{ThemeResource SystemColorHighlightTextColor}" />
                     <SolidColorBrush x:Key="CaptionButtonForegroundPressed"
                                      Color="{ThemeResource SystemColorHighlightTextColor}" />
+                    <SolidColorBrush x:Key="CaptionButtonForegroundUnfocused"
+                                     Color="{ThemeResource SystemColorButtonTextColor}" />
+                    <StaticResource x:Key="CaptionButtonForegroundUnfocusedColor"
+                                    ResourceKey="SystemColorButtonTextColor" />
                     <SolidColorBrush x:Key="CloseButtonBackgroundPointerOver"
                                      Color="{ThemeResource SystemColorHighlightColor}" />
                     <SolidColorBrush x:Key="CloseButtonForegroundPointerOver"
@@ -189,6 +201,20 @@
                                                                     Duration="0:0:0.1" />
                                                 </Storyboard>
                                             </VisualTransition>
+
+                                            <VisualTransition From="PointerOver"
+                                                              To="Unfocused">
+                                                <Storyboard>
+                                                    <ColorAnimation Storyboard.TargetName="ButtonBaseElement"
+                                                                    Storyboard.TargetProperty="(UIElement.Background).(SolidColorBrush.Color)"
+                                                                    To="{ThemeResource CaptionButtonBackgroundColor}"
+                                                                    Duration="0:0:0.15" />
+                                                    <ColorAnimation Storyboard.TargetName="ButtonIcon"
+                                                                    Storyboard.TargetProperty="(UIElement.Foreground).(SolidColorBrush.Color)"
+                                                                    To="{ThemeResource CaptionButtonForegroundUnfocusedColor}"
+                                                                    Duration="0:0:0.1" />
+                                                </Storyboard>
+                                            </VisualTransition>
                                         </VisualStateGroup.Transitions>
 
                                         <VisualState x:Name="Normal">
@@ -198,6 +224,13 @@
                                             </VisualState.Setters>
                                         </VisualState>
 
+                                        <VisualState x:Name="Unfocused">
+                                            <VisualState.Setters>
+                                                <Setter Target="ButtonBaseElement.Background" Value="{ThemeResource CaptionButtonBackground}" />
+                                                <Setter Target="ButtonIcon.Foreground" Value="{ThemeResource CaptionButtonForegroundUnfocused}" />
+                                            </VisualState.Setters>
+                                        </VisualState>
+
                                         <VisualState x:Name="PointerOver">
                                             <VisualState.Setters>
                                                 <Setter Target="ButtonBaseElement.Background" Value="{ThemeResource CaptionButtonBackgroundPointerOver}" />
diff --git a/src/cascadia/TerminalApp/TitlebarControl.cpp b/src/cascadia/TerminalApp/TitlebarControl.cpp
@@ -54,6 +54,16 @@ namespace winrt::TerminalApp::implementation
         return static_cast<float>(minMaxCloseWidth) / 3.0f;
     }
 
+    bool TitlebarControl::Focused()
+    {
+        return MinMaxCloseControl().Focused();
+    }
+
+    void TitlebarControl::Focused(bool focused)
+    {
+        MinMaxCloseControl().Focused(focused);
+    }
+
     IInspectable TitlebarControl::Content()
     {
         return ContentRoot().Content();
diff --git a/src/cascadia/TerminalApp/TitlebarControl.h b/src/cascadia/TerminalApp/TitlebarControl.h
@@ -17,6 +17,9 @@ namespace winrt::TerminalApp::implementation
         void ReleaseButtons();
         float CaptionButtonWidth();
 
+        bool Focused();
+        void Focused(bool focused);
+
         IInspectable Content();
         void Content(IInspectable content);
 
diff --git a/src/cascadia/TerminalApp/TitlebarControl.idl b/src/cascadia/TerminalApp/TitlebarControl.idl
@@ -29,6 +29,7 @@ namespace TerminalApp
         void ClickButton(CaptionButton button);
         void ReleaseButtons();
         Single CaptionButtonWidth { get; };
+        Boolean Focused { get; set; };
 
         IInspectable Content;
         Windows.UI.Xaml.Controls.Border DragBar { get; };
diff --git a/src/cascadia/WindowsTerminal/NonClientIslandWindow.cpp b/src/cascadia/WindowsTerminal/NonClientIslandWindow.cpp
@@ -958,6 +958,12 @@ void NonClientIslandWindow::_UpdateFrameMargins() const noexcept
 {
     switch (message)
     {
+    case WM_NCACTIVATE:
+    {
+        const bool activated = LOWORD(wParam) != 0;
+        _titlebar.Focused(activated);
+        break;
+    }
     case WM_SETCURSOR:
         return _OnSetCursor(wParam, lParam);
     case WM_DISPLAYCHANGE:

Original file line number	Diff line number	Diff line change
`@@ -958,6 +958,12 @@ void NonClientIslandWindow::_UpdateFrameMargins() const noexcept`
`958`	`958`	`{`
`959`	`959`	`switch (message)`
`960`	`960`	`{`
	`961`	`+ case WM_NCACTIVATE:`
	`962`	`+ {`
	`963`	`+ const bool activated = LOWORD(wParam) != 0;`
	`964`	`+ _titlebar.Focused(activated);`
	`965`	`+ break;`
	`966`	`+ }`
`961`	`967`	`case WM_SETCURSOR:`
`962`	`968`	`return _OnSetCursor(wParam, lParam);`
`963`	`969`	`case WM_DISPLAYCHANGE:`