elisp: Window Parameters
27.26 Window Parameters
=======================
This section describes how window parameters can be used to associate
additional information with windows.
-- Function: window-parameter window parameter
This function returns WINDOW’s value for PARAMETER. The default
for WINDOW is the selected window. If WINDOW has no setting for
PARAMETER, this function returns ‘nil’.
-- Function: window-parameters &optional window
This function returns all parameters of WINDOW and their values.
The default for WINDOW is the selected window. The return value is
either ‘nil’, or an association list whose elements have the form
‘(PARAMETER . VALUE)’.
-- Function: set-window-parameter window parameter value
This function sets WINDOW’s value of PARAMETER to VALUE and returns
VALUE. The default for WINDOW is the selected window.
By default, the functions that save and restore window configurations
or the states of windows (
Window Configurations) do not care
about window parameters. This means that when you change the value of a
parameter within the body of a ‘save-window-excursion’, the previous
value is not restored when that macro exits. It also means that when
you restore via ‘window-state-put’ a window state saved earlier by
‘window-state-get’, all cloned windows have their parameters reset to
‘nil’. The following variable allows you to override the standard
behavior:
-- Variable: window-persistent-parameters
This variable is an alist specifying which parameters get saved by
‘current-window-configuration’ and ‘window-state-get’, and
subsequently restored by ‘set-window-configuration’ and
‘window-state-put’. Window Configurations.
The CAR of each entry of this alist is a symbol specifying the
parameter. The CDR should be one of the following:
‘nil’
This value means the parameter is saved neither by
‘window-state-get’ nor by ‘current-window-configuration’.
‘t’
This value specifies that the parameter is saved by
‘current-window-configuration’ and (provided its WRITABLE
argument is ‘nil’) by ‘window-state-get’.
‘writable’
This means that the parameter is saved unconditionally by both
‘current-window-configuration’ and ‘window-state-get’. This
value should not be used for parameters whose values do not
have a read syntax. Otherwise, invoking ‘window-state-put’ in
another session may fail with an ‘invalid-read-syntax’ error.
Some functions (notably ‘delete-window’, ‘delete-other-windows’ and
‘split-window’), may behave specially when their WINDOW argument has a
parameter set. You can override such special behavior by binding the
following variable to a non-‘nil’ value:
-- Variable: ignore-window-parameters
If this variable is non-‘nil’, some standard functions do not
process window parameters. The functions currently affected by
this are ‘split-window’, ‘delete-window’, ‘delete-other-windows’,
and ‘other-window’.
An application can bind this variable to a non-‘nil’ value around
calls to these functions. If it does so, the application is fully
responsible for correctly assigning the parameters of all involved
windows when exiting that function.
The following parameters are currently used by the window management
code:
‘delete-window’
This parameter affects the execution of ‘delete-window’ (
Deleting Windows).
‘delete-other-windows’
This parameter affects the execution of ‘delete-other-windows’
(Deleting Windows).
‘split-window’
This parameter affects the execution of ‘split-window’ (
Splitting Windows).
‘other-window’
This parameter affects the execution of ‘other-window’ (
Cyclic Window Ordering).
‘no-other-window’
This parameter marks the window as not selectable by ‘other-window’
(Cyclic Window Ordering).
‘clone-of’
This parameter specifies the window that this one has been cloned
from. It is installed by ‘window-state-get’ (Window
Configurations).
‘preserved-size’
This parameter specifies a buffer, a direction where ‘nil’ means
vertical and ‘t’ horizontal, and a size in pixels. If this window
displays the specified buffer and its size in the indicated
direction equals the size specified by this parameter, then Emacs
will try to preserve the size of this window in the indicated
direction. This parameter is installed and updated by the function
‘window-preserve-size’ (Preserving Window Sizes).
‘quit-restore’
Choosing Window::) and consulted by ‘quit-restore-window’ (
Quitting Windows). It contains four elements:
The first element is one of the symbols ‘window’, meaning that the
window has been specially created by ‘display-buffer’; ‘frame’, a
separate frame has been created; ‘same’, the window has only ever
displayed this buffer; or ‘other’, the window showed another buffer
before. ‘frame’ and ‘window’ affect how the window is quit, while
‘same’ and ‘other’ affect the redisplay of buffers previously shown
in this window.
The second element is either one of the symbols ‘window’ or
‘frame’, or a list whose elements are the buffer shown in the
window before, that buffer’s window start and window point
positions, and the window’s height at that time. If that buffer is
still live when the window is quit, then the function
‘quit-restore-window’ reuses the window to display the buffer.
The third element is the window selected at the time the parameter
was created. If ‘quit-restore-window’ deletes the window passed to
it as argument, it then tries to reselect this window.
The fourth element is the buffer whose display caused the creation
of this parameter. ‘quit-restore-window’ deletes the specified
window only if it still shows that buffer.
‘min-margins’
The value of this parameter is a cons cell whose CAR and CDR, if
non-‘nil’, specify the minimum values (in columns) for the left and
right margin of this window. When present, Emacs will use these
values instead of the actual margin widths for determining whether
a window can be split or shrunk horizontally.
Emacs never auto-adjusts the margins of any window after splitting
or resizing it. It is the sole responsibility of any application
setting this parameter to adjust the margins of this window as well
as those of any new window that inherits this window’s margins due
to a split. Both ‘window-configuration-change-hook’ and
‘window-size-change-functions’ (Window Hooks) should be
employed for this purpose.
This parameter was introduced in Emacs version 25.1 to support
applications that use large margins to center buffer text within a
window and should be used, with due care, exclusively by those
applications. It might be replaced by an improved solution in
future versions of Emacs.
There are additional parameters ‘window-atom’ and ‘window-side’;
these are reserved and should not be used by applications.
Info Catalog
elisp: Window Configurations
elisp: Windows
elisp: Window Hooks