Allow configurable bindings for alternate-scroll-mode #2229

Lodifice commented 2025年12月05日 17:30:23 +01:00

Describe your feature request

Hi! First I'd like to express my sincere gratitude for developing foot. It's so far the only terminal that has all the features I want, and only the features I want.

In the time I've been using it, I encountered no bugs, but a difference to all previously used terminal emulators: in the alt screen, the mouse wheel does not scroll the screen contents, but sends up and down key events.

This is most obvious in Vim, where the cursor is moved to another line instead of moving the screen but keeping the cursor in place.

I realize that I could emulate the behavior I'm used to by disabling alternate-scroll-mode and relying on mouse support by the application, but (1) not all applications support mouse and (2) this leads to additional problems (for instance, with mouse support enabled, Vim moves the cursor every time you click, which is highly unusable).

So I would appreciate an option which lets me specify what key bindings are sent with alternate-scroll-mode. The usual choice compatible with many applications would be CTRL+Y/CTRL+E instead of up/down.

### Describe your feature request Hi! First I'd like to express my sincere gratitude for developing foot. It's so far the only terminal that has all the features I want, and only the features I want. In the time I've been using it, I encountered no bugs, but a difference to all previously used terminal emulators: in the alt screen, the mouse wheel does not scroll the screen contents, but sends up and down key events. This is most obvious in Vim, where the cursor is moved to another line instead of moving the screen but keeping the cursor in place. I realize that I could emulate the behavior I'm used to by disabling alternate-scroll-mode and relying on mouse support by the application, but (1) not all applications support mouse and (2) this leads to additional problems (for instance, with mouse support enabled, Vim moves the cursor every time you click, which is highly unusable). So I would appreciate an option which lets me specify what key bindings are sent with alternate-scroll-mode. The usual choice compatible with many applications would be CTRL+Y/CTRL+E instead of up/down.

dnkl commented 2025年12月10日 09:16:41 +01:00

In my experience, other terminal either emit up/down key events, or do nothing at all. The terminal cannot scroll the contents in (neo)vim.

What terminals usually do is enable alternate-scroll by default, and disable it if the TUI application enables mouse support.

We do have [text-bindings], but unfortunately it doesn't support mouse/wheel events. It would probably not too hard to add support for mouse/wheel events though.

In my experience, other terminal either emit up/down key events, or do nothing at all. The terminal _cannot_ scroll the contents in (neo)vim. What terminals usually do is enable alternate-scroll by default, and disable it if the TUI application enables mouse support. We do have `[text-bindings`], but unfortunately it doesn't support mouse/wheel events. It would probably not too hard to add support for mouse/wheel events though.

dnkl commented 2025年12月10日 09:18:23 +01:00

In the time I've been using it, I encountered no bugs, but a difference to all previously used terminal emulators: in the alt screen, the mouse wheel does not scroll the screen contents, but sends up and down key events.

Are you sure those applications automatically enable their built-in mouse support in those other terminals? This is typically TUI behavior - recognize and special case a few select terminals, and do something different from the rest.

> In the time I've been using it, I encountered no bugs, but a difference to all previously used terminal emulators: in the alt screen, the mouse wheel does not scroll the screen contents, but sends up and down key events. Are you sure those applications automatically enable their built-in mouse support in those other terminals? This is typically TUI behavior - recognize and special case a few select terminals, and do something different from the rest.

dnkl commented 2025年12月10日 09:22:08 +01:00

We do have [text-bindings], but unfortunately it doesn't support mouse/wheel events. It would probably not too hard to add support for mouse/wheel events though.

It's likely possible, but I'm afraid you'd also have to disable scrolling the normal (non-alt) screen.

But what I'd like come back to is that I don't really think other terminals do anything different. It's much more likely that the TUI applications is enabling different features in foot compared to the "other" terminals.

> We do have [text-bindings], but unfortunately it doesn't support mouse/wheel events. It would probably not too hard to add support for mouse/wheel events though. It's likely possible, but I'm afraid you'd also have to disable scrolling the normal (non-alt) screen. But what I'd like come back to is that I don't really think other terminals do anything different. It's much more likely that the TUI applications is enabling different features in foot compared to the "other" terminals.

Lodifice commented 2025年12月10日 10:50:22 +01:00

But what I'd like come back to is that I don't really think other terminals do anything different. It's much more likely that the TUI applications is enabling different features in foot compared to the "other" terminals.

I must admit that I don't know how these applications do it under the hood, but I can provide the following anecdotal evidence. Before switching to Wayland, I used both st and urxvt as terminal emulators.

1. In mutt, I had the problem that scrolling the mouse wheel in the index executed some weird commands. After binding CTRL+Y/CTRL+E to scrolling up/down, I could scroll in the index. After switching to foot, scrolling kept having the same effect, because up/down are bound to scroll this way by default.
2. In Vim, scrolling the mouse wheel always moved the screen contents without changing the line in which the cursor is positioned (unless scroll so far that the cursor line reaches one end of the screen, then it follows; there is actually a Vim option called scrolloff to fine-tune the behavior in that case). This corresponds to the Vim keybindings CTRL+Y/CTRL+E. After switching to foot, scrolling moves the cursor instead, which corresponds to up/down.

Based on this, I assume that these applications (and others I use) do nothing fancy, but just interpret the key codes they get. Interestingly, both terminals don't have scrolling by default. For st I installed all the scrollback patches and it "just worked" this way (not helpful, I know). For urxvt, I installed the common vtwheel Perl extension where you can configure the key code that is sent when scrolling. In my case, I set it to CTRL+Y/CTRL+E.

So to sum it up, I really think that there is an argument to make the key codes foot emits when using the mouse wheel in alternate screens configurable. I recognize that this is not as easy as adding simple mouse wheel bindings, because those would prevent scrolling in the "normal" screen. However, it should be possible to change those up/down keycodes in some way. I just don't know how large the effort would be for this – I admit it – niche use case :D

> But what I'd like come back to is that I don't really think other terminals do anything different. It's much more likely that the TUI applications is enabling different features in foot compared to the "other" terminals. I must admit that I don't know how these applications do it under the hood, but I can provide the following anecdotal evidence. Before switching to Wayland, I used both st and urxvt as terminal emulators. 1. In mutt, I had the problem that scrolling the mouse wheel in the index executed some weird commands. After binding CTRL+Y/CTRL+E to scrolling up/down, I could scroll in the index. After switching to foot, scrolling kept having the same effect, because up/down are bound to scroll this way by default. 2. In Vim, scrolling the mouse wheel always moved the screen contents without changing the line in which the cursor is positioned (unless scroll so far that the cursor line reaches one end of the screen, then it follows; there is actually a Vim option called scrolloff to fine-tune the behavior in that case). This corresponds to the Vim keybindings CTRL+Y/CTRL+E. After switching to foot, scrolling moves the cursor instead, which corresponds to up/down. Based on this, I assume that these applications (and others I use) do nothing fancy, but just interpret the key codes they get. Interestingly, both terminals don't have scrolling by default. For st I installed all the scrollback patches and it "just worked" this way (not helpful, I know). For urxvt, I installed the common vtwheel Perl extension where you can configure the key code that is sent when scrolling. In my case, I set it to CTRL+Y/CTRL+E. So to sum it up, I really think that there is an argument to make the key codes foot emits when using the mouse wheel in alternate screens configurable. I recognize that this is not as easy as adding simple mouse wheel bindings, because those would prevent scrolling in the "normal" screen. However, it should be possible to change those up/down keycodes in some way. I just don't know how large the effort would be for this – I admit it – niche use case :D

dnkl commented 2025年12月10日 11:36:09 +01:00

Ok, I see. I agree, the TUI applications likely not doing anything differently. It's just that you've configured the terminals differently.

FWIW, alternate-scroll is spec:ed to send up/down (https://invisible-island.net/xterm/manpage/xterm.html#VT100-Widget-Resources:alternateScroll).

That said, I don't want to close this issue right away; let me think a bit.

Ok, I see. I agree, the TUI applications likely not doing anything differently. It's just that you've configured the terminals differently. FWIW, alternate-scroll is spec:ed to send up/down (https://invisible-island.net/xterm/manpage/xterm.html#VT100-Widget-Resources:alternateScroll). That said, I don't want to close this issue right away; let me think a bit.

Lodifice commented 2025年12月10日 12:49:30 +01:00

Thanks for considering it.

I didn't realize there was a standard for alternate-scroll, CTRL+Y/CTRL+E seems to originate from Vi: https://docs-archive.freebsd.org/44doc/usd/12.vi/paper-2.html#section10

I must have picked it up from st (where it somehow was the default) and liked the behavior so much (more than moving the cursor) that I also used it in urxvt (and now miss it in foot).

Thanks for considering it. I didn't realize there was a standard for alternate-scroll, CTRL+Y/CTRL+E seems to originate from Vi: https://docs-archive.freebsd.org/44doc/usd/12.vi/paper-2.html#section10 I must have picked it up from st (where it somehow was the default) and liked the behavior so much (more than moving the cursor) that I also used it in urxvt (and now miss it in foot).