From c3b6742b3fb7459af64eec4986837c4714636c51 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Fri, 22 Dec 2017 12:18:12 +0200 Subject: [PATCH] Improve documentation of selecting windows * doc/lispref/windows.texi (Basic Windows, Selecting Windows): Clarify what selecting a window means for keyboard input, and that input focus may need to be considered when selecting windows on other frames. See http://lists.gnu.org/archive/html/emacs-devel/2017-12/msg00372.html for more details. --- doc/lispref/windows.texi | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index 07c8f27bc81..d73b410f977 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -125,11 +125,13 @@ including for the case where @var{object} is a deleted window. as @dfn{selected within the frame}. For the selected frame, that window is called the @dfn{selected window}---the one in which most editing takes place, and in which the cursor for selected windows -appears (@pxref{Cursor Parameters}). The selected window's buffer is -usually also the current buffer, except when @code{set-buffer} has -been used (@pxref{Current Buffer}). As for non-selected frames, the -window selected within the frame becomes the selected window if the -frame is ever selected. @xref{Selecting Windows}. +appears (@pxref{Cursor Parameters}). Keyboard input that inserts or +deletes text is also normally directed to this window. The selected +window's buffer is usually also the current buffer, except when +@code{set-buffer} has been used (@pxref{Current Buffer}). As for +non-selected frames, the window selected within the frame becomes the +selected window if the frame is ever selected. @xref{Selecting +Windows}. @defun selected-window This function returns the selected window (which is always a live @@ -1726,7 +1728,7 @@ windows. @defun select-window window &optional norecord This function makes @var{window} the selected window and the window -selected within its frame (@pxref{Basic Windows}) and selects that +selected within its frame (@pxref{Basic Windows}), and selects that frame. It also makes @var{window}'s buffer (@pxref{Buffers and Windows}) current and sets that buffer's value of @code{point} to the value of @code{window-point} (@pxref{Window Point}) in @var{window}. @@ -1743,6 +1745,11 @@ next time. If @var{norecord} is non-@code{nil}, such updates are usually not performed. If, however, @var{norecord} equals the special symbol @code{mark-for-redisplay}, the additional actions mentioned above are omitted but @var{window} will be nevertheless updated. + +Note that sometimes selecting a window is not enough to show it, or +make its frame the top-most frame on display: you may also need to +raise the frame or make sure input focus is directed to that frame. +@xref{Input Focus}. @end defun @cindex select window hook -- 2.39.5