diff options
Diffstat (limited to 'devdocs/elisp/buffer-display-action-functions.html')
| -rw-r--r-- | devdocs/elisp/buffer-display-action-functions.html | 56 |
1 files changed, 56 insertions, 0 deletions
diff --git a/devdocs/elisp/buffer-display-action-functions.html b/devdocs/elisp/buffer-display-action-functions.html new file mode 100644 index 00000000..097db7e4 --- /dev/null +++ b/devdocs/elisp/buffer-display-action-functions.html @@ -0,0 +1,56 @@ + <h4 class="subsection">Action Functions for Buffer Display</h4> <p>An <em>action function</em> is a function <code>display-buffer</code> calls for choosing a window to display a buffer. Action functions take two arguments: <var>buffer</var>, the buffer to display, and <var>alist</var>, an action alist (see <a href="buffer-display-action-alists">Buffer Display Action Alists</a>). They are supposed to return a window displaying <var>buffer</var> if they succeed and <code>nil</code> if they fail. </p> <p>The following basic action functions are defined in Emacs. </p> <dl> <dt id="display-buffer-same-window">Function: <strong>display-buffer-same-window</strong> <em>buffer alist</em> +</dt> <dd><p>This function tries to display <var>buffer</var> in the selected window. It fails if the selected window is a minibuffer window or is dedicated to another buffer (see <a href="dedicated-windows">Dedicated Windows</a>). It also fails if <var>alist</var> has a non-<code>nil</code> <code>inhibit-same-window</code> entry. </p></dd> +</dl> <dl> <dt id="display-buffer-reuse-window">Function: <strong>display-buffer-reuse-window</strong> <em>buffer alist</em> +</dt> <dd> +<p>This function tries to display <var>buffer</var> by finding a window that is already displaying it. Windows on the selected frame are preferred to windows on other frames. </p> <p>If <var>alist</var> has a non-<code>nil</code> <code>inhibit-same-window</code> entry, the selected window is not eligible for reuse. The set of frames to search for a window already displaying <var>buffer</var> can be specified with the help of the <code>reusable-frames</code> action alist entry. If <var>alist</var> contains no <code>reusable-frames</code> entry, this function searches just the selected frame. </p> <p>If this function chooses a window on another frame, it makes that frame visible and, unless <var>alist</var> contains an <code>inhibit-switch-frame</code> entry, raises that frame if necessary. </p> +</dd> +</dl> <dl> <dt id="display-buffer-reuse-mode-window">Function: <strong>display-buffer-reuse-mode-window</strong> <em>buffer alist</em> +</dt> <dd> +<p>This function tries to display <var>buffer</var> by finding a window that is displaying a buffer in a given mode. </p> <p>If <var>alist</var> contains a <code>mode</code> entry, its value specifies a major mode (a symbol) or a list of major modes. If <var>alist</var> contains no <code>mode</code> entry, the current major mode of <var>buffer</var> is used instead. A window is a candidate if it displays a buffer whose mode derives from one of the modes specified thusly. </p> <p>The behavior is also controlled by <var>alist</var> entries for <code>inhibit-same-window</code>, <code>reusable-frames</code> and <code>inhibit-switch-frame</code>, like <code>display-buffer-reuse-window</code> does. </p> +</dd> +</dl> <dl> <dt id="display-buffer-pop-up-window">Function: <strong>display-buffer-pop-up-window</strong> <em>buffer alist</em> +</dt> <dd> +<p>This function tries to display <var>buffer</var> by splitting the largest or least recently-used window (usually located on the selected frame). It actually performs the split by calling the function specified by <code>split-window-preferred-function</code> (see <a href="choosing-window-options">Choosing Window Options</a>). </p> <p>The size of the new window can be adjusted by supplying <code>window-height</code> and <code>window-width</code> entries in <var>alist</var>. If <var>alist</var> contains a <code>preserve-size</code> entry, Emacs will also try to preserve the size of the new window during future resize operations (see <a href="preserving-window-sizes">Preserving Window Sizes</a>). </p> <p>This function fails if no window can be split. More often than not, this happens because no window is large enough to allow splitting. Setting <code>split-height-threshold</code> or <code>split-width-threshold</code> to lower values may help in this regard. Splitting also fails when the selected frame has an <code>unsplittable</code> frame parameter; see <a href="buffer-parameters">Buffer Parameters</a>. </p> +</dd> +</dl> <dl> <dt id="display-buffer-in-previous-window">Function: <strong>display-buffer-in-previous-window</strong> <em>buffer alist</em> +</dt> <dd> +<p>This function tries to display <var>buffer</var> in a window where it was displayed previously. </p> <p>If <var>alist</var> contains a non-<code>nil</code> <code>inhibit-same-window</code> entry, the selected window is not eligible for use. A dedicated window is usable only if it already shows <var>buffer</var>. If <var>alist</var> contains a <code>previous-window</code> entry, the window specified by that entry is usable even if it never showed <var>buffer</var> before. </p> <p>If <var>alist</var> contains a <code>reusable-frames</code> entry (see <a href="buffer-display-action-alists">Buffer Display Action Alists</a>), its value determines which frames to search for a suitable window. If <var>alist</var> contains no <code>reusable-frames</code> entry, this function searches just the selected frame if <code>display-buffer-reuse-frames</code> and <code>pop-up-frames</code> are both <code>nil</code>; it searches all frames on the current terminal if either of those variables is non-<code>nil</code>. </p> <p>If more than one window qualifies as usable according to these rules, this function makes a choice in the following order of preference: </p> <ul> <li> The window specified by any <code>previous-window</code> <var>alist</var> entry, provided it is not the selected window. </li> +<li> A window that showed <var>buffer</var> before, provided it is not the selected window. </li> +<li> The selected window if it is either specified by a <code>previous-window</code> <var>alist</var> entry or showed <var>buffer</var> before. </li> +</ul> </dd> +</dl> <dl> <dt id="display-buffer-use-some-window">Function: <strong>display-buffer-use-some-window</strong> <em>buffer alist</em> +</dt> <dd><p>This function tries to display <var>buffer</var> by choosing an existing window and displaying the buffer in that window. It can fail if all windows are dedicated to other buffers (see <a href="dedicated-windows">Dedicated Windows</a>). </p></dd> +</dl> <dl> <dt id="display-buffer-use-least-recent-window">Function: <strong>display-buffer-use-least-recent-window</strong> <em>buffer alist</em> +</dt> <dd><p>This function is like <code>display-buffer-use-some-window</code>, but will not reuse the current window, and will use the least recently switched-to window. </p></dd> +</dl> <dl> <dt id="display-buffer-in-direction">Function: <strong>display-buffer-in-direction</strong> <em>buffer alist</em> +</dt> <dd> +<p>This function tries to display <var>buffer</var> at a location specified by <var>alist</var>. For this purpose, <var>alist</var> should contain a <code>direction</code> entry whose value is one of <code>left</code>, <code>above</code> (or <code>up</code>), <code>right</code> and <code>below</code> (or <code>down</code>). Other values are usually interpreted as <code>below</code>. </p> <p>If <var>alist</var> also contains a <code>window</code> entry, its value specifies a reference window. That value can be a special symbol like <code>main</code> which stands for the selected frame’s main window (see <a href="side-window-options-and-functions">Side Window Options and Functions</a>) or <code>root</code> standing for the selected frame’s root window (see <a href="windows-and-frames">Windows and Frames</a>). It can also specify an arbitrary valid window. Any other value (or omitting the <code>window</code> entry entirely) means to use the selected window as reference window. </p> <p>This function first tries to reuse a window in the specified direction that already shows <var>buffer</var>. If no such window exists, it tries to split the reference window in order to produce a new window in the specified direction. If this fails as well, it will try to display <var>buffer</var> in an existing window in the specified direction. In either case, the window chosen will appear on the side of the reference window specified by the <code>direction</code> entry, sharing at least one edge with the reference window. </p> <p>If the reference window is live, the edge the chosen window will share with it is always the opposite of the one specified by the <code>direction</code> entry. For example, if the value of the <code>direction</code> entry is <code>left</code>, the chosen window’s right edge coordinate (see <a href="coordinates-and-windows">Coordinates and Windows</a>) will equal the reference window’s left edge coordinate. </p> <p>If the reference window is internal, a reused window must share with it the edge specified by the <code>direction</code> entry. Hence if, for example, the reference window is the frame’s root window and the value of the <code>direction</code> entry is <code>left</code>, a reused window must be on the left of the frame. This means that the left edge coordinate of the chosen window and that of the reference window are the same. </p> <p>A new window, however, will be created by splitting the reference window such that the chosen window will share the opposite edge with the reference window. In our example, a new root window would be created with a new live window and the reference window as its children. The chosen window’s right edge coordinate would then equal the left edge coordinate of the reference window. Its left edge coordinate would equal the left edge coordinate of the frame’s new root window. </p> <p>Four special values for <code>direction</code> entries allow to implicitly specify the selected frame’s main window as the reference window: <code>leftmost</code>, <code>top</code>, <code>rightmost</code> and <code>bottom</code>. This means that instead of, for example, <code>(direction . left) (window . main)</code> one can just specify <code>(direction . leftmost)</code>. An existing <code>window</code> <var>alist</var> entry is ignored in such cases. </p> +</dd> +</dl> <dl> <dt id="display-buffer-below-selected">Function: <strong>display-buffer-below-selected</strong> <em>buffer alist</em> +</dt> <dd> +<p>This function tries to display <var>buffer</var> in a window below the selected window. If there is a window below the selected one and that window already displays <var>buffer</var>, it reuses that window. </p> <p>If there is no such window, this function tries to create a new window by splitting the selected one, and displays <var>buffer</var> there. It will also try to adjust that window’s size provided <var>alist</var> contains a suitable <code>window-height</code> or <code>window-width</code> entry, see above. </p> <p>If splitting the selected window fails and there is a non-dedicated window below the selected one showing some other buffer, this function tries to use that window for showing <var>buffer</var>. </p> <p>If <var>alist</var> contains a <code>window-min-height</code> entry, this function ensures that the window used is or can become at least as high as specified by that entry’s value. Note that this is only a guarantee. In order to actually resize the window used, <var>alist</var> must also provide an appropriate <code>window-height</code> entry. </p> +</dd> +</dl> <dl> <dt id="display-buffer-at-bottom">Function: <strong>display-buffer-at-bottom</strong> <em>buffer alist</em> +</dt> <dd> +<p>This function tries to display <var>buffer</var> in a window at the bottom of the selected frame. </p> <p>This either tries to split the window at the bottom of the frame or the frame’s root window, or to reuse an existing window at the bottom of the selected frame. </p> +</dd> +</dl> <dl> <dt id="display-buffer-pop-up-frame">Function: <strong>display-buffer-pop-up-frame</strong> <em>buffer alist</em> +</dt> <dd><p>This function creates a new frame, and displays the buffer in that frame’s window. It actually performs the frame creation by calling the function specified in <code>pop-up-frame-function</code> (see <a href="choosing-window-options">Choosing Window Options</a>). If <var>alist</var> contains a <code>pop-up-frame-parameters</code> entry, the associated value is added to the newly created frame’s parameters. </p></dd> +</dl> <dl> <dt id="display-buffer-in-child-frame">Function: <strong>display-buffer-in-child-frame</strong> <em>buffer alist</em> +</dt> <dd> +<p>This function tries to display <var>buffer</var> in a child frame (see <a href="child-frames">Child Frames</a>) of the selected frame, either reusing an existing child frame or by making a new one. If <var>alist</var> has a non-<code>nil</code> <code>child-frame-parameters</code> entry, the corresponding value is an alist of frame parameters to give the new frame. A <code>parent-frame</code> parameter specifying the selected frame is provided by default. If the child frame should become the child of another frame, a corresponding entry must be added to <var>alist</var>. </p> <p>The appearance of child frames is largely dependent on the parameters provided via <var>alist</var>. It is advisable to use at least ratios to specify the size (see <a href="size-parameters">Size Parameters</a>) and the position (see <a href="position-parameters">Position Parameters</a>) of the child frame, and to add a <code>keep-ratio</code> parameter (see <a href="frame-interaction-parameters">Frame Interaction Parameters</a>), in order to make sure that the child frame remains visible. For other parameters that should be considered see <a href="child-frames">Child Frames</a>. </p> +</dd> +</dl> <dl> <dt id="display-buffer-use-some-frame">Function: <strong>display-buffer-use-some-frame</strong> <em>buffer alist</em> +</dt> <dd> +<p>This function tries to display <var>buffer</var> by finding a frame that meets a predicate (by default any frame other than the selected frame). </p> <p>If this function chooses a window on another frame, it makes that frame visible and, unless <var>alist</var> contains an <code>inhibit-switch-frame</code> entry, raises that frame if necessary. </p> <p>If <var>alist</var> has a non-<code>nil</code> <code>frame-predicate</code> entry, its value is a function taking one argument (a frame), returning non-<code>nil</code> if the frame is a candidate; this function replaces the default predicate. </p> <p>If <var>alist</var> has a non-<code>nil</code> <code>inhibit-same-window</code> entry, the selected window is not used; thus if the selected frame has a single window, it is not used. </p> +</dd> +</dl> <dl> <dt id="display-buffer-no-window">Function: <strong>display-buffer-no-window</strong> <em>buffer alist</em> +</dt> <dd> +<p>If <var>alist</var> has a non-<code>nil</code> <code>allow-no-window</code> entry, then this function does not display <var>buffer</var> and returns the symbol <code>fail</code>. This constitutes the only exception to the convention that an action function returns either <code>nil</code> or a window showing <var>buffer</var>. If <var>alist</var> has no such <code>allow-no-window</code> entry, this function returns <code>nil</code>. </p> <p>If this function returns <code>fail</code>, <code>display-buffer</code> will skip the execution of any further display actions and return <code>nil</code> immediately. If this function returns <code>nil</code>, <code>display-buffer</code> will continue with the next display action, if any. </p> <p>It is assumed that when a caller of <code>display-buffer</code> specifies a non-<code>nil</code> <code>allow-no-window</code> entry, it is also able to handle a <code>nil</code> return value. </p> +</dd> +</dl> <p>Two other action functions are described in their proper sections—<code>display-buffer-in-side-window</code> (see <a href="displaying-buffers-in-side-windows">Displaying Buffers in Side Windows</a>) and <code>display-buffer-in-atom-window</code> (see <a href="atomic-windows">Atomic Windows</a>). </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-Functions.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Buffer-Display-Action-Functions.html</a> + </p> +</div> |