Feature: The horizontal mouse wheel scrolling in the process list

[andis-sprinkis]

htop with the process command line column enabled provides very wide and very useful text output that currently requires keyboard controls to patiently scroll.

It is convenient that long non-wrapped and tabular lines in programs like less and nvim can be scrolled horizontally via the respective mouse wheel (less also supports scrolling via the mouse drag events, maybe for a separate Issue).

As in the title, this is a feature request for the horizontal scroll wheel scrolling support in the process list.

Via the mouse / pointer device buttons that xev identifies as button6 and button7 and wev identifies as axis: 1 (horizontal).

[fasterit]

This needs ncurses 6.6 (Debian forky or sid atm)

[fasterit]

Somebody with such a fancy mouse and ncurses 6.6 please try:

diff --git a/CRT.c b/CRT.c
index e4d2655e..2f4b293e 100644
--- a/CRT.c
+++ b/CRT.c
@@ -1119,7 +1119,9 @@ void CRT_resetSignalHandlers(void) {
 #ifdef HAVE_GETMOUSE
 void CRT_setMouse(bool enabled) {
    if (enabled) {
-#if NCURSES_MOUSE_VERSION > 1
+#if NCURSES_MOUSE_VERSION > 2
+      mousemask(BUTTON1_RELEASED | BUTTON3_RELEASED | BUTTON4_PRESSED | BUTTON5_PRESSED | BUTTON6_PRESSED | BUTTON7_PRESSED, NULL);
+#elif NCURSES_MOUSE_VERSION > 1
       mousemask(BUTTON1_RELEASED | BUTTON3_RELEASED | BUTTON4_PRESSED | BUTTON5_PRESSED, NULL);
 #else
       mousemask(BUTTON1_RELEASED | BUTTON3_RELEASED, NULL);
diff --git a/ScreenManager.c b/ScreenManager.c
index f79596c3..b7727539 100644
--- a/ScreenManager.c
+++ b/ScreenManager.c
@@ -333,6 +333,12 @@ void ScreenManager_run(ScreenManager* this, Panel** lastFocus, int* lastKey, con
                ch = KEY_WHEELDOWN;
             #endif
             }
+            #if NCURSES_MOUSE_VERSION > 2
+            } else if (mevent.bstate & BUTTON6_PRESSED) {
+               ch = KEY_LEFT;
+            } else if (mevent.bstate & BUTTON7_PRESSED) {
+               ch = KEY_RIGHT;
+            #endif
          }
       }
 #endif

[andis-sprinkis]

Tried the above patch in Arch Linux in foot terminal with and without tmux, horizontal scroll doesn't work for me, only the vertical does.

yay -Qi ncurses | grep Version
# Version         : 6.6-2
git clone https://github.com/htop-dev/htop
cd htop
# ...create HMOUSE.diff...
git apply HMOUSE.diff
./autogen.sh && ./configure && make
./htop --version
# htop 3.6.0-dev-3.5.3-5-g1a4504c-dirty
./htop
make clean

---

fancy mouse

If I am not mistaken, a horizontal scroll on a laptop trackpad would send the same button events.
EDIT: Checked - identical button6 button7 output for horizontal mouse wheel and horizontal trackpad scroll in the X11 xev, the Wayland wev distinguishes axis-source wheel and finger.
Diff doesn't work in xterm running under Xwayland either (less and nvim h-scroll works.)

[fasterit]

I think I have one "}" in the wrong line for the #if's.
Also ncurses 6.6 needs to be compiled with --enable-ext-mouse2 which it seems to not be on Debian atm.

[ravi-arnan]

I have a box where the ncurses this needs can be built, so I tested the patch rather than guessing.
Short version: the terminal side works, and the patch cannot work as written, because ncurses throws
the horizontal wheel away before an application can see it. Details below, all measured on
Linux 6.18.44, niri 26.04, foot 1.27.0, scroll events injected with wlrctl so nothing depends on my
hand on a trackpad.

1. The terminal really does send buttons 6 and 7

Raw SGR capture (\e[?1000h\e[?1006h, dump the bytes) with the pointer over a fullscreen foot window:

injected	bytes from the terminal
wlrctl pointer scroll 30 0 (wheel down)	\e[<65;119;33M x5
wlrctl pointer scroll 0 30 (wheel right)	\e[<67;119;33M x5, then \e[<67;119;33m
wlrctl pointer scroll 0 -30 (wheel left)	\e[<66;119;33M x4, then \e[<66;119;33m

So 66 and 67 do arrive on the application's tty.

2. ncurses turns them into REPORT_MOUSE_POSITION, at every mouse version

A probe calling mousemask(~(mmask_t)0, NULL) and printing MEVENT.bstate, linked against two builds
of the same snapshot (ncurses 6.6.20260822), same terminal, same injected events:

ncurses build	NCURSES_MOUSE_VERSION	wheel up / down	wheel left / right
--enable-ext-mouse2	2	BUTTON4_PRESSED / BUTTON5_PRESSED	REPORT_MOUSE_POSITION
--enable-ext-mouse2 --with-abi-version=7	3	BUTTON4_PRESSED / BUTTON5_PRESSED	REPORT_MOUSE_POSITION

BUTTON6_PRESSED and BUTTON7_PRESSED are defined in the second build and were in the requested mask.
They are never delivered.

The reason is handle_wheel() in ncurses/base/lib_mouse.c, which switches on button & 3, so
SGR 66 lands in case 2:

    case 2:
	if (wheel) {
	    /* Ignore this event as it is not a true press of the button */
	    eventp->bstate = REPORT_MOUSE_POSITION;

and SGR 67 lands in default:, which does the same. I instrumented that function in my own build to
be sure it is the place the value dies rather than inferring it from the source.

3. --enable-ext-mouse2 on its own does not give mouse version 3

This is the part that makes the earlier test result misleading. configure accepts the option and prints

checking if you want to use extension 2 for mouse encoding... yes

and the generated include/curses.h still says #define NCURSES_MOUSE_VERSION 2, because configure.in
tests the ABI first and never reaches the option:

if test $cf_cv_abi_default -le 5 ; then
	NCURSES_MOUSE_VERSION=1
elif test $cf_cv_abi_default -le 6 ; then
	NCURSES_MOUSE_VERSION=2
elif test $with_ext_mouse2 = yes ; then
	NCURSES_MOUSE_VERSION=3

Mouse version 3 needs --with-abi-version=7 as well, which builds libncursesw.so.7 and is a full ABI
break. Arch's ncurses 6.6 PKGBUILD passes neither option, and nixpkgs' does not either; both ship
NCURSES_MOUSE_VERSION 2. So on @andis-sprinkis's build the #if NCURSES_MOUSE_VERSION > 2 branch was
never compiled and the patch was not actually under test. The result was right by accident, and for a
different reason than it looked.

4. Mouse version 3 is not usable as shipped anyway

Printed from a program compiled against the ABI 7 build:

NCURSES_MOUSE_VERSION=3 sizeof(mmask_t)=8
BUTTON_SHIFT             0x0000000004000000
REPORT_MOUSE_POSITION    0x0000000010000000
BUTTON6_PRESSED          0x0000000004000000
BUTTON6_DOUBLE_CLICKED   0x0000000010000000
BUTTON7_PRESSED          0x0000000080000000
ALL_MOUSE_EVENTS         0x000000000fffffff

The modifier bits were never moved out of the way when buttons 6 to 11 were added, so at version 3
BUTTON6_RELEASED is BUTTON_CTRL, BUTTON6_PRESSED is BUTTON_SHIFT, BUTTON6_CLICKED is
BUTTON_ALT and BUTTON6_DOUBLE_CLICKED is REPORT_MOUSE_POSITION. ALL_MOUSE_EVENTS stops at
0x0fffffff, below BUTTON7_PRESSED.

Where that leaves the feature

This is blocked in ncurses, not in htop. A trial change to handle_wheel() in my own build does start
delivering BUTTON6_PRESSED for wheel-left, which confirms that is the right function, but wheel-right
still does not arrive, so the library-side fix is more than a two-line guard and I have not finished
tracking the rest of it down.

If it is useful I will write this up for the ncurses maintainer and report back here. Worth noting for
whenever it does land: htop would want a configure feature test rather than #if NCURSES_MOUSE_VERSION > 2,
since as shown above that macro does not imply the events are actually delivered.

Happy to re-run any of the above; the harness is scripted and needs no hands on the trackpad.

[fasterit]

Thank you @ravi-arnan.

If you have the time, send your analysis to https://lists.gnu.org/mailman/listinfo/bug-ncurses . Let's see what that upstream says.

[ravi-arnan]

Sent, and it is in the archive:
https://lists.gnu.org/archive/html/bug-ncurses/2026-08/msg00081.html

While writing it up I found the answer to the part I said I had not tracked down, and it turns out to
be the more useful half. mousemask() filters the caller's request through the aggregate macros in
lib_mouse.c, which stop at button 5:

result = newmask &
    (REPORT_MOUSE_POSITION | BUTTON_ALT | BUTTON_CTRL | BUTTON_SHIFT
     | BUTTON_PRESSED | BUTTON_RELEASED | BUTTON_CLICKED
     | BUTTON_DOUBLE_CLICKED | BUTTON_TRIPLE_CLICKED);

Asking for ~(mmask_t)0 at mouse version 3 returns 0x1fffffff. BUTTON7_PRESSED is 0x80000000,
outside it, and getmouse() discards any queued event not in the accepted mask. So buttons 6 to 11
cannot be requested at all. BUTTON6_PRESSED appeared to work under my trial patch only because it is
bit-identical to BUTTON_SHIFT, which is in the allowed set. Both halves were the same defect.

One more thing that went in the report: X11 buttons 8 to 11 arrive as BUTTON1_PRESSED,
BUTTON1_RELEASED and BUTTON2_PRESSED, because decode_xterm_SGR1006 routes every final == 'M'
report through handle_wheel, b >= 128 included, where button & 3 then picks a button 1 to 4
branch.

Nothing for htop to do until ncurses changes. I will report back here either way.

[fasterit]

@ravi-arnan managed to get ncurses fixed ... https://lists.gnu.org/archive/html/bug-ncurses/2026-08/msg00086.html . Congrats 🥳 !

So from ncurses-6.6-20260829 it might work now.

[ravi-arnan]

Thank you, and congrats to the ncurses side: the two NEWS entries are exactly the two halves I hit.

I rebuilt ncurses 6.6-20260829 in both configurations and re-ran the same pty harness from the report (SGR 1006 into a pty, no compositor, no mouse):

• default build: NCURSES_MOUSE_VERSION 2, mmask_t 4 bytes
• --enable-ext-mouse2 --with-abi-version=7: NCURSES_MOUSE_VERSION 3, mmask_t 8 bytes

The configure check is in too: mouse version 3 is now refused unless mmask_t is 8 bytes, and --enable-ext-mouse2 without ABI 7 warns, which closes the trap from item 1 of the report.

Measured, same injected events as before:

injected	v2 (6.6.20260829)	v3 (6.6.20260829)
wheel up	BUTTON4_PRESSED	BUTTON4_PRESSED
wheel down	BUTTON5_PRESSED	BUTTON5_PRESSED
wheel left	REPORT_MOUSE_POSITION	BUTTON6_PRESSED + ALT
wheel right	REPORT_MOUSE_POSITION	BUTTON7_PRESSED + SHIFT + ALT
button 8	BUTTON1_PRESSED	BUTTON8_PRESSED / BUTTON8_RELEASED
button 9	BUTTON2_PRESSED	BUTTON9_PRESSED + SHIFT / BUTTON9_RELEASED
button 10	BUTTON3_PRESSED	BUTTON10_PRESSED + ALT / BUTTON10_RELEASED
button 11	REPORT_MOUSE_POSITION	BUTTON11_PRESSED + SHIFT + ALT / BUTTON11_RELEASED

So the events I reported as unreachable now arrive, buttons 8-11 decode to their own bits instead of being relabelled 1/2/3, and the version-3 aliasing of the modifier bits onto button 6 is gone (BUTTON_CTRL/SHIFT/ALT and REPORT_MOUSE_POSITION moved to 0x0080000000000000 and above).

Two notes, one for htop and one for ncurses.

For htop, the horizontal wheel is now usable: mevent.bstate & BUTTON6_PRESSED / & BUTTON7_PRESSED works against this build, so the mapping in your patch has something to read. One condition still stands from the original analysis: it needs an ncurses built at mouse version 3, i.e. ABI 7 plus --enable-ext-mouse2, which no distro ships yet (Arch and nixpkgs both stop at version 2). The #if NCURSES_MOUSE_VERSION > 2 guard in your patch is therefore the right call, but the feature stays off until a distro moves.

For ncurses, a small residual: wheel-left comes with BUTTON_ALT set and wheel-right with BUTTON_SHIFT|BUTTON_ALT, and buttons 9-11 carry the same spurious modifiers. In the new handle_wheel(), the button > 3 branch applies bbits & 1/2/4 to the button code itself (66 and 67 have low bits set), not to a decoded modifier field, so the events claim modifiers that were never on the wire. Harmless for a & BUTTONn_PRESSED test, but it will confuse any caller that also reads the modifier bits. Worth a note upstream if you agree; happy to write it up the same way as the first report.

This is the report-back I owed you either way.

[fasterit]

Sounds great @ravi-arnan, thank you very much!

Please do report the spurious modifiers to bug-ncurses. These can (and should) still be fixed while nobody depends on the new functionality.

Oblig xkcd: https://xkcd.com/1172/

[ravi-arnan]

Follow-up on the spurious modifiers is up on bug-ncurses, same mailing-list
thread as the first report, and Dickey replied the same morning:

https://lists.gnu.org/archive/html/bug-ncurses/2026-08/msg00090.html

Short version of the report: the events now arrive cleanly (the two halves of
the first report are fixed in 6.6-20260829), but wheel-left/right and buttons
9-11 come with BUTTON_SHIFT/BUTTON_ALT set because handle_wheel() tests
bbits & 1/2/4 against the full SGR button code, whose low bits are part of
the button number (66/67, 129-131), not a decoded modifier field. Button 8 is
the clean control (SGR 128 has no low bits) and decodes correctly, which pins
the fault to exactly those low bits. Harmless for & BUTTONn_PRESSED,
misleading for anything reading the modifier bits.

Dickey: "thanks (I'll have to set up a more complete test) I did most of the
work using the single-byte code and then integrated the SGR-style code." So
the report landed where the defect came from; no patch was sent, I offered one
against the 20260829 tree if ncurses wants it, and the reproducer is scripted.

Not blocking the htop side: the horizontal wheel feature still needs ncurses
mouse version 3 (ABI 7 + --enable-ext-mouse2) which no distro ships, and
the #if NCURSES_MOUSE_VERSION > 2 guard remains the right call.