Mouse Support 🐭

[flatcap]

Adding mouse support to NeoMutt is a big job, but we can start simply.

• Proof of concept
• Hard-coded behaviour
  • Left-Click
    • Sidebar (<sidebar-open>)
    • Index (<display-message>)
    • Mini-Index (<display-message>)
  • Scrolling
    • Index
    • Mini-Index
  • Multi-selection
    • Ctrl-click
    • Shift-click
• Config
  • Enable mouse
  • Customise behaviour

[flatcap]

Test Code

Here's some sample code...

mouse.php

• https://gist.github.com/flatcap/0306116f7c8d103873e5b57014987a78
  Run: php mouse.php

This shows what the terminal can give us.
It tracks the mouse and catches mouse clicks and scrolling.

mouse.c

• https://gist.github.com/flatcap/7d4cdc9250cdd1ea80e009fb99968faa
  Compile: gcc -o mouse mouse.c -lncursesw
  Run: ./mouse

It tracks the mouse and catches mouse clicks and scrolling.
It also shows which if shift, ctrl and alt are active.

[devel/mouse]

• https://github.com/neomutt/neomutt-old/tree/mouse
  Configure: ./configure --devel-mouse
  Run: ./neomutt

This branch is a Proof-of-concept for mouse support in NeoMutt.
It has one hard-coded function: <left-click> on the sidebar calls <sidebar-open>.

[flatcap]

How it works

I wrote the proof-of-concept nearly two years ago. Quite a lot has changed since then.
The dialogs have become much more modular, each having a clear Event Loop and calling function dispatchers to do the work.
The code is currently Window-centric; this might change.

NeoMutt's windows are nested:

See also:

• Window Glossary: Technical Glossary #3265 (comment)
• Screenshots: https://github.com/neomutt/gfx/tree/main/screenshots

Each dialog's event loop calls km_dokey() which leads to mutt_getch().
Ncurses' getch() gives us both keyboard and mouse events.
I added a call to mouse_handle_event() in mutt_getch() which looks and notifies the correct window.

struct MuttWindow already has several methods, e.g. repaint().
I've added a mouse() function that each window/dialog can override.

Finally, sidebar_mouse() receives an EventMouse.
It looks up which Mailbox corresponds to the Window coordinates and changes to that folder.

Refs:

• km_dokey https://github.com/neomutt/neomutt/blob/a79634d2e336b2299b1d06ae8903caf14b2e4924/gui/keymap.c#L798
• mutt_getch https://github.com/neomutt/neomutt/blob/a79634d2e336b2299b1d06ae8903caf14b2e4924/gui/gui/curs_lib.c#L242
• mouse_handle_event https://github.com/neomutt/neomutt/blob/a79634d2e336b2299b1d06ae8903caf14b2e4924/gui/gui/mouse.c#L130
• struct MuttWindow https://github.com/neomutt/neomutt/blob/a79634d2e336b2299b1d06ae8903caf14b2e4924/gui/gui/mutt_window.h:L123
• struct MuttWindow.mouse https://github.com/neomutt/neomutt/blob/a79634d2e336b2299b1d06ae8903caf14b2e4924/gui/gui/mutt_window.h:L194
• sidebar_mouse() https://github.com/neomutt/neomutt/blob/a79634d2e336b2299b1d06ae8903caf14b2e4924/gui/sidebar/sidebar.c:#208

[flatcap]

Events

We can start with hard-coded behaviours, e.g. click here means this function.

In increasing order of difficulty, the events are:

Single Click

The simplest event is a single left mouse click.

We can convert this into a selection of an item in a list.
Many of the dialogs have a struct Menu list.

Scrolling

The mouse wheel gives us button 4/5 events.
Currently, ncurses turns these into <up> / <down> cursor movements.
It'd be more natural to move the viewport rather than the selection.

For the Pager, this should be pretty simple.

However, struct Menu isn't ready for this.
As you move the viewport, it drags the selection with it.
We'd need to change the Menu so that the selection can move offscreen.

Shift/Ctrl Left-Click

Some dialogs allow multi-selection, e.g. Alias dialog.
It'd be nice to be able to support the usual: click, shift-click, ctrl-click behaviours.

Again, this is likely to need some changes to the Menu.

[flatcap]

Config

The final challenge would be to make everything configurable.

We'd need to start with a simple:

# Enable mouse features
set mouse = yes

but we'd want to be able to bind mouse events like keyboard events:

bind index <left-mouse> display-message
macro index <2-left-mouse> <create-alias><compose-to-sender>

I don't know how this would work :-)

[gerazov]

Thanks for the awesome work laying it all down! 😎

This would really be helpful! 👍

One more suggestion - maybe adding scrolling to the pager as well?

[flatcap]

Good point. I listed the hard problems, but forgot a simple one.
Updated :-)

[aliceinwire]

This is really needed :/ ?!? just wondering

[flatcap]

Needed? No :-)
There are bound to be some purists who will hate the idea, but it's easy to add and quite useful.

I'd certainly like to be able to select emails/mailboxes with my trackpad.

[aliceinwire]

IMHO I would give this really low priority :P

[asdf8dfafjk]

I know I'm just begging in disguise but one nice thing with mouse support would be a header in pager so I can change the sort fields. Also some kinda "quick limit" button such that if I click a particular author/sender, I see their emails.

[flatcap]

Sound like nice ideas. Noted.

I know I'm just begging in disguise

:-)

[Freed-Wu]

I have a touchable device then by some strange chance I found this discussion. Just for fun:

diff --git a/key/get.c b/key/get.c
index 8e3dfd3..1030d11 100644
--- a/key/get.c
+++ b/key/get.c
@@ -231,6 +231,7 @@ struct KeyEvent mutt_getch(GetChFlags flags)
   SigInt = false;
   mutt_sig_allow_interrupt(true);
   timeout(1000); // 1 second
+  mousemask(ALL_MOUSE_EVENTS, NULL);
 #ifdef USE_INOTIFY
   ch = mutt_monitor_getch();
 #else
@@ -253,6 +254,14 @@ struct KeyEvent mutt_getch(GetChFlags flags)
     }
   }

+  if (ch == KEY_MOUSE)
+  {
+    MEVENT event;
+    if (getmouse(&event) == OK) {
+      mvprintw(5, 5, "mouse is pressed on (%d, %d)", event.x + 1, event.y + 1);
+    }
+  }
+
   if (ch == ERR)
   {
     if (!isatty(0)) // terminal was lost

Refer: https://tldp.org/HOWTO/NCURSES-Programming-HOWTO/mouse.html

[flatcap]

hehe, nice!

I created a proof-of-concept, years ago -- https://github.com/neomutt/neomutt-old/tree/mouse
I've just rebased it over main and it still works -- you can click on the sidebar.

git clone --branch mouse https://github.com/neomutt/neomutt-old/
./configure --devel-mouse ...
make

[alexbarton]

I'm running NeoMutt with this patch now; thanks a lot @flatcap!
Would really like to see this further tweaked, improved and integrated 😉

[flatcap]

It's a quick hack. Nothing more.
I'm way too busy fixing other things to work on this.

What we need is a volunteer -- Help will be given.