From 2bab3ccb18cfc9472c24261db66718a5f77dafc8 Mon Sep 17 00:00:00 2001 From: Kovid Goyal Date: Mon, 12 Oct 2026 12:37:58 +0530 Subject: [PATCH] macOS specific changes for wheel events PR --- kitty/mouse.c | 38 ++++++++++++++++++++------ kitty/options/definition.py | 9 +++++++ kitty/state.h | 11 +++++--- kitty_tests/mouse.py | 54 ++++++++++++++++++++++++++++++++++++- 4 files changed, 99 insertions(+), 13 deletions(-) diff --git a/kitty/mouse.c b/kitty/mouse.c index 1af5f737c..46be85f27 100644 --- a/kitty/mouse.c +++ b/kitty/mouse.c @@ -1656,8 +1656,8 @@ dispatch_mapped_scroll_axis(OSWindow *osw, Window *w, const GLFWScrollEvent *ev, // whole event is consumed. static bool dispatch_mapped_scroll(OSWindow *osw, Window *w, const GLFWScrollEvent *ev, int mods, bool grabbed) { - // A partial step does not carry over to a different window or modifiers - if (osw->scroll.mapped_window_id != w->id || osw->scroll.mapped_modifiers != mods) + // A partial step does not carry over to a different window, modifiers or mouse mode + if (osw->scroll.mapped_window_id != w->id || osw->scroll.mapped_modifiers != mods || osw->scroll.mapped_grabbed != grabbed) osw->scroll.mapped_pending_pixels_x = osw->scroll.mapped_pending_pixels_y = 0; // Both axes are always dispatched, so that a diagonal gesture can fire both const bool consumed_y = ev->y_offset != 0.0 && dispatch_mapped_scroll_axis(osw, w, ev, true, mods, grabbed); @@ -1665,16 +1665,29 @@ dispatch_mapped_scroll(OSWindow *osw, Window *w, const GLFWScrollEvent *ev, int if (!consumed_x && !consumed_y) return false; osw->scroll.mapped_window_id = w->id; osw->scroll.mapped_modifiers = mods; + osw->scroll.mapped_grabbed = grabbed; + osw->scroll.mapped_last_event_at = monotonic(); return true; } -// An unmapped event continues a mapped gesture only if it is in the same window -// with the same modifiers and only scrolls along axes that have no mappings at -// all, for example, horizontal jitter during a vertical gesture. Otherwise the -// momentum of a following, unmapped gesture would be swallowed. +// The longest gap between two scroll events that can belong to the same +// gesture. Touchpads report at least at display refresh rate while the fingers +// move, so this only has to outlast a dropped frame or two. +#define MAPPED_GESTURE_MAX_GAP_MS 200ll + +// An unmapped event continues a mapped gesture only if it belongs to the same +// gesture, that is, it arrives promptly after the previous event of that +// gesture, in the same window and mouse mode with the same modifiers, and only +// scrolls along axes that have no mappings at all, for example, horizontal +// jitter during a vertical gesture. Otherwise the momentum of a following, +// unmapped gesture would be swallowed. Both the mouse mode and the elapsed time +// have to be checked because the set of mapped wheel buttons changes with the +// mode and a classic wheel has no end-of-gesture event, so without them an +// unmapped direction would stay swallowed indefinitely. static bool continues_mapped_gesture(const OSWindow *osw, const Window *w, const GLFWScrollEvent *ev, int mods, bool grabbed) { - if (osw->scroll.mapped_window_id != w->id || osw->scroll.mapped_modifiers != mods) return false; + if (osw->scroll.mapped_window_id != w->id || osw->scroll.mapped_modifiers != mods || osw->scroll.mapped_grabbed != grabbed) return false; + if (monotonic() - osw->scroll.mapped_last_event_at > ms_to_monotonic_t(MAPPED_GESTURE_MAX_GAP_MS)) return false; if (ev->y_offset != 0.0 && (wheel_is_mapped(MOUSE_WHEEL_UP, grabbed, mods) || wheel_is_mapped(MOUSE_WHEEL_DOWN, grabbed, mods))) return false; if (ev->x_offset != 0.0 && (wheel_is_mapped(MOUSE_WHEEL_LEFT, grabbed, mods) || wheel_is_mapped(MOUSE_WHEEL_RIGHT, grabbed, mods))) return false; return true; @@ -1735,11 +1748,20 @@ scroll_event_in_window(OSWindow *osw, Window *w, const GLFWScrollEvent *ev, unsi const bool grabbed = screen->modes.mouse_tracking_mode != NO_TRACKING; const int mods = ev->keyboard_modifiers & WHEEL_MAPPING_MODS_MASK; if (dispatch_mapped_scroll(osw, w, ev, mods, grabbed)) osw->scroll.mapped_gesture = true; - else if (osw->scroll.mapped_gesture) osw->scroll.mapped_gesture = continues_mapped_gesture(osw, w, ev, mods, grabbed); + else if (osw->scroll.mapped_gesture) { + osw->scroll.mapped_gesture = continues_mapped_gesture(osw, w, ev, mods, grabbed); + // The gesture now extends to this event, so the next one is timed from here + if (osw->scroll.mapped_gesture) osw->scroll.mapped_last_event_at = monotonic(); + } if (osw->scroll.mapped_gesture) return; } else if (osw->scroll.mapped_gesture) { // Inertial scrolling after a mapped gesture neither fires the mappings nor scrolls osw->scroll.mapped_pending_pixels_x = osw->scroll.mapped_pending_pixels_y = 0; + osw->scroll.mapped_last_event_at = monotonic(); + // Once the momentum is spent the gesture is over, so a later unmapped + // event in the same window with the same modifiers scrolls normally + if (ev->momentum_type == GLFW_MOMENTUM_PHASE_ENDED || ev->momentum_type == GLFW_MOMENTUM_PHASE_CANCELED) + osw->scroll.mapped_gesture = false; return; } finish_scroll_animation(screen); diff --git a/kitty/options/definition.py b/kitty/options/definition.py index 14a03e62d..429b00f14 100644 --- a/kitty/options/definition.py +++ b/kitty/options/definition.py @@ -1252,6 +1252,15 @@ Or to switch tabs by scrolling horizontally with :kbd:`Ctrl`:: mouse_map ctrl+wheel_left press ungrabbed,grabbed previous_tab mouse_map ctrl+wheel_right press ungrabbed,grabbed next_tab +.. note:: + On macOS, holding :kbd:`Shift` while turning a classic mouse wheel is + translated by the operating system into horizontal scrolling, so such a + gesture triggers :code:`shift+wheel_left` and :code:`shift+wheel_right` + rather than :code:`shift+wheel_up` and :code:`shift+wheel_down`. Touchpads + are unaffected, so the same mapping can be reached by two different buttons + depending on the device. Prefer a modifier other than :kbd:`Shift` for + vertical wheel mappings that have to work with both. + :code:`event-type` is one of :code:`press`, :code:`release`, :code:`doublepress`, :code:`triplepress`, :code:`click`, :code:`doubleclick`. :code:`modes` indicates whether the action is performed when the mouse is diff --git a/kitty/state.h b/kitty/state.h index 35940d35d..35045506f 100644 --- a/kitty/state.h +++ b/kitty/state.h @@ -603,13 +603,16 @@ typedef struct OSWindow { struct { double pending_pixels_x, pending_pixels_y; int last_v120_dir_x, last_v120_dir_y; - // mouse_map wheel state: the partial steps and the window and - // modifiers they belong to, and whether the current gesture fired a - // mapping, so that its momentum is swallowed + // mouse_map wheel state: the partial steps and the window, modifiers + // and mouse mode they belong to, and whether the current gesture fired + // a mapping, so that its momentum is swallowed. mapped_last_event_at + // bounds the gesture in time, as there is no end-of-gesture event for a + // classic wheel. double mapped_pending_pixels_x, mapped_pending_pixels_y; id_type mapped_window_id; int mapped_modifiers; - bool mapped_gesture; + monotonic_t mapped_last_event_at; + bool mapped_gesture, mapped_grabbed; } scroll; unsigned shader_anim_event_registry; id_type last_bell_window_id; // ID of the most recent window that received a bell event diff --git a/kitty_tests/mouse.py b/kitty_tests/mouse.py index a16fdb780..c3439a3eb 100644 --- a/kitty_tests/mouse.py +++ b/kitty_tests/mouse.py @@ -2,6 +2,7 @@ # License: GPL v3 Copyright: 2016, Kovid Goyal from functools import partial +from time import sleep from kitty.fast_data_types import ( GLFW_MOD_ALT, @@ -484,7 +485,7 @@ class TestMouse(BaseTest): from kitty.config import load_config LINES, HIGHRES = 0, 2 # GLFWOffsetType - MOMENTUM_BEGAN, MOMENTUM_ACTIVE = 1, 3 # GLFWMomentumType + MOMENTUM_BEGAN, MOMENTUM_ACTIVE, MOMENTUM_ENDED = 1, 3, 4 # GLFWMomentumType s = self.create_screen(lines=5, scrollback=50) errors = [] opts = load_config( @@ -586,3 +587,54 @@ class TestMouse(BaseTest): scroll(0, GLFW_MOD_CONTROL, HIGHRES, x=-10) scroll(-20, GLFW_MOD_CONTROL, HIGHRES, MOMENTUM_BEGAN) ac(['+'], 1) + # Spent momentum ends the gesture, so a later unmapped event in the same + # window with the same modifiers scrolls instead of being swallowed. + # shift is mapped horizontally only, so vertical scrolling is unmapped. + scroll(0, GLFW_MOD_SHIFT, HIGHRES, x=100) + scroll(0, GLFW_MOD_SHIFT, HIGHRES, MOMENTUM_BEGAN, x=-200) + scroll(0, GLFW_MOD_SHIFT, HIGHRES, MOMENTUM_ENDED, x=-100) + ac(['left'], 1) + scroll(1, GLFW_MOD_SHIFT) + ac([], 2) + + # A classic wheel has no end-of-gesture event, so a gesture is also + # bounded by the time between its events and by the mouse mode, which + # changes the set of mapped wheel buttons. Without that, an unmapped + # direction would stay swallowed indefinitely. Reload the mappings so + # that ctrl is mapped horizontally only, as in the mouse_map docs. + opts = load_config( + overrides=( + 'pixel_scroll no', + 'wheel_scroll_multiplier 1', + 'mouse_map ctrl+wheel_left press ungrabbed,grabbed previous_tab', + 'mouse_map ctrl+wheel_right press ungrabbed,grabbed next_tab', + 'mouse_map alt+wheel_up press ungrabbed change_font_size all +1', + ), + accumulate_bad_lines=errors, + ) + self.ae(errors, []) + set_options(opts) + # Vertical is unmapped for ctrl now, so it scrolls + scroll(1, GLFW_MOD_CONTROL) + ac([], 3) + # A mapped horizontal event starts a gesture, during which off-axis + # jitter is still swallowed + scroll(0, GLFW_MOD_CONTROL, x=1) + ac(['left'], 3) + scroll(1, GLFW_MOD_CONTROL) + ac([], 3) + # But once the gesture times out, vertical scrolling works again + sleep(0.3) + scroll(1, GLFW_MOD_CONTROL) + ac([], 4) + # Changing the mouse mode ends the gesture too. alt+wheel_up is mapped + # only when ungrabbed, so once grabbed the wheel goes to the program + # instead of being swallowed as a continuation of the mapped gesture. + scroll(1, GLFW_MOD_ALT) + ac(['+'], 4) + parse_bytes(s, b'\x1b[?1000h') + s.callbacks.wtcbuf = b'' + scroll(1, GLFW_MOD_ALT) + ac([], 4) + self.assertTrue(s.callbacks.wtcbuf, 'the wheel event was not reported to the program') + parse_bytes(s, b'\x1b[?1000l')