Function: display-buffer
display-buffer is an interactive and byte-compiled function defined in
window.el.gz.
Signature
(display-buffer BUFFER-OR-NAME &optional ACTION FRAME)
Documentation
Display BUFFER-OR-NAME in some window, without selecting it.
To change which window is used, set display-buffer-alist
to an expression containing one of these "action" functions:
display-buffer-same-window -- Use the selected window.
display-buffer-reuse-window -- Use a window already showing
the buffer.
display-buffer-in-previous-window -- Use a window that did
show the buffer before.
display-buffer-use-some-window -- Use some existing window.
display-buffer-use-least-recent-window -- Try to avoid reusing
windows that have recently been switched to.
display-buffer-pop-up-window -- Pop up a new window.
display-buffer-full-frame -- Delete other windows and use the full frame.
display-buffer-below-selected -- Use or pop up a window below
the selected one.
display-buffer-at-bottom -- Use or pop up a window at the
bottom of the selected frame.
display-buffer-pop-up-frame -- Show the buffer on a new frame.
display-buffer-in-child-frame -- Show the buffer in a
child frame.
display-buffer-no-window -- Do not display the buffer and
have display-buffer return nil immediately.
For instance:
(setq display-buffer-alist '((".*" display-buffer-at-bottom)))
Buffer display can be further customized to a very high degree; the rest of this docstring explains some of the many possibilities, and also see Info node (emacs)Window Choice for more information.
BUFFER-OR-NAME must be a buffer or a string naming a live buffer. Return the window chosen for displaying that buffer, or nil if no such window is found.
Optional argument ACTION, if non-nil, should specify a buffer display action of the form (FUNCTIONS . ALIST). FUNCTIONS is either an "action function" or a possibly empty list of action functions. ALIST is a possibly empty "action alist".
An action function is a function that accepts two arguments: the buffer to display and an action alist. Based on those arguments, it should try to display the buffer in a window and return that window. An action alist is an association list mapping symbols to values. Action functions use the action alist passed to them to fine-tune their behaviors.
display-buffer builds a list of action functions and an action
alist by combining any action functions and alists specified by
display-buffer-overriding-action, display-buffer-alist, the
ACTION argument, display-buffer-base-action, and
display-buffer-fallback-action (in order). Then it calls each
function in the combined function list in turn, passing the
buffer as the first argument and the combined action alist as the
second argument, until one of the functions returns non-nil.
See above for the action functions and the action they try to perform.
Action alist entries are:
inhibit-same-window -- A non-nil value prevents the same
window from being used for display.
inhibit-switch-frame -- A non-nil value prevents any frame
used for showing the buffer from being raised or selected.
Note that a window manager may still raise a new frame and
give it focus, effectively overriding the value specified
here.
reusable-frames -- The value specifies the set of frames to
search for a window that already displays the buffer.
Possible values are nil (the selected frame), t (any live
frame), visible (any visible frame), 0 (any visible or
iconified frame) or an existing live frame.
pop-up-frames -- Same effect as the eponymous variable.
Takes precedence over the variable.
pop-up-frame-parameters -- The value specifies an alist of
frame parameters to give a new frame, if one is created.
window-height -- The value specifies the desired height of the
window chosen and is either an integer (the total height of
the window specified in frame lines), a floating point
number (the fraction of its total height with respect to the
total height of the frame's root window), a cons cell whose
car is body-lines and whose cdr is an integer that
specifies the height of the window's body in frame lines, or
a function to be called with one argument - the chosen
window. That function is supposed to adjust the height of
the window. Suitable functions are fit-window-to-buffer
and shrink-window-if-larger-than-buffer.
window-width -- The value specifies the desired width of the
window chosen and is either an integer (the total width of
the window specified in frame lines), a floating point
number (the fraction of its total width with respect to the
width of the frame's root window), a cons cell whose car is
body-columns and whose cdr is an integer that specifies the
width of the window's body in frame columns, or a function to
be called with one argument - the chosen window. That
function is supposed to adjust the width of the window.
window-size -- This entry is only useful for windows appearing
alone on their frame and specifies the desired size of that
window either as a cons of integers (the total width and
height of the window on that frame), a cons cell whose car is
body-chars and whose cdr is a cons of integers (the desired
width and height of the window's body in columns and lines of
its frame), or a function to be called with one argument -
the chosen window. That function is supposed to adjust the
size of the frame.
preserve-size -- The value should be either (t . nil) to
preserve the width of the chosen window, (nil . t) to
preserve its height or (t . t) to preserve its height and
width in future changes of the window configuration.
window-parameters -- The value specifies an alist of window
parameters to give the chosen window.
allow-no-window -- A non-nil value means that display-buffer
may not display the buffer and return nil immediately.
some-window -- This entry defines which window
display-buffer-use-some-window should choose. The possible choices
are lru or nil (the default) to select the least recently used window,
and mru to select the most recently used window. It can also be a
function that takes two arguments: a buffer and an alist, and should
return the window in which to display the buffer. If the value is
lru, it avoids selecting windows that are not full-width and windows
on another frame. If the value is mru, it does not consider the
selected window and windows on any frame but the selected one. It's
useful to customize display-buffer-base-action to
(nil . ((some-window . mru))) when you want to display buffers in the
same non-selected window in a configuration with more than two windows.
body-function -- A function called with one argument - the
displayed window. It is called after the buffer is
displayed, and before window-height, window-width
and preserve-size are applied. The function is supposed
to fill the window body with some contents that might depend
on dimensions of the displayed window.
post-command-select-window -- A non-nil value means that after the
current command is executed and the hook post-command-hook is called,
the window displayed by this function will be selected. A nil value
means that if functions like pop-to-buffer selected another window,
at the end of this command that window will be deselected, and the
window that was selected before calling this function will remain
selected regardless of which windows were selected afterwards within
this command.
category -- If the caller of display-buffer passes an alist entry
(category . symbol) in its action argument, then you can match
the displayed buffer by using the same category in the condition
part of display-buffer-alist entries.
The entries window-height, window-width, window-size and
preserve-size are applied only when the window used for
displaying the buffer never showed another buffer before.
The ACTION argument can also have a non-nil and non-list value. This means to display the buffer in a window other than the selected one, even if it is already displayed in the selected window. If called interactively with a prefix argument, ACTION is t. Non-interactive calls should always supply a list or nil.
The optional third argument FRAME, if non-nil, acts like a
(reusable-frames . FRAME) entry appended to the action alist
specified by the ACTION argument.
Probably introduced at or before Emacs version 17.
Key Bindings
Source Code
;; Defined in /usr/src/emacs/lisp/window.el.gz
(defun display-buffer (buffer-or-name &optional action frame)
"Display BUFFER-OR-NAME in some window, without selecting it.
To change which window is used, set `display-buffer-alist'
to an expression containing one of these \"action\" functions:
`display-buffer-same-window' -- Use the selected window.
`display-buffer-reuse-window' -- Use a window already showing
the buffer.
`display-buffer-in-previous-window' -- Use a window that did
show the buffer before.
`display-buffer-use-some-window' -- Use some existing window.
`display-buffer-use-least-recent-window' -- Try to avoid reusing
windows that have recently been switched to.
`display-buffer-pop-up-window' -- Pop up a new window.
`display-buffer-full-frame' -- Delete other windows and use the full frame.
`display-buffer-below-selected' -- Use or pop up a window below
the selected one.
`display-buffer-at-bottom' -- Use or pop up a window at the
bottom of the selected frame.
`display-buffer-pop-up-frame' -- Show the buffer on a new frame.
`display-buffer-in-child-frame' -- Show the buffer in a
child frame.
`display-buffer-no-window' -- Do not display the buffer and
have `display-buffer' return nil immediately.
For instance:
(setq display-buffer-alist \\='((\".*\" display-buffer-at-bottom)))
Buffer display can be further customized to a very high degree;
the rest of this docstring explains some of the many
possibilities, and also see Info node `(emacs)Window Choice' for
more information.
BUFFER-OR-NAME must be a buffer or a string naming a live buffer.
Return the window chosen for displaying that buffer, or nil if no
such window is found.
Optional argument ACTION, if non-nil, should specify a buffer
display action of the form (FUNCTIONS . ALIST). FUNCTIONS is
either an \"action function\" or a possibly empty list of action
functions. ALIST is a possibly empty \"action alist\".
An action function is a function that accepts two arguments: the
buffer to display and an action alist. Based on those arguments,
it should try to display the buffer in a window and return that
window. An action alist is an association list mapping symbols
to values. Action functions use the action alist passed to them
to fine-tune their behaviors.
`display-buffer' builds a list of action functions and an action
alist by combining any action functions and alists specified by
`display-buffer-overriding-action', `display-buffer-alist', the
ACTION argument, `display-buffer-base-action', and
`display-buffer-fallback-action' (in order). Then it calls each
function in the combined function list in turn, passing the
buffer as the first argument and the combined action alist as the
second argument, until one of the functions returns non-nil.
See above for the action functions and the action they try to
perform.
Action alist entries are:
`inhibit-same-window' -- A non-nil value prevents the same
window from being used for display.
`inhibit-switch-frame' -- A non-nil value prevents any frame
used for showing the buffer from being raised or selected.
Note that a window manager may still raise a new frame and
give it focus, effectively overriding the value specified
here.
`reusable-frames' -- The value specifies the set of frames to
search for a window that already displays the buffer.
Possible values are nil (the selected frame), t (any live
frame), visible (any visible frame), 0 (any visible or
iconified frame) or an existing live frame.
`pop-up-frames' -- Same effect as the eponymous variable.
Takes precedence over the variable.
`pop-up-frame-parameters' -- The value specifies an alist of
frame parameters to give a new frame, if one is created.
`window-height' -- The value specifies the desired height of the
window chosen and is either an integer (the total height of
the window specified in frame lines), a floating point
number (the fraction of its total height with respect to the
total height of the frame's root window), a cons cell whose
car is `body-lines' and whose cdr is an integer that
specifies the height of the window's body in frame lines, or
a function to be called with one argument - the chosen
window. That function is supposed to adjust the height of
the window. Suitable functions are `fit-window-to-buffer'
and `shrink-window-if-larger-than-buffer'.
`window-width' -- The value specifies the desired width of the
window chosen and is either an integer (the total width of
the window specified in frame lines), a floating point
number (the fraction of its total width with respect to the
width of the frame's root window), a cons cell whose car is
`body-columns' and whose cdr is an integer that specifies the
width of the window's body in frame columns, or a function to
be called with one argument - the chosen window. That
function is supposed to adjust the width of the window.
`window-size' -- This entry is only useful for windows appearing
alone on their frame and specifies the desired size of that
window either as a cons of integers (the total width and
height of the window on that frame), a cons cell whose car is
`body-chars' and whose cdr is a cons of integers (the desired
width and height of the window's body in columns and lines of
its frame), or a function to be called with one argument -
the chosen window. That function is supposed to adjust the
size of the frame.
`preserve-size' -- The value should be either (t . nil) to
preserve the width of the chosen window, (nil . t) to
preserve its height or (t . t) to preserve its height and
width in future changes of the window configuration.
`window-parameters' -- The value specifies an alist of window
parameters to give the chosen window.
`allow-no-window' -- A non-nil value means that `display-buffer'
may not display the buffer and return nil immediately.
`some-window' -- This entry defines which window
`display-buffer-use-some-window' should choose. The possible choices
are `lru' or nil (the default) to select the least recently used window,
and `mru' to select the most recently used window. It can also be a
function that takes two arguments: a buffer and an alist, and should
return the window in which to display the buffer. If the value is
`lru', it avoids selecting windows that are not full-width and windows
on another frame. If the value is `mru', it does not consider the
selected window and windows on any frame but the selected one. It's
useful to customize `display-buffer-base-action' to
`(nil . ((some-window . mru)))' when you want to display buffers in the
same non-selected window in a configuration with more than two windows.
`body-function' -- A function called with one argument - the
displayed window. It is called after the buffer is
displayed, and before `window-height', `window-width'
and `preserve-size' are applied. The function is supposed
to fill the window body with some contents that might depend
on dimensions of the displayed window.
`post-command-select-window' -- A non-nil value means that after the
current command is executed and the hook `post-command-hook' is called,
the window displayed by this function will be selected. A nil value
means that if functions like `pop-to-buffer' selected another window,
at the end of this command that window will be deselected, and the
window that was selected before calling this function will remain
selected regardless of which windows were selected afterwards within
this command.
`category' -- If the caller of `display-buffer' passes an alist entry
`(category . symbol)' in its action argument, then you can match
the displayed buffer by using the same category in the condition
part of `display-buffer-alist' entries.
The entries `window-height', `window-width', `window-size' and
`preserve-size' are applied only when the window used for
displaying the buffer never showed another buffer before.
The ACTION argument can also have a non-nil and non-list value.
This means to display the buffer in a window other than the
selected one, even if it is already displayed in the selected
window. If called interactively with a prefix argument, ACTION
is t. Non-interactive calls should always supply a list or nil.
The optional third argument FRAME, if non-nil, acts like a
\(reusable-frames . FRAME) entry appended to the action alist
specified by the ACTION argument."
(interactive (list (read-buffer "Display buffer: " (other-buffer))
(if current-prefix-arg t)))
(let ((buffer (if (bufferp buffer-or-name)
buffer-or-name
(get-buffer buffer-or-name)))
(buf-name (if (bufferp buffer-or-name)
(buffer-name buffer-or-name)
buffer-or-name))
;; Make sure that when we split windows the old window keeps
;; point, bug#14829.
(split-window-keep-point t)
;; Handle the old form of the first argument.
(inhibit-same-window (and action (not (listp action)))))
(unless (listp action) (setq action nil))
(let* ((user-action
(display-buffer-assq-regexp
buf-name display-buffer-alist action))
(special-action (display-buffer--special-action buffer))
;; Extra actions from the arguments to this function:
(extra-action
(cons nil (append (if inhibit-same-window
'((inhibit-same-window . t)))
(if frame
`((reusable-frames . ,frame))))))
;; Construct action function list and action alist.
(actions (list display-buffer-overriding-action
user-action special-action action extra-action
display-buffer-base-action
display-buffer-fallback-action))
(functions (apply #'append
(mapcar (lambda (x)
(setq x (car x))
(if (functionp x) (list x) x))
actions)))
(alist (apply #'append (mapcar #'cdr actions)))
window)
(unless (buffer-live-p buffer)
(error "Invalid buffer"))
(while (and functions (not window))
(setq window (funcall (car functions) buffer alist)
functions (cdr functions)))
(when-let ((select (assq 'post-command-select-window alist)))
(letrec ((old-selected-window (selected-window))
(postfun
(lambda ()
(if (cdr select)
(when (window-live-p window)
(select-window window))
(when (window-live-p old-selected-window)
(select-window old-selected-window)))
(remove-hook 'post-command-hook postfun))))
(add-hook 'post-command-hook postfun)))
(and (windowp window) window))))