diff options
Diffstat (limited to 'devdocs/elisp/buffer-display-action-alists.html')
| -rw-r--r-- | devdocs/elisp/buffer-display-action-alists.html | 39 |
1 files changed, 39 insertions, 0 deletions
diff --git a/devdocs/elisp/buffer-display-action-alists.html b/devdocs/elisp/buffer-display-action-alists.html new file mode 100644 index 00000000..14a8af93 --- /dev/null +++ b/devdocs/elisp/buffer-display-action-alists.html @@ -0,0 +1,39 @@ + <h4 class="subsection">Action Alists for Buffer Display</h4> <p>An <em>action alist</em> is an association list mapping predefined symbols recognized by action functions to values these functions are supposed to interpret accordingly. In each call, <code>display-buffer</code> constructs a new, possibly empty action alist and passes that entire list on to any action function it calls. </p> <p>By design, action functions are free in their interpretation of action alist entries. In fact, some entries like <code>allow-no-window</code> or <code>previous-window</code> have a meaning only for one or a few action functions, and are ignored by the rest. Other entries, like <code>inhibit-same-window</code> or <code>window-parameters</code>, are supposed to be respected by most action functions, including those provided by application programs and external packages. </p> <p>In the previous subsection we have described in detail how individual action functions interpret the action alist entries they care about. Here we give a reference list of all known action alist entries according to their symbols, together with their values and action functions (see <a href="buffer-display-action-functions">Buffer Display Action Functions</a>) that recognize them. Throughout this list, the terms “buffer” will refer to the buffer <code>display-buffer</code> is supposed to display, and “value” refers to the entry’s value. </p> <dl compact> <dt><code>inhibit-same-window</code></dt> <dd> +<p>If the value is non-<code>nil</code>, this signals that the selected window must not be used for displaying the buffer. All action functions that (re-)use an existing window should respect this entry. </p> </dd> <dt><code>previous-window</code></dt> <dd> +<p>The value must specify a window that may have displayed the buffer previously. <code>display-buffer-in-previous-window</code> will give preference to such a window provided it is still live and not dedicated to another buffer. </p> </dd> <dt><code>mode</code></dt> <dd> +<p>The value is either a major mode or a list of major modes. <code>display-buffer-reuse-mode-window</code> may reuse a window whenever the value specified by this entry matches the major mode of that window’s buffer. Other action functions ignore such entries. </p> </dd> <dt><code>frame-predicate</code></dt> <dd> +<p>The value must be a function taking one argument (a frame), supposed to return non-<code>nil</code> if that frame is a candidate for displaying the buffer. This entry is used by <code>display-buffer-use-some-frame</code>. </p> </dd> <dt><code>reusable-frames</code></dt> <dd> +<p>The value specifies the set of frames to search for a window that can be reused because it already displays the buffer. It can be set as follows: </p> <ul> <li> <code>nil</code> means consider only windows on the selected frame. (Actually, the last frame used that is not a minibuffer-only frame.) </li> +<li> <code>t</code> means consider windows on all frames. </li> +<li> <code>visible</code> means consider windows on all visible frames. </li> +<li> 0 means consider windows on all visible or iconified frames. </li> +<li> A frame means consider windows on that frame only. </li> +</ul> <p>Note that the meaning of <code>nil</code> differs slightly from that of the <var>all-frames</var> argument to <code>next-window</code> (see <a href="cyclic-window-ordering">Cyclic Window Ordering</a>). </p> <p>A major client of this is <code>display-buffer-reuse-window</code>, but all other action functions that try to reuse a window are affected as well. <code>display-buffer-in-previous-window</code> consults it when searching for a window that previously displayed the buffer on another frame. </p> </dd> <dt><code>inhibit-switch-frame</code></dt> <dd> +<p>A non-<code>nil</code> value prevents another frame from being raised or selected, if the window chosen by <code>display-buffer</code> is displayed there. Primarily affected by this are <code>display-buffer-use-some-frame</code> and <code>display-buffer-reuse-window</code>. Ideally, <code>display-buffer-pop-up-frame</code> should be affected as well, but there is no guarantee that the window manager will comply. </p> </dd> <dt><code>window-parameters</code></dt> <dd> +<p>The value specifies an alist of window parameters to give the chosen window. All action functions that choose a window should process this entry. </p> </dd> <dt><code>window-min-height</code></dt> <dd> +<p>The value specifies a minimum height of the window used, in lines. If a window is not or cannot be made as high as specified by this entry, the window is not considered for use. The only client of this entry is presently <code>display-buffer-below-selected</code>. </p> <p>Note that providing such an entry alone does not necessarily make the window as tall as specified by its value. To actually resize an existing window or make a new window as tall as specified by that value, a <code>window-height</code> entry specifying that value should be provided as well. Such a <code>window-height</code> entry can, however, specify a completely different value or ask the window height to be fit to that of its buffer in which case the <code>window-min-height</code> entry provides the guaranteed minimum height of the window used. </p> </dd> <dt><code>window-height</code></dt> <dd> +<p>The value specifies whether and how to adjust the height of the chosen window and can be one of the following: </p> <ul> <li> <code>nil</code> means to leave the height of the chosen window alone. </li> +<li> An integer number specifies the desired total height of the chosen window in lines. </li> +<li> A floating-point number specifies the fraction of the chosen window’s desired total height with respect to the total height of its frame’s root window. </li> +<li> If the value specifies a function, that function is called with one argument—the chosen window. The function is supposed to adjust the height of the window; its return value is ignored. Suitable functions are <code>fit-window-to-buffer</code> and <code>shrink-window-if-larger-than-buffer</code>, see <a href="resizing-windows">Resizing Windows</a>. </li> +</ul> <p>By convention, the height of the chosen window is adjusted only if the window is part of a vertical combination (see <a href="windows-and-frames">Windows and Frames</a>) to avoid changing the height of other, unrelated windows. Also, this entry should be processed only under certain conditions which are specified right below this list. </p> </dd> <dt><code>window-width</code></dt> <dd> +<p>This entry is similar to the <code>window-height</code> entry described before, but used to adjust the chosen window’s width instead. The value can be one of the following: </p> <ul> <li> <code>nil</code> means to leave the width of the chosen window alone. </li> +<li> An integer specifies the desired total width of the chosen window in columns. </li> +<li> A floating-point number specifies the fraction of the chosen window’s desired total width with respect to the total width of the frame’s root window. </li> +<li> If the value specifies a function, that function is called with one argument—the chosen window. The function is supposed to adjust the width of the window; its return value is ignored. </li> +</ul> <p>By convention, the width of the chosen window is adjusted only if the window is part of a horizontal combination (see <a href="windows-and-frames">Windows and Frames</a>) to avoid changing the width of other, unrelated windows. Also, this entry should be processed under only certain conditions which are specified right below this list. </p> </dd> <dt><code>dedicated</code></dt> <dd> +<p>If non-<code>nil</code>, such an entry tells <code>display-buffer</code> to mark any window it creates as dedicated to its buffer (see <a href="dedicated-windows">Dedicated Windows</a>). It does that by calling <code>set-window-dedicated-p</code> with the chosen window as first argument and the entry’s value as second. Side windows are by default dedicated with the value <code>side</code> ((see <a href="side-window-options-and-functions">Side Window Options and Functions</a>). </p> </dd> <dt><code>preserve-size</code></dt> <dd> +<p>If non-<code>nil</code> such an entry tells Emacs to preserve the size of the window chosen (see <a href="preserving-window-sizes">Preserving Window Sizes</a>). The value should be either <code>(t . nil)</code> to preserve the width of the window, <code>(nil . t)</code> to preserve its height or <code>(t . t)</code> to preserve both, its width and its height. This entry should be processed only under certain conditions which are specified right after this list. </p> </dd> <dt><code>pop-up-frame-parameters</code></dt> <dd> +<p>The value specifies an alist of frame parameters to give a new frame, if one is created. <code>display-buffer-pop-up-frame</code> is its one and only addressee. </p> </dd> <dt><code>parent-frame</code></dt> <dd> +<p>The value specifies the parent frame to be used when the buffer is displayed on a child frame. This entry is used only by <code>display-buffer-in-child-frame</code>. </p> </dd> <dt><code>child-frame-parameters</code></dt> <dd> +<p>The value specifies an alist of frame parameters to use when the buffer is displayed on a child frame. This entry is used only by <code>display-buffer-in-child-frame</code>. </p> </dd> <dt><code>side</code></dt> <dd> +<p>The value denotes the side of the frame or window where a new window displaying the buffer shall be created. This entry is used by <code>display-buffer-in-side-window</code> to indicate the side of the frame where a new side window shall be placed (see <a href="displaying-buffers-in-side-windows">Displaying Buffers in Side Windows</a>). It is also used by <code>display-buffer-in-atom-window</code> to indicate the side of an existing window where the new window shall be located (see <a href="atomic-windows">Atomic Windows</a>). </p> </dd> <dt><code>slot</code></dt> <dd> +<p>If non-<code>nil</code>, the value specifies the slot of the side window supposed to display the buffer. This entry is used only by <code>display-buffer-in-side-window</code>. </p> </dd> <dt><code>direction</code></dt> <dd> +<p>The value specifies a direction which, together with a <code>window</code> entry, allows <code>display-buffer-in-direction</code> to determine the location of the window to display the buffer. </p> </dd> <dt><code>window</code></dt> <dd> +<p>The value specifies a window that is in some way related to the window chosen by <code>display-buffer</code>. This entry is currently used by <code>display-buffer-in-atom-window</code> to indicate the window on whose side the new window shall be created. It is also used by <code>display-buffer-in-direction</code> to specify the reference window on whose side the resulting window shall appear. </p> </dd> <dt><code>allow-no-window</code></dt> <dd> +<p>If the value is non-<code>nil</code>, <code>display-buffer</code> does not necessarily have to display the buffer and the caller is prepared to accept that. This entry is not intended for user customizations, since there is no guarantee that an arbitrary caller of <code>display-buffer</code> will be able to handle the case that no window will display the buffer. <code>display-buffer-no-window</code> is the only action function that cares about this entry. </p> </dd> <dt><code>body-function</code></dt> <dd><p>The value must be a function taking one argument (a displayed window). This function can be used to fill the displayed window’s body with some contents that might depend on dimensions of the displayed window. It is called <em>after</em> the buffer is displayed, and <em>before</em> the entries <code>window-height</code>, <code>window-width</code> and <code>preserve-size</code> are applied that could resize the window to fit it to the inserted contents. </p></dd> </dl> <p>By convention, the entries <code>window-height</code>, <code>window-width</code> and <code>preserve-size</code> are applied after the chosen window’s buffer has been set up and if and only if that window never showed another buffer before. More precisely, the latter means that the window must have been either created by the current <code>display-buffer</code> call or the window was created earlier by <code>display-buffer</code> to show the buffer and never was used to show another buffer until it was reused by the current invocation of <code>display-buffer</code>. </p><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/Buffer-Display-Action-Alists.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Buffer-Display-Action-Alists.html</a> + </p> +</div> |