New focus management interface

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.