path: root/devdocs/elisp/displaying-buffers-in-side-windows.html

 <h4 class="subsection">Displaying Buffers in Side Windows</h4> <p>The following action function for <code>display-buffer</code> (see <a href="buffer-display-action-functions">Buffer Display Action Functions</a>) creates or reuses a side window for displaying the specified buffer. </p> <dl> <dt id="display-buffer-in-side-window">Function: <strong>display-buffer-in-side-window</strong> <em>buffer alist</em>
</dt> <dd>
<p>This function displays <var>buffer</var> in a side window of the selected frame. It returns the window used for displaying <var>buffer</var>, <code>nil</code> if no such window can be found or created. </p> <p><var>alist</var> is an association list of symbols and values as for <code>display-buffer</code>. The following symbols in <var>alist</var> are special for this function: </p> <dl compact> <dt><code>side</code></dt> <dd>
<p>Denotes the side of the frame where the window shall be located. Valid values are <code>left</code>, <code>top</code>, <code>right</code> and <code>bottom</code>. If unspecified, the window is located at the bottom of the frame. </p> </dd> <dt><code>slot</code></dt> <dd>
<p>Denotes a slot at the specified side where to locate the window. A value of zero means to preferably position the window in the middle of the specified side. A negative value means to use a slot preceding (that is, above or on the left of) the middle slot. A positive value means to use a slot following (that is, below or on the right of) the middle slot. Hence, all windows on a specific side are ordered by their <code>slot</code> value. If unspecified, the window is located in the middle of the specified side. </p> </dd> <dt><code>dedicated</code></dt> <dd>
<p>The dedicated flag (see <a href="dedicated-windows">Dedicated Windows</a>) has a slightly different meaning for side windows. When a side window is created, that flag is set to the value <code>side</code> to prevent <code>display-buffer</code> to use the window in other action functions. Its value persists across invocations of <code>quit-window</code>, <code>kill-buffer</code>, <code>previous-buffer</code> and <code>next-buffer</code>. </p> <p>In particular, these commands will refrain from showing, in a side window, buffers that have not been displayed in that window before. They will also refrain from having a normal, non-side window show a buffer that has been already displayed in a side window. A notable exception to the latter rule occurs when an application, after displaying a buffer, resets that buffer’s local variables. To override these rules and always delete a side window with <code>quit-window</code> or <code>kill-buffer</code>, and eventually prevent the use of <code>previous-buffer</code> and <code>next-buffer</code>, set this value to <code>t</code> or specify a value via <code>display-buffer-mark-dedicated</code>. </p>
</dd> </dl> <p>If you specify the same slot on the same side for two or more different buffers, the buffer displayed last is shown in the corresponding window. Hence, slots can be used for sharing the same side window between buffers. </p> <p>This function installs the <code>window-side</code> and <code>window-slot</code> parameters (see <a href="window-parameters">Window Parameters</a>) and makes them persistent. It does not install any other window parameters unless they have been explicitly provided via a <code>window-parameters</code> entry in <var>alist</var>. </p>
</dd>
</dl> <p>By default, side windows cannot be split via <code>split-window</code> (see <a href="splitting-windows">Splitting Windows</a>). Also, a side window is not reused or split by any buffer display action (see <a href="buffer-display-action-functions">Buffer Display Action Functions</a>) unless it is explicitly specified as target of that action. Note also that <code>delete-other-windows</code> cannot make a side window the only window on its frame (see <a href="deleting-windows">Deleting Windows</a>). </p><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/Displaying-Buffers-in-Side-Windows.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Displaying-Buffers-in-Side-Windows.html</a>
  </p>
</div>