---

29.13.6 The Zen of Buffer Display

In its most simplistic form, a frame accommodates always one single window that can be used for displaying a buffer. As a consequence, it is always the latest call of display-buffer that will have succeeded in placing its buffer there.

Since working with such a frame is not very practical, Emacs by default allows for more complex frame layouts controlled by the default values of the frame size and the split-height-threshold and split-width-threshold options. Displaying a buffer not yet shown on a frame then either splits the single window on that frame or (re-)uses one of its two windows.

The default behavior is abandoned as soon as the user customizes one of these thresholds or manually changes the frame’s layout. The default behavior is also abandoned when calling display-buffer with a non-nil action argument or the user customizes one of the options mentioned in the previous subsections. Mastering display-buffer soon may become a frustrating experience due to the plethora of applicable display actions and the resulting frame layouts.

However, refraining from using buffer display functions and falling back on a split & delete windows metaphor is not a good idea either. Buffer display functions give Lisp programs and users a framework to reconcile their different needs; no comparable framework exists for splitting and deleting windows. Buffer display functions also allow to at least partially restore the layout of a frame when removing a buffer from it later (see Quitting Windows).

Below we will give a number of guidelines to redeem the frustration mentioned above and thus to avoid literally losing buffers in-between the windows of a frame.

Write display actions without stress

Writing display actions can be a pain because one has to lump together action functions and action alists in one huge list. (Historical reasons prevented us from having display-buffer support separate arguments for these.) It might help to memorize some basic forms like the ones listed below:

'(nil (inhibit-same-window . t))

specifies an action alist entry only and no action function. Its sole purpose is to inhibit a display-buffer-same-window function specified elsewhere from showing the buffer in the same window, see also the last example of the preceding subsection.

'(display-buffer-below-selected)

on the other hand, specifies one action function and an empty action alist. To combine the effects of the above two specifications one would write the form

'(display-buffer-below-selected (inhibit-same-window . t))

to add another action function one would write

'((display-buffer-below-selected display-buffer-at-bottom)
  (inhibit-same-window . t))

and to add another alist entry one would write

'((display-buffer-below-selected display-buffer-at-bottom)
  (inhibit-same-window . t)
  (window-height . fit-window-to-buffer))

That last form can be used as action argument of display-buffer in the following way:

(display-buffer
 (get-buffer-create "*foo*")
 '((display-buffer-below-selected display-buffer-at-bottom)
   (inhibit-same-window . t)
   (window-height . fit-window-to-buffer)))

In a customization of display-buffer-alist it would be used as follows:

(setopt
 display-buffer-alist
 '(("\\*foo\\*"
    (display-buffer-below-selected display-buffer-at-bottom)
    (inhibit-same-window . t)
    (window-height . fit-window-to-buffer))))

To add a customization for a second buffer one would then write:

(setopt
 display-buffer-alist
 '(("\\*foo\\*"
    (display-buffer-below-selected display-buffer-at-bottom)
    (inhibit-same-window . t)
    (window-height . fit-window-to-buffer))
   ("\\*bar\\*"
    (display-buffer-reuse-window display-buffer-pop-up-frame)
    (reusable-frames . visible))))

Treat each other with respect

display-buffer-alist and display-buffer-base-action are user options—Lisp programs must never set or rebind them. display-buffer-overriding-action, on the other hand, is reserved for applications—who seldom use that option and if they use it, then with utmost care.

Older implementations of display-buffer frequently caused users and applications to fight over the settings of user options like pop-up-frames and pop-up-windows (see Additional Options for Displaying Buffers). This was one major reason for redesigning display-buffer—to provide a clear framework specifying what users and applications should be allowed to do.

Lisp programs must be prepared that user customizations may cause buffers to get displayed in an unexpected way. They should never assume in their subsequent behavior, that the buffer has been shown precisely the way they asked for in the action argument of display-buffer.

Users should not pose too many and too severe restrictions on how arbitrary buffers get displayed. Otherwise, they will risk to lose the characteristics of showing a buffer for a certain purpose. Suppose a Lisp program has been written to compare different versions of a buffer in two windows side-by-side. If the customization of display-buffer-alist prescribes that any such buffer should be always shown in or below the selected window, the program will have a hard time to set up the desired window configuration via display-buffer.

To specify a preference for showing an arbitrary buffer, users should customize display-buffer-base-action. An example of how users who prefer working with multiple frames would do that was given in the previous subsection. display-buffer-alist should be reserved for displaying specific buffers in a specific way.

Consider reusing a window that already shows the buffer

Generally, it’s always a good idea for users and Lisp programmers to be prepared for the case that a window already shows the buffer in question and to reuse that window. In the preceding subsection we have shown that failing to do so properly may cause display-buffer to continuously pop up a new frame although a frame showing that buffer existed already. In a few cases only, it might be undesirable to reuse a window, for example, when a different portion of the buffer should be shown in that window.

Hence, display-buffer-reuse-window is one action function that should be used as often as possible, both in action arguments and customizations. An inhibit-same-window entry in the action argument usually takes care of the most common case where reusing a window showing the buffer should be avoided—that where the window in question is the selected one.

Attract focus to the window chosen

This is a no-brainer for people working with multiple frames—the frame showing the buffer will automatically raise and get focus unless an inhibit-switch-frame entry forbids it. For single frame users this task can be considerably more difficult. In particular, display-buffer-pop-up-window and display-buffer-use-some-window can become obtrusive in this regard. They split or use a seemingly arbitrary (often the largest or least recently used) window, distracting the user’s attention.

Some Lisp programs therefore try to choose a window at the bottom of the frame, for example, in order to display the buffer in vicinity of the minibuffer window where the user is expected to answer a question related to the new window. For non-input related actions display-buffer-below-selected might be preferable because the selected window usually already has the user’s attention.

Take care which window is selected

Many applications call display-buffer from within window excursions produced by with-selected-window or select-window calls with a non-nil norecord argument. This is almost always a bad idea because the window selected within such an excursion is usually not the window selected in the configuration presented to the user.

If, for example, a user had added an inhibit-same-window alist entry, that entry would have avoided the window selected within the scope of the excursion and not the window selected in the resulting configuration. Even if no such entry has been added, the resulting behavior might be strange. While in a frame containing one live window, evaluating the following form

(progn
  (split-window)
  (display-buffer "*Messages*"))

will display a window showing the *Messages* buffer at the bottom and leave the other window selected. Evaluating the next form

(with-selected-window (split-window)
  (display-buffer "*Messages*"))

will display *Messages* in a window on the top and select it which is usually not what display-buffer is supposed to do.

On the other hand, while evaluating the following form

(progn
  (split-window)
  (pop-to-buffer "*Messages*"))

will correctly select the *Messages* buffer, the next form

(progn
  (split-window)
  (with-selected-window (selected-window)
    (pop-to-buffer "*Messages*")))

will not.

Also, invocations of action functions like display-buffer-use-some-window and display-buffer-use-least-recent-window that expect the selected window to have the highest use time among all windows, may fail to produce a window according to their specifications.

Hence, an application that relies on using a window excursion should try to postpone the display-buffer call until after the excursion has terminated.