diff options
Diffstat (limited to 'devdocs/elisp/recombining-windows.html')
| -rw-r--r-- | devdocs/elisp/recombining-windows.html | 168 |
1 files changed, 168 insertions, 0 deletions
diff --git a/devdocs/elisp/recombining-windows.html b/devdocs/elisp/recombining-windows.html new file mode 100644 index 00000000..cb55a477 --- /dev/null +++ b/devdocs/elisp/recombining-windows.html @@ -0,0 +1,168 @@ + <h3 class="section">Recombining Windows</h3> <p>When deleting the last sibling of a window <var>W</var>, its parent window is deleted too, with <var>W</var> replacing it in the window tree. This means that <var>W</var> must be recombined with its parent’s siblings to form a new window combination (see <a href="windows-and-frames">Windows and Frames</a>). In some occasions, deleting a live window may even entail the deletion of two internal windows. </p> <div class="example"> <pre class="example"> ______________________________________ + | ______ ____________________________ | + || || __________________________ || + || ||| ___________ ___________ ||| + || |||| || |||| + || ||||____W6_____||_____W7____|||| + || |||____________W4____________||| + || || __________________________ || + || ||| ||| + || ||| ||| + || |||____________W5____________||| + ||__W2__||_____________W3_____________ | + |__________________W1__________________| + +</pre> +</div> <p>Deleting <var>W5</var> in this configuration normally causes the deletion of <var>W3</var> and <var>W4</var>. The remaining live windows <var>W2</var>, <var>W6</var> and <var>W7</var> are recombined to form a new horizontal combination with parent <var>W1</var>. </p> <p>Sometimes, however, it makes sense to not delete a parent window like <var>W4</var>. In particular, a parent window should not be removed when it was used to preserve a combination embedded in a combination of the same type. Such embeddings make sense to assure that when you split a window and subsequently delete the new window, Emacs reestablishes the layout of the associated frame as it existed before the splitting. </p> <p>Consider a scenario starting with two live windows <var>W2</var> and <var>W3</var> and their parent <var>W1</var>. </p> <div class="example"> <pre class="example"> ______________________________________ + | ____________________________________ | + || || + || || + || || + || || + || || + || || + ||_________________W2_________________|| + | ____________________________________ | + || || + || || + ||_________________W3_________________|| + |__________________W1__________________| + +</pre> +</div> <p>Split <var>W2</var> to make a new window <var>W4</var> as follows. </p> <div class="example"> <pre class="example"> ______________________________________ + | ____________________________________ | + || || + || || + ||_________________W2_________________|| + | ____________________________________ | + || || + || || + ||_________________W4_________________|| + | ____________________________________ | + || || + || || + ||_________________W3_________________|| + |__________________W1__________________| + +</pre> +</div> <p>Now, when enlarging a window vertically, Emacs tries to obtain the corresponding space from its lower sibling, provided such a window exists. In our scenario, enlarging <var>W4</var> will steal space from <var>W3</var>. </p> <div class="example"> <pre class="example"> ______________________________________ + | ____________________________________ | + || || + || || + ||_________________W2_________________|| + | ____________________________________ | + || || + || || + || || + || || + ||_________________W4_________________|| + | ____________________________________ | + ||_________________W3_________________|| + |__________________W1__________________| + +</pre> +</div> <p>Deleting <var>W4</var> will now give its entire space to <var>W2</var>, including the space earlier stolen from <var>W3</var>. </p> <div class="example"> <pre class="example"> ______________________________________ + | ____________________________________ | + || || + || || + || || + || || + || || + || || + || || + || || + ||_________________W2_________________|| + | ____________________________________ | + ||_________________W3_________________|| + |__________________W1__________________| + +</pre> +</div> <p>This can be counterintuitive, in particular if <var>W4</var> were used for displaying a buffer only temporarily (see <a href="temporary-displays">Temporary Displays</a>), and you want to continue working with the initial layout. </p> <p>The behavior can be fixed by making a new parent window when splitting <var>W2</var>. The variable described next allows that to be done. </p> <dl> <dt id="window-combination-limit">User Option: <strong>window-combination-limit</strong> +</dt> <dd> +<p>This variable controls whether splitting a window shall make a new parent window. The following values are recognized: </p> <dl compact> <dt><code>nil</code></dt> <dd> +<p>This means that the new live window is allowed to share the existing parent window, if one exists, provided the split occurs in the same direction as the existing window combination (otherwise, a new internal window is created anyway). </p> </dd> <dt><code>window-size</code></dt> <dd> +<p>This means that <code>display-buffer</code> makes a new parent window when it splits a window and is passed a <code>window-height</code> or <code>window-width</code> entry in the <var>alist</var> argument (see <a href="buffer-display-action-functions">Buffer Display Action Functions</a>). Otherwise, window splitting behaves as for a value of <code>nil</code>. </p> </dd> <dt><code>temp-buffer-resize</code></dt> <dd> +<p>In this case <code>with-temp-buffer-window</code> makes a new parent window when it splits a window and <code>temp-buffer-resize-mode</code> is enabled (see <a href="temporary-displays">Temporary Displays</a>). Otherwise, window splitting behaves as for <code>nil</code>. </p> </dd> <dt><code>temp-buffer</code></dt> <dd> +<p>In this case <code>with-temp-buffer-window</code> always makes a new parent window when it splits an existing window (see <a href="temporary-displays">Temporary Displays</a>). Otherwise, window splitting behaves as for <code>nil</code>. </p> </dd> <dt><code>display-buffer</code></dt> <dd> +<p>This means that when <code>display-buffer</code> (see <a href="choosing-window">Choosing Window</a>) splits a window it always makes a new parent window. Otherwise, window splitting behaves as for <code>nil</code>. </p> </dd> <dt><code>t</code></dt> <dd><p>This means that splitting a window always creates a new parent window. Thus, if the value of this variable is at all times <code>t</code>, then at all times every window tree is a binary tree (a tree where each window except the root window has exactly one sibling). </p></dd> </dl> <p>The default is <code>window-size</code>. Other values are reserved for future use. </p> <p>If, as a consequence of this variable’s setting, <code>split-window</code> makes a new parent window, it also calls <code>set-window-combination-limit</code> (see below) on the newly-created internal window. This affects how the window tree is rearranged when the child windows are deleted (see below). </p> +</dd> +</dl> <p>If <code>window-combination-limit</code> is <code>t</code>, splitting <var>W2</var> in the initial configuration of our scenario would have produced this: </p> <div class="example"> <pre class="example"> ______________________________________ + | ____________________________________ | + || __________________________________ || + ||| ||| + |||________________W2________________||| + || __________________________________ || + ||| ||| + |||________________W4________________||| + ||_________________W5_________________|| + | ____________________________________ | + || || + || || + ||_________________W3_________________|| + |__________________W1__________________| + +</pre> +</div> <p>A new internal window <var>W5</var> has been created; its children are <var>W2</var> and the new live window <var>W4</var>. Now, <var>W2</var> is the only sibling of <var>W4</var>, so enlarging <var>W4</var> will try to shrink <var>W2</var>, leaving <var>W3</var> unaffected. Observe that <var>W5</var> represents a vertical combination of two windows embedded in the vertical combination <var>W1</var>. </p> <dl> <dt id="set-window-combination-limit">Function: <strong>set-window-combination-limit</strong> <em>window limit</em> +</dt> <dd><p>This function sets the <em>combination limit</em> of the window <var>window</var> to <var>limit</var>. This value can be retrieved via the function <code>window-combination-limit</code>. See below for its effects; note that it is only meaningful for internal windows. The <code>split-window</code> function automatically calls this function, passing it <code>t</code> as <var>limit</var>, provided the value of the variable <code>window-combination-limit</code> is <code>t</code> when it is called. </p></dd> +</dl> <dl> <dt id="window-combination-limit">Function: <strong>window-combination-limit</strong> <em>window</em> +</dt> <dd> +<p>This function returns the combination limit for <var>window</var>. </p> <p>The combination limit is meaningful only for an internal window. If it is <code>nil</code>, then Emacs is allowed to automatically delete <var>window</var>, in response to a window deletion, in order to group the child windows of <var>window</var> with its sibling windows to form a new window combination. If the combination limit is <code>t</code>, the child windows of <var>window</var> are never automatically recombined with its siblings. </p> <p>If, in the configuration shown at the beginning of this section, the combination limit of <var>W4</var> (the parent window of <var>W6</var> and <var>W7</var>) is <code>t</code>, deleting <var>W5</var> will not implicitly delete <var>W4</var> too. </p> +</dd> +</dl> <p>Alternatively, the problems sketched above can be avoided by always resizing all windows in the same combination whenever one of its windows is split or deleted. This also permits splitting windows that would be otherwise too small for such an operation. </p> <dl> <dt id="window-combination-resize">User Option: <strong>window-combination-resize</strong> +</dt> <dd> +<p>If this variable is <code>nil</code>, <code>split-window</code> can only split a window (denoted by <var>window</var>) if <var>window</var>’s screen area is large enough to accommodate both itself and the new window. </p> <p>If this variable is <code>t</code>, <code>split-window</code> tries to resize all windows that are part of the same combination as <var>window</var>, in order to accommodate the new window. In particular, this may allow <code>split-window</code> to succeed even if <var>window</var> is a fixed-size window or too small to ordinarily split. Furthermore, subsequently resizing or deleting <var>window</var> may resize all other windows in its combination. </p> <p>The default is <code>nil</code>. Other values are reserved for future use. A specific split operation may ignore the value of this variable if it is affected by a non-<code>nil</code> value of <code>window-combination-limit</code>. </p> +</dd> +</dl> <p>To illustrate the effect of <code>window-combination-resize</code>, consider the following frame layout. </p> <div class="example"> <pre class="example"> ______________________________________ + | ____________________________________ | + || || + || || + || || + || || + ||_________________W2_________________|| + | ____________________________________ | + || || + || || + || || + || || + ||_________________W3_________________|| + |__________________W1__________________| + +</pre> +</div> <p>If <code>window-combination-resize</code> is <code>nil</code>, splitting window <var>W3</var> leaves the size of <var>W2</var> unchanged: </p> <div class="example"> <pre class="example"> ______________________________________ + | ____________________________________ | + || || + || || + || || + || || + ||_________________W2_________________|| + | ____________________________________ | + || || + ||_________________W3_________________|| + | ____________________________________ | + || || + ||_________________W4_________________|| + |__________________W1__________________| + +</pre> +</div> <p>If <code>window-combination-resize</code> is <code>t</code>, splitting <var>W3</var> instead leaves all three live windows with approximately the same height: </p> <div class="example"> <pre class="example"> ______________________________________ + | ____________________________________ | + || || + || || + ||_________________W2_________________|| + | ____________________________________ | + || || + || || + ||_________________W3_________________|| + | ____________________________________ | + || || + || || + ||_________________W4_________________|| + |__________________W1__________________| + +</pre> +</div> <p>Deleting any of the live windows <var>W2</var>, <var>W3</var> or <var>W4</var> will distribute its space proportionally among the two remaining live windows. </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/Recombining-Windows.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Recombining-Windows.html</a> + </p> +</div> |