new repository

1 files changed, 61 insertions, 0 deletions

diff --git a/devdocs/elisp/windows-and-frames.html b/devdocs/elisp/windows-and-frames.html
new file mode 100644
index 00000000..c5ad6d1e
--- /dev/null
+++ b/devdocs/elisp/windows-and-frames.html
@@ -0,0 +1,61 @@
+ <h3 class="section">Windows and Frames</h3> <p>Each window belongs to exactly one frame (see <a href="frames">Frames</a>). For all windows belonging to a specific frame, we sometimes also say that these windows are <em>owned</em> by that frame or simply that they are on that frame. </p> <dl> <dt id="window-frame">Function: <strong>window-frame</strong> <em>&amp;optional window</em>
+</dt> <dd><p>This function returns the specified <var>window</var>’s frame—the frame that <var>window</var> belongs to. If <var>window</var> is omitted or <code>nil</code>, it defaults to the selected window (see <a href="selecting-windows">Selecting Windows</a>). </p></dd>
+</dl> <dl> <dt id="window-list">Function: <strong>window-list</strong> <em>&amp;optional frame minibuffer window</em>
+</dt> <dd>
+<p>This function returns a list of all live windows owned by the specified <var>frame</var>. If <var>frame</var> is omitted or <code>nil</code>, it defaults to the selected frame (see <a href="input-focus">Input Focus</a>). </p> <p>The optional argument <var>minibuffer</var> specifies whether to include the minibuffer window (see <a href="minibuffer-windows">Minibuffer Windows</a>) in that list. If <var>minibuffer</var> is <code>t</code>, the minibuffer window is included. If <code>nil</code> or omitted, the minibuffer window is included only if it is active. If <var>minibuffer</var> is neither <code>nil</code> nor <code>t</code>, the minibuffer window is never included. </p> <p>The optional argument <var>window</var>, if non-<code>nil</code>, must be a live window on the specified frame; then <var>window</var> will be the first element in the returned list. If <var>window</var> is omitted or <code>nil</code>, the window selected within <var>frame</var> (see <a href="selecting-windows">Selecting Windows</a>) is the first element. </p>
+</dd>
+</dl>   <p>Windows on the same frame are organized into a <em>window tree</em>, whose leaf nodes are the live windows. The internal nodes of a window tree are not live; they exist for the purpose of organizing the relationships between live windows. The root node of a window tree is called the <em>root window</em>. It is either a live window or an internal window. If it is a live window, then the frame has just one window besides the minibuffer window, or the frame is a minibuffer-only frame, see <a href="frame-layout">Frame Layout</a>. </p> <p>A minibuffer window (see <a href="minibuffer-windows">Minibuffer Windows</a>) that is not alone on its frame does not have a parent window, so it strictly speaking is not part of its frame’s window tree. Nonetheless, it is a sibling window of the frame’s root window, and thus can be reached from the root window via <code>window-next-sibling</code>, see below. Also, the function <code>window-tree</code> described at the end of this section lists the minibuffer window alongside the actual window tree. </p> <dl> <dt id="frame-root-window">Function: <strong>frame-root-window</strong> <em>&amp;optional frame-or-window</em>
+</dt> <dd><p>This function returns the root window for <var>frame-or-window</var>. The argument <var>frame-or-window</var> should be either a window or a frame; if omitted or <code>nil</code>, it defaults to the selected frame. If <var>frame-or-window</var> is a window, the return value is the root window of that window’s frame. </p></dd>
+</dl>    <p>When a live window is split (see <a href="splitting-windows">Splitting Windows</a>), there are two live windows where previously there was one. One of these is represented by the same Lisp window object as the original window, and the other is represented by a newly-created Lisp window object. Both of these live windows become leaf nodes of the window tree, as <em>child windows</em> of a single internal window. If necessary, Emacs automatically creates this internal window, which is also called the <em>parent window</em>, and assigns it to the appropriate position in the window tree. The set of windows that share the same parent are called <em>siblings</em>. </p>  <dl> <dt id="window-parent">Function: <strong>window-parent</strong> <em>&amp;optional window</em>
+</dt> <dd><p>This function returns the parent window of <var>window</var>. If <var>window</var> is omitted or <code>nil</code>, it defaults to the selected window. The return value is <code>nil</code> if <var>window</var> has no parent (i.e., it is a minibuffer window or the root window of its frame). </p></dd>
+</dl> <p>A parent window always has at least two child windows. If this number were to fall to one as a result of window deletion (see <a href="deleting-windows">Deleting Windows</a>), Emacs automatically deletes the parent window too, and its sole remaining child window takes its place in the window tree. </p> <p>A child window can be either a live window, or an internal window (which in turn would have its own child windows). Therefore, each internal window can be thought of as occupying a certain rectangular <em>screen area</em>—the union of the areas occupied by the live windows that are ultimately descended from it. </p>    <p>For each internal window, the screen areas of the immediate children are arranged either vertically or horizontally (never both). If the child windows are arranged one above the other, they are said to form a <em>vertical combination</em>; if they are arranged side by side, they are said to form a <em>horizontal combination</em>. Consider the following example: </p> <div class="example"> <pre class="example">     ______________________________________
+    | ______  ____________________________ |
+    ||      || __________________________ ||
+    ||      |||                          |||
+    ||      |||                          |||
+    ||      |||                          |||
+    ||      |||____________W4____________|||
+    ||      || __________________________ ||
+    ||      |||                          |||
+    ||      |||                          |||
+    ||      |||____________W5____________|||
+    ||__W2__||_____________W3_____________ |
+    |__________________W1__________________|
+
+</pre>
+</div> <p>The root window of this frame is an internal window, <var>W1</var>. Its child windows form a horizontal combination, consisting of the live window <var>W2</var> and the internal window <var>W3</var>. The child windows of <var>W3</var> form a vertical combination, consisting of the live windows <var>W4</var> and <var>W5</var>. Hence, the live windows in this window tree are <var>W2</var>, <var>W4</var>, and <var>W5</var>. </p> <p>The following functions can be used to retrieve a child window of an internal window, and the siblings of a child window. Their <var>window</var> argument always defaults to the selected window (see <a href="selecting-windows">Selecting Windows</a>). </p> <dl> <dt id="window-top-child">Function: <strong>window-top-child</strong> <em>&amp;optional window</em>
+</dt> <dd><p>This function returns the topmost child window of <var>window</var>, if <var>window</var> is an internal window whose children form a vertical combination. For any other type of window, the return value is <code>nil</code>. </p></dd>
+</dl> <dl> <dt id="window-left-child">Function: <strong>window-left-child</strong> <em>&amp;optional window</em>
+</dt> <dd><p>This function returns the leftmost child window of <var>window</var>, if <var>window</var> is an internal window whose children form a horizontal combination. For any other type of window, the return value is <code>nil</code>. </p></dd>
+</dl> <dl> <dt id="window-child">Function: <strong>window-child</strong> <em>window</em>
+</dt> <dd><p>This function returns the first child window of the internal window <var>window</var>—the topmost child window for a vertical combination, or the leftmost child window for a horizontal combination. If <var>window</var> is a live window, the return value is <code>nil</code>. </p></dd>
+</dl> <dl> <dt id="window-combined-p">Function: <strong>window-combined-p</strong> <em>&amp;optional window horizontal</em>
+</dt> <dd>
+<p>This function returns a non-<code>nil</code> value if and only if <var>window</var> is part of a vertical combination. </p> <p>If the optional argument <var>horizontal</var> is non-<code>nil</code>, this means to return non-<code>nil</code> if and only if <var>window</var> is part of a horizontal combination. </p>
+</dd>
+</dl> <dl> <dt id="window-next-sibling">Function: <strong>window-next-sibling</strong> <em>&amp;optional window</em>
+</dt> <dd><p>This function returns the next sibling of the specified <var>window</var>. The return value is <code>nil</code> if <var>window</var> is the last child of its parent. </p></dd>
+</dl> <dl> <dt id="window-prev-sibling">Function: <strong>window-prev-sibling</strong> <em>&amp;optional window</em>
+</dt> <dd><p>This function returns the previous sibling of the specified <var>window</var>. The return value is <code>nil</code> if <var>window</var> is the first child of its parent. </p></dd>
+</dl> <p>The functions <code>window-next-sibling</code> and <code>window-prev-sibling</code> should not be confused with the functions <code>next-window</code> and <code>previous-window</code>, which return the next and previous window in the cyclic ordering of windows (see <a href="cyclic-window-ordering">Cyclic Window Ordering</a>). </p> <p>The following functions can be useful to locate a window within its frame. </p> <dl> <dt id="frame-first-window">Function: <strong>frame-first-window</strong> <em>&amp;optional frame-or-window</em>
+</dt> <dd><p>This function returns the live window at the upper left corner of the frame specified by <var>frame-or-window</var>. The argument <var>frame-or-window</var> must denote a window or a live frame and defaults to the selected frame. If <var>frame-or-window</var> specifies a window, this function returns the first window on that window’s frame. Under the assumption that the frame from our canonical example is selected <code>(frame-first-window)</code> returns <var>W2</var>. </p></dd>
+</dl> <dl> <dt id="window-at-side-p">Function: <strong>window-at-side-p</strong> <em>&amp;optional window side</em>
+</dt> <dd>
+<p>This function returns <code>t</code> if <var>window</var> is located at <var>side</var> of its containing frame. The argument <var>window</var> must be a valid window and defaults to the selected one. The argument <var>side</var> can be any of the symbols <code>left</code>, <code>top</code>, <code>right</code> or <code>bottom</code>. The default value <code>nil</code> is handled like <code>bottom</code>. </p> <p>Note that this function disregards the minibuffer window (see <a href="minibuffer-windows">Minibuffer Windows</a>). Hence, with <var>side</var> equal to <code>bottom</code> it may return <code>t</code> also when the minibuffer window appears right below <var>window</var>. </p>
+</dd>
+</dl>  <dl> <dt id="window-in-direction">Function: <strong>window-in-direction</strong> <em>direction &amp;optional window ignore sign wrap minibuf</em>
+</dt> <dd>
+<p>This function returns the nearest live window in direction <var>direction</var> as seen from the position of <code>window-point</code> in window <var>window</var>. The argument <var>direction</var> must be one of <code>above</code>, <code>below</code>, <code>left</code> or <code>right</code>. The optional argument <var>window</var> must denote a live window and defaults to the selected one. </p> <p>This function does not return a window whose <code>no-other-window</code> parameter is non-<code>nil</code> (see <a href="window-parameters">Window Parameters</a>). If the nearest window’s <code>no-other-window</code> parameter is non-<code>nil</code>, this function tries to find another window in the indicated direction whose <code>no-other-window</code> parameter is <code>nil</code>. If the optional argument <var>ignore</var> is non-<code>nil</code>, a window may be returned even if its <code>no-other-window</code> parameter is non-<code>nil</code>. </p> <p>If the optional argument <var>sign</var> is a negative number, it means to use the right or bottom edge of <var>window</var> as reference position instead of <code>window-point</code>. If <var>sign</var> is a positive number, it means to use the left or top edge of <var>window</var> as reference position. </p> <p>If the optional argument <var>wrap</var> is non-<code>nil</code>, this means to wrap <var>direction</var> around frame borders. For example, if <var>window</var> is at the top of the frame and <var>direction</var> is <code>above</code>, then this function usually returns the frame’s minibuffer window if it’s active and a window at the bottom of the frame otherwise. </p> <p>If the optional argument <var>minibuf</var> is <code>t</code>, this function may return the minibuffer window even when it’s not active. If the optional argument <var>minibuf</var> is <code>nil</code>, this means to return the minibuffer window if and only if it is currently active. If <var>minibuf</var> is neither <code>nil</code> nor <code>t</code>, this function never returns the minibuffer window. However, if <var>wrap</var> is non-<code>nil</code>, it always acts as if <var>minibuf</var> were <code>nil</code>. </p> <p>If it doesn’t find a suitable window, this function returns <code>nil</code>. </p> <p>Don’t use this function to check whether there is <em>no</em> window in <var>direction</var>. Calling <code>window-at-side-p</code> described above is a much more efficient way to do that. </p>
+</dd>
+</dl> <p>The following function retrieves the entire window tree of a frame: </p> <dl> <dt id="window-tree">Function: <strong>window-tree</strong> <em>&amp;optional frame</em>
+</dt> <dd>
+<p>This function returns a list representing the window tree for frame <var>frame</var>. If <var>frame</var> is omitted or <code>nil</code>, it defaults to the selected frame. </p> <p>The return value is a list of the form <code>(<var>root</var> <var>mini</var>)</code>, where <var>root</var> represents the window tree of the frame’s root window, and <var>mini</var> is the frame’s minibuffer window. </p> <p>If the root window is live, <var>root</var> is that window itself. Otherwise, <var>root</var> is a list <code>(<var>dir</var> <var>edges</var> <var>w1</var>
+<var>w2</var> ...)</code> where <var>dir</var> is <code>nil</code> for a horizontal combination and <code>t</code> for a vertical combination, <var>edges</var> gives the size and position of the combination, and the remaining elements are the child windows. Each child window may again be a window object (for a live window) or a list with the same format as above (for an internal window). The <var>edges</var> element is a list <code>(<var>left</var>
+<var>top</var> <var>right</var> <var>bottom</var>)</code>, similar to the value returned by <code>window-edges</code> (see <a href="coordinates-and-windows">Coordinates and Windows</a>). </p>
+</dd>
+</dl><div class="_attribution">
+  <p class="_attribution-p">
+    Copyright &copy; 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/Windows-and-Frames.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Windows-and-Frames.html</a>
+  </p>
+</div>