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

Improve docs of functions/variables related to 'display-buffer'

Browse source 
* lisp/window.el (display-buffer, pop-to-buffer-same-window)
(display-buffer-same-window, display-buffer-in-side-window)
(same-window-p, display-buffer-overriding-action)
(display-buffer-base-action)
(display-buffer--same-window-action)
(display-buffer--other-frame-action)
(with-current-buffer-window, with-displayed-buffer-window)
(display-buffer-alist, display-buffer-assq-regexp)
(display-buffer-other-frame): Clarify and improve the doc
strings.  (Bug#32798)
This commit is contained in:
Eli Zaretskii 2018-09-24 18:07:02 +03:00
parent a3639317bc
commit 17766a14cc
1 changed files with 53 additions and 28 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

81
lisp/window.el
View file

@ -201,7 +201,7 @@ argument replaces this)."
(defmacro with-current-buffer-window (buffer-or-name action quit-function &rest body)
"Evaluate BODY with a buffer BUFFER-OR-NAME current and show that buffer.
This construct is like `with-temp-buffer-window' but unlike that
This construct is like `with-temp-buffer-window' but unlike that,
makes the buffer specified by BUFFER-OR-NAME current for running
BODY."
(declare (debug t))
@ -224,7 +224,7 @@ BODY."
(defmacro with-displayed-buffer-window (buffer-or-name action quit-function &rest body)
"Show a buffer BUFFER-OR-NAME and evaluate BODY in that buffer.
This construct is like `with-current-buffer-window' but unlike that
This construct is like `with-current-buffer-window' but unlike that,
displays the buffer specified by BUFFER-OR-NAME before running BODY."
(declare (debug t))
(let ((buffer (make-symbol "buffer"))
@ -992,16 +992,16 @@ and may be called only if no window on SIDE exists yet."
ALIST is an association list of symbols and values. The
following special symbols can be used in ALIST.
`side' denotes the side of the frame where the new window shall
be located. Valid values are `bottom', `right', `top' and
`left'. The default is `bottom'.
`side' denotes the side of the frame where the new window shall
be located. Valid values are `bottom', `right', `top' and
`left'. The default is `bottom'.
`slot' if non-nil, specifies the window slot where to display
BUFFER. A value of zero or nil means use the middle slot on
the specified side. A negative value means use a slot
preceding (that is, above or on the left of) the middle slot.
A positive value means use a slot following (that is, below or
on the right of) the middle slot. The default is zero.
`slot' if non-nil, specifies the window slot where to display
BUFFER. A value of zero or nil means use the middle slot on
the specified side. A negative value means use a slot
preceding (that is, above or on the left of) the middle slot.
A positive value means use a slot following (that is, below or
on the right of) the middle slot. The default is zero.
If the current frame size or the settings of `window-sides-slots'
do not permit making a new window, a suitable existing window may
@ -6382,7 +6382,7 @@ See also `same-window-buffer-names'."
:group 'windows)
(defun same-window-p (buffer-name)
"Return non-nil if a buffer named BUFFER-NAME would be shown in the \"same\" window.
"Return non-nil if buffer BUFFER-NAME would be shown in the \"same\" window.
This function returns non-nil if `display-buffer' or
`pop-to-buffer' would show a buffer named BUFFER-NAME in the
selected rather than (as usual) some other window. See
@ -6820,16 +6820,22 @@ The actual non-nil value of this variable will be copied to the
"Custom type for `display-buffer' actions.")
(defvar display-buffer-overriding-action '(nil . nil)
"Overriding action to perform to display a buffer.
It should be a cons cell (FUNCTION . ALIST), where FUNCTION is a
function or a list of functions. Each function should accept two
arguments: a buffer to display and an alist similar to ALIST.
"User-defined overriding action to perform to display a buffer.
This action overrides all the other actions in the action variables
and arguments passed to `display-buffer'.
Value should be a cons cell (FUNCTION . ALIST), where FUNCTION is
a function or a list of functions. Each function should accept
two arguments: a buffer to display and an alist similar to ALIST.
The default value is empty.
See `display-buffer' for details.")
(put 'display-buffer-overriding-action 'risky-local-variable t)
(defcustom display-buffer-alist nil
"Alist of conditional actions for `display-buffer'.
This is a list of elements (CONDITION . ACTION), where:
"Alist of uder-defined conditional actions for `display-buffer'.
Its value takes effect before `display-buffer-base-action'
and `display-buffer-fallback-action', but after
`display-buffer-overriding-action', which see.
If non-nil, this is a list of elements (CONDITION . ACTION), where:
CONDITION is either a regexp matching buffer names, or a
function that takes two arguments - a buffer name and the
@ -6855,9 +6861,13 @@ associated action to the list of actions it will try."
(defcustom display-buffer-base-action '(nil . nil)
"User-specified default action for `display-buffer'.
This is the default action used by `display-buffer' if no other
actions are specified or all fail, before falling back on
`display-buffer-fallback-action'.
It should be a cons cell (FUNCTION . ALIST), where FUNCTION is a
function or a list of functions. Each function should accept two
arguments: a buffer to display and an alist similar to ALIST.
The default value is empty.
See `display-buffer' for details."
:type display-buffer--action-custom-type
:risky t
@ -6875,12 +6885,16 @@ See `display-buffer' for details."
"Default fallback action for `display-buffer'.
This is the action used by `display-buffer' if no other actions
specified, e.g. by the user options `display-buffer-alist' or
`display-buffer-base-action'. See `display-buffer'.")
`display-buffer-base-action', or they all fail. See `display-buffer'.")
(put 'display-buffer-fallback-action 'risky-local-variable t)
(defun display-buffer-assq-regexp (buffer-name alist action)
"Retrieve ALIST entry corresponding to BUFFER-NAME.
ACTION is the action argument passed to `display-buffer'."
This returns the cdr of the ALIST entry if either its key is a
string that matches BUFFER-NAME, as reported by `string-match-p';
or if the key is a function that returns a non-nil when called
with 3 arguments: the ALIST key, BUFFER-NAME, and ACTION.
ACTION should have the form of the action argument passed to `display-buffer'."
(catch 'match
(dolist (entry alist)
(let ((key (car entry)))
@ -6893,7 +6907,8 @@ ACTION is the action argument passed to `display-buffer'."
(defvar display-buffer--same-window-action
'(display-buffer-same-window
(inhibit-same-window . nil))
"A `display-buffer' action for displaying in the same window.")
"A `display-buffer' action for displaying in the same window.
Specifies to call `display-buffer-same-window'.")
(put 'display-buffer--same-window-action 'risky-local-variable t)
(defvar display-buffer--other-frame-action
@ -6901,7 +6916,9 @@ ACTION is the action argument passed to `display-buffer'."
display-buffer-pop-up-frame)
(reusable-frames . 0)
(inhibit-same-window . t))
"A `display-buffer' action for displaying in another frame.")
"A `display-buffer' action for displaying in another frame.
Specifies to call `display-buffer-reuse-window', and if that
fails, call `display-buffer-pop-up-frame'.")
(put 'display-buffer--other-frame-action 'risky-local-variable t)
(defun display-buffer (buffer-or-name &optional action frame)
@ -6922,7 +6939,7 @@ If ACTION is non-nil, it should have the form (FUNCTION . ALIST),
where FUNCTION is either a function or a list of functions, and
ALIST is an arbitrary association list (alist).
Each such FUNCTION should accept two arguments: the buffer to
Each such function should accept two arguments: the buffer to
display and an alist. Based on those arguments, it should
display the buffer and return the window. If the caller is
prepared to handle the case of not displaying the buffer
@ -7046,6 +7063,9 @@ argument, ACTION is t."
(defun display-buffer-other-frame (buffer)
"Display buffer BUFFER preferably in another frame.
This function attempts to look for a window displaying BUFFER,
on all the frames on the current terminal, skipping the selected
window; if that fails, it pops up a new frame.
This uses the function `display-buffer' as a subroutine; see
its documentation for additional customization information."
(interactive "BDisplay buffer in other frame: ")
@ -7089,10 +7109,10 @@ that allows the selected frame)."
(defun display-buffer-same-window (buffer alist)
"Display BUFFER in the selected window.
This fails if ALIST has a non-nil `inhibit-same-window' entry, or
if the selected window is a minibuffer window or is dedicated to
another buffer; in that case, return nil. Otherwise, return the
selected window."
This fails if ALIST has an `inhibit-same-window' element whose
value is non-nil, or if the selected window is a minibuffer
window or is dedicated to another buffer; in that case, return nil.
Otherwise, return the selected window."
(unless (or (cdr (assq 'inhibit-same-window alist))
(window-minibuffer-p)
(window-dedicated-p))
@ -7557,7 +7577,12 @@ Optional argument NORECORD, if non-nil means do not put this
buffer at the front of the list of recently selected ones.
Unlike `pop-to-buffer', this function prefers using the selected
window over popping up a new window or frame."
window over popping up a new window or frame. Specifically, if
the selected window is neither a minibuffer window (as reported
by `window-minibuffer-p'), nor is dedicated to another buffer
(see `window-dedicated-p'), BUFFER will be displayed in the
currently selected window; otherwise it will be displayed in
another window."
(pop-to-buffer buffer display-buffer--same-window-action norecord))
(defun read-buffer-to-switch (prompt)