How does emacs catch scroll events in the terminal?

Question

The exact title. this is a somewhat related question. I'd specifically like to know how mouse scroll events are caught when invoked as emacs -nw.

Mode 1049 (alternate screen buffer) and 1000 (mouse tracking) roughly emulate it but don't get it quite right (for example, click events are caught as well and highlighting with cursor is not possible in the terminal).

I've scoured the source code on GitHub, but there's no details leading me to finding this.

Answer 1

The document that you linked to contains exactly the information you need:

Normal tracking mode sends an escape sequence on both button press and
release.  Modifier key (shift, ctrl, meta) information is also sent.  It
is enabled by specifying parameter 1000 to DECSET.  On button press or
release, xterm sends CSI M CbCxCy.

Note that last bit: any mouse button press or release event that xterm gets is translated into a sequence of characters to be sent to the application inside. Specifically, it sends CSI M followed by three parameters, Cb, Cx, and Cy. I bet you could figure out what they mean just by guessing. CSI is defined much earlier in the document to be the escape character followed by an open square brace. Emacs translates ESC [ into M-[, and when running in a terminal installs a keymap there that does the job of translating the terminal’s escape sequences into commands.

Note that xterm mostly emulates a DEC VT340 terminal, but some things (such as mouse events) are extensions allowing features that the VT340 never had. Most terminal emulators default to copying whatever xterm does, but the specific terminal emulator that you use might not. You should investigate its documentation as well, in case its author decided to do their own thing.