elisp: Window Configurations
27.25 Window Configurations
===========================
A “window configuration” records the entire layout of one frame—all
windows, their sizes, which buffers they contain, how those buffers are
scrolled, and their value of point; also their fringes, margins, and
scroll bar settings. 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. 
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. Window
Parameters.
-- Function: set-window-configuration configuration
This function restores the configuration of windows and buffers as
specified by CONFIGURATION, for the frame that CONFIGURATION was
created for.
The argument CONFIGURATION must be a value that was previously
returned by ‘current-window-configuration’. The configuration is
restored in the frame from which CONFIGURATION was made, whether
that frame is selected or not. This always counts as a window size
change and triggers execution of the ‘window-size-change-functions’
(Window Hooks), because ‘set-window-configuration’ doesn’t
know how to tell whether the new configuration actually differs
from the old one.
If the frame from which CONFIGURATION was saved is dead, all this
function does is restore the three variables ‘window-min-height’,
‘window-min-width’ and ‘minibuffer-scroll-window’. In this case,
the function returns ‘nil’. Otherwise, it returns ‘t’.
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 (Choosing Window),
and ‘save-window-excursion’ only saves and restores the window
configuration on the current frame.
Do not use this macro in ‘window-size-change-functions’; exiting
the macro triggers execution of ‘window-size-change-functions’,
leading to an endless loop.
-- Function: window-configuration-p object
This function returns ‘t’ if OBJECT is a window configuration.
-- Function: compare-window-configurations config1 config2
This function compares two window configurations as regards the
structure of windows, but ignores the values of point and the saved
scrolling positions—it can return ‘t’ even if those aspects differ.
The function ‘equal’ can also compare two window configurations; it
regards configurations as unequal if they differ in any respect,
even a saved point.
-- 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. 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
(Windows and Frames) and defaults to the selected one. If
WINDOW is not live, it is replaced by a live window before putting
STATE into it.
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.
Info Catalog
elisp: Coordinates and Windows
elisp: Windows
elisp: Window Parameters