diff options
Diffstat (limited to 'devdocs/elisp/position-parameters.html')
| -rw-r--r-- | devdocs/elisp/position-parameters.html | 21 |
1 files changed, 21 insertions, 0 deletions
diff --git a/devdocs/elisp/position-parameters.html b/devdocs/elisp/position-parameters.html new file mode 100644 index 00000000..ffd79bbf --- /dev/null +++ b/devdocs/elisp/position-parameters.html @@ -0,0 +1,21 @@ + <h4 class="subsubsection">Position Parameters</h4> <p>Parameters describing the X- and Y-offsets of a frame are always measured in pixels. For a normal, non-child frame they specify the frame’s outer position (see <a href="frame-geometry">Frame Geometry</a>) relative to its display’s origin. For a child frame (see <a href="child-frames">Child Frames</a>) they specify the frame’s outer position relative to the native position of the frame’s parent frame. (Note that none of these parameters is meaningful on TTY frames.) </p> <dl compact> <dt><code>left</code></dt> <dd> +<p>The position, in pixels, of the left outer edge of the frame with respect to the left edge of the frame’s display or parent frame. It can be specified in one of the following ways. </p> <dl compact> <dt>an integer</dt> <dd> +<p>A positive integer always relates the left edge of the frame to the left edge of its display or parent frame. A negative integer relates the right frame edge to the right edge of the display or parent frame. </p> </dd> <dt><code>(+ <var>pos</var>)</code></dt> <dd> +<p>This specifies the position of the left frame edge relative to the left edge of its display or parent frame. The integer <var>pos</var> may be positive or negative; a negative value specifies a position outside the screen or parent frame or on a monitor other than the primary one (for multi-monitor displays). </p> </dd> <dt><code>(- <var>pos</var>)</code></dt> <dd> +<p>This specifies the position of the right frame edge relative to the right edge of the display or parent frame. The integer <var>pos</var> may be positive or negative; a negative value specifies a position outside the screen or parent frame or on a monitor other than the primary one (for multi-monitor displays). </p> </dd> <dt>a floating-point value</dt> <dd> +<p>A floating-point value in the range 0.0 to 1.0 specifies the left edge’s offset via the <em>left position ratio</em> of the frame—the ratio of the left edge of its outer frame to the width of the frame’s workarea (see <a href="multiple-terminals">Multiple Terminals</a>) or its parent’s native frame (see <a href="child-frames">Child Frames</a>) minus the width of the outer frame. Thus, a left position ratio of 0.0 flushes a frame to the left, a ratio of 0.5 centers it and a ratio of 1.0 flushes it to the right of its display or parent frame. Similarly, the <em>top position ratio</em> of a frame is the ratio of the frame’s top position to the height of its workarea or parent frame minus the height of the frame. </p> <p>Emacs will try to keep the position ratios of a child frame unaltered if that frame has a non-<code>nil</code> <code>keep-ratio</code> parameter (see <a href="frame-interaction-parameters">Frame Interaction Parameters</a>) and its parent frame is resized. </p> <p>Since the outer size of a frame (see <a href="frame-geometry">Frame Geometry</a>) is usually unavailable before a frame has been made visible, it is generally not advisable to use floating-point values when creating decorated frames. Floating-point values are more suited for ensuring that an (undecorated) child frame is positioned nicely within the area of its parent frame. </p> +</dd> </dl> <p>Some window managers ignore program-specified positions. If you want to be sure the position you specify is not ignored, specify a non-<code>nil</code> value for the <code>user-position</code> parameter as in the following example: </p> <div class="example"> <pre class="example">(modify-frame-parameters + nil '((user-position . t) (left . (+ -4)))) +</pre> +</div> <p>In general, it is not a good idea to position a frame relative to the right or bottom edge of its display. Positioning the initial or a new frame is either not accurate (because the size of the outer frame is not yet fully known before the frame has been made visible) or will cause additional flicker (if the frame has to be repositioned after becoming visible). </p> <p>Note also, that positions specified relative to the right/bottom edge of a display, workarea or parent frame as well as floating-point offsets are stored internally as integer offsets relative to the left/top edge of the display, workarea or parent frame edge. They are also returned as such by functions like <code>frame-parameters</code> and restored as such by the desktop saving routines. </p> </dd> <dt><code>top</code></dt> <dd> +<p>The screen position of the top (or bottom) edge, in pixels, with respect to the top (or bottom) edge of the display or parent frame. It works just like <code>left</code>, except vertically instead of horizontally. </p> </dd> <dt><code>icon-left</code></dt> <dd> +<p>The screen position of the left edge of the frame’s icon, in pixels, counting from the left edge of the screen. This takes effect when the frame is iconified, if the window manager supports this feature. If you specify a value for this parameter, then you must also specify a value for <code>icon-top</code> and vice versa. </p> </dd> <dt><code>icon-top</code></dt> <dd> +<p>The screen position of the top edge of the frame’s icon, in pixels, counting from the top edge of the screen. This takes effect when the frame is iconified, if the window manager supports this feature. </p> </dd> <dt><code>user-position</code></dt> <dd> +<p>When you create a frame and specify its screen position with the <code>left</code> and <code>top</code> parameters, use this parameter to say whether the specified position was user-specified (explicitly requested in some way by a human user) or merely program-specified (chosen by a program). A non-<code>nil</code> value says the position was user-specified. </p> <p>Window managers generally heed user-specified positions, and some heed program-specified positions too. But many ignore program-specified positions, placing the window in a default fashion or letting the user place it with the mouse. Some window managers, including <code>twm</code>, let the user specify whether to obey program-specified positions or ignore them. </p> <p>When you call <code>make-frame</code>, you should specify a non-<code>nil</code> value for this parameter if the values of the <code>left</code> and <code>top</code> parameters represent the user’s stated preference; otherwise, use <code>nil</code>. </p> </dd> <dt><code>z-group</code></dt> <dd> +<p>This parameter specifies a relative position of the frame’s window-system window in the stacking (Z-) order of the frame’s display. </p> <p>If this is <code>above</code>, the window-system will display the window that corresponds to the frame above all other window-system windows that do not have the <code>above</code> property set. If this is <code>nil</code>, the frame’s window is displayed below all windows that have the <code>above</code> property set and above all windows that have the <code>below</code> property set. If this is <code>below</code>, the frame’s window is displayed below all windows that do not have the <code>below</code> property set. </p> <p>To position the frame above or below a specific other frame use the function <code>frame-restack</code> (see <a href="raising-and-lowering">Raising and Lowering</a>). </p> +</dd> </dl><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/Position-Parameters.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Position-Parameters.html</a> + </p> +</div> |