new repository

1 files changed, 18 insertions, 0 deletions

diff --git a/devdocs/elisp/raising-and-lowering.html b/devdocs/elisp/raising-and-lowering.html
new file mode 100644
index 00000000..ff639825
--- /dev/null
+++ b/devdocs/elisp/raising-and-lowering.html
@@ -0,0 +1,18 @@
+ <h3 class="section">Raising, Lowering and Restacking Frames</h3>       <p>Most window systems use a desktop metaphor. Part of this metaphor is the idea that system-level windows (representing, e.g., Emacs frames) are stacked in a notional third dimension perpendicular to the screen surface. The order induced by stacking is total and usually referred to as stacking (or Z-) order. Where the areas of two windows overlap, the one higher up in that order will (partially) cover the one underneath. </p> <p>You can <em>raise</em> a frame to the top of that order or <em>lower</em> a frame to its bottom by using the functions <code>raise-frame</code> and <code>lower-frame</code>. You can <em>restack</em> a frame directly above or below another frame using the function <code>frame-restack</code>. </p> <p>Note that all functions described below will respect the adherence of frames (and all other window-system windows) to their respective z-group (see <a href="position-parameters">Position Parameters</a>). For example, you usually cannot lower a frame below that of the desktop window and you cannot raise a frame whose <code>z-group</code> parameter is <code>nil</code> above the window-system’s taskbar or tooltip window. </p> <dl> <dt id="raise-frame">Command: <strong>raise-frame</strong> <em>&amp;optional frame</em>
+</dt> <dd><p>This function raises frame <var>frame</var> (default, the selected frame) above all other frames belonging to the same or a lower z-group as <var>frame</var>. If <var>frame</var> is invisible or iconified, this makes it visible. If <var>frame</var> is a child frame (see <a href="child-frames">Child Frames</a>), this raises <var>frame</var> above all other child frames of its parent. </p></dd>
+</dl> <dl> <dt id="lower-frame">Command: <strong>lower-frame</strong> <em>&amp;optional frame</em>
+</dt> <dd><p>This function lowers frame <var>frame</var> (default, the selected frame) below all other frames belonging to the same or a higher z-group as <var>frame</var>. If <var>frame</var> is a child frame (see <a href="child-frames">Child Frames</a>), this lowers <var>frame</var> below all other child frames of its parent. </p></dd>
+</dl> <dl> <dt id="frame-restack">Function: <strong>frame-restack</strong> <em>frame1 frame2 &amp;optional above</em>
+</dt> <dd>
+<p>This function restacks <var>frame1</var> below <var>frame2</var>. This implies that if both frames are visible and their display areas overlap, <var>frame2</var> will (partially) obscure <var>frame1</var>. If the optional third argument <var>above</var> is non-<code>nil</code>, this function restacks <var>frame1</var> above <var>frame2</var>. This means that if both frames are visible and their display areas overlap, <var>frame1</var> will (partially) obscure <var>frame2</var>. </p> <p>Technically, this function may be thought of as an atomic action performed in two steps: The first step removes <var>frame1</var>’s window-system window from the display. The second step reinserts <var>frame1</var>’s window into the display below (above if <var>above</var> is true) that of <var>frame2</var>. Hence the position of <var>frame2</var> in its display’s Z (stacking) order relative to all other frames excluding <var>frame1</var> remains unaltered. </p> <p>Some window managers may refuse to restack windows. </p>
+</dd>
+</dl> <p>Note that the effect of restacking will only hold as long as neither of the involved frames is iconified or made invisible. You can use the <code>z-group</code> (see <a href="position-parameters">Position Parameters</a>) frame parameter to add a frame to a group of frames permanently shown above or below other frames. As long as a frame belongs to one of these groups, restacking it will only affect its relative stacking position within that group. The effect of restacking frames belonging to different z-groups is undefined. You can list frames in their current stacking order with the function <code>frame-list-z-order</code> (see <a href="finding-all-frames">Finding All Frames</a>). </p> <dl> <dt id="minibuffer-auto-raise">User Option: <strong>minibuffer-auto-raise</strong>
+</dt> <dd><p>If this is non-<code>nil</code>, activation of the minibuffer raises the frame that the minibuffer window is in. </p></dd>
+</dl> <p>On window systems, you can also enable auto-raising (on frame selection) or auto-lowering (on frame deselection) using frame parameters. See <a href="management-parameters">Management Parameters</a>. </p>  <p>The concept of raising and lowering frames also applies to text terminal frames. On each text terminal, only the top frame is displayed at any one time. </p> <dl> <dt id="tty-top-frame">Function: <strong>tty-top-frame</strong> <em>&amp;optional terminal</em>
+</dt> <dd><p>This function returns the top frame on <var>terminal</var>. <var>terminal</var> should be a terminal object, a frame (meaning that frame’s terminal), or <code>nil</code> (meaning the selected frame’s terminal). If it does not refer to a text terminal, the return value is <code>nil</code>. </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/Raising-and-Lowering.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Raising-and-Lowering.html</a>
+  </p>
+</div>