Patch scrolling back in suckless ST terminal to support mouse wheel

Question

The ST terminal has a patch for scrolling back. I want to update said patch to enable mouse wheel up and down signals in additions to "PageUp" and "PageDown". I suspect that a small change in config.h is what is needed but I have no experience in terminal code thus my plea for help.

In the source code, in config.h these lines appear:

static Mousekey mshortcuts[] = {
    /* button               mask            string */
    { Button4,              XK_ANY_MOD,     "\031" },
    { Button5,              XK_ANY_MOD,     "\005" },
};

So, clearly, we know what Button4/5 are. In addition, we have these:

static Shortcut shortcuts[] = {
    /* mask                 keysym          function        argument */
    [...]
    { ShiftMask,            XK_Page_Up,     kscrollup,      {.i = -1} },
    { ShiftMask,            XK_Page_Down,   kscrolldown,    {.i = -1} },
};

So, naively, I a assuming that adding another two raw (one for wheel up, one for wheel down) would do the trick. However, what?

---

Note: I know that suckless recommends using a terminal multiplexer such as tmux. I use that already. However, sometimes (rarely) I just want to use a terminal without tmux and this feature would be useful. Please do not comment/answer to use tmux, this is not what this question is about.

Solution 1

It is not that simple. This question occasionally arises when someone wants left/right scrolling for a mouse trackball.

On the left column of the tables is an X event. Those are limited to combinations of predefined symbols.

Button4 and Button5 are mentioned because those are conventionally used to pass the mouse wheel events. That has been the case for quite a while; there was a resource file used before modifying xterm in 1999 (patch #120) to make this a built-in feature.

The possible X events are laid out in C header files — X.h — and tables in the X source code; no wheel mouse events are provided for as such. For instance, there is a table in the X Toolkit library which lists all of the possibilities (for clients using X Toolkit such as xterm). xev uses the header-definitions.

If X were to support wheel mouse events in a different way, it would probably use new function calls for this purpose since the existing information may be packed into bit-fields in a way that precludes easy extensibility.

Solution 2

There is now a standalone program scroll that provides scrollback buffer for any terminal emulator. At the time of writing this answer, it is still in an experimental state, a lot of bugs are expected. In spite of that, it already handles scrollback better than the scrollback patches for st. E.g. resizing the terminal will wrap previous output instead of cut off and lose them.

To enable it, first of course download/clone the source code from suckless website and build it locally.

Then modify this line in config.def.h of st (you have to fetch the recent git commits to get support for scroll)

char *scroll = NULL;

to

char *scroll = "/path/to/scroll";

Now rebuild st, and run st. It will automatically use scroll to provide the scrollback buffer.

As stated in the manual, another way without modifying st's source code is to run st with the following command after you have installed both st and scroll:

/path/to/st -e /path/to/scroll /bin/sh

Solution 3

From the suckless site, there are some scroll back patches that allow scrolling using Shift+MouseWheel as well as full mouse scroll. The last patch might break other mkeys excluding scrolling functions.