Next: Window Hooks, Previous: Window Configurations, Up: Windows [Contents][Index]

### 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 (see 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`. See 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` (see Deleting Windows).

`delete-other-windows`

  This parameter affects the execution of `delete-other-windows` (see Deleting Windows).

`split-window`

  This parameter affects the execution of `split-window` (see Splitting Windows).

`other-window`

  This parameter affects the execution of `other-window` (see Cyclic Window Ordering).

`no-other-window`

  This parameter marks the window as not selectable by `other-window` (see Cyclic Window Ordering).

`clone-of`

  This parameter specifies the window that this one has been cloned from. It is installed by `window-state-get` (see 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` (see Preserving Window Sizes).

`quit-restore`

  This parameter is installed by the buffer display functions (see Choosing Window) and consulted by `quit-restore-window` (see 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 displayed the same buffer before; or `other`, the window showed another buffer before.

  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.

  The third element is the window selected at the time the parameter was created. The function `quit-restore-window` tries to reselect that window when it deletes the window passed to it as argument.

  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` (see 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.

Next: Window Hooks, Previous: Window Configurations, Up: Windows [Contents][Index]