27.15 Window History

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 replace-buffer-in-windows (see Buffers and Windows). The list is automatically maintained by Emacs, but you can use the following functions to explicitly inspect or alter it:

Function: window-prev-buffers &optional window

This function returns a list specifying the previous contents of window. The optional argument window should be a live window and defaults to the selected one.

Each list element has the form (buffer window-start window-pos), where buffer is a buffer previously shown in the window, window-start is the window start position (see Window Start and End) when that buffer was last shown, and window-pos is the point position (see Window Point) when that buffer was last shown in window.

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.

Function: set-window-prev-buffers window prev-buffers

This function sets window’s previous buffers to the value of prev-buffers. The argument window must be a live window and defaults to the selected one. The argument prev-buffers should be a list of the same form as that returned by window-prev-buffers.

In addition, each buffer maintains a list of next buffers, which is a list of buffers re-shown by switch-to-prev-buffer (see below). This list is mainly used by switch-to-prev-buffer and switch-to-next-buffer for choosing buffers to switch to.

Function: window-next-buffers &optional window

This function returns the list of buffers recently re-shown in window via switch-to-prev-buffer. The window argument must denote a live window or nil (meaning the selected window).

Function: set-window-next-buffers window next-buffers

This function sets the next buffer list of window to next-buffers. The window argument should be a live window or nil (meaning the selected window). The argument next-buffers should be a list of buffers.

The following commands can be used to cycle through the global buffer list, much like bury-buffer and unbury-buffer. 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 switch-to-prev-buffer command, in particular, is used by replace-buffer-in-windows, bury-buffer and quit-window to find a replacement buffer for a window.

Command: switch-to-prev-buffer &optional window bury-or-kill

This command displays the previous buffer in window. The argument window should be a live window or nil (meaning the selected window). If the optional argument bury-or-kill is non-nil, this means that the buffer currently shown in window is about to be buried or killed and consequently should not be switched to in future invocations of this command.

The previous buffer is usually the buffer shown before the buffer currently shown in window. However, a buffer that has been buried or killed, or has been already shown by a recent invocation of switch-to-prev-buffer, does not qualify as previous buffer.

If repeated invocations of this command have already shown all buffers previously shown in window, further invocations will show buffers from the buffer list of the frame window appears on (see Buffer List), trying to skip buffers that are already shown in another window on that frame.

Command: switch-to-next-buffer &optional window

This command switches to the next buffer in window, thus undoing the effect of the last switch-to-prev-buffer command in window. The argument window must be a live window and defaults to the selected one.

If there is no recent invocation of switch-to-prev-buffer that can be undone, this function tries to show a buffer from the buffer list of the frame window appears on (see Buffer List).

By default switch-to-prev-buffer and switch-to-next-buffer can switch to a buffer that is already shown in another window on the same frame. The following option can be used to override this behavior.

User Option: switch-to-visible-buffer

If this variable is non-nil, switch-to-prev-buffer and switch-to-next-buffer may switch to a buffer that is already visible on the same frame, provided the buffer was shown in the relevant window before. If it is nil, switch-to-prev-buffer and switch-to-next-buffer always try to avoid switching to a buffer that is already visible in another window on the same frame. The default is t.