Terminal Guide

Mouse

Mouse tracking modes enable the application to react to mouse input.

Configuration is for 2 independent aspects:

Additionally there are some special modes.

Events

These modes are mutually exclusive. The last activated mode wins.

mouse click-only trackingSend 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 trackingSend mouse button press and release.
Also send scroll wheel events.
mouse highlight modeLike mouse down+up tracking, but shows a text selection.
Needs a cooperating application to avoid rendering the terminal non operative
mouse click and dragging trackingSend mouse button press and release. Send mouse move events while a button is pressed.
Also send scroll wheel events.
mouse tracking with movementSend mouse button press and release. Always send mouse move events.
Also send scroll wheel events.

 

Reporting format

defaultMouse information is reported as
ESC1b [5b M4d btn column row 
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 NUL00  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 ESC1b >3e M4d )
mouse report format multibyteMouse information is reported as
ESC1b [5b M4d btn column row 
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 NUL00  is used as out of range marker. The output is decodable with an standard utf-8 decoder. There is no separator between the bytes.
(TODO: sometimes starts with ESC1b >3e M4d )
mouse reporting format digitsMouse information is reported as
ESC1b [5b <3c btn ;3b column ;3b row M4d  for button press or movement, and
ESC1b [5b <3c btn ;3b column ;3b row m6d  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 an standard utf-8 decoder, because it only contains ascii characters.
mouse reporting format urxvtMouse information is reported as
ESC1b [5b btn ;3b column ;3b row M4d 
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 333 434 ). This mode does not have an arbitrary range limit. The output is decodable with an standard utf-8 decoder, because it only contains ascii characters.

Mouse button ids:

left0
middle1
right2
some button was released3
wheel up4
wheel down5
wheel left6 (only xterm since version 338)
wheel right7 (only xterm since version 338)
additional buttonssee 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 mousebtnencoded value in btn
11
22
464
8128

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 move32
shift4
alt8
ctrl16

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)

Reporting buttons (unless in mouse reporting format digits)

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).

Reporting buttons in mouse reporting format digits

When a button is pressed it's id is used in the report with a final character M4d . When a button is released the same id is used but with a final character m6d . 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).

Highlight tracking

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 a 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.