bug#51862: after-focus-change-function: hard to understand documentation

bug#51862: after-focus-change-function: hard to understand documentation

[Stefan Kangas]

I have the following in my init file:

    (add-hook 'focus-out-hook #'foo-bar)

But `focus-out-hook' is obsolete in 27.1 and replaced with
`after-focus-change-function' (see commit 2f6c682061).  However, I find
it substantially harder to understand how to use the latter.

Please find below some comments based on my reading of the documentation
in (info "(elisp) Input Focus").

> -- Variable: after-focus-change-function This function is an extension
> point that code can use to receive a notification that focus has
> changed.

Why does this use the terminology "extension point"?  We don't use that
anywhere else in the ELisp manual.

Can't it be used for other things than "receiving a notification that
focus has 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.

This for me comes off as pretty scary.  It sounds to me like I would
need to invest couple of hours at least into understanding all this,
when all I really want to do call a very simple function whenever focus
leaves a frame.

Could we have a simpler interface for this?  If not, could we perhaps
include some examples that would explain in a straightforward way what
one would need to do?

>     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.

How do I "defer work until redisplay"?  Could we have an example?

>     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.

Could we have some examples of what care I would need to take, or a
pointer to where that is explained?

Thanks.

bug#51862: after-focus-change-function: hard to understand documentation

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

>> -- Variable: after-focus-change-function This function is an extension
>> point that code can use to receive a notification that focus has
>> changed.
>
> Why does this use the terminology "extension point"?  We don't use that
> anywhere else in the ELisp manual.

That's an odd way of putting it, yes.

> Could we have a simpler interface for this?  If not, could we perhaps
> include some examples that would explain in a straightforward way what
> one would need to do?

I think it would make sense to add a different mechanism here.  People
who need this want two things: The affected frame and the new status
(i.e., focus-in and focus-out).  So the function should be called with
these two arguments.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#51862: after-focus-change-function: hard to understand documentation

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Date: Tue, 16 Nov 2021 08:57:20 +0100
> Cc: 51862@debbugs.gnu.org
> 
> Stefan Kangas <stefan@marxist.se> writes:
> 
> >> -- Variable: after-focus-change-function This function is an extension
> >> point that code can use to receive a notification that focus has
> >> changed.
> >
> > Why does this use the terminology "extension point"?  We don't use that
> > anywhere else in the ELisp manual.
> 
> That's an odd way of putting it, yes.
> 
> > Could we have a simpler interface for this?  If not, could we perhaps
> > include some examples that would explain in a straightforward way what
> > one would need to do?
> 
> I think it would make sense to add a different mechanism here.  People
> who need this want two things: The affected frame and the new status
> (i.e., focus-in and focus-out).  So the function should be called with
> these two arguments.

Daniel, any comments?

Thanks.

bug#51862: after-focus-change-function: hard to understand documentation

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

> This for me comes off as pretty scary.  It sounds to me like I would
> need to invest couple of hours at least into understanding all this,
> when all I really want to do call a very simple function whenever focus
> leaves a frame.

I think the reason is to be found in the doc string of the obsoleted
variables.  That is:

---
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.
---

So it's not reliable (any more?), and that's why the new variable is the
way it is.  Probably (but it'd be helpful if Daniel could chime in).

But looking at the code, I don't understand these caveats at all.  In
addition to the calls from xterm.el, the only place
after-focus-change-function is called is from
handle-focus-in/handle-focus-out -- which also call the old, obsolete
hooks.

So it doesn't seem to be more reliable, but just more incomprehensible.

In addition, handle-focus-in/out know which frame they got the event
for, but that's discarded.

I guess the idea here might be that since you can get more than one
focus-in event per real event, you should write your code to ensure that
you don't trigger it more than once per frame?  I.e., since this is all
apparently probabilistic, we leave the hard stuff to the user.

So I've tried to make the documentation here clearer and less scary, and
I've added a really un-scary example.