Button-event mouse

AI-Generated Content

This page was generated with the assistance of AI and may contain inaccuracies. It is intended as a placeholder for future human verification. If you spot issues ahead of its initial review, please report them on GitHub!

Experimental

Button-Event Mouse Tracking (Mode 1002) is a DECSET/DECRST mode that extends normal mouse tracking (Mode 1000) by also reporting mouse motion events while a button is held down.

Syntax

CSI ? 1002 h    DECSET — Enable button-event mouse tracking
CSI ? 1002 l    DECRST — Disable button-event mouse tracking

Formal syntax

DECSET-mode1002 = 0x1b, "[", "?", "1", "0", "0", "2", "h" ;
DECRST-mode1002 = 0x1b, "[", "?", "1", "0", "0", "2", "l" ;

Description

Mode 1002 is an XTerm extension that enables button-event tracking, also known as "drag tracking." When enabled, the terminal reports all events that Mode 1000 reports (button press and release), and additionally reports mouse motion events whenever a button is held down.

Set — The terminal reports mouse button press, release, and motion-while-pressed events.
Reset — Mouse events are not reported. The terminal handles mouse events normally. This is the default.

Report format

Button-event tracking uses the same report format as Mode 1000:

CSI M Cb Cx Cy

Where:

Cb is the button/event byte: the button number plus modifier flags, plus 32
Cx is the column (x coordinate) plus 32
Cy is the row (y coordinate) plus 32

For motion events, bit 5 (value 32) is added to Cb to distinguish them from press events. The low bits still indicate which button is being held.

Value (Cb - 32)	Meaning
`32`	Motion with left button held
`33`	Motion with middle button held
`34`	Motion with right button held

Difference from Mode 1000 and Mode 1003

Mode 1002 sits between Mode 1000 and Mode 1003 in terms of verbosity:

Mode 1000 reports only press and release events.
Mode 1002 adds motion events, but only while a button is held down (i.e., during a drag operation).
Mode 1003 reports all motion events regardless of button state, generating significantly more traffic.

Mode 1002 is the most practical choice for applications that need drag support without the overhead of tracking every mouse movement.

note

Mode 1002 mutually excludes other mouse tracking modes. Enabling it implicitly disables Mode 1000 and Mode 1003.

Examples

printf '\e[?1002h'   # Enable button-event mouse tracking
printf '\e[?1002l'   # Disable button-event mouse tracking

# Combine with SGR encoding for coordinates beyond 223:
printf '\e[?1002h\e[?1006h'   # Enable button-event tracking + SGR encoding
printf '\e[?1006l\e[?1002l'   # Disable both (reverse order)

Specifications

Specification	Section
XTerm ctlseqs	—

Terminal support

Terminal	Support	Version	Notes
Terminal Emulators
Alacritty	✓	Yes
Bobcat	✓	0.9.0	Implemented in TerminalCtrl library. README states 'Full Mouse & Keyboard Support across all major protocols'.
contour	✓	v0.3.0.198	Implemented as DECMode::MouseProtocolButtonTracking, handled in Terminal.cpp:2402
foot	✓	Yes
Ghostty	✓	v1.0.0
iTerm2	✓	v20260216-nightly
Kitty	✓	Yes
Konsole	✓	Yes	MODE_Mouse1002 for drag tracking
mintty	✓	Yes	Implemented at src/termout.c:2490
mlterm	✓	rel-0_2_1	Present since initial public release
PuTTY	✓	0.52
Rio	✓	v0.1.13
rxvt-unicode	✓	8.4
st	✓	0.4
terminology	✓	v0.2.0	Sets mouse_mode to MOUSE_NORMAL_BTN_MOVE
VT100	✗	No
VTE	✓	Yes
WezTerm	✓	Yes
Windows Terminal	✓	Yes	BUTTON_EVENT_MOUSE_MODE at adaptDispatch.cpp:1850-1852
xterm	✓	Yes	Button-event mouse tracking
xterm.js	✓	0.3
Multiplexers
cy	✓	Yes
GNU Screen	✓	v.4.2.0	Present since at least v.4.0.2 (2005)
tmux	✓	1.7
tuios	✓	v0.0.15
Zellij	✓	v0.31.2

Syntax​

Description​

Report format​

Difference from Mode 1000 and Mode 1003​

Examples​

Specifications​

Terminal support​

See also​