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

Please note: This is a static page, with minimal formatting, updated once a day.
Click here to see this page with the latest information and nicer formatting.

Package: emacs; Reported by: Stefan Kangas <stefan@HIDDEN>; dated Mon, 15 Nov 2021 11:01:01 UTC; Maintainer for emacs is bug-gnu-emacs@HIDDEN.

Message received at 51862 <at> debbugs.gnu.org:


Received: (at 51862) by debbugs.gnu.org; 16 Nov 2021 07:57:34 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Tue Nov 16 02:57:34 2021
Received: from localhost ([127.0.0.1]:56951 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1mmtLR-0003Ql-Up
	for submit <at> debbugs.gnu.org; Tue, 16 Nov 2021 02:57:34 -0500
Received: from quimby.gnus.org ([95.216.78.240]:51926)
 by debbugs.gnu.org with esmtp (Exim 4.84_2)
 (envelope-from <larsi@HIDDEN>) id 1mmtLP-0003QX-TF
 for 51862 <at> debbugs.gnu.org; Tue, 16 Nov 2021 02:57:32 -0500
DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnus.org;
 s=20200322; h=Content-Type:MIME-Version:Message-ID:In-Reply-To:Date:
 References:Subject:Cc:To:From:Sender:Reply-To:Content-Transfer-Encoding:
 Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender:
 Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help:List-Unsubscribe:
 List-Subscribe:List-Post:List-Owner:List-Archive;
 bh=LnN2CNJlSb5kW/Mi8QO0BvPq8LBiFNDRaR19aoqiEO0=; b=os9h66KFGWd/YsT1/QOD4yojr8
 tQ7wCDXCqDf/jHTkTIpovMkdZ6OUtc8YeWtXj1pk0mtxJ77REjDW6XnxjsFX0+yRxkLNnNI+gZzEf
 qJNvu/NG7iHi/8kfZaFNyfAYkOj3K1e2YKEosVSt+6ieOTuBngLlzP/+9Hmudv+zTN4U=;
Received: from [84.212.220.105] (helo=xo)
 by quimby.gnus.org with esmtpsa (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256)
 (Exim 4.92) (envelope-from <larsi@HIDDEN>)
 id 1mmtLG-0003lS-Jw; Tue, 16 Nov 2021 08:57:24 +0100
From: Lars Ingebrigtsen <larsi@HIDDEN>
To: Stefan Kangas <stefan@HIDDEN>
Subject: Re: bug#51862: after-focus-change-function: hard to understand
 documentation
References: <CADwFkmmODbKyKN57RxOsdkPDJo2nmzse7zZVYObkJpWP-edSUw@HIDDEN>
X-Now-Playing: Joni Mitchell's _Archives: The Early Years (3)_: "Gemini Twin"
Date: Tue, 16 Nov 2021 08:57:20 +0100
In-Reply-To: <CADwFkmmODbKyKN57RxOsdkPDJo2nmzse7zZVYObkJpWP-edSUw@HIDDEN>
 (Stefan Kangas's message of "Mon, 15 Nov 2021 03:00:35 -0800")
Message-ID: <87czn07ctb.fsf@HIDDEN>
User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (gnu/linux)
MIME-Version: 1.0
Content-Type: text/plain
X-Spam-Report: Spam detection software, running on the system "quimby.gnus.org",
 has NOT identified this incoming email as spam.  The original
 message has been attached to this so you can view it or label
 similar future email.  If you have any questions, see
 @@CONTACT_ADDRESS@@ for details.
 Content preview:  Stefan Kangas <stefan@HIDDEN> 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 "extensi [...] 
 Content analysis details:   (-2.9 points, 5.0 required)
 pts rule name              description
 ---- ---------------------- --------------------------------------------------
 -1.0 ALL_TRUSTED            Passed through trusted hosts only via SMTP
 -1.9 BAYES_00               BODY: Bayes spam probability is 0 to 1%
 [score: 0.0000]
X-Spam-Score: -2.3 (--)
X-Debbugs-Envelope-To: 51862
Cc: Daniel Colascione <dancol@HIDDEN>, 51862 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -3.3 (---)

Stefan Kangas <stefan@HIDDEN> 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




Information forwarded to bug-gnu-emacs@HIDDEN:
bug#51862; Package emacs. Full text available.

Message received at submit <at> debbugs.gnu.org:


Received: (at submit) by debbugs.gnu.org; 15 Nov 2021 11:00:48 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Mon Nov 15 06:00:48 2021
Received: from localhost ([127.0.0.1]:52759 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1mmZjE-0007tH-B2
	for submit <at> debbugs.gnu.org; Mon, 15 Nov 2021 06:00:48 -0500
Received: from lists.gnu.org ([209.51.188.17]:39702)
 by debbugs.gnu.org with esmtp (Exim 4.84_2)
 (envelope-from <stefankangas@HIDDEN>) id 1mmZjC-0007tA-Vx
 for submit <at> debbugs.gnu.org; Mon, 15 Nov 2021 06:00:47 -0500
Received: from eggs.gnu.org ([209.51.188.92]:54904)
 by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
 (Exim 4.90_1) (envelope-from <stefankangas@HIDDEN>)
 id 1mmZjC-0001xY-NP
 for bug-gnu-emacs@HIDDEN; Mon, 15 Nov 2021 06:00:46 -0500
Received: from mail-pl1-f178.google.com ([209.85.214.178]:40708)
 by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128)
 (Exim 4.90_1) (envelope-from <stefankangas@HIDDEN>)
 id 1mmZjA-000538-0t
 for bug-gnu-emacs@HIDDEN; Mon, 15 Nov 2021 06:00:46 -0500
Received: by mail-pl1-f178.google.com with SMTP id v19so3403721plo.7
 for <bug-gnu-emacs@HIDDEN>; Mon, 15 Nov 2021 03:00:37 -0800 (PST)
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
 d=1e100.net; s=20210112;
 h=x-gm-message-state:from:mime-version:date:message-id:subject:to
 :content-transfer-encoding;
 bh=YI1wybTmMvhIvbmGR9TntEYhdF8MCryOOhq+gMhkPLY=;
 b=ZkyxY5W5w1Y0R/kFwcSgqUACxoJ00JdjOUq1mF3FrwZ+c6pYXbq08dJ4LZWuj/5OS9
 CDXMDc90gPA+Z4N6SYj/2OCjZvK4l0mMdFyTH2+jJ5MuRz7oQLSQf441IQjhaNm08bfo
 OW9s3n0gSdXnTr1OPIDd+Ia+vZJlgv4EbqRO2awcXxNio/zDuLw0+wjXJQUOor2JHSVe
 SXVg+ywbyKbNbRDLkBbHjAe+9fOWjKnFHmJIX5402+E5Cral5GAkfpNRTpE+cYhoY4td
 NrA1qgg5Mzhr7cmlD5ZwpBf86HCibXsKYeLL94Y0ij6s/rZA0Y5Ql9r37uohsMVZMOrE
 A9XA==
X-Gm-Message-State: AOAM531iz6B/SLHY8Sq+qie3dmu/XGWoe/QU40fMdpFAdMN7ZpSDg8gA
 KgCm2d7MsOndD2/PVpmYEvg/Ti2cJPPLhEpMzg7y9sC4UO8=
X-Google-Smtp-Source: ABdhPJxHtN3ct0PRuc6dFocFFCmsCc8t5/kWn4SiaQUgkouZk7asRozZdK1Tid2RkfgZdajoB6+bGvXlINAemg0Dy3Q=
X-Received: by 2002:a17:902:e294:b0:143:86a8:c56d with SMTP id
 o20-20020a170902e29400b0014386a8c56dmr34248995plc.22.1636974036045; Mon, 15
 Nov 2021 03:00:36 -0800 (PST)
Received: from 753933720722 named unknown by gmailapi.google.com with
 HTTPREST; Mon, 15 Nov 2021 03:00:35 -0800
From: Stefan Kangas <stefan@HIDDEN>
X-Debbugs-CC: Daniel Colascione <dancol@HIDDEN>
MIME-Version: 1.0
Date: Mon, 15 Nov 2021 03:00:35 -0800
Message-ID: <CADwFkmmODbKyKN57RxOsdkPDJo2nmzse7zZVYObkJpWP-edSUw@HIDDEN>
Subject: after-focus-change-function: hard to understand documentation
To: bug-gnu-emacs@HIDDEN
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
Received-SPF: pass client-ip=209.85.214.178;
 envelope-from=stefankangas@HIDDEN; helo=mail-pl1-f178.google.com
X-Spam_score_int: -13
X-Spam_score: -1.4
X-Spam_bar: -
X-Spam_report: (-1.4 / 5.0 requ) BAYES_00=-1.9, FREEMAIL_FORGED_FROMDOMAIN=0.25,
 FREEMAIL_FROM=0.001, HEADER_FROM_DIFFERENT_DOMAINS=0.25,
 RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H3=0.001, RCVD_IN_MSPIKE_WL=0.001,
 SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=no autolearn_force=no
X-Spam_action: no action
X-Spam-Score: -0.8 (/)
X-Debbugs-Envelope-To: submit
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -1.8 (-)

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 =E2=80=98add-function=
=E2=80=99 to add
>     a function to this one, and in this added function, re-scan the set
>     of focused frames, calling =E2=80=98frame-focus-state=E2=80=99 to ret=
rieve 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
>     =E2=80=9Cdebounce=E2=80=9D any user-visible updates arising from focu=
s 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 =E2=80=98read-event=E2=80=99, so take the same care as you mig=
ht 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.




Acknowledgement sent to Stefan Kangas <stefan@HIDDEN>:
New bug report received and forwarded. Copy sent to dancol@HIDDEN, bug-gnu-emacs@HIDDEN. Full text available.
Report forwarded to dancol@HIDDEN, bug-gnu-emacs@HIDDEN:
bug#51862; Package emacs. Full text available.
Please note: This is a static page, with minimal formatting, updated once a day.
Click here to see this page with the latest information and nicer formatting.
Last modified: Tue, 16 Nov 2021 08:00:02 UTC

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997 nCipher Corporation Ltd, 1994-97 Ian Jackson.