diff options
Diffstat (limited to 'devdocs/elisp/window-parameters.html')
| -rw-r--r-- | devdocs/elisp/window-parameters.html | 37 |
1 files changed, 37 insertions, 0 deletions
diff --git a/devdocs/elisp/window-parameters.html b/devdocs/elisp/window-parameters.html new file mode 100644 index 00000000..099b521e --- /dev/null +++ b/devdocs/elisp/window-parameters.html @@ -0,0 +1,37 @@ + <h3 class="section">Window Parameters</h3> <p>This section describes the window parameters that can be used to associate additional information with windows. </p> <dl> <dt id="window-parameter">Function: <strong>window-parameter</strong> <em>window parameter</em> +</dt> <dd><p>This function returns <var>window</var>’s value for <var>parameter</var>. The default for <var>window</var> is the selected window. If <var>window</var> has no setting for <var>parameter</var>, this function returns <code>nil</code>. </p></dd> +</dl> <dl> <dt id="window-parameters">Function: <strong>window-parameters</strong> <em>&optional window</em> +</dt> <dd><p>This function returns all parameters of <var>window</var> and their values. The default for <var>window</var> is the selected window. The return value is either <code>nil</code>, or an association list whose elements have the form <code>(<var>parameter</var> . <var>value</var>)</code>. </p></dd> +</dl> <dl> <dt id="set-window-parameter">Function: <strong>set-window-parameter</strong> <em>window parameter value</em> +</dt> <dd><p>This function sets <var>window</var>’s value of <var>parameter</var> to <var>value</var> and returns <var>value</var>. The default for <var>window</var> is the selected window. </p></dd> +</dl> <p>By default, the functions that save and restore window configurations or the states of windows (see <a href="window-configurations">Window Configurations</a>) do not care about window parameters. This means that when you change the value of a parameter within the body of a <code>save-window-excursion</code>, the previous value is not restored when that macro exits. It also means that when you restore via <code>window-state-put</code> a window state saved earlier by <code>window-state-get</code>, all cloned windows have their parameters reset to <code>nil</code>. The following variable allows you to override the standard behavior: </p> <dl> <dt id="window-persistent-parameters">Variable: <strong>window-persistent-parameters</strong> +</dt> <dd> +<p>This variable is an alist specifying which parameters get saved by <code>current-window-configuration</code> and <code>window-state-get</code>, and subsequently restored by <code>set-window-configuration</code> and <code>window-state-put</code>. See <a href="window-configurations">Window Configurations</a>. </p> <p>The <small>CAR</small> of each entry of this alist is a symbol specifying the parameter. The <small>CDR</small> should be one of the following: </p> <dl compact> <dt><code>nil</code></dt> <dd> +<p>This value means the parameter is saved neither by <code>window-state-get</code> nor by <code>current-window-configuration</code>. </p> </dd> <dt><code>t</code></dt> <dd> +<p>This value specifies that the parameter is saved by <code>current-window-configuration</code> and (provided its <var>writable</var> argument is <code>nil</code>) by <code>window-state-get</code>. </p> </dd> <dt><code>writable</code></dt> <dd><p>This means that the parameter is saved unconditionally by both <code>current-window-configuration</code> and <code>window-state-get</code>. This value should not be used for parameters whose values do not have a read syntax. Otherwise, invoking <code>window-state-put</code> in another session may fail with an <code>invalid-read-syntax</code> error. </p></dd> </dl> </dd> +</dl> <p>Some functions (notably <code>delete-window</code>, <code>delete-other-windows</code> and <code>split-window</code>), may behave specially when the window specified by their <var>window</var> argument has a parameter whose name is equal to the function’s name. You can override such special behavior by binding the following variable to a non-<code>nil</code> value: </p> <dl> <dt id="ignore-window-parameters">Variable: <strong>ignore-window-parameters</strong> +</dt> <dd> +<p>If this variable is non-<code>nil</code>, some standard functions do not process window parameters. The functions currently affected by this are <code>split-window</code>, <code>delete-window</code>, <code>delete-other-windows</code>, and <code>other-window</code>. </p> <p>An application can bind this variable to a non-<code>nil</code> 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. </p> +</dd> +</dl> <p>The following parameters are currently used by the window management code: </p> <dl compact> <dt><code>delete-window</code></dt> <dd> + <p>This parameter affects the execution of <code>delete-window</code> (see <a href="deleting-windows">Deleting Windows</a>). </p> </dd> <dt><code>delete-other-windows</code></dt> <dd> + <p>This parameter affects the execution of <code>delete-other-windows</code> (see <a href="deleting-windows">Deleting Windows</a>). </p> </dd> <dt><code>no-delete-other-windows</code></dt> <dd> + <p>This parameter marks the window as not deletable by <code>delete-other-windows</code> (see <a href="deleting-windows">Deleting Windows</a>). </p> </dd> <dt><code>split-window</code></dt> <dd> + <p>This parameter affects the execution of <code>split-window</code> (see <a href="splitting-windows">Splitting Windows</a>). </p> </dd> <dt><code>other-window</code></dt> <dd> + <p>This parameter affects the execution of <code>other-window</code> (see <a href="cyclic-window-ordering">Cyclic Window Ordering</a>). </p> </dd> <dt><code>no-other-window</code></dt> <dd> + <p>This parameter marks the window as not selectable by <code>other-window</code> (see <a href="cyclic-window-ordering">Cyclic Window Ordering</a>). </p> </dd> <dt><code>clone-of</code></dt> <dd> + <p>This parameter specifies the window that this one has been cloned from. It is installed by <code>window-state-get</code> (see <a href="window-configurations">Window Configurations</a>). </p> </dd> <dt><code>window-preserved-size</code></dt> <dd> + <p>This parameter specifies a buffer, a direction where <code>nil</code> means vertical and <code>t</code> 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 <code>window-preserve-size</code> (see <a href="preserving-window-sizes">Preserving Window Sizes</a>). </p> </dd> <dt><code>quit-restore</code></dt> <dd> + <p>This parameter is installed by the buffer display functions (see <a href="choosing-window">Choosing Window</a>) and consulted by <code>quit-restore-window</code> (see <a href="quitting-windows">Quitting Windows</a>). It is a list of four elements, see the description of <code>quit-restore-window</code> in <a href="quitting-windows">Quitting Windows</a> for details. </p> </dd> <dt><code>window-side</code></dt> <dt><code>window-slot</code></dt> <dd> + <p>These parameters are used internally for implementing side windows (see <a href="side-windows">Side Windows</a>). </p> </dd> <dt><code>window-atom</code></dt> <dd> + <p>This parameter is used internally for implementing atomic windows, see <a href="atomic-windows">Atomic Windows</a>. </p> </dd> <dt><code>mode-line-format</code></dt> <dd> + <p>This parameter replaces the value of the buffer-local variable <code>mode-line-format</code> (see <a href="mode-line-basics">Mode Line Basics</a>) of this window’s buffer whenever this window is displayed. The symbol <code>none</code> means to suppress display of a mode line for this window. Display and contents of the mode line on other windows showing this buffer are not affected. </p> </dd> <dt><code>header-line-format</code></dt> <dd> + <p>This parameter replaces the value of the buffer-local variable <code>header-line-format</code> (see <a href="mode-line-basics">Mode Line Basics</a>) of this window’s buffer whenever this window is displayed. The symbol <code>none</code> means to suppress display of a header line for this window. Display and contents of the header line on other windows showing this buffer are not affected. </p> </dd> <dt><code>tab-line-format</code></dt> <dd> + <p>This parameter replaces the value of the buffer-local variable <code>tab-line-format</code> (see <a href="mode-line-basics">Mode Line Basics</a>) of this window’s buffer whenever this window is displayed. The symbol <code>none</code> means to suppress display of a tab line for this window. Display and contents of the tab line on other windows showing this buffer are not affected. </p> </dd> <dt><code>min-margins</code></dt> <dd> + <p>The value of this parameter is a cons cell whose <small>CAR</small> and <small>CDR</small>, if non-<code>nil</code>, specify the minimum values (in columns) for the left and right margin of this window (see <a href="display-margins">Display Margins</a>. When present, Emacs will use these values instead of the actual margin widths for determining whether a window can be split or shrunk horizontally. </p> <p>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 <code>window-configuration-change-hook</code> and <code>window-size-change-functions</code> (see <a href="window-hooks">Window Hooks</a>) should be employed for this purpose. </p> <p>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. </p> +</dd> </dl><div class="_attribution"> + <p class="_attribution-p"> + Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br> + <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Window-Parameters.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Window-Parameters.html</a> + </p> +</div> |