config: add bypass_mouse_reporting_modifiers option

This allows changing eg: SHIFT to ALT for bypassing mouse reporting.

refs: https://github.com/wez/wezterm/issues/911

config/src/keys.rs

@@ -165,7 +165,7 @@ where
     }
 }
 
-fn de_modifiers<'de, D>(deserializer: D) -> Result<Modifiers, D::Error>
+pub(crate) fn de_modifiers<'de, D>(deserializer: D) -> Result<Modifiers, D::Error>
 where
     D: Deserializer<'de>,
 {

config/src/lib.rs

@@ -887,6 +887,12 @@ pub struct Config {
 
     #[serde(default)]
     pub keys: Vec<Key>,
+    #[serde(
+        default = "default_bypass_mouse_reporting_modifiers",
+        deserialize_with = "crate::keys::de_modifiers"
+    )]
+    pub bypass_mouse_reporting_modifiers: Modifiers,
+
     #[serde(default)]
     pub debug_key_events: bool,
 
@@ -1782,3 +1788,7 @@ fn default_read_timeout() -> Duration {
 fn default_write_timeout() -> Duration {
     Duration::from_secs(60)
 }
+
+fn default_bypass_mouse_reporting_modifiers() -> Modifiers {
+    Modifiers::SHIFT
+}

docs/changelog.md

@@ -54,6 +54,7 @@ As features stabilize some brief notes about them will accumulate here.
 * Improved: implement braille characters as custom glyphs, to have perfect rendering when `custom_block_glyphs` is enabled. Thanks to [@bew](http://github.com/bew)!
 * Fixed: Mod3 is no longer treater as SUPER on X11 and Wayland [#933](https://github.com/wez/wezterm/issues/933)
 * Fixed: paste now respects `scroll_to_bottom_on_input`. [#931](https://github.com/wez/wezterm/issues/931)
+* New: [bypass_mouse_reporting_modifiers](config/lua/config/bypass_mouse_reporting_modifiers.md) to specify which modifier(s) override application mouse reporting mode.
 
 ### 20210502-154244-3f7122cb
 

docs/config/lua/config/bypass_mouse_reporting_modifiers.md

@@ -0,0 +1,23 @@
+# bypass_mouse_reporting_modifiers = "SHIFT"
+
+*Since: nightly builds only*
+
+If an application has enabled mouse reporting mode, mouse events are sent
+directly to the application, and do not get routed through the mouse
+assignment logic.
+
+Holding down the `bypass_mouse_reporting_modifiers` modifier key(s) will
+prevent the event from being passed to the application.
+
+The default value for `bypass_mouse_reporting_modifiers` is `SHIFT`, which
+means that holding down shift while clicking will not send the mouse
+event to eg: vim running in mouse mode and will instead treat the event
+as though `SHIFT` was not pressed and then match it against the mouse
+assignments.
+
+```lua
+return {
+  -- Use ALT instead of SHIFT to bypass application mouse reporting
+  bypass_mouse_reporting_modifiers = "ALT"
+}
+```

docs/config/mouse.md

@@ -1,8 +1,22 @@
-Mouse bindings are configurable.
+Mouse bindings are configurable, and there are a number of default assignments
+described below.
 
 The assignments are based around a triggering mouse event which may be combined
 with a set of modifier keys to produce an action.
 
+By default applications running in the terminal don't respond to the mouse.
+However, applications can emit escape sequences to request mouse event tracking.
+When mouse event tracking is enabled, mouse events are NOT matched against
+the mouse assignments and are instead passed through to the application.
+
+You can bypass the mouse reporting capture by holding down the `SHIFT` key;
+that will prevent the event from being passed to the application and allow matching
+it against your assignments as though the `SHIFT` key were not pressed.
+
+The [bypass_mouse_reporting_modifiers](config/lua/config/bypass_mouse_reporting_modifiers.md)
+option allows you to specify an alternative set of modifiers to use for
+bypassing mouse reporting capture.
+
 ## Default Mouse Assignments
 
 In the table below, `Triple Left Down` means that the left mouse button is

wezterm-gui/src/termwindow/mouseevent.rs

@@ -2,8 +2,7 @@ use crate::tabbar::TabBarItem;
 use crate::termwindow::keyevent::window_mods_to_termwiz_mods;
 use crate::termwindow::{ScrollHit, TMB};
 use ::window::{
-    Modifiers, MouseButtons as WMB, MouseCursor, MouseEvent, MouseEventKind as WMEK, MousePress,
-    WindowOps,
+    MouseButtons as WMB, MouseCursor, MouseEvent, MouseEventKind as WMEK, MousePress, WindowOps,
 };
 use config::keyassignment::{MouseEventTrigger, SpawnTabDomain};
 use mux::pane::Pane;
@@ -486,16 +485,20 @@ impl super::TermWindow {
             WMEK::VertWheel(_) | WMEK::HorzWheel(_) => None,
         };
 
-        let ignore_grab_modifier = Modifiers::SHIFT;
-
-        if !pane.is_mouse_grabbed() || event.modifiers.contains(ignore_grab_modifier) {
+        if !pane.is_mouse_grabbed()
+            || event
+                .modifiers
+                .contains(self.config.bypass_mouse_reporting_modifiers)
+        {
             if let Some(event_trigger_type) = event_trigger_type {
                 let mut modifiers = event.modifiers;
 
                 // Since we use shift to force assessing the mouse bindings, pretend
                 // that shift is not one of the mods when the mouse is grabbed.
                 if pane.is_mouse_grabbed() {
-                    modifiers -= ignore_grab_modifier;
+                    if modifiers.contains(self.config.bypass_mouse_reporting_modifiers) {
+                        modifiers.remove(self.config.bypass_mouse_reporting_modifiers);
+                    }
                 }
 
                 if let Some(action) = self