29.26 Window Configurations

A window configuration records the entire layout of one frame—all windows, their sizes, their decorations, which buffers they contain, how those buffers are scrolled, and their value of point, It also includes the value of minibuffer-scroll-window. As a special exception, the window configuration does not record the value of point in the selected window for the current buffer.

You can bring back an entire frame layout by restoring a previously saved window configuration. If you want to record the layout of all frames instead of just one, use a frame configuration instead of a window configuration. See Frame Configurations.

Function: current-window-configuration &optional frame ¶

This function returns a new object representing frame’s current window configuration. The default for frame is the selected frame. The variable window-persistent-parameters specifies which window parameters (if any) are saved by this function. See Window Parameters.

Function: set-window-configuration configuration &optional dont-set-frame dont-set-miniwindow ¶

This function restores the configuration of windows and buffers as specified by configuration, for the frame that configuration was created for, regardless of whether that frame is selected or not. The argument configuration must be a value that was previously returned by current-window-configuration for that frame. Normally the function also selects the frame which is recorded in the configuration, but if dont-set-frame is non-nil, it leaves selected the frame which was already selected at the start of the function.

Normally the function restores the saved minibuffer (if any), but if dont-set-miniwindow is non-nil, the minibuffer current at the start of the function (if any) remains in the mini-window.

If the frame from which configuration was saved is dead, all this function does is to restore the value of the variable minibuffer-scroll-window and to adjust the value returned by minibuffer-selected-window. In this case, the function returns nil. Otherwise, it returns t.

This function consults the variable window-restore-killed-buffer-windows (see below) when it tries to restore a window whose buffer was killed after configuration was recorded.

Here is a way of using this function to get the same effect as save-window-excursion:

(let ((config (current-window-configuration)))
  (unwind-protect
      (progn (split-window-below nil)
             …)
    (set-window-configuration config)))

Macro: save-window-excursion forms… ¶

This macro records the window configuration of the selected frame, executes forms in sequence, then restores the earlier window configuration. The return value is the value of the final form in forms.

Most Lisp code should not use this macro; save-selected-window is typically sufficient. In particular, this macro cannot reliably prevent the code in forms from opening new windows, because new windows might be opened in other frames (see Choosing a Window for Displaying a Buffer), and save-window-excursion only saves and restores the window configuration on the current frame.

Function: window-configuration-p object ¶

This function returns t if object is a window configuration.

Function: window-configuration-equal-p config1 config2 ¶

This function says whether two window configurations have the same window layout, but ignores the values of point and the saved scrolling positions—it can return t even if those aspects differ.

Function: window-configuration-frame config ¶

This function returns the frame for which the window configuration config was made.

Other primitives to look inside of window configurations would make sense, but are not implemented because we did not need them. See the file winner.el for some more operations on windows configurations.

The objects returned by current-window-configuration die together with the Emacs process. In order to store a window configuration on disk and read it back in another Emacs session, you can use the functions described next. These functions are also useful to clone the state of a frame into an arbitrary live window (set-window-configuration effectively clones the windows of a frame into the root window of that very frame only).

Function: window-state-get &optional window writable ¶

This function returns the state of window as a Lisp object. The argument window must be a valid window and defaults to the root window of the selected frame.

If the optional argument writable is non-nil, this means to not use markers for sampling positions like window-point or window-start. This argument should be non-nil when the state will be written to disk and read back in another session.

Together, the argument writable and the variable window-persistent-parameters specify which window parameters are saved by this function. See Window Parameters.

The value returned by window-state-get can be used in the same session to make a clone of a window in another window. It can be also written to disk and read back in another session. In either case, use the following function to restore the state of the window.

Function: window-state-put state &optional window ignore ¶

This function puts the window state state into window. The argument state should be the state of a window returned by an earlier invocation of window-state-get, see above. The optional argument window can be either a live window or an internal window (see Windows and Frames). If window is not a live window, it is replaced by a new live window created on the same frame before putting state into it. If window is nil, it puts the window state into a new window.

This function consults the variable window-restore-killed-buffer-windows (see below) when it tries to restore a window whose buffer was killed after state was recorded.

If the optional argument ignore is non-nil, it means to ignore minimum window sizes and fixed-size restrictions. If ignore is safe, this means windows can get as small as one line and/or two columns.

By default, set-window-configuration and window-state-put may delete a window from the restored configuration when they find out that its buffer was killed since the corresponding configuration or state has been recorded. The variable described next can be used to fine-tune that behavior.

Variable: window-restore-killed-buffer-windows ¶

This variable specifies how set-window-configuration and window-state-put shall handle a window whose buffer has been killed since the corresponding configuration or state was recorded. Any such window may be live—in which case it shows some other buffer—or dead at the time one of these functions is called. Usually, set-window-configuration leaves the window alone if it is live while window-state-put deletes it.

The following values can be used to override the default behavior for dead windows in the case of set-window-configuration and for dead and live windows in the case of window-state-put.

t

This value means to unconditionally restore the window and show some other buffer in it.

delete

This means to unconditionally try to delete the window.

dedicated

This means to try to delete the window if and only if it is dedicated to its buffer.

nil

This is the default, and it means that set-window-configuration will try to delete the window if and only if it is dedicated to its buffer, and window-state-put will unconditionally try to delete it.

a function

This means to restore the window and show some other buffer in it, like if the value is t, and also add an entry for that window to a list that will be later passed as the second argument to that function.

If a window cannot be deleted (typically, because it is the last window on its frame), set-window-configuration and window-state-put will show another buffer in it.

If the value of this variable is a function, that function should take three arguments. The first argument specifies the frame whose windows have been restored. The third argument is either the symbol configuration if the windows are restored by set-window-configuration, or the symbol state if the windows are restored by window-state-put.

The second argument specifies a list of entries for all windows whose previous buffers have been found dead at the time set-window-configuration or window-state-put tried to restore them (minibuffer windows are excluded). This means that the function may also delete windows which were found live by set-window-configuration.

Each entry in the list that is passed as the second argument to the function is itself a list of six values: the window whose buffer was found dead, the dead buffer or its name, the positions of window-start (see The Window Start and End Positions) and window-point (see Windows and Point) of the buffer in that window, the dedicated state of the window as previously reported by window-dedicated-p and a flag that is t if the window has been found to be alive by set-window-configuration and nil otherwise.

The functions window-state-get and window-state-put also allow exchanging the contents of two live windows. The following function does precisely that:

Command: window-swap-states &optional window-1 window-2 size ¶

This command swaps the states of the two live windows window-1 and window-2. window-1 must specify a live window and defaults to the selected one. window-2 must specify a live window and defaults to the window following window-1 in the cyclic ordering of windows, excluding minibuffer windows and including live windows on all visible frames.

Optional argument size non-nil means to try swapping the sizes of window-1 and window-2 as well. A value of height means to swap heights only, a value of width means to swap widths only, while t means to swap both widths and heights, if possible. Frames are not resized by this function.