new repository

1 files changed, 24 insertions, 0 deletions

diff --git a/devdocs/elisp/atomic-windows.html b/devdocs/elisp/atomic-windows.html
new file mode 100644
index 00000000..39697000
--- /dev/null
+++ b/devdocs/elisp/atomic-windows.html
@@ -0,0 +1,24 @@
+ <h3 class="section">Atomic Windows</h3>  <p>Atomic windows are rectangular compositions of at least two live windows. They have the following distinctive characteristics: </p> <ul> <li> The function <code>split-window</code> (see <a href="splitting-windows">Splitting Windows</a>), when applied to a constituent of an atomic window, will try to create the new window outside of the atomic window. </li>
+<li> The function <code>delete-window</code> (see <a href="deleting-windows">Deleting Windows</a>), when applied to a constituent of an atomic window, will try to delete the entire atomic window instead. </li>
+<li> The function <code>delete-other-windows</code> (see <a href="deleting-windows">Deleting Windows</a>), when applied to a constituent of an atomic window, will try to make the atomic window fill its frame or main window (see <a href="side-windows">Side Windows</a>). </li>
+</ul> <p>This means that the basic groups of functions that alter the window structure treat an atomic window like a live one, thus preserving the internal structure of the atomic window. </p> <p>Atomic windows are useful to construct and preserve window layouts that are meaningful only when all involved buffers are shown simultaneously in a specific manner, such as when showing differences between file revisions, or the same text in different languages or markups. They can also be used to permanently display information pertinent to a specific window in bars on that window’s sides. </p>  <p>Atomic windows are implemented with the help of the reserved <code>window-atom</code> window parameter (see <a href="window-parameters">Window Parameters</a>) and an internal window (see <a href="basic-windows">Basic Windows</a>) called the root window of the atomic window. All windows that are part of the same atomic window have this root window as their common ancestor and are assigned a non-<code>nil</code> <code>window-atom</code> parameter. </p> <p>The following function returns the root of the atomic window a specified window is part of: </p> <dl> <dt id="window-atom-root">Function: <strong>window-atom-root</strong> <em>&amp;optional window</em>
+</dt> <dd><p>This functions returns the root of the atomic window <var>window</var> is a part of. The specified <var>window</var> must be a valid window and defaults to the selected one. It returns <code>nil</code> if <var>window</var> is not part of an atomic window. </p></dd>
+</dl> <p>The most simple approach to make a new atomic window is to take an existing internal window and apply the following function: </p> <dl> <dt id="window-make-atom">Function: <strong>window-make-atom</strong> <em>window</em>
+</dt> <dd><p>This function converts <var>window</var> into an atomic window. The specified <var>window</var> must be an internal window. All this function does is to set the <code>window-atom</code> parameter of each descendant of <var>window</var> to <code>t</code>. </p></dd>
+</dl> <p>To create a new atomic window from an existing live window or to add a new window to an existing atomic window, the following buffer display action function (see <a href="buffer-display-action-functions">Buffer Display Action Functions</a>) can be used: </p> <dl> <dt id="display-buffer-in-atom-window">Function: <strong>display-buffer-in-atom-window</strong> <em>buffer alist</em>
+</dt> <dd>
+<p>This function tries to display <var>buffer</var> in a new window that will be combined with an existing window to form an atomic window. If the existing window is already part of an atomic window, it adds the new window to that atomic window. </p> <p>The specified <var>alist</var> is an association list of symbols and values. The following symbols have a special meaning: </p> <dl compact> <dt><code>window</code></dt> <dd>
+<p>The value of such an element specifies an existing window the new window shall be combined with. If it specifies an internal window, all children of that window become part of the atomic window too. If no window is specified, the new window becomes a sibling of the selected window. The <code>window-atom</code> parameter of the existing window is set to <code>main</code> provided that window is live and its <code>window-atom</code> parameter was not already set. </p> </dd> <dt><code>side</code></dt> <dd><p>The value of such an element denotes the side of the existing window where the new window shall be located. Valid values are <code>below</code>, <code>right</code>, <code>above</code> and <code>left</code>. The default is <code>below</code>. The <code>window-atom</code> parameter of the new window is set to this value. </p></dd> </dl> <p>The return value is the new window, <code>nil</code> when creating that window failed. </p>
+</dd>
+</dl> <p>Note that the value of the <code>window-atom</code> parameter does not really matter as long as it is non-<code>nil</code>. The values assigned by <code>display-buffer-in-atom-window</code> just allow for easy retrieval of the original and the new window after that function has been applied. Note also that the <code>window-atom</code> parameter is the only window parameter assigned by <code>display-buffer-in-atom-window</code>. Further parameters have to be set by the application explicitly via a <code>window-parameters</code> entry in <var>alist</var>. </p> <p>Atomic windows automatically cease to exist when one of their constituents gets deleted. To dissolve an atomic window manually, reset the <code>window-atom</code> parameter of its constituents—the root of the atomic window and all its descendants. </p> <p>The following code snippet, when applied to a single-window frame, first splits the selected window and makes the selected and the new window constituents of an atomic window with their parent as root. It then displays the buffer <samp>*Messages*</samp> in a new window at the frame’s bottom and makes that new window part of the atomic window just created. </p> <div class="example"> <pre class="example">(let ((window (split-window-right)))
+  (window-make-atom (window-parent window))
+  (display-buffer-in-atom-window
+   (get-buffer-create "*Messages*")
+   `((window . ,(window-parent window)) (window-height . 5))))
+</pre>
+</div> <p>At this moment typing <kbd><span class="nolinebreak">C-x</span> 2</kbd> in any window of that frame produces a new window at the bottom of the frame. Typing <kbd><span class="nolinebreak">C-x</span> 3</kbd> instead will put the new window at the frame’s right. In either case, typing now <kbd><span class="nolinebreak">C-x</span> 1</kbd> in any window of the atomic window will remove the new window only. Typing <kbd><span class="nolinebreak">C-x</span> 0</kbd> in any window of the atomic window will make that new window fill the frame. </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/Atomic-Windows.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Atomic-Windows.html</a>
+  </p>
+</div>