Skip to main content
ansicode

DEC locator suite — DECELR / DECEFR / DECSLE / DECRQLP (mouse / locator events)

The original DEC pointing-device protocol (predates xterm SGR mouse modes by a decade). Four sequences enable, filter, select, and query locator events; modern interactive UIs use SGR mouse modes (?1000 + ?1006) instead.

Byte forms

Every common string-literal form so you can paste-and-search either direction.

\\x1b[\x1b[<Pn>;<Pu>'z \x1b[<Pm>'{ \x1b[<Pt>;<Pl>;<Pb>;<Pr>'w \x1b[<Ps>'|
\\033[\033[1;2'z
\\e[\e[1;2'z
ESC [ESC [ ... ' z / ' { / ' w / ' |
hex1b 5b ... 27 7a / 7b / 77 / 7c

Description

The DEC locator protocol predates the xterm extended mouse modes by a decade and is how VT300+ hardware terminals (and software emulators when bumped to a high DECSCL conformance — see decscl-compat-level) report pointing-device events. Four sequences make up the family — all share the single-quote (0x27) intermediate byte:

- DECELR — *Enable Locator Reports* — \x1b[<Pn>;<Pu>'z - Pn: 0 = disable locator reports, 1 = enable, 2 = enable for one report only (then auto-disable). - Pu: 0 or 2 = report coordinates in character cells, 1 = report in device units (pixels). - Once enabled, the terminal sends a DECLRP report on every button transition that passes the DECSLE filter, plus one when an outside-the-rectangle move happens (if DECEFR has set a rectangle).

- DECSLE — *Select Locator Events* — \x1b[<Pm>'{ - Pm: 0 = only explicit DECRQLP requests trigger a report; 1 = button-down events trigger reports; 2 = disable button-down reporting; 3 = button-up events trigger reports; 4 = disable button-up reporting. - May be repeated with different Pm values to enable button-down AND button-up: \x1b[1'{\x1b[3'{.

- DECEFR — *Enable Filter Rectangle* — \x1b[<Pt>;<Pl>;<Pb>;<Pr>'w - Defines an inclusive rectangle: top row, left col, bottom row, right col. Locator movement *outside* the rectangle triggers one DECLRP report, then the filter is auto-disabled. - Used for cursor-tracking apps that only care about 'mouse exited my widget' transitions.

- DECRQLP — *Request Locator Position* — \x1b[<Ps>'| - Ps: number of transactions (currently always 1). - Forces an immediate DECLRP report regardless of filter / event settings.

DECLRP — the reply — \x1b[<Pe>;<Pb>;<Pr>;<Pc>;<Pp>&w (note the & intermediate, distinct from request finals): - Pe = event type: 0 = locator unavailable (no pointer), 1 = response to DECRQLP, 2 = left button down, 3 = left button up, 4 = middle down, 5 = middle up, 6 = right down, 7 = right up, 8 = M4 (button 4) down, 9 = M4 up, 10 = locator outside filter rectangle. - Pb = button-state bitmask: 1 = left, 2 = middle, 4 = right, 8 = button 4. OR them together. - Pr, Pc = row, column (1-indexed) in whatever units DECELR's Pu selected. - Pp = page number (always 1 on modern emulators — multi-page is a hardware-terminal concept).

Why you almost certainly don't need this: certain legacy CAD, terminal-based GIS, and radar / SCADA apps written in the 1980s expect this protocol. Some xterm extensions (the xterm*set-locator-events X resource) still enable it. Modern interactive UIs — tmux, htop, mc, lazygit, fzf, neovim's :terminal — all use SGR mouse modes (?1000 enable + ?1006 SGR encoding; see dec-mouse-tracking and sgr-mouse-encoding) because they're easier to parse, support multi-byte coordinates trivially, and have near-universal cross-emulator coverage.

Coverage matrix: xterm = full implementation (only widely-deployed emulator that does). gnome-terminal / konsole = partial (DECRQLP returns a synthetic 'no pointer' DECLRP). iTerm2 / kitty / wezterm / alacritty / ghostty / Windows Terminal / cmd / Linux console / macOS Terminal = none — the sequences are silently consumed and produce no reply.

When you might still reach for it: targeting xterm specifically on a legacy XFCE / CDE system; porting old SCADA terminal apps; testing terminfo entries for locator_* capabilities. Otherwise use SGR mouse modes.

Spec citation: DEC VT510 RM (DECELR / DECEFR / DECSLE / DECRQLP / DECLRP) / xterm-ctlseqs

Examples

bash
# Enable locator reports (cell coords, one-shot), then query position.\nprintf \"\\033[2;0'z\"   # DECELR Pn=2 one-shot, Pu=0 cells\nprintf \"\\033[1'|\"     # DECRQLP — force immediate DECLRP reply\n# read reply matching: \\x1b[1;Pb;Pr;Pc;1&w
python
import sys\n# Set filter rectangle around rows 5-20, cols 10-60 then enable button-down events.\nsys.stdout.write(\"\\x1b[1;0'z\")        # DECELR enable, cells\nsys.stdout.write(\"\\x1b[5;10;20;60'w\") # DECEFR filter rect\nsys.stdout.write(\"\\x1b[1'{\")          # DECSLE enable button-down reports\nsys.stdout.flush()
go
// Disable locator reports (clean exit).\nfmt.Print(\"\\x1b[0;0'z\")
javascript
// Parse a DECLRP reply: \\x1b[Pe;Pb;Pr;Pc;Pp&w\nfunction parseDECLRP(buf) {\n  const m = /\\x1b\\[(\\d+);(\\d+);(\\d+);(\\d+);(\\d+)&w/.exec(buf);\n  if (!m) return null;\n  return { event: +m[1], buttons: +m[2], row: +m[3], col: +m[4], page: +m[5] };\n}
c
/* Force a single locator-position report (synchronous-ish probe). */\nprintf(\"\\x1b[1;0'z\");   /* DECELR enable, cells */\nprintf(\"\\x1b[1'|\");     /* DECRQLP */\nfflush(stdout);\n/* read reply: matches sscanf(\"\\x1b[%d;%d;%d;%d;%d&w\", &pe,&pb,&pr,&pc,&pp) */

Terminal support

xterm
yes
Linux console (fbcon)
no
macOS Terminal.app
no
iTerm2
no
Windows Terminal
no
cmd.exe / ConPTY
no
kitty
no
alacritty
no
WezTerm
no
Ghostty
no
GNOME Terminal
partial
Konsole
partial
tmux
no
GNU screen
no

Related sequences