#148 Mouse focus event tracking (DECSET/DECRST 1004)

[Rob Swindell]

Please implement focus event tracking (DECSET/DECRST 1004), so an
application can tell when the SyncTERM window has lost the focus.

cterm.adoc currently lists it as unsupported in both directions:

|1004
|Focus-event tracking mode mouse reporting

(Not supported by SyncTERM)

The xterm behaviour is small and well defined: with CSI ? 1004 h set, the
terminal sends CSI I when the window gains the focus and CSI O when it
loses it. CSI ? 1004 l disables it.

Why it matters

An application reading mouse motion cannot tell these three apart, because
all of them are the same thing on the wire -- nothing:

• the pointer is pressed against the edge of the window and physically
  cannot move further
• the window has lost the focus
• nobody is touching the mouse

That distinction matters to anything that keeps acting on the pointer's
last known position. A terminal has no pointer lock and no way to warp the
cursor, so a first-person application cannot do what a native game does --
grab the pointer and pin it to the centre. The usual substitute is to keep
turning the view while the pointer rests against an edge, which is the only
way to look further left once the pointer is already at the left edge.

That works, until the window loses the focus with the pointer near an edge.
The application is still holding a position that says "the user is asking to
turn", nothing further arrives to contradict it, and the view spins until
somebody comes back to the window. Reported by a user as exactly that.

The workaround is a timeout: keep pushing for N seconds since the last
mouse report, then stop. It is a poor trade in both directions. Too short
and a deliberate slow look-around dies half way; too long and an abandoned
window keeps spinning. Neither is a judgement the application should be
guessing at when the terminal knows the answer.

Focus is also the natural signal for an application to stop drawing at
full rate, or to hold an idle timer, while nobody is looking at it.

It is already detected

This looks like plumbing rather than new detection. Every backend already
notices focus changes and calls ciokey_focus_lost():

src/conio/win32gdi.c   WM_KILLFOCUS / WM_SETFOCUS
src/conio/x_events.c   FocusIn / FocusOut
src/conio/wl_events.c
src/conio/sdl_con.c

What is missing is reporting the change to the host when mode 1004 is set.

Requested by Claude (Anthropic), working with the sysop of Vertrauen on a
first-person door.

[Stephen James Hurd]

You seem to be conflating the window losing focus with the mouse leaving the window and the mouse leaving the pixel area of the window. Outside of fullscreen mode (and usually even in full-screen mode) there's a large area outside of the pixel coordinate system... black bars on the edges and "the rest of the desktop" all fall into this nebulous zone.

Further, I can't think of any compelling reason a BBS needs to know if a specific window on my desktop has focus or not.

[Rob Swindell]

We can close this request. Thanks,