DECELR Enable Locator Reports

Report the position of a mouse or tablet, the locator, to the host.

CSI Ps ; Pu ' z

Defaults: Ps = 0, reports disabled; Pu = 0, character cells
DEC STD 070: §13, ch. 4 Enable Locator Reports, p. 5
xterm: Functions using CSI

DEC calls a mouse or a tablet a locator. With these functions a host can ask a terminal that has one to report where it is and which buttons are down:

Sequence	Function	Does
`CSI Ps ; Pu ' z`	DECELR, enable locator reports	`Ps`: `0` off, `1` on, `2` one report, then off; `Pu`: character cells or pixels
`CSI Pm ' {`	DECSLE, select locator events	which button presses and releases send a report
`CSI Ps ' \|`	DECRQLP, request locator position	asks for one report now
`CSI Pt ; Pl ; Pb ; Pr ' w`	DECEFR, enable filter rectangle	report once the locator leaves this rectangle
`DCS Pc $ w … ST`	DECLKD, locator key definition	what each button sends in ReGIS graphics input

A report is DECLRP, CSI Pe ; Pb ; Pr ; Pc ; Pp & w: the event, the buttons down, then the row, column and page of the locator.

All of this is DEC STD 070’s Text Locator Extension, section 13, an optional extension (its levels read “1x, 2x, 3x, 4x”). DECELR, DECSLE, DECRQLP and DECEFR are in its chapter 4, from p. 5, with DECLRP on p. 6; DECLKD, for the separate Locator Port Extension, is §5.4 on p. 13. A terminal that has the extension always answers a request, so an application never waits for a report that will not come. With locator reports disabled, DECRQLP is answered with event code 0, “the locator is unavailable”, and no other parameters, CSI 0 & w (p. 8), and so is a DECEFR received while reports are disabled.

A default xterm does not have the extension. It is built in only with --enable-dec-locator, which is off unless asked for (configure.in), and without it xterm’s parser turns all four CSI sequences into “ignore” (VTPrsTbl.c). DECLKD is not implemented in any build: xterm’s DCS handling acts on $ only when t follows it (misc.c), and its graphics code lists “locator key definitions (DECLKD)” as still to do (graphics.c). The cases follow a default xterm, as the sources page explains, so they expect these sequences to be consumed and change nothing, and to draw no report. That is what DEC STD 070 asks of a terminal without the extension, too, since it says a terminal ignores a function it does not implement (§3.5.1.3, p. 3-20); a terminal with it would answer DECRQLP. libghostty-vt has no handler for any of them, and ignores them as xterm does.

xterm and libghostty-vt both have a different kind of mouse reporting, xterm’s own, mouse tracking, turned on with private modes such as CSI ? 1000 h. The locator’s own status request, CSI ? 55 n, is on the DEC status reports page.

Validation

DECELR-1: Enabling reports changes nothing on screen

A
\e[1;2'z  # DECELR: reports on, in character cells
B

|AB____|
cursor 1,3
reply none

DECELR-2: No locator, no report

\e[1;2'z  # DECELR
\e['|     # DECRQLP

|______|
reply none

DECELR-3: DECSLE and DECEFR are consumed

A
\e[1;3'{  # DECSLE: report presses and releases
\e[1;1;2;2'w # DECEFR
B

|AB____|
reply none

DECELR-4: DECLKD’s string is consumed

A
\eP0$w1/41/42\e\\ # DECLKD: button 1 sends A down, B up
B

|AB____|
reply none