procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Fix description of 'display-buffer-in-previous-window' again (Bug#36161)

Browse source 
* lisp/window.el (display-buffer-in-previous-window): Make
doc-string more explicit (Bug#36161).
* doc/lispref/windows.texi (Buffer Display Action Functions):
Make description of 'display-buffer-in-previous-window' more
explicit.
(Buffer Display Action Alists): Mention
'display-buffer-in-previous-window' in description of
'reusable-frames' entry.
This commit is contained in:
Martin Rudalics 2019-06-12 11:02:02 +02:00
parent 7be50cda56
commit eca2677b1d
2 changed files with 51 additions and 19 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

48
doc/lispref/windows.texi
View file

@ -2581,25 +2581,47 @@ operations (@pxref{Preserving Window Sizes}).
This function fails if no window can be split. More often than not,
this happens because no window is large enough to allow splitting.
Setting @code{split-height-threshold} or @code{split-width-threshold}
to lower values may help in this regard. Spliting also fails when the
selected frame has an @code{unsplittable} frame parameter;
to lower values may help in this regard. Splitting also fails when
the selected frame has an @code{unsplittable} frame parameter;
@pxref{Buffer Parameters}.
@end defun
@defun display-buffer-in-previous-window buffer alist
This function tries to display @var{buffer} in a window where it was
previously displayed. If @var{alist} has a non-@code{nil}
@code{inhibit-same-window} entry, the selected window is not eligible
for reuse. If @var{alist} contains a @code{reusable-frames} entry,
its value determines which frames to search for a suitable window.
displayed previously.
If @var{alist} has a @code{previous-window} entry and the window
specified by that entry is live and not dedicated to another buffer,
that window will be preferred, even if it never showed @var{buffer}
If @var{alist} contains a non-@code{nil} @code{inhibit-same-window}
entry, the selected window is not eligible for use. A dedicated
window is usable only if it already shows @var{buffer}. If
@var{alist} contains a @code{previous-window} entry, the window
specified by that entry is usable even if it never showed @var{buffer}
before.
This function will not choose the selected window if it finds another
eligible window that has shown @var{buffer} previously.
If @var{alist} contains a @code{reusable-frames} entry (@pxref{Buffer
Display Action Alists}), its value determines which frames to search
for a suitable window. If @var{alist} contains no
@code{reusable-frames} entry, this function searches just the selected
frame if @code{display-buffer-reuse-frames} and @code{pop-up-frames}
are both @code{nil}; it searches all frames on the current terminal if
either of those variables is non-@code{nil}.
If more than one window qualifies as usable according to these rules,
this function makes a choice in the following order of preference:
@itemize @bullet
@item
The window specified by any @code{previous-window} @var{alist} entry,
provided it is not the selected window.
@item
A window that showed @var{buffer} before, provided it is not the
selected window.
@item
The selected window if it is either specified by a
@code{previous-window} @var{alist} entry or showed @var{buffer}
before.
@end itemize
@end defun
@defun display-buffer-use-some-window buffer alist
@ -2786,7 +2808,9 @@ Ordering}).
A major client of this is @code{display-buffer-reuse-window}, but all
other action functions that try to reuse a window are affected as
well.
well. @code{display-buffer-in-previous-window} consults it when
searching for a window that previosuly displayed the buffer on another
frame.
@vindex inhibit-switch-frame@r{, a buffer display action alist entry}
@item inhibit-switch-frame

22
lisp/window.el
View file

@ -7457,10 +7457,13 @@ selected frame."
(defun display-buffer-in-previous-window (buffer alist)
"Display BUFFER in a window previously showing it.
If ALIST has a non-nil `inhibit-same-window' entry, the selected
window is not eligible for reuse.
window is not usable. A dedicated window is usable only if it
already shows BUFFER. If ALIST contains a `previous-window'
entry, the window specified by that entry is usable even if it
never showed BUFFER before.
If ALIST contains a `reusable-frames' entry, its value determines
which frames to search for a reusable window:
which frames to search for a usable window:
nil -- the selected frame (actually the last non-minibuffer frame)
A frame -- just that frame
`visible' -- all visible frames
@ -7472,12 +7475,17 @@ selected frame if `display-buffer-reuse-frames' and
`pop-up-frames' are both nil; search all frames on the current
terminal if either of those variables is non-nil.
If ALIST has a `previous-window' entry, the window specified by
that entry may override any other window found by the methods
above, even if that window never showed BUFFER before.
If more than one window is usable according to these rules,
apply the following order of preference:
Avoid using the selected window if another eligible window has
shown BUFFER before."
- Use the window specified by any 'previous-window' ALIST entry,
provided it is not the selected window.
- Use a window that showed BUFFER before, provided it is not the
selected window.
- Use the selected window if it is either specified by a
'previous-window' ALIST entry or showed BUFFER before."
(let* ((alist-entry (assq 'reusable-frames alist))
(inhibit-same-window
(cdr (assq 'inhibit-same-window alist)))