diff options
Diffstat (limited to 'devdocs/elisp/splitting-windows.html')
| -rw-r--r-- | devdocs/elisp/splitting-windows.html | 46 |
1 files changed, 46 insertions, 0 deletions
diff --git a/devdocs/elisp/splitting-windows.html b/devdocs/elisp/splitting-windows.html new file mode 100644 index 00000000..f67d98e5 --- /dev/null +++ b/devdocs/elisp/splitting-windows.html @@ -0,0 +1,46 @@ + <h3 class="section">Splitting Windows</h3> <p>This section describes functions for creating a new window by <em>splitting</em> an existing one. Note that some windows are special in the sense that these functions may fail to split them as described here. Examples of such windows are side windows (see <a href="side-windows">Side Windows</a>) and atomic windows (see <a href="atomic-windows">Atomic Windows</a>). </p> <dl> <dt id="split-window">Function: <strong>split-window</strong> <em>&optional window size side pixelwise</em> +</dt> <dd> +<p>This function creates a new live window next to the window <var>window</var>. If <var>window</var> is omitted or <code>nil</code>, it defaults to the selected window. That window is split, and reduced in size. The space is taken up by the new window, which is returned. </p> <p>The optional second argument <var>size</var> determines the sizes of <var>window</var> and/or the new window. If it is omitted or <code>nil</code>, both windows are given equal sizes; if there is an odd line, it is allocated to the new window. If <var>size</var> is a positive number, <var>window</var> is given <var>size</var> lines (or columns, depending on the value of <var>side</var>). If <var>size</var> is a negative number, the new window is given -<var>size</var> lines (or columns). </p> <p>If <var>size</var> is <code>nil</code>, this function obeys the variables <code>window-min-height</code> and <code>window-min-width</code> (see <a href="window-sizes">Window Sizes</a>). Thus, it signals an error if splitting would result in making a window smaller than those variables specify. However, a non-<code>nil</code> value for <var>size</var> causes those variables to be ignored; in that case, the smallest allowable window is considered to be one that has space for a text that is one line tall and/or two columns wide. </p> <p>Hence, if <var>size</var> is specified, it’s the caller’s responsibility to check whether the emanating windows are large enough to encompass all of their decorations like a mode line or a scroll bar. The function <code>window-min-size</code> (see <a href="window-sizes">Window Sizes</a>) can be used to determine the minimum requirements of <var>window</var> in this regard. Since the new window usually inherits areas like the mode line or the scroll bar from <var>window</var>, that function is also a good guess for the minimum size of the new window. The caller should specify a smaller size only if it correspondingly removes an inherited area before the next redisplay. </p> <p>The optional third argument <var>side</var> determines the position of the new window relative to <var>window</var>. If it is <code>nil</code> or <code>below</code>, the new window is placed below <var>window</var>. If it is <code>above</code>, the new window is placed above <var>window</var>. In both these cases, <var>size</var> specifies a total window height, in lines. </p> <p>If <var>side</var> is <code>t</code> or <code>right</code>, the new window is placed on the right of <var>window</var>. If <var>side</var> is <code>left</code>, the new window is placed on the left of <var>window</var>. In both these cases, <var>size</var> specifies a total window width, in columns. </p> <p>The optional fourth argument <var>pixelwise</var>, if non-<code>nil</code>, means to interpret <var>size</var> in units of pixels, instead of lines and columns. </p> <p>If <var>window</var> is a live window, the new window inherits various properties from it, including margins and scroll bars. If <var>window</var> is an internal window, the new window inherits the properties of the window selected within <var>window</var>’s frame. </p> <p>The behavior of this function may be altered by the window parameters of <var>window</var>, so long as the variable <code>ignore-window-parameters</code> is <code>nil</code>. If the value of the <code>split-window</code> window parameter is <code>t</code>, this function ignores all other window parameters. Otherwise, if the value of the <code>split-window</code> window parameter is a function, that function is called with the arguments <var>window</var>, <var>size</var>, and <var>side</var>, in lieu of the usual action of <code>split-window</code>. Otherwise, this function obeys the <code>window-atom</code> or <code>window-side</code> window parameter, if any. See <a href="window-parameters">Window Parameters</a>. </p> +</dd> +</dl> <p>As an example, here is a sequence of <code>split-window</code> calls that yields the window configuration discussed in <a href="windows-and-frames">Windows and Frames</a>. This example demonstrates splitting a live window as well as splitting an internal window. We begin with a frame containing a single window (a live root window), which we denote by <var>W4</var>. Calling <code>(split-window W4)</code> yields this window configuration: </p> <div class="example"> <pre class="example"> ______________________________________ + | ____________________________________ | + || || + || || + || || + ||_________________W4_________________|| + | ____________________________________ | + || || + || || + || || + ||_________________W5_________________|| + |__________________W3__________________| + +</pre> +</div> <p>The <code>split-window</code> call has created a new live window, denoted by <var>W5</var>. It has also created a new internal window, denoted by <var>W3</var>, which becomes the root window and the parent of both <var>W4</var> and <var>W5</var>. </p> <p>Next, we call <code>(split-window W3 nil 'left)</code>, passing the internal window <var>W3</var> as the argument. The result: </p> <div class="example"> <pre class="example"> ______________________________________ + | ______ ____________________________ | + || || __________________________ || + || ||| ||| + || ||| ||| + || ||| ||| + || |||____________W4____________||| + || || __________________________ || + || ||| ||| + || ||| ||| + || |||____________W5____________||| + ||__W2__||_____________W3_____________ | + |__________________W1__________________| +</pre> +</div> <p>A new live window <var>W2</var> is created, to the left of the internal window <var>W3</var>. A new internal window <var>W1</var> is created, becoming the new root window. </p> <p>For interactive use, Emacs provides two commands which always split the selected window. These call <code>split-window</code> internally. </p> <dl> <dt id="split-window-right">Command: <strong>split-window-right</strong> <em>&optional size</em> +</dt> <dd><p>This function splits the selected window into two side-by-side windows, putting the selected window on the left. If <var>size</var> is positive, the left window gets <var>size</var> columns; if <var>size</var> is negative, the right window gets -<var>size</var> columns. </p></dd> +</dl> <dl> <dt id="split-window-below">Command: <strong>split-window-below</strong> <em>&optional size</em> +</dt> <dd><p>This function splits the selected window into two windows, one above the other, leaving the upper window selected. If <var>size</var> is positive, the upper window gets <var>size</var> lines; if <var>size</var> is negative, the lower window gets -<var>size</var> lines. </p></dd> +</dl> <dl> <dt id="split-window-keep-point">User Option: <strong>split-window-keep-point</strong> +</dt> <dd> +<p>If the value of this variable is non-<code>nil</code> (the default), <code>split-window-below</code> behaves as described above. </p> <p>If it is <code>nil</code>, <code>split-window-below</code> adjusts point in each of the two windows to minimize redisplay. (This is useful on slow terminals.) It selects whichever window contains the screen line that point was previously on. Note that this only affects <code>split-window-below</code>, not the lower-level <code>split-window</code> function. </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/Splitting-Windows.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Splitting-Windows.html</a> + </p> +</div> |