Mouse tracking modes enable the application to react to mouse input.
Configuration is for 2 independent aspects:
Additionally there are some special modes.
These modes are mutually exclusive. The last activated mode wins.
| mouse click-only tracking | Send mouse button press. Button encoding btn does not contain bits for modifiers etc, but is the button number without moved bits. Only left, middle and right mouse buttons are reported |
| mouse down+up tracking | Send mouse button press and release. Also send scroll wheel events. |
| mouse highlight mode | Like mouse down+up tracking, but shows a text selection. Needs a cooperating application to avoid rendering the terminal non operative |
| mouse click and dragging tracking | Send mouse button press and release. Send mouse move events while a button is pressed. Also send scroll wheel events. |
| mouse tracking with movement | Send mouse button press and release. Always send mouse move events. Also send scroll wheel events. |
| default | Mouse information is reported as ESC[MⒸⒸⒸ with btn, column and row encoded as bytes with code 32 + value. This mode has a range from 1 to 223. If the value exceeds the range a NUL is used as out of range marker. These are not encoded in utf-8 but output as raw bytes. There is no separator between the bytes.(TODO: sometimes starts with ESC>M) |
| mouse report format multibyte | Mouse information is reported as ESC[MⒸⒸⒸ with btn, column and row encoded as variable length byte sequences. For values < 96 the format is identical to the default mode. Values above that boundary are encoded as 2 bytes as if encoding codepoint value + 32 as utf-8. This mode has a range from 1 to 2015. If the value exceeds the range a NUL is used as out of range marker. The output is decodable with a standard utf-8 decoder. There is no separator between the bytes.(TODO: sometimes starts with ESC>M) |
| mouse reporting format digits | Mouse information is reported as ESC[<Ⓝ;Ⓝ;ⓃM for button press or movement, and ESC[<Ⓝ;Ⓝ;Ⓝm for button release with btn, column and row encoded as variable length digit sequences in base 10. This mode does not have an arbitrary range limit. The output is decodable with a standard utf-8 decoder, because it only contains ascii characters. |
| mouse reporting format urxvt | Mouse information is reported as ESC[Ⓝ;Ⓝ;ⓃM with btn, column and row encoded as variable length digit sequences in base 10. For `btn` the encoded value is offset by the value 32(i.e. the right button is encoded as 34). This mode does not have an arbitrary range limit. The output is decodable with a standard utf-8 decoder, because it only contains ascii characters. |
Mouse button ids:
| left | 0 |
| middle | 1 |
| right | 2 |
| some button was released | 3 |
| wheel up | 4 |
| wheel down | 5 |
| wheel left | 6 (only xterm since version 338) |
| wheel right | 7 (only xterm since version 338) |
| additional buttons | see below (only xterm since version 341) |
The mouse button number mousebtn has valid ids of 0 to 2 and 4 to 15.
In all modes except for mouse click-only tracking mousebtn is encoded by using the two lower bits of mousebtn as is and translating the next bits to 64 and 128.
bit value in mousebtn | encoded value in btn |
|---|---|
| 1 | 1 |
| 2 | 2 |
| 4 | 64 |
| 8 | 128 |
Buttons 12 to 15 are only available when using mouse reporting format digits or mouse reporting format urxvt.
The btn parameter also contains additional information encoded as special bits (not used in mouse click-only tracking):
| mouse move | 32 |
| shift | 4 |
| alt | 8 |
| ctrl | 16 |
column and row always are coordinates of a cell in the terminal (never < 1 and never bigger than the size in their dimension of the terminal)
When a button is pressed its id is used in the report. When a button is released the generic id '3' is used, it is impossible to deduce which button was released.
When multiple buttons are held down while moving the mouse the report contains the held button with the lowest id.
When no buttons are held down while moving the mouse the reported button id is 3 (button released).
When a button is pressed it's id is used in the report with a final character M. When a button is released the same id is used but with a final character m. By using different final characters the application can track which buttons are held down even after multiple buttons where held at the same time.
When multiple buttons are held down while moving the mouse the report contains the held button with the lowest id.
When no buttons are held down while moving the mouse the reported button id is 3 (button released).
mouse highlight mode is a special case.
For left button clicks the terminal will render a text selection highlight starting at an application specified point and restricted to an application specified range of lines. After ending the selection it's not automatically transferred to the clipboard. After release of the mouse button the highlighting is automatically removed.
For other mouse button clicks the reporting is as in mode mouse down+up tracking.
Protocol Details
When the user presses the left mouse button the terminal sends a mouse down according to the currently selected encoding. Next it waits for the application to reply with further instructions using track mouse. The only known implementation (xterm) freezes until it receives an answer (no repaint handling, no input processing). If the application replies with an abort mouse tracking sequence the terminal proceeds like in mode mouse down+up tracking.
Otherwise the terminal has received a start position and a line range from the application. On following mouse moves by the user it paints a selection from that start position to the position of the mouse pointer. The selection is clamped to the given range of lines (all columns are allowed). When the user releases the mouse button the terminal reports the end position of the selection using the currently selected encoding but replacing the M sequence identifier by T or 't'.
If the user did not move the mouse pointer the reply uses t and contains two parameters which are the same position (reported as row and column) as the mouse down event. If the selection is empty the terminal does not reply at all. If the selection only contains one character it replies with t and the position following the start position. If the mouse was moved otherwise the reply uses ´T` and has 6 parameters: startx, starty, endx, endy, mousex and mousey. The start and end parameters contain the selected range (between the start position given by the application and the clamped mouse position) normalized so start is before end. start is inclusive and end is exclusive. If the last line in the range is fully selected the reported position will be the first column on the first unreachable line. The mouse parameters contain the un-clamped mouse pointer position.