From 7cd83458caa3940f8a826233c1903bc69aafdef8 Mon Sep 17 00:00:00 2001 From: Jared Finder Date: Sat, 30 Mar 2024 13:14:43 -0700 Subject: [PATCH] Adding documentation for event * doc/lispref/commands.texi (Focus Events): Adding documentation for the structure of 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