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

 <h4 class="subsection">Additional Options for Displaying Buffers</h4> <p>The behavior of buffer display actions (see <a href="choosing-window">Choosing Window</a>) can be further modified by the following user options. </p> <dl> <dt id="pop-up-windows">User Option: <strong>pop-up-windows</strong>
</dt> <dd>
<p>If the value of this variable is non-<code>nil</code>, <code>display-buffer</code> is allowed to split an existing window to make a new window for displaying in. This is the default. </p> <p>This variable is provided for backward compatibility only. It is obeyed by <code>display-buffer</code> via a special mechanism in <code>display-buffer-fallback-action</code>, which calls the action function <code>display-buffer-pop-up-window</code> (see <a href="buffer-display-action-functions">Buffer Display Action Functions</a>) when the value of this option is non-<code>nil</code>. It is not consulted by <code>display-buffer-pop-up-window</code> itself, which the user may specify directly in <code>display-buffer-alist</code> etc. </p>
</dd>
</dl> <dl> <dt id="split-window-preferred-function">User Option: <strong>split-window-preferred-function</strong>
</dt> <dd>
<p>This variable specifies a function for splitting a window, in order to make a new window for displaying a buffer. It is used by the <code>display-buffer-pop-up-window</code> action function to actually split the window. </p> <p>The value must be a function that takes one argument, a window, and returns either a new window (which will be used to display the desired buffer) or <code>nil</code> (which means the splitting failed). The default value is <code>split-window-sensibly</code>, which is documented next. </p>
</dd>
</dl> <dl> <dt id="split-window-sensibly">Function: <strong>split-window-sensibly</strong> <em>&amp;optional window</em>
</dt> <dd>
<p>This function tries to split <var>window</var> and return the newly created window. If <var>window</var> cannot be split, it returns <code>nil</code>. If <var>window</var> is omitted or <code>nil</code>, it defaults to the selected window. </p> <p>This function obeys the usual rules that determine when a window may be split (see <a href="splitting-windows">Splitting Windows</a>). It first tries to split by placing the new window below, subject to the restriction imposed by <code>split-height-threshold</code> (see below), in addition to any other restrictions. If that fails, it tries to split by placing the new window to the right, subject to <code>split-width-threshold</code> (see below). If that also fails, and the window is the only window on its frame, this function again tries to split and place the new window below, disregarding <code>split-height-threshold</code>. If this fails as well, this function gives up and returns <code>nil</code>. </p>
</dd>
</dl> <dl> <dt id="split-height-threshold">User Option: <strong>split-height-threshold</strong>
</dt> <dd><p>This variable specifies whether <code>split-window-sensibly</code> is allowed to split the window placing the new window below. If it is an integer, that means to split only if the original window has at least that many lines. If it is <code>nil</code>, that means not to split this way. </p></dd>
</dl> <dl> <dt id="split-width-threshold">User Option: <strong>split-width-threshold</strong>
</dt> <dd><p>This variable specifies whether <code>split-window-sensibly</code> is allowed to split the window placing the new window to the right. If the value is an integer, that means to split only if the original window has at least that many columns. If the value is <code>nil</code>, that means not to split this way. </p></dd>
</dl> <dl> <dt id="even-window-sizes">User Option: <strong>even-window-sizes</strong>
</dt> <dd>
<p>This variable, if non-<code>nil</code>, causes <code>display-buffer</code> to even window sizes whenever it reuses an existing window, and that window is adjacent to the selected one. </p> <p>If its value is <code>width-only</code>, sizes are evened only if the reused window is on the left or right of the selected one and the selected window is wider than the reused one. If its value is <code>height-only</code> sizes are evened only if the reused window is above or beneath the selected window and the selected window is higher than the reused one. Any other non-<code>nil</code> value means to even sizes in any of these cases provided the selected window is larger than the reused one in the sense of their combination. </p>
</dd>
</dl> <dl> <dt id="pop-up-frames">User Option: <strong>pop-up-frames</strong>
</dt> <dd>
<p>If the value of this variable is non-<code>nil</code>, that means <code>display-buffer</code> may display buffers by making new frames. The default is <code>nil</code>. </p> <p>A non-<code>nil</code> value also means that when <code>display-buffer</code> is looking for a window already displaying <var>buffer-or-name</var>, it can search any visible or iconified frame, not just the selected frame. </p> <p>This variable is provided mainly for backward compatibility. It is obeyed by <code>display-buffer</code> via a special mechanism in <code>display-buffer-fallback-action</code>, which calls the action function <code>display-buffer-pop-up-frame</code> (see <a href="buffer-display-action-functions">Buffer Display Action Functions</a>) if the value is non-<code>nil</code>. (This is done before attempting to split a window.) This variable is not consulted by <code>display-buffer-pop-up-frame</code> itself, which the user may specify directly in <code>display-buffer-alist</code> etc. </p>
</dd>
</dl> <dl> <dt id="pop-up-frame-function">User Option: <strong>pop-up-frame-function</strong>
</dt> <dd>
<p>This variable specifies a function for creating a new frame, in order to make a new window for displaying a buffer. It is used by the <code>display-buffer-pop-up-frame</code> action function. </p> <p>The value should be a function that takes no arguments and returns a frame, or <code>nil</code> if no frame could be created. The default value is a function that creates a frame using the parameters specified by <code>pop-up-frame-alist</code> (see below). </p>
</dd>
</dl> <dl> <dt id="pop-up-frame-alist">User Option: <strong>pop-up-frame-alist</strong>
</dt> <dd>
<p>This variable holds an alist of frame parameters (see <a href="frame-parameters">Frame Parameters</a>), which is used by the function specified by <code>pop-up-frame-function</code> to make a new frame. The default is <code>nil</code>. </p> <p>This option is provided for backward compatibility only. Note, that when <code>display-buffer-pop-up-frame</code> calls the function specified by <code>pop-up-frame-function</code>, it prepends the value of all <code>pop-up-frame-parameters</code> action alist entries to <code>pop-up-frame-alist</code> so that the values specified by the action alist entry effectively override any corresponding values of <code>pop-up-frame-alist</code>. </p> <p>Hence, users should set up a <code>pop-up-frame-parameters</code> action alist entry in <code>display-buffer-alist</code> instead of customizing <code>pop-up-frame-alist</code>. Only this will guarantee that the value of a parameter specified by the user overrides the value of that parameter specified by the caller of <code>display-buffer</code>. </p>
</dd>
</dl> <p>Many efforts in the design of <code>display-buffer</code> have been given to maintain compatibility with code that uses older options like <code>pop-up-windows</code>, <code>pop-up-frames</code>, <code>pop-up-frame-alist</code>, <code>same-window-buffer-names</code> and <code>same-window-regexps</code>. Lisp Programs and users should refrain from using these options. Above we already warned against customizing <code>pop-up-frame-alist</code>. Here we describe how to convert the remaining options to use display actions instead. </p> <dl compact> <dt><code>pop-up-windows</code></dt> <dd>
 <p>This variable is <code>t</code> by default. Instead of customizing it to <code>nil</code> and thus telling <code>display-buffer</code> what not to do, it’s much better to list in <code>display-buffer-base-action</code> the action functions it should try instead as, for example: </p> <div class="example"> <pre class="example">(customize-set-variable
 'display-buffer-base-action
 '((display-buffer-reuse-window display-buffer-same-window
    display-buffer-in-previous-window
    display-buffer-use-some-window)))
</pre>
</div> </dd> <dt><code>pop-up-frames</code></dt> <dd>
 <p>Instead of customizing this variable to <code>t</code>, customize <code>display-buffer-base-action</code>, for example, as follows: </p> <div class="example"> <pre class="example">(customize-set-variable
 'display-buffer-base-action
 '((display-buffer-reuse-window display-buffer-pop-up-frame)
   (reusable-frames . 0)))
</pre>
</div> </dd> <dt><code>same-window-buffer-names</code></dt> <dt><code>same-window-regexps</code></dt> <dd>
  <p>Instead of adding a buffer name or a regular expression to one of these options use a <code>display-buffer-alist</code> entry for that buffer specifying the action function <code>display-buffer-same-window</code>. </p> <div class="example"> <pre class="example">(customize-set-variable
 'display-buffer-alist
 (cons '("\\*foo\\*" (display-buffer-same-window))
        display-buffer-alist))
</pre>
</div> </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-Options.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Choosing-Window-Options.html</a>
  </p>
</div>