feat: add option to adjust opacity with Ctrl+Shift+scroll (#19151)

paulinek13 · web-flow · commit 452fa87937f0 · 2025-07-21T15:24:46.000-07:00
## Summary of the Pull Request This PR introduces an experimental setting that allows to toggle opacity changes with scrolling. ## References and Relevant Issues #3793 ## Detailed Description of the Pull Request / Additional comments By default, holding Ctrl + Shift while scrolling changes the terminal's opacity. This PR adds an option to disable that behavior. ## Validation Steps Performed I built the project locally and verified that the new feature works as intended. ## PR Checklist - [x] Resolves #3793 (comment) - [x] Tests ~~added/~~ passed - [x] Documentation updated - If checked, please file a pull request on [our docs repo](https://github.com/MicrosoftDocs/terminal) and link it here: MicrosoftDocs/terminal#873 - [X] Schema updated (if necessary)
diff --git a/doc/cascadia/profiles.schema.json b/doc/cascadia/profiles.schema.json
@@ -2381,6 +2381,11 @@
           "description": "When set to true, holding the Ctrl key while scrolling will increase or decrease the terminal font size.",
           "type": "boolean"
         },
+        "experimental.scrollToChangeOpacity": {
+          "default": true,
+          "description": "When set to true, holding the Ctrl and Shift keys while scrolling will change the window opacity.",
+          "type": "boolean"
+        },
         "compatibility.allowHeadless": {
           "default": false,
           "description": "When set to true, Windows Terminal will run in the background. This allows globalSummon and quakeMode actions to work even when no windows are open.",
diff --git a/src/cascadia/TerminalControl/ControlInteractivity.cpp b/src/cascadia/TerminalControl/ControlInteractivity.cpp
@@ -515,11 +515,11 @@ namespace winrt::Microsoft::Terminal::Control::implementation
         const auto ctrlPressed = modifiers.IsCtrlPressed();
         const auto shiftPressed = modifiers.IsShiftPressed();
 
-        if (ctrlPressed && shiftPressed)
+        if (ctrlPressed && shiftPressed && _core->Settings().ScrollToChangeOpacity())
         {
             _mouseTransparencyHandler(delta);
         }
-        else if (ctrlPressed && _core->Settings().ScrollToZoom())
+        else if (ctrlPressed && !shiftPressed && _core->Settings().ScrollToZoom())
         {
             _mouseZoomHandler(delta);
         }
diff --git a/src/cascadia/TerminalControl/IControlSettings.idl b/src/cascadia/TerminalControl/IControlSettings.idl
@@ -61,6 +61,7 @@ namespace Microsoft.Terminal.Control
         Microsoft.Terminal.Control.CopyFormat CopyFormatting { get; };
         Boolean FocusFollowMouse { get; };
         Boolean ScrollToZoom { get; };
+        Boolean ScrollToChangeOpacity { get; };
 
         String Commandline { get; };
         String StartingDirectory { get; };
diff --git a/src/cascadia/TerminalSettingsEditor/Interaction.xaml b/src/cascadia/TerminalSettingsEditor/Interaction.xaml
@@ -89,6 +89,12 @@
                               Style="{StaticResource ToggleSwitchInExpanderStyle}" />
             </local:SettingContainer>
 
+            <!--  Enable Window Opacity Changes with Scrolling  -->
+            <local:SettingContainer x:Uid="Globals_ScrollToChangeOpacity">
+                <ToggleSwitch IsOn="{x:Bind ViewModel.ScrollToChangeOpacity, Mode=TwoWay}"
+                              Style="{StaticResource ToggleSwitchInExpanderStyle}" />
+            </local:SettingContainer>
+
             <!--  Detect URLs  -->
             <local:SettingContainer x:Uid="Globals_DetectURLs">
                 <ToggleSwitch IsOn="{x:Bind ViewModel.DetectURLs, Mode=TwoWay}"
diff --git a/src/cascadia/TerminalSettingsEditor/InteractionViewModel.h b/src/cascadia/TerminalSettingsEditor/InteractionViewModel.h
@@ -26,6 +26,7 @@ namespace winrt::Microsoft::Terminal::Settings::Editor::implementation
         PERMANENT_OBSERVABLE_PROJECTED_SETTING(_GlobalSettings, SnapToGridOnResize);
         PERMANENT_OBSERVABLE_PROJECTED_SETTING(_GlobalSettings, FocusFollowMouse);
         PERMANENT_OBSERVABLE_PROJECTED_SETTING(_GlobalSettings, ScrollToZoom);
+        PERMANENT_OBSERVABLE_PROJECTED_SETTING(_GlobalSettings, ScrollToChangeOpacity);
         PERMANENT_OBSERVABLE_PROJECTED_SETTING(_GlobalSettings, DetectURLs);
         PERMANENT_OBSERVABLE_PROJECTED_SETTING(_GlobalSettings, SearchWebDefaultQueryUrl);
         PERMANENT_OBSERVABLE_PROJECTED_SETTING(_GlobalSettings, WordDelimiters);
diff --git a/src/cascadia/TerminalSettingsEditor/InteractionViewModel.idl b/src/cascadia/TerminalSettingsEditor/InteractionViewModel.idl
@@ -23,6 +23,7 @@ namespace Microsoft.Terminal.Settings.Editor
         PERMANENT_OBSERVABLE_PROJECTED_SETTING(Boolean, SnapToGridOnResize);
         PERMANENT_OBSERVABLE_PROJECTED_SETTING(Boolean, FocusFollowMouse);
         PERMANENT_OBSERVABLE_PROJECTED_SETTING(Boolean, ScrollToZoom);
+        PERMANENT_OBSERVABLE_PROJECTED_SETTING(Boolean, ScrollToChangeOpacity);
         PERMANENT_OBSERVABLE_PROJECTED_SETTING(Boolean, DetectURLs);
         PERMANENT_OBSERVABLE_PROJECTED_SETTING(String, SearchWebDefaultQueryUrl);
         PERMANENT_OBSERVABLE_PROJECTED_SETTING(String, WordDelimiters);
diff --git a/src/cascadia/TerminalSettingsEditor/Resources/en-US/Resources.resw b/src/cascadia/TerminalSettingsEditor/Resources/en-US/Resources.resw
@@ -1740,6 +1740,10 @@
     <value>Adjust terminal font size by scrolling while holding the Ctrl key</value>
     <comment>Header for a control to toggle font size changes with scrolling. When enabled, holding the Ctrl key while scrolling will increase or decrease the terminal font size.</comment>
   </data>
+  <data name="Globals_ScrollToChangeOpacity.Header" xml:space="preserve">
+    <value>Adjust terminal opacity by scrolling while holding the Ctrl and Shift keys</value>
+    <comment>Header for a control to toggle opacity changes with scrolling. When enabled, holding the Ctrl and Shift keys while scrolling will increase or decrease the window opacity.</comment>
+  </data>
   <data name="Globals_DisableAnimationsReversed.Header" xml:space="preserve">
     <value>Pane animations</value>
     <comment>Header for a control to toggle animations on panes. "Enabled" value enables the animations.</comment>
diff --git a/src/cascadia/TerminalSettingsModel/GlobalAppSettings.idl b/src/cascadia/TerminalSettingsModel/GlobalAppSettings.idl
@@ -91,6 +91,7 @@ namespace Microsoft.Terminal.Settings.Model
         INHERITABLE_SETTING(String, StartupActions);
         INHERITABLE_SETTING(Boolean, FocusFollowMouse);
         INHERITABLE_SETTING(Boolean, ScrollToZoom);
+        INHERITABLE_SETTING(Boolean, ScrollToChangeOpacity);
         INHERITABLE_SETTING(WindowingMode, WindowingBehavior);
         INHERITABLE_SETTING(Boolean, TrimBlockSelection);
         INHERITABLE_SETTING(Boolean, DetectURLs);
diff --git a/src/cascadia/TerminalSettingsModel/MTSMSettings.h b/src/cascadia/TerminalSettingsModel/MTSMSettings.h
@@ -25,6 +25,7 @@ Author(s):
     X(bool, CopyOnSelect, "copyOnSelect", false)                                                                                                                                                      \
     X(bool, FocusFollowMouse, "focusFollowMouse", false)                                                                                                                                              \
     X(bool, ScrollToZoom, "experimental.scrollToZoom", true)                                                                                                                                          \
+    X(bool, ScrollToChangeOpacity, "experimental.scrollToChangeOpacity", true)                                                                                                                        \
     X(winrt::Microsoft::Terminal::Control::GraphicsAPI, GraphicsAPI, "rendering.graphicsAPI")                                                                                                         \
     X(bool, DisablePartialInvalidation, "rendering.disablePartialInvalidation", false)                                                                                                                \
     X(bool, SoftwareRendering, "rendering.software", false)                                                                                                                                           \
diff --git a/src/cascadia/TerminalSettingsModel/TerminalSettings.cpp b/src/cascadia/TerminalSettingsModel/TerminalSettings.cpp
@@ -368,6 +368,7 @@ namespace winrt::Microsoft::Terminal::Settings::Model::implementation
         _CopyFormatting = globalSettings.CopyFormatting();
         _FocusFollowMouse = globalSettings.FocusFollowMouse();
         _ScrollToZoom = globalSettings.ScrollToZoom();
+        _ScrollToChangeOpacity = globalSettings.ScrollToChangeOpacity();
         _GraphicsAPI = globalSettings.GraphicsAPI();
         _DisablePartialInvalidation = globalSettings.DisablePartialInvalidation();
         _SoftwareRendering = globalSettings.SoftwareRendering();
diff --git a/src/cascadia/TerminalSettingsModel/TerminalSettings.h b/src/cascadia/TerminalSettingsModel/TerminalSettings.h
@@ -95,6 +95,7 @@ namespace winrt::Microsoft::Terminal::Settings::Model::implementation
         INHERITABLE_SETTING(Model::TerminalSettings, Microsoft::Terminal::Control::CopyFormat, CopyFormatting, 0);
         INHERITABLE_SETTING(Model::TerminalSettings, bool, FocusFollowMouse, false);
         INHERITABLE_SETTING(Model::TerminalSettings, bool, ScrollToZoom, true);
+        INHERITABLE_SETTING(Model::TerminalSettings, bool, ScrollToChangeOpacity, true);
         INHERITABLE_SETTING(Model::TerminalSettings, bool, AllowVtChecksumReport, false);
         INHERITABLE_SETTING(Model::TerminalSettings, bool, TrimBlockSelection, true);
         INHERITABLE_SETTING(Model::TerminalSettings, bool, DetectURLs, true);
diff --git a/src/cascadia/inc/ControlProperties.h b/src/cascadia/inc/ControlProperties.h
@@ -43,6 +43,7 @@
     X(bool, CopyOnSelect, false)                                                                                  \
     X(bool, FocusFollowMouse, false)                                                                              \
     X(bool, ScrollToZoom, true)                                                                                   \
+    X(bool, ScrollToChangeOpacity, true)                                                                          \
     X(winrt::Windows::Foundation::IReference<winrt::Microsoft::Terminal::Core::Color>, TabColor, nullptr)         \
     X(winrt::Windows::Foundation::IReference<winrt::Microsoft::Terminal::Core::Color>, StartingTabColor, nullptr) \
     X(bool, TrimBlockSelection, true)                                                                             \

Original file line number	Diff line number	Diff line change
`@@ -515,11 +515,11 @@ namespace winrt::Microsoft::Terminal::Control::implementation`
`515`	`515`	`const auto ctrlPressed = modifiers.IsCtrlPressed();`
`516`	`516`	`const auto shiftPressed = modifiers.IsShiftPressed();`
`517`	`517`
`518`		`- if (ctrlPressed && shiftPressed)`
	`518`	`+ if (ctrlPressed && shiftPressed && _core->Settings().ScrollToChangeOpacity())`
`519`	`519`	`{`
`520`	`520`	`_mouseTransparencyHandler(delta);`
`521`	`521`	`}`
`522`		`- else if (ctrlPressed && _core->Settings().ScrollToZoom())`
	`522`	`+ else if (ctrlPressed && !shiftPressed && _core->Settings().ScrollToZoom())`
`523`	`523`	`{`
`524`	`524`	`_mouseZoomHandler(delta);`
`525`	`525`	`}`