new repository

1 files changed, 30 insertions, 0 deletions

diff --git a/devdocs/elisp/basic-windows.html b/devdocs/elisp/basic-windows.html
new file mode 100644
index 00000000..57e07491
--- /dev/null
+++ b/devdocs/elisp/basic-windows.html
@@ -0,0 +1,30 @@
+ <h3 class="section">Basic Concepts of Emacs Windows</h3>   <p>A <em>window</em> is an area of the screen that can be used to display a buffer (see <a href="buffers">Buffers</a>). Windows are grouped into frames (see <a href="frames">Frames</a>). Each frame contains at least one window; the user can subdivide a frame into multiple, non-overlapping windows to view several buffers at once. Lisp programs can use multiple windows for a variety of purposes. In Rmail, for example, you can view a summary of message titles in one window, and the contents of the selected message in another window. </p>    <p>Emacs uses the term “window” with a different meaning than in graphical desktop environments and window systems, such as the X Window System. When Emacs is run on X, each graphical X window owned by the Emacs process corresponds to one Emacs frame. When Emacs is run on a text terminal, each Emacs frame fills the entire terminal screen. In either case, the frame may contain one or more Emacs windows. For disambiguation, we use the term <em>window-system window</em> when we mean the window-system window corresponding to an Emacs frame. </p>  <p>Unlike X windows, Emacs windows are <em>tiled</em>; they never overlap within the area of their frame. When a window is created, resized, or deleted, the change in window space is taken from or given to other windows on the same frame, so that the total area of the frame is unchanged. </p> <p>In Emacs Lisp, windows are represented by a special Lisp object type (see <a href="window-type">Window Type</a>). </p> <dl> <dt id="windowp">Function: <strong>windowp</strong> <em>object</em>
+</dt> <dd><p>This function returns <code>t</code> if <var>object</var> is a window (whether or not it displays a buffer). Otherwise, it returns <code>nil</code>. </p></dd>
+</dl>  <p>A <em>live window</em> is one that is actually displaying a buffer in a frame. </p> <dl> <dt id="window-live-p">Function: <strong>window-live-p</strong> <em>object</em>
+</dt> <dd><p>This function returns <code>t</code> if <var>object</var> is a live window and <code>nil</code> otherwise. A live window is one that displays a buffer. </p></dd>
+</dl>  <p>The windows in each frame are organized into a <em>window tree</em>. See <a href="windows-and-frames">Windows and Frames</a>. The leaf nodes of each window tree are live windows—the ones actually displaying buffers. The internal nodes of the window tree are <em>internal windows</em>, which are not live. </p>  <p>A <em>valid window</em> is one that is either live or internal. A valid window can be <em>deleted</em>, i.e., removed from its frame (see <a href="deleting-windows">Deleting Windows</a>); then it is no longer valid, but the Lisp object representing it might be still referenced from other Lisp objects. A deleted window may be made valid again by restoring a saved window configuration (see <a href="window-configurations">Window Configurations</a>). </p> <p>You can distinguish valid windows from deleted windows with <code>window-valid-p</code>. </p> <dl> <dt id="window-valid-p">Function: <strong>window-valid-p</strong> <em>object</em>
+</dt> <dd><p>This function returns <code>t</code> if <var>object</var> is a live window, or an internal window in a window tree. Otherwise, it returns <code>nil</code>, including for the case where <var>object</var> is a deleted window. </p></dd>
+</dl> <p>The following schematic shows the structure of a live window: </p> <div class="example"> <pre class="example">        ____________________________________________
+       |________________ Tab Line _______________|RD| ^
+       |______________ Header Line ______________|  | |
+     ^ |LS|LM|LF|                       |RF|RM|RS|  | |
+     | |  |  |  |                       |  |  |  |  | |
+Window |  |  |  |                       |  |  |  |  | Window
+Body | |  |  |  |      Window Body      |  |  |  |  | Total
+Height |  |  |  |                       |  |  |  |  | Height
+     | |  |  |  |&lt;- Window Body Width -&gt;|  |  |  |  | |
+     v |__|__|__|_______________________|__|__|__|  | |
+       |_________ Horizontal Scroll Bar _________|  | |
+       |_______________ Mode Line _______________|__| |
+       |_____________ Bottom Divider _______________| v
+        &lt;---------- Window Total Width ------------&gt;
+
+</pre>
+</div>      <p>At the center of that window is the <em>body</em>, where the buffer text is displayed. The body can be surrounded by a series of optional areas which we will call <em>window decorations</em>. On the left and right, from innermost to outermost, these are the left and right fringes, denoted by LF and RF (see <a href="fringes">Fringes</a>); the left and right margins, denoted by LM and RM in the schematic (see <a href="display-margins">Display Margins</a>); the left or right vertical scroll bar, only one of which is present at any time, denoted by LS and RS (see <a href="scroll-bars">Scroll Bars</a>); and the right divider, denoted by RD (see <a href="window-dividers">Window Dividers</a>). Together these are the window’s <em>left and right decorations</em>. </p>  <p>At the top of the window are the tab line and the header line (see <a href="header-lines">Header Lines</a>). The <em>text area</em> of the window includes the header line and the tab line, if they are present in the window. At the bottom of the window are the horizontal scroll bar (see <a href="scroll-bars">Scroll Bars</a>); the mode line (see <a href="mode-line-format">Mode Line Format</a>); and the bottom divider (see <a href="window-dividers">Window Dividers</a>). Together these form the window’s <em>top and bottom decorations</em>. </p> <p>There are two special areas omitted in the schematic: </p> <ul> <li> When any of the fringes is missing, the display engine may use one character cell in its place for showing a continuation or truncation glyph provided a text line doesn’t fit in a window. </li>
+<li> When both, the vertical scroll bar and the right divider are missing, the display engine usurps one pixel for drawing a vertical divider line between this window and the window on its right, provided such a window exists. On a text terminal, this divider always occupies an entire character cell. </li>
+</ul> <p>In either case, the resulting artifact is considered part of the window’s body although its screen space cannot be used for displaying buffer text. </p> <p>Note also, that line numbers (and their surrounding whitespace) as displayed by <code>display-line-numbers-mode</code> (see <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Display-Custom.html#Display-Custom">Display Custom</a> in <cite>The GNU Emacs Manual</cite>) do not count as decorations either; they are part of the window’s body too. </p> <p>Internal windows neither show any text nor do they have decorations. Hence, the concept of “body” does not make sense for them. In fact, most functions operating on the body of a window will yield an error when applied to an internal window. </p>   <p>By default, an Emacs frame exhibits one special live window that is used for displaying messages and accepting user input—the <em>minibuffer window</em> (see <a href="minibuffer-windows">Minibuffer Windows</a>). Since the minibuffer window is used for displaying text, it has a body but it does not have a tab or header line or any margins. Finally, a <em>tooltip window</em> which is used for displaying a tooltip in a tooltip frame (see <a href="tooltips">Tooltips</a>) has a body too but no decorations at all. </p><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/Basic-Windows.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Basic-Windows.html</a>
+  </p>
+</div>