path: root/devdocs/elisp/choosing-window.html

 <h4 class="subsection">Choosing a Window for Displaying a Buffer</h4> <p>The command <code>display-buffer</code> flexibly chooses a window for display, and displays a specified buffer in that window. It can be called interactively, via the key binding <kbd>C-x 4 C-o</kbd>. It is also used as a subroutine by many functions and commands, including <code>switch-to-buffer</code> and <code>pop-to-buffer</code> (see <a href="switching-buffers">Switching Buffers</a>). </p>   <p>This command performs several complex steps to find a window to display in. These steps are described by means of <em>display actions</em>, which have the form <code>(<var>functions</var> . <var>alist</var>)</code>. Here, <var>functions</var> is either a single function or a list of functions, referred to as “action functions” (see <a href="buffer-display-action-functions">Buffer Display Action Functions</a>); and <var>alist</var> is an association list, referred to as “action alist” (see <a href="buffer-display-action-alists">Buffer Display Action Alists</a>). See <a href="the-zen-of-buffer-display">The Zen of Buffer Display</a>, for samples of display actions. </p> <p>An action function accepts two arguments: the buffer to display and an action alist. It attempts to display the buffer in some window, picking or creating a window according to its own criteria. If successful, it returns the window; otherwise, it returns <code>nil</code>. </p> <p><code>display-buffer</code> works by combining display actions from several sources, and calling the action functions in turn, until one of them manages to display the buffer and returns a non-<code>nil</code> value. </p> <dl> <dt id="display-buffer">Command: <strong>display-buffer</strong> <em>buffer-or-name &amp;optional action frame</em>
</dt> <dd>
<p>This command makes <var>buffer-or-name</var> appear in some window, without selecting the window or making the buffer current. The argument <var>buffer-or-name</var> must be a buffer or the name of an existing buffer. The return value is the window chosen to display the buffer, or <code>nil</code> if no suitable window was found. </p> <p>The optional argument <var>action</var>, if non-<code>nil</code>, should normally be a display action (described above). <code>display-buffer</code> builds a list of action functions and an action alist, by consolidating display actions from the following sources (in order of their precedence, from highest to lowest): </p> <ul> <li> The variable <code>display-buffer-overriding-action</code>. </li>
<li> The user option <code>display-buffer-alist</code>. </li>
<li> The <var>action</var> argument. </li>
<li> The user option <code>display-buffer-base-action</code>. </li>
<li> The constant <code>display-buffer-fallback-action</code>. </li>
</ul> <p>In practice this means that <code>display-buffer</code> builds a list of all action functions specified by these display actions. The first element of this list is the first action function specified by <code>display-buffer-overriding-action</code>, if any. Its last element is <code>display-buffer-pop-up-frame</code>—the last action function specified by <code>display-buffer-fallback-action</code>. Duplicates are not removed from this list—hence one and the same action function may be called multiple times during one call of <code>display-buffer</code>. </p> <p><code>display-buffer</code> calls the action functions specified by this 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-<code>nil</code>. See <a href="precedence-of-action-functions">Precedence of Action Functions</a>, for examples how display actions specified by different sources are processed by <code>display-buffer</code>. </p> <p>Note that the second argument is always the list of <em>all</em> action alist entries specified by the sources named above. Hence, the first element of that list is the first action alist entry specified by <code>display-buffer-overriding-action</code>, if any. Its last element is the last alist entry of <code>display-buffer-base-action</code>, if any (the action alist of <code>display-buffer-fallback-action</code> is empty). </p> <p>Note also, that the combined action alist may contain duplicate entries and entries for the same key with different values. As a rule, action functions always use the first association of a key they find. Hence, the association an action function uses is not necessarily the association provided by the display action that specified that action function, </p> <p>The argument <var>action</var> can also have a non-<code>nil</code>, non-list value. This has the special meaning that the buffer should be displayed in a window other than the selected one, even if the selected window is already displaying it. If called interactively with a prefix argument, <var>action</var> is <code>t</code>. Lisp programs should always supply a list value. </p> <p>The optional argument <var>frame</var>, if non-<code>nil</code>, specifies which frames to check when deciding whether the buffer is already displayed. It is equivalent to adding an element <code><span class="nolinebreak">(reusable-frames</span> . <var>frame</var>)</code> to the action alist of <var>action</var> (see <a href="buffer-display-action-alists">Buffer Display Action Alists</a>). The <var>frame</var> argument is provided for compatibility reasons, Lisp programs should not use it. </p>
</dd>
</dl> <dl> <dt id="display-buffer-overriding-action">Variable: <strong>display-buffer-overriding-action</strong>
</dt> <dd><p>The value of this variable should be a display action, which is treated with the highest priority by <code>display-buffer</code>. The default value is an empty display action, i.e., <code>(nil . nil)</code>. </p></dd>
</dl> <dl> <dt id="display-buffer-alist">User Option: <strong>display-buffer-alist</strong>
</dt> <dd><p>The value of this option is an alist mapping conditions to display actions. Each condition may be either a regular expression matching a buffer name or a function that takes two arguments: a buffer name and the <var>action</var> argument passed to <code>display-buffer</code>. If either the name of the buffer passed to <code>display-buffer</code> matches a regular expression in this alist, or the function specified by a condition returns non-<code>nil</code>, then <code>display-buffer</code> uses the corresponding display action to display the buffer. </p></dd>
</dl> <dl> <dt id="display-buffer-base-action">User Option: <strong>display-buffer-base-action</strong>
</dt> <dd><p>The value of this option should be a display action. This option can be used to define a standard display action for calls to <code>display-buffer</code>. </p></dd>
</dl> <dl> <dt id="display-buffer-fallback-action">Constant: <strong>display-buffer-fallback-action</strong>
</dt> <dd><p>This display action specifies the fallback behavior for <code>display-buffer</code> if no other display actions are given. </p></dd>
</dl><div class="_attribution">
  <p class="_attribution-p">
    Copyright &copy; 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
    <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Choosing-Window.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Choosing-Window.html</a>
  </p>
</div>