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

 <h3 class="section">Window History</h3>  <p>Each window remembers in a list the buffers it has previously displayed, and the order in which these buffers were removed from it. This history is used, for example, by <code>replace-buffer-in-windows</code> (see <a href="buffers-and-windows">Buffers and Windows</a>), and when quitting windows (see <a href="quitting-windows">Quitting Windows</a>). The list is automatically maintained by Emacs, but you can use the following functions to explicitly inspect or alter it: </p> <dl> <dt id="window-prev-buffers">Function: <strong>window-prev-buffers</strong> <em>&amp;optional window</em>
</dt> <dd>
<p>This function returns a list specifying the previous contents of <var>window</var>. The optional argument <var>window</var> should be a live window and defaults to the selected one. </p> <p>Each list element has the form <code>(<var>buffer</var> <var>window-start</var>
<var>window-pos</var>)</code>, where <var>buffer</var> is a buffer previously shown in the window, <var>window-start</var> is the window start position (see <a href="window-start-and-end">Window Start and End</a>) when that buffer was last shown, and <var>window-pos</var> is the point position (see <a href="window-point">Window Point</a>) when that buffer was last shown in <var>window</var>. </p> <p>The list is ordered so that earlier elements correspond to more recently-shown buffers, and the first element usually corresponds to the buffer most recently removed from the window. </p>
</dd>
</dl> <dl> <dt id="set-window-prev-buffers">Function: <strong>set-window-prev-buffers</strong> <em>window prev-buffers</em>
</dt> <dd><p>This function sets <var>window</var>’s previous buffers to the value of <var>prev-buffers</var>. The argument <var>window</var> must be a live window and defaults to the selected one. The argument <var>prev-buffers</var> should be a list of the same form as that returned by <code>window-prev-buffers</code>. </p></dd>
</dl> <p>In addition, each window maintains a list of <em>next buffers</em>, which is a list of buffers re-shown by <code>switch-to-prev-buffer</code> (see below). This list is mainly used by <code>switch-to-prev-buffer</code> and <code>switch-to-next-buffer</code> for choosing buffers to switch to. </p> <dl> <dt id="window-next-buffers">Function: <strong>window-next-buffers</strong> <em>&amp;optional window</em>
</dt> <dd><p>This function returns the list of buffers recently re-shown in <var>window</var> via <code>switch-to-prev-buffer</code>. The <var>window</var> argument must denote a live window or <code>nil</code> (meaning the selected window). </p></dd>
</dl> <dl> <dt id="set-window-next-buffers">Function: <strong>set-window-next-buffers</strong> <em>window next-buffers</em>
</dt> <dd><p>This function sets the next buffer list of <var>window</var> to <var>next-buffers</var>. The <var>window</var> argument should be a live window or <code>nil</code> (meaning the selected window). The argument <var>next-buffers</var> should be a list of buffers. </p></dd>
</dl> <p>The following commands can be used to cycle through the global buffer list, much like <code>bury-buffer</code> and <code>unbury-buffer</code>. However, they cycle according to the specified window’s history list, rather than the global buffer list. In addition, they restore window-specific window start and point positions, and may show a buffer even if it is already shown in another window. The <code>switch-to-prev-buffer</code> command, in particular, is used by <code>replace-buffer-in-windows</code>, <code>bury-buffer</code> and <code>quit-window</code> to find a replacement buffer for a window. </p> <dl> <dt id="switch-to-prev-buffer">Command: <strong>switch-to-prev-buffer</strong> <em>&amp;optional window bury-or-kill</em>
</dt> <dd>
<p>This command displays the previous buffer in <var>window</var>. The argument <var>window</var> should be a live window or <code>nil</code> (meaning the selected window). If the optional argument <var>bury-or-kill</var> is non-<code>nil</code>, this means that the buffer currently shown in <var>window</var> is about to be buried or killed and consequently should not be switched to in future invocations of this command. </p> <p>The previous buffer is usually the buffer shown before the buffer currently shown in <var>window</var>. However, a buffer that has been buried or killed, or has been already shown by a recent invocation of <code>switch-to-prev-buffer</code>, does not qualify as previous buffer. </p> <p>If repeated invocations of this command have already shown all buffers previously shown in <var>window</var>, further invocations will show buffers from the buffer list of the frame <var>window</var> appears on (see <a href="buffer-list">Buffer List</a>). </p> <p>The option <code>switch-to-prev-buffer-skip</code> described below can be used to inhibit switching to certain buffers, for example, to those already shown in another window. Also, if <var>window</var>’s frame has a <code>buffer-predicate</code> parameter (see <a href="buffer-parameters">Buffer Parameters</a>), that predicate may inhibit switching to certain buffers. </p>
</dd>
</dl> <dl> <dt id="switch-to-next-buffer">Command: <strong>switch-to-next-buffer</strong> <em>&amp;optional window</em>
</dt> <dd>
<p>This command switches to the next buffer in <var>window</var>, thus undoing the effect of the last <code>switch-to-prev-buffer</code> command in <var>window</var>. The argument <var>window</var> must be a live window and defaults to the selected one. </p> <p>If there is no recent invocation of <code>switch-to-prev-buffer</code> that can be undone, this function tries to show a buffer from the buffer list of the frame <var>window</var> appears on (see <a href="buffer-list">Buffer List</a>). </p> <p>The option <code>switch-to-prev-buffer-skip</code> and the <code>buffer-predicate</code> (see <a href="buffer-parameters">Buffer Parameters</a>) of <var>window</var>’s frame affect this command as they do for <code>switch-to-prev-buffer</code>. </p>
</dd>
</dl> <p>By default <code>switch-to-prev-buffer</code> and <code>switch-to-next-buffer</code> can switch to a buffer that is already shown in another window. The following option can be used to override this behavior. </p> <dl> <dt id="switch-to-prev-buffer-skip">User Option: <strong>switch-to-prev-buffer-skip</strong>
</dt> <dd>
<p>If this variable is <code>nil</code>, <code>switch-to-prev-buffer</code> may switch to any buffer, including those already shown in other windows. </p> <p>If this variable is non-<code>nil</code>, <code>switch-to-prev-buffer</code> will refrain from switching to certain buffers. The following values can be used: </p> <ul> <li> <code>this</code> means do not switch to a buffer shown on the frame that hosts the window <code>switch-to-prev-buffer</code> is acting upon. </li>
<li> <code>visible</code> means do not switch to a buffer shown on any visible frame. </li>
<li> 0 (the number zero) means do not switch to a buffer shown on any visible or iconified frame. </li>
<li> <code>t</code> means do not switch to a buffer shown on any live frame. </li>
<li> A function that takes three arguments—the <var>window</var> argument of <code>switch-to-prev-buffer</code>, a buffer <code>switch-to-prev-buffer</code> intends to switch to and the <var>bury-or-kill</var> argument of <code>switch-to-prev-buffer</code>. If that function returns non-<code>nil</code>, <code>switch-to-prev-buffer</code> will refrain from switching to the buffer specified by the second argument. </li>
</ul> <p>The command <code>switch-to-next-buffer</code> obeys this option in a similar way. If this option specifies a function, <code>switch-to-next-buffer</code> will call that function with the third argument always <code>nil</code>. </p> <p>Note that since <code>switch-to-prev-buffer</code> is called by <code>bury-buffer</code>, <code>replace-buffer-in-windows</code> and <code>quit-restore-window</code> as well, customizing this option may also affect the behavior of Emacs when a window is quit or a buffer gets buried or killed. </p> <p>Note also that under certain circumstances <code>switch-to-prev-buffer</code> and <code>switch-to-next-buffer</code> may ignore this option, for example, when there is only one buffer left these functions can switch to. </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/Window-History.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Window-History.html</a>
  </p>
</div>