New focus management interface

focus-in-hook and focus-out-hook don't accurately reflect actual
user-visible focus states.  Add a new focus interface and mark the old
one obsolete.

* doc/lispref/frames.texi (Input Focus): Document new focus
functions.  Remove references to the now-obsolete focus hooks.

* lisp/frame.el (frame-focus-state): New function.
(after-focus-change-function): New variable.
(focus-in-hook, focus-out-hook): Move to lisp from C;
mark obsolete.

* lisp/term/xterm.el (xterm-translate-focus-in)
(xterm-translate-focus-out): Track tty focus in `tty-focus-state'
terminal parameter; call `after-focus-change-function'.
(xterm--suspend-tty-function): New function.

* src/frame.c (Fhandle_switch_frame): Update docstring; don't call
focus hooks.
(focus-in-hook, focus-out-hook): Remove: moved to lisp.
(syms_of_frame): Remove unread_switch_frame; add
Vunread_switch_frame.

* src/keyboard.c:
(Finternal_handle_focus_in): New function.
(make_lispy_event): Always report focus events to lisp; don't
translate them to switch events sometimes.  Lisp can take care of
creating synthetic switch-frame events via
`internal-handle-focus-in'.

* src/w32term.c (x_focus_changed): Remove switch-avoidance logic:
just directly report focus changes to lisp.

* src/xterm.c (x_focus_changed): Remove switch-avoidance logic:
just directly report focus changes to lisp.

2 files changed, 103 insertions, 14 deletions

diff --git a/lisp/frame.el b/lisp/frame.el
index c3daff44406..2a2391e8a53 100644
--- a/lisp/frame.el
+++ b/lisp/frame.el
@@ -129,22 +129,104 @@ appended when the minibuffer frame is created."
       ;; Gildea@x.org says it is ok to ask questions before terminating.
       (save-buffers-kill-emacs))))
 
-(defun handle-focus-in (&optional _event)
+(defun frame-focus-state (&optional frame)
+  "Return FRAME's last known focus state.
+Return nil if the frame is definitely known not be focused, t if
+the frame is known to be focused, and 'unknown if we don't know.  If
+FRAME is nil, query the selected frame."
+  (let* ((frame (or frame (selected-frame)))
+         (tty-top-frame (tty-top-frame frame)))
+    (if (not tty-top-frame)
+        (frame-parameter frame 'last-focus-update)
+      ;; All tty frames are frame-visible-p if the terminal is
+      ;; visible, so check whether the frame is the top tty frame
+      ;; before checking visibility.
+      (cond ((not (eq tty-top-frame frame)) nil)
+            ((not (frame-visible-p frame)) nil)
+            (t (let ((tty-focus-state
+                      (terminal-parameter frame 'tty-focus-state)))
+                 (cond ((eq tty-focus-state 'focused) t)
+                       ((eq tty-focus-state 'defocused) nil)
+                       (t 'unknown))))))))
+
+(defvar after-focus-change-function #'ignore
+  "Function called after frame focus may have changed.
+
+This function is called with no arguments when Emacs notices that
+the set of focused frames may have changed.  Code wanting to do
+something when frame focus changes should use `add-function' to
+add a function to this one, and in this added function, re-scan
+the set of focused frames, calling `frame-focus-state' to
+retrieve the last known focus state of each frame.  Focus events
+are delivered asynchronously, and frame input focus according to
+an external system may not correspond to the notion of the Emacs
+selected frame.  Multiple frames may appear to have input focus
+simultaneously due to focus event delivery differences, the
+presence of multiple Emacs terminals, and other factors, and code
+should be robust in the face of this situation.
+
+Depending on window system, focus events may also be delivered
+repeatedly and with different focus states before settling to the
+expected values.  Code relying on focus notifications should
+\"debounce\" any user-visible updates arising from focus changes,
+perhaps by deferring work until redisplay.
+
+This function may be called in arbitrary contexts, including from
+inside `read-event', so take the same care as you might when
+writing a process filter.")
+
+(defvar focus-in-hook nil
+  "Normal hook run when a frame gains focus.
+The frame gaining focus is selected at the time this hook is run.
+
+This hook is obsolete.  Despite its name, this hook may be run in
+situations other than when a frame obtains input focus: for
+example, we also run this hook when switching the selected frame
+internally to handle certain input events (like mouse wheel
+scrolling) even when the user's notion of input focus
+hasn't changed.
+
+Prefer using `after-focus-change-function'.")
+(make-obsolete-variable
+ 'focus-in-hook "after-focus-change-function" "27.1" 'set)
+
+(defvar focus-out-hook nil
+  "Normal hook run when all frames lost input focus.
+
+This hook is obsolete; see `focus-in-hook'.  Depending on timing,
+this hook may be delivered when a frame does in fact have focus.
+Prefer `after-focus-change-function'.")
+(make-obsolete-variable
+ 'focus-out-hook "after-focus-change-function" "27.1" 'set)
+
+(defun handle-focus-in (event)
   "Handle a focus-in event.
-Focus-in events are usually bound to this function.
-Focus-in events occur when a frame has focus, but a switch-frame event
-is not generated.
-This function runs the hook `focus-in-hook'."
+Focus-in events are bound to this function; do not change this
+binding.  Focus-in events occur when a frame receives focus from
+the window system."
+  ;; N.B. tty focus goes down a different path; see xterm.el.
   (interactive "e")
-  (run-hooks 'focus-in-hook))
-
-(defun handle-focus-out (&optional _event)
+  (unless (eq (car-safe event) 'focus-in)
+    (error "handle-focus-in should handle focus-in events"))
+  (internal-handle-focus-in event)
+  (let ((frame (nth 1 event)))
+    (setf (frame-parameter frame 'last-focus-update) t)
+  (run-hooks 'focus-in-hook)
+  (funcall after-focus-change-function)))
+
+(defun handle-focus-out (event)
   "Handle a focus-out event.
-Focus-out events are usually bound to this function.
-Focus-out events occur when no frame has focus.
-This function runs the hook `focus-out-hook'."
+Focus-out events are bound to this function; do not change this
+binding.  Focus-out events occur when a frame loses focus, but
+that's not the whole story: see `after-focus-change-function'."
+  ;; N.B. tty focus goes down a different path; see xterm.el.
   (interactive "e")
-  (run-hooks 'focus-out-hook))
+  (unless (eq (car event) 'focus-out)
+    (error "handle-focus-out should handle focus-out events"))
+  (let ((frame (nth 1 event)))
+    (setf (frame-parameter frame 'last-focus-update) nil)
+    (run-hooks 'focus-out-hook)
+    (funcall after-focus-change-function)))
 
 (defun handle-move-frame (event)
   "Handle a move-frame event.
diff --git a/lisp/term/xterm.el b/lisp/term/xterm.el
index b3b7a216352..ce4e18efff8 100644
--- a/lisp/term/xterm.el
+++ b/lisp/term/xterm.el
@@ -115,13 +115,20 @@ Return the pasted text as a string."
 ;; notifications) instead of read-event (which can't).
 
 (defun xterm-translate-focus-in (_prompt)
-  (handle-focus-in)
+  (setf (terminal-parameter nil 'tty-focus-state) 'focused)
+  (funcall after-focus-change-function)
   [])
 
 (defun xterm-translate-focus-out (_prompt)
-  (handle-focus-out)
+  (setf (terminal-parameter nil 'tty-focus-state) 'defocused)
+  (funcall after-focus-change-function)
   [])
 
+(defun xterm--suspend-tty-function (_tty)
+  ;; We can't know what happens to the tty after we're suspended
+  (setf (terminal-parameter nil 'tty-focus-state) nil)
+  (funcall after-focus-change-function))
+
 ;; Similarly, we want to transparently slurp the entirety of a
 ;; bracketed paste and encapsulate it into a single event.  We used to
 ;; just slurp up the bracketed paste content in the event handler, but