Auto-delay modifier+mouse combos so Alt+scroll, Ctrl+click etc. work

When a single event batch contains both a keyboard modifier press
(Ctrl/Shift/Alt/Meta) and a mouse event (REL_WHEEL/REL_HWHEEL/BTN_LEFT/
BTN_RIGHT/BTN_MIDDLE), insert a small built-in delay between the
modifier and the mouse event so the compositor has time to latch the
modifier into keystate before the pointer event arrives. Without this,
bindings like KEY_LEFTALT+REL_WHEEL:1 were delivered as plain scrolls
because Alt was never registered as held when the wheel event reached
the application.

The existing modifier_delay setting still applies to pure-keyboard
combos and is unchanged. If the user has set modifier_delay larger than
the auto floor, their value still wins (max(user, auto)). Pure keyboard
combos, plain mouse events, and single-key bindings are all unaffected.

Bumps version to 3.1.1.

Author: AndyCappDev

README.md

@@ -1,6 +1,6 @@
 # TuxBox — Linux Driver for TourBox Controllers
 
-[![Version](https://img.shields.io/badge/version-3.1.0-green.svg)](https://github.com/AndyCappDev/tuxbox/releases)
+[![Version](https://img.shields.io/badge/version-3.1.1-green.svg)](https://github.com/AndyCappDev/tuxbox/releases)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Platform: Linux](https://img.shields.io/badge/platform-linux-lightgrey.svg)](https://www.linux.org/)
 [![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)

docs/CONFIG_GUIDE.md

@@ -117,7 +117,7 @@ Configures your TourBox device connection.
 
 **Available settings:**
 - `mac_address` - Your TourBox's Bluetooth MAC address (XX:XX:XX:XX:XX:XX) - Elite/Elite Plus only
-- `modifier_delay` - Milliseconds to wait between modifier keys (Ctrl/Shift/Alt/Meta) and other keys when sending key combinations. Default: `0` (disabled). Set to `20`-`50` if apps like GIMP don't recognize key combos. Can be overridden per-profile in `.profile` files (see below).
+- `modifier_delay` - Milliseconds to wait between modifier keys (Ctrl/Shift/Alt/Meta) and other **keyboard** keys when sending key combinations. Default: `0` (disabled). Set to `20`-`50` if apps like GIMP don't recognize keyboard combos. Can be overridden per-profile in `.profile` files (see below). **Note:** modifier+mouse combos (e.g. Alt+scroll, Ctrl+click) get a small built-in delay automatically and do not require this setting.
 
 **How to find your MAC address:**
 ```bash
@@ -454,7 +454,9 @@ scroll_down = KEY_LEFTCTRL+KEY_MINUS
 
 ## Modifier Key Delay
 
-Some applications (notably GIMP) don't recognize key combinations when the modifier key and main key arrive at nearly the same time. The `modifier_delay` setting adds a small pause between them.
+Some applications (notably GIMP) don't recognize **keyboard** combinations when the modifier key and the main key arrive at nearly the same time. The `modifier_delay` setting adds a small pause between them.
+
+> **Mouse combos are handled automatically.** When a binding mixes a modifier (Ctrl/Shift/Alt/Meta) with a mouse event (`REL_WHEEL`, `REL_HWHEEL`, `BTN_LEFT`, `BTN_RIGHT`, `BTN_MIDDLE`), TuxBox always inserts a small delay between the modifier press and the mouse event so the compositor has time to latch the modifier into keystate. You do **not** need to set `modifier_delay` for things like `KEY_LEFTALT+REL_WHEEL:1` (Alt+scroll) or `KEY_LEFTCTRL+BTN_LEFT` (Ctrl+click). If you have set `modifier_delay` to a value larger than the built-in floor, your value wins.
 
 ### Global Setting
 

docs/GUI_USER_GUIDE.md

@@ -1,7 +1,7 @@
 # TuxBox Configuration GUI - User Guide
 
-**Version:** 3.1.0
-**Last Updated:** 2026-03-13
+**Version:** 3.1.1
+**Last Updated:** 2026-04-07
 
 ## Table of Contents
 
@@ -1205,11 +1205,13 @@ When the TourBox sends a key combination like Ctrl+Z, it sends the modifier key
 
 **Modifier key delay** adds a small pause (in milliseconds) between sending the modifier keys (Ctrl, Shift, Alt, Super) and the remaining keys in a combination. This gives the application time to register the modifier before the main key arrives.
 
+> **Mouse combos are handled automatically.** Bindings that mix a modifier with a mouse event -- e.g. `Alt+Scroll Wheel`, `Ctrl+Left Click` -- always get a small built-in delay so the compositor has time to register the modifier before the click or scroll. You do **not** need to enable Modifier Key Delay for these. The setting documented here is specifically for **keyboard-only** combos in stubborn applications like GIMP. If you set a value larger than the built-in floor, your value still wins for mouse combos too.
+
 ### When Do You Need It?
 
 You likely need modifier key delay if:
 
-- **Key combinations don't work in specific applications** -- e.g., pressing a button mapped to Ctrl+Z does nothing in GIMP, but works fine in other apps
+- **Keyboard combinations don't work in specific applications** -- e.g., pressing a button mapped to Ctrl+Z does nothing in GIMP, but works fine in other apps
 - **Only the main key registers** -- e.g., you get "z" instead of "Ctrl+Z"
 - **Combinations work intermittently** -- sometimes the combo registers, sometimes it doesn't
 

tuxbox/__init__.py

@@ -1 +1 @@
-VERSION = '3.1.0'
+VERSION = '3.1.1'

tuxbox/default_mappings.conf

@@ -27,11 +27,15 @@
 #
 # KEY COMBO TIMING:
 #   modifier_delay: Milliseconds to wait between modifier keys (Ctrl/Shift/Alt/Meta)
-#                   and other keys when sending key combinations. Default: 0 (disabled)
-#                   Set to 20-50 if apps like GIMP don't recognize key combos.
-#                   This adds a small delay so apps register the modifier first.
-#                   Can also be set per-profile in the [profile] section of .profile files
-#                   (per-profile value overrides this global setting).
+#                   and other KEYBOARD keys when sending key combinations.
+#                   Default: 0 (disabled). Set to 20-50 if apps like GIMP don't
+#                   recognize key combos. This adds a small delay so apps register
+#                   the modifier first. Can also be set per-profile in the [profile]
+#                   section of .profile files (per-profile value overrides this
+#                   global setting).
+#                   Note: modifier+mouse combos (Alt+scroll, Ctrl+click, etc.)
+#                   get a small built-in delay automatically and do not require
+#                   this setting.
 
 [device]
 # usb_port = /dev/ttyACM0

tuxbox/device_base.py

@@ -27,6 +27,18 @@
     e.KEY_LEFTMETA, e.KEY_RIGHTMETA,
 }
 
+# Mouse button keys - paired with KEYBOARD_MODIFIER_KEYS to detect modifier+mouse
+# combos that need a forced delay (see AUTO_MOUSE_MODIFIER_DELAY_MS).
+MOUSE_EVENT_KEYS = {e.BTN_LEFT, e.BTN_RIGHT, e.BTN_MIDDLE}
+
+# When a single batch contains both a modifier press and a mouse event (REL_* or
+# BTN_LEFT/RIGHT/MIDDLE), we force at least this much delay between the modifier
+# and the mouse event so the compositor has time to latch the modifier into
+# keystate before the pointer event arrives. Without this, apps like DaVinci
+# Resolve see Alt+scroll as a plain scroll. Pure-keyboard combos are not
+# affected and still honor the user's `modifier_delay` setting verbatim.
+AUTO_MOUSE_MODIFIER_DELAY_MS = 15
+
 logger = logging.getLogger(__name__)
 
 # Controls that can be held (buttons) vs momentary (rotary)
@@ -147,47 +159,64 @@ def is_modifier_button(self, control_name: str) -> bool:
     def _send_events(self, events: List[Tuple[int, int, int]]):
         """Send events to the virtual input device with optional modifier delay
 
-        If modifier_delay is configured and the events contain both keyboard
-        modifier keys (Ctrl, Shift, Alt, Meta) and non-modifier keys, sends
-        the modifier keys first, syncs, waits for the delay, then sends the
-        remaining keys. This helps applications recognize key combinations.
+        If the batch contains a modifier key press (Ctrl/Shift/Alt/Meta) along
+        with other events, the modifier is sent first, syned, then the rest of
+        the events are sent after a delay. This helps applications recognize
+        key combinations.
+
+        The delay used is `max(self.modifier_delay, AUTO_MOUSE_MODIFIER_DELAY_MS)`
+        when the batch mixes a modifier with a mouse event (REL_* or BTN_LEFT/
+        RIGHT/MIDDLE), and `self.modifier_delay` otherwise. The auto-delay
+        exists because compositors need a moment to latch a modifier into
+        keystate before processing pointer events; without it, things like
+        Alt+scroll get delivered as plain scrolls. Pure keyboard combos still
+        honor `self.modifier_delay` verbatim (default 0).
 
         Args:
             events: List of (event_type, event_code, value) tuples
         """
         if not events or not self.controller:
             return
 
-        # Check if we need to apply modifier delay
-        if self.modifier_delay > 0:
-            # Separate modifier key presses from other events
-            modifier_presses = []
-            other_events = []
-
-            for event in events:
-                event_type, event_code, value = event
-                if (event_type == e.EV_KEY and
-                    value == 1 and
-                    event_code in KEYBOARD_MODIFIER_KEYS):
-                    modifier_presses.append(event)
-                else:
-                    other_events.append(event)
+        # Single pass: partition events and detect mouse-mixing.
+        modifier_presses = []
+        other_events = []
+        has_mouse_event = False
 
-            # If we have both modifiers and other events, send with delay
-            if modifier_presses and other_events:
-                # Send modifier keys first
-                for event in modifier_presses:
-                    self.controller.write(*event)
-                self.controller.syn()
+        for event in events:
+            event_type, event_code, value = event
+            if (event_type == e.EV_KEY and
+                value == 1 and
+                event_code in KEYBOARD_MODIFIER_KEYS):
+                modifier_presses.append(event)
+            else:
+                other_events.append(event)
+                if event_type == e.EV_REL:
+                    has_mouse_event = True
+                elif (event_type == e.EV_KEY and
+                      value == 1 and
+                      event_code in MOUSE_EVENT_KEYS):
+                    has_mouse_event = True
+
+        # Compute the delay to use for this batch. Mouse+modifier combos get
+        # the auto floor; everything else just uses the configured value.
+        effective_delay = self.modifier_delay
+        if modifier_presses and has_mouse_event:
+            effective_delay = max(effective_delay, AUTO_MOUSE_MODIFIER_DELAY_MS)
+
+        # If we have both modifiers and other events and a non-zero delay,
+        # send the modifier first, wait, then send the rest.
+        if effective_delay > 0 and modifier_presses and other_events:
+            for event in modifier_presses:
+                self.controller.write(*event)
+            self.controller.syn()
 
-                # Wait for modifier delay
-                time.sleep(self.modifier_delay / 1000.0)
+            time.sleep(effective_delay / 1000.0)
 
-                # Send remaining events
-                for event in other_events:
-                    self.controller.write(*event)
-                self.controller.syn()
-                return
+            for event in other_events:
+                self.controller.write(*event)
+            self.controller.syn()
+            return
 
         # No delay needed - send all events normally
         for event in events:

tuxbox/gui/__init__.py

@@ -3,4 +3,4 @@
 Graphical interface for configuring TourBox button mappings and profiles.
 """
 
-__version__ = "3.1.0"
+__version__ = "3.1.1"