From 452fa87937f0335bb2f34036168d9f66ca6d7ca2 Mon Sep 17 00:00:00 2001
From: Paulina Kalicka <71526180+paulinek13@users.noreply.github.com>
Date: Tue, 22 Jul 2025 00:24:46 +0200
Subject: [PATCH] feat: add option to adjust opacity with Ctrl+Shift+scroll
 (#19151)

## 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
https://github.com/microsoft/terminal/issues/3793#issuecomment-3085684640
- [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:
https://github.com/MicrosoftDocs/terminal/pull/873
- [X] Schema updated (if necessary)
---
 doc/cascadia/profiles.schema.json                           | 5 +++++
 src/cascadia/TerminalControl/ControlInteractivity.cpp       | 4 ++--
 src/cascadia/TerminalControl/IControlSettings.idl           | 1 +
 src/cascadia/TerminalSettingsEditor/Interaction.xaml        | 6 ++++++
 src/cascadia/TerminalSettingsEditor/InteractionViewModel.h  | 1 +
 .../TerminalSettingsEditor/InteractionViewModel.idl         | 1 +
 .../TerminalSettingsEditor/Resources/en-US/Resources.resw   | 4 ++++
 src/cascadia/TerminalSettingsModel/GlobalAppSettings.idl    | 1 +
 src/cascadia/TerminalSettingsModel/MTSMSettings.h           | 1 +
 src/cascadia/TerminalSettingsModel/TerminalSettings.cpp     | 1 +
 src/cascadia/TerminalSettingsModel/TerminalSettings.h       | 1 +
 src/cascadia/inc/ControlProperties.h                        | 1 +
 12 files changed, 25 insertions(+), 2 deletions(-)

diff --git a/doc/cascadia/profiles.schema.json b/doc/cascadia/profiles.schema.json
index 10f5a8b87f..275db4fa37 100644
--- 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
index ba740a4364..d9bc37571b 100644
--- 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
index 2bd4bfc854..c273574ed7 100644
--- 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
index eba8b8129e..84a5019ea6 100644
--- 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
index 576c29ec03..c3e48715f7 100644
--- 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
index 6143dee5ea..c178c9f744 100644
--- 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
index 7704424ef8..816c799eb1 100644
--- 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
index 5a99e05bc3..7e6c1180e4 100644
--- 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
index 725cddbb68..5fa1fdd59c 100644
--- 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
index 5b34afbc5a..5e7e5ec29f 100644
--- 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
index b9f4af3d30..a2f20bd4b2 100644
--- 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
index ab6fa1fe01..d4e12a94b4 100644
--- 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)                                                                             \