bug#69915: 30.0.50; mouse-autoselect-window has no effect in terminal

[Jared Finder via "Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>]

[-- Attachment #1: Type: text/plain, Size: 895 bytes --]

I am happy with the contents of Olaf's patch.  I would just do some 
minor reformatting at this point: converting tabs to spaces, removing 
commented out line, change comment wording slightly.

On 2024-03-30 10:03, Olaf Rogalsky wrote:
> Hi Jared and Eli,
> 
>>> I can't find the documentation of the format of the select-window
>>> event. Maybe its a good idea to add it.
>> Agreed.  I think it should be added to Focus Events in commands.texi.
> 
> But probaly by someone who knows the texi format and has a better
> command of the english language than I do. Sorry.

I took a stab at generating documentation here.  I'm not that familiar 
with texi format either, so I'd appreciate a review.

> PS: sorry for the horrible formatting of the previous messages: I
> usually do not use my gmail account ... Hope, this one comes out 
> better.

No worries, everything looked fine to me!

   -- MJF

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Adding-documentation-for-switch-window-event.patch --]
[-- Type: text/x-diff; name=0001-Adding-documentation-for-switch-window-event.patch, Size: 5358 bytes --]

From 7cd83458caa3940f8a826233c1903bc69aafdef8 Mon Sep 17 00:00:00 2001
From: Jared Finder <jared@finder.org>
Date: Sat, 30 Mar 2024 13:14:43 -0700
Subject: [PATCH] Adding documentation for <switch-window> event

* doc/lispref/commands.texi (Focus Events): Adding documentation
for the structure of <switch-window> events.  Making sure to be
clear when referring to window system windows vs Emacs windows.
* doc/lispref/windows.texi (Mouse Window Auto-selection): Adding
link to Focus Events.
---
 doc/lispref/commands.texi | 66 ++++++++++++++++++++++++++++-----------
 doc/lispref/windows.texi  |  2 +-
 2 files changed, 48 insertions(+), 20 deletions(-)

diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index 4fe4969c0db..335a41dbb44 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -2303,15 +2303,34 @@ Focus Events
 @subsection Focus Events
 @cindex focus event
 
+This section talks about both window systems and Emacs frames.  When
+talking about just ``frames'' or ``windows'', it refers to Emacs frames
+and Emacs windows.  When talking about window system windows, which are
+also Emacs frames, this section always says ``window system window''.
+
+@noindent
 Window systems provide general ways for the user to control which window
-gets keyboard input.  This choice of window is called the @dfn{focus}.
-When the user does something to switch between Emacs frames, that
-generates a @dfn{focus event}.  The normal definition of a focus event,
-in the global keymap, is to select a new frame within Emacs, as the user
-would expect.  @xref{Input Focus}, which also describes hooks related
-to focus events.
+system window, or Emacs frame, gets keyboard input.  This choice of
+window system window is called the @dfn{focus}.  When the user does
+something to switch between Emacs frames, that generates a @dfn{focus
+event}.  Emacs also generates focus events when using
+@var{mouse-autoselect-window} to switch between Emacs windows within
+Emacs frames.
+
+A focus event in the middle of a key sequence would garble the
+sequence.  So Emacs never generates a focus event in the middle of a key
+sequence.  If the user changes focus in the middle of a key
+sequence---that is, after a prefix key---then Emacs reorders the events
+so that the focus event comes either before or after the multi-event key
+sequence, and not within it.
 
-Focus events are represented in Lisp as lists that look like this:
+@heading Focus events for frames
+
+The normal definition of a focus event that switches frames, in the
+global keymap, is to select that new frame within Emacs, as the user
+would expect.  @xref{Input Focus}, which also describes hooks related to
+focus events for frames.  Focus events for frames are represented in
+Lisp as lists that look like this:
 
 @example
 (switch-frame @var{new-frame})
@@ -2321,19 +2340,28 @@ Focus Events
 where @var{new-frame} is the frame switched to.
 
 Some X window managers are set up so that just moving the mouse into a
-window is enough to set the focus there.  Usually, there is no need
-for a Lisp program to know about the focus change until some other
-kind of input arrives.  Emacs generates a focus event only when the
-user actually types a keyboard key or presses a mouse button in the
-new frame; just moving the mouse between frames does not generate a
-focus event.
+frame is enough to set the focus there.  Usually, there is no need for a
+Lisp program to know about the focus change until some other kind of
+input arrives.  Emacs generates a focus event only when the user
+actually types a keyboard key or presses a mouse button in the new
+frame; just moving the mouse between frames does not generate a focus
+event.
 
-A focus event in the middle of a key sequence would garble the
-sequence.  So Emacs never generates a focus event in the middle of a key
-sequence.  If the user changes focus in the middle of a key
-sequence---that is, after a prefix key---then Emacs reorders the events
-so that the focus event comes either before or after the multi-event key
-sequence, and not within it.
+@heading Focus events for windows
+
+When @var{mouse-autoselect-window} is set, moving the mouse over a new
+window within a frame can also switch the selected window.  @xref{Mouse
+Window Auto-selection}, which describes the behavior for different
+values.  When the mouse is moved over a new window, a focus event for
+switching windows is generated.  Focus events for windows are
+reperesented in Lisp as lists that look like this:
+
+@example
+(select-window @var{new-window})
+@end example
+
+@noindent
+where @var{new-window} is the window switched to.
 
 @node Xwidget Events
 @subsection Xwidget events
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index eef05d94fdb..54ef3851820 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -6177,7 +6177,7 @@ Mouse Window Auto-selection
 the mouse pointer.  This accomplishes a policy similar to that of
 window managers that give focus to a frame (and thus trigger its
 subsequent selection) whenever the mouse pointer enters its
-window-system window (@pxref{Input Focus}).
+window-system window (@pxref{Input Focus}, @pxref{Focus Events}).
 
 @defopt mouse-autoselect-window
 If this variable is non-@code{nil}, Emacs will try to automatically
-- 
2.39.2