1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
|
<h4 class="subsection">Frame Layout</h4> <p>A visible frame occupies a rectangular area on its terminal’s display. This area may contain a number of nested rectangles, each serving a different purpose. The drawing below sketches the layout of a frame on a graphical terminal: </p>
<div class="example"> <pre class="example">
<------------ Outer Frame Width ----------->
____________________________________________
^(0) ________ External/Outer Border _______ |
| | |_____________ Title Bar ______________| |
| | (1)_____________ Menu Bar ______________| | ^
| | (2)_____________ Tool Bar ______________| | ^
| | (3)_____________ Tab Bar _______________| | ^
| | | _________ Internal Border ________ | | ^
| | | | ^ | | | |
| | | | | | | | |
Outer | | | Inner | | | Native
Frame | | | Frame | | | Frame
Height | | | Height | | | Height
| | | | | | | | |
| | | |<--+--- Inner Frame Width ------->| | | |
| | | | | | | | |
| | | |___v______________________________| | | |
| | |___________ Internal Border __________| | v
v |___________ External/Outer Border __________|
<-------- Native Frame Width -------->
</pre>
</div> <p>In practice not all of the areas shown in the drawing will or may be present. The meaning of these areas is described below. </p> <dl compact> <dt>Outer Frame</dt> <dd>
<p>The <em>outer frame</em> is a rectangle comprising all areas shown in the drawing. The edges of that rectangle are called the <em>outer edges</em> of the frame. Together, the <em>outer width</em> and <em>outer height</em> of the frame specify the <em>outer size</em> of that rectangle. </p> <p>Knowing the outer size of a frame is useful for fitting a frame into the working area of its display (see <a href="multiple-terminals">Multiple Terminals</a>) or for placing two frames adjacent to each other on the screen. Usually, the outer size of a frame is available only after the frame has been mapped (made visible, see <a href="visibility-of-frames">Visibility of Frames</a>) at least once. For the initial frame or a frame that has not been created yet, the outer size can be only estimated or must be calculated from the window-system’s or window manager’s defaults. One workaround is to obtain the differences of the outer and native (see below) sizes of a mapped frame and use them for calculating the outer size of the new frame. </p> <p>The position of the upper left corner of the outer frame (indicated by ‘<samp>(0)</samp>’ in the drawing above) is the <em>outer position</em> of the frame. The outer position of a graphical frame is also referred to as “the position” of the frame because it usually remains unchanged on its display whenever the frame is resized or its layout is changed. </p> <p>The outer position is specified by and can be set via the <code>left</code> and <code>top</code> frame parameters (see <a href="position-parameters">Position Parameters</a>). For a normal, top-level frame these parameters usually represent its absolute position (see below) with respect to its display’s origin. For a child frame (see <a href="child-frames">Child Frames</a>) these parameters represent its position relative to the native position (see below) of its parent frame. For frames on text terminals the values of these parameters are meaningless and always zero. </p> </dd> <dt>External Border</dt> <dd>
<p>The <em>external border</em> is part of the decorations supplied by the window manager. It is typically used for resizing the frame with the mouse and is therefore not shown on “fullboth” and maximized frames (see <a href="size-parameters">Size Parameters</a>). Its width is determined by the window manager and cannot be changed by Emacs’ functions. </p> <p>External borders don’t exist on text terminal frames. For graphical frames, their display can be suppressed by setting the <code>override-redirect</code> or <code>undecorated</code> frame parameter (see <a href="management-parameters">Management Parameters</a>). </p> </dd> <dt>Outer Border</dt> <dd>
<p>The <em>outer border</em> is a separate border whose width can be specified with the <code>border-width</code> frame parameter (see <a href="layout-parameters">Layout Parameters</a>). In practice, either the external or the outer border of a frame are displayed but never both at the same time. Usually, the outer border is shown only for special frames that are not (fully) controlled by the window manager like tooltip frames (see <a href="tooltips">Tooltips</a>), child frames (see <a href="child-frames">Child Frames</a>) and <code>undecorated</code> or <code>override-redirect</code> frames (see <a href="management-parameters">Management Parameters</a>). </p> <p>Outer borders are never shown on text terminal frames and on frames generated by GTK+ routines. On MS-Windows, the outer border is emulated with the help of a one pixel wide external border. Non-toolkit builds on X allow to change the color of the outer border by setting the <code>border-color</code> frame parameter (see <a href="layout-parameters">Layout Parameters</a>). </p> </dd> <dt>Title Bar</dt> <dd>
<p>The <em>title bar</em>, a.k.a. <em>caption bar</em>, is also part of the window manager’s decorations and typically displays the title of the frame (see <a href="frame-titles">Frame Titles</a>) as well as buttons for minimizing, maximizing and deleting the frame. It can be also used for dragging the frame with the mouse. The title bar is usually not displayed for fullboth (see <a href="size-parameters">Size Parameters</a>), tooltip (see <a href="tooltips">Tooltips</a>) and child frames (see <a href="child-frames">Child Frames</a>) and doesn’t exist for terminal frames. Display of the title bar can be suppressed by setting the <code>override-redirect</code> or the <code>undecorated</code> frame parameters (see <a href="management-parameters">Management Parameters</a>). </p> </dd> <dt>Menu Bar</dt> <dd>
<p>The menu bar (see <a href="menu-bar">Menu Bar</a>) can be either internal (drawn by Emacs itself) or external (drawn by the toolkit). Most builds (GTK+, Lucid, Motif and MS-Windows) rely on an external menu bar. NS also uses an external menu bar which, however, is not part of the outer frame. Non-toolkit builds can provide an internal menu bar. On text terminal frames, the menu bar is part of the frame’s root window (see <a href="windows-and-frames">Windows and Frames</a>). As a rule, menu bars are never shown on child frames (see <a href="child-frames">Child Frames</a>). Display of the menu bar can be suppressed by setting the <code>menu-bar-lines</code> parameter (see <a href="layout-parameters">Layout Parameters</a>) to zero. </p> <p>Whether the menu bar is wrapped or truncated whenever its width becomes too large to fit on its frame depends on the toolkit . Usually, only Motif and MS-Windows builds can wrap the menu bar. When they (un-)wrap the menu bar, they try to keep the outer height of the frame unchanged, so the native height of the frame (see below) will change instead. </p> </dd> <dt>Tool Bar</dt> <dd>
<p>Like the menu bar, the tool bar (see <a href="tool-bar">Tool Bar</a>) can be either internal (drawn by Emacs itself) or external (drawn by a toolkit). The GTK+ and NS builds have the tool bar drawn by the toolkit. The remaining builds use internal tool bars. With GTK+ the tool bar can be located on either side of the frame, immediately outside the internal border, see below. Tool bars are usually not shown for child frames (see <a href="child-frames">Child Frames</a>). Display of the tool bar can be suppressed by setting the <code>tool-bar-lines</code> parameter (see <a href="layout-parameters">Layout Parameters</a>) to zero. </p> <p>If the variable <code>auto-resize-tool-bars</code> is non-<code>nil</code>, Emacs wraps the internal tool bar when its width becomes too large for its frame. If and when Emacs (un-)wraps the internal tool bar, it by default keeps the outer height of the frame unchanged, so the native height of the frame (see below) will change instead. Emacs built with GTK+, on the other hand, never wraps the tool bar but may automatically increase the outer width of a frame in order to accommodate an overlong tool bar. </p> </dd> <dt>Tab Bar</dt> <dd>
<p>The tab bar (see <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Tab-Bars.html#Tab-Bars">Tab Bars</a> in <cite>The GNU Emacs Manual</cite>) is always drawn by Emacs itself. The tab bar appears above the tool bar in Emacs built with an internal tool bar, and below the tool bar in builds with an external tool bar. Display of the tab bar can be suppressed by setting the <code>tab-bar-lines</code> parameter (see <a href="layout-parameters">Layout Parameters</a>) to zero. </p> </dd> <dt>Native Frame</dt> <dd>
<p>The <em>native frame</em> is a rectangle located entirely within the outer frame. It excludes the areas occupied by an external or outer border, the title bar and any external menu or tool bar. The edges of the native frame are called the <em>native edges</em> of the frame. Together, the <em>native width</em> and <em>native height</em> of a frame specify the <em>native size</em> of the frame. </p> <p>The native size of a frame is the size Emacs passes to the window-system or window manager when creating or resizing the frame from within Emacs. It is also the size Emacs receives from the window-system or window manager whenever these resize the frame’s window-system window, for example, after maximizing the frame by clicking on the corresponding button in the title bar or when dragging its external border with the mouse. </p> <p>The position of the top left corner of the native frame specifies the <em>native position</em> of the frame. (1)–(3) in the drawing above indicate that position for the various builds: </p> <ul class="no-bullet"> <li> (1) non-toolkit and terminal frames </li>
<li> (2) Lucid, Motif and MS-Windows frames </li>
<li> (3) GTK+ and NS frames </li>
</ul> <p>Accordingly, the native height of a frame may include the height of the tool bar but not that of the menu bar (Lucid, Motif, MS-Windows) or those of the menu bar and the tool bar (non-toolkit and text terminal frames). </p> <p>The native position of a frame is the reference position for functions that set or return the current position of the mouse (see <a href="mouse-position">Mouse Position</a>) and for functions dealing with the position of windows like <code>window-edges</code>, <code>window-at</code> or <code>coordinates-in-window-p</code> (see <a href="coordinates-and-windows">Coordinates and Windows</a>). It also specifies the (0, 0) origin for locating and positioning child frames within this frame (see <a href="child-frames">Child Frames</a>). </p> <p>Note also that the native position of a frame usually remains unaltered on its display when removing or adding the window manager decorations by changing the frame’s <code>override-redirect</code> or <code>undecorated</code> parameter (see <a href="management-parameters">Management Parameters</a>). </p> </dd> <dt>Internal Border</dt> <dd>
<p>The internal border is a border drawn by Emacs around the inner frame (see below). The specification of its appearance depends on whether or not the given frame is a child frame (see <a href="child-frames">Child Frames</a>). </p> <p>For normal frames its width is specified by the <code>internal-border-width</code> frame parameter (see <a href="layout-parameters">Layout Parameters</a>), and its color is specified by the background of the <code>internal-border</code> face. </p> <p>For child frames its width is specified by the <code>child-frame-border-width</code> frame parameter (but will use the <code>internal-border-width</code> parameter as fallback), and its color is specified by the background of the <code>child-frame-border</code> face. </p> </dd> <dt>Inner Frame</dt> <dd>
<p>The <em>inner frame</em> is the rectangle reserved for the frame’s windows. It’s enclosed by the internal border which, however, is not part of the inner frame. Its edges are called the <em>inner edges</em> of the frame. The <em>inner width</em> and <em>inner height</em> specify the <em>inner size</em> of the rectangle. The inner frame is sometimes also referred to as the <em>display area</em> of the frame. </p> <p>As a rule, the inner frame is subdivided into the frame’s root window (see <a href="windows-and-frames">Windows and Frames</a>) and the frame’s minibuffer window (see <a href="minibuffer-windows">Minibuffer Windows</a>). There are two notable exceptions to this rule: A <em>minibuffer-less frame</em> contains a root window only and does not contain a minibuffer window. A <em>minibuffer-only frame</em> contains only a minibuffer window which also serves as that frame’s root window. See <a href="initial-parameters">Initial Parameters</a> for how to create such frame configurations. </p> </dd> <dt>Text Area</dt> <dd>
<p>The <em>text area</em> of a frame is a somewhat fictitious area that can be embedded in the native frame. Its position is unspecified. Its width can be obtained by removing from that of the native width the widths of the internal border, one vertical scroll bar, and one left and one right fringe if they are specified for this frame, see <a href="layout-parameters">Layout Parameters</a>. Its height can be obtained by removing from that of the native height the widths of the internal border and the heights of the frame’s internal menu and tool bars, the tab bar and one horizontal scroll bar if specified for this frame. </p>
</dd> </dl> <p>The <em>absolute position</em> of a frame is given as a pair (X, Y) of horizontal and vertical pixel offsets relative to an origin (0, 0) of the frame’s display. Correspondingly, the <em>absolute edges</em> of a frame are given as pixel offsets from that origin. </p> <p>Note that with multiple monitors, the origin of the display does not necessarily coincide with the top-left corner of the entire usable display area of the terminal. Hence the absolute position of a frame can be negative in such an environment even when that frame is completely visible. </p> <p>By convention, vertical offsets increase “downwards”. This means that the height of a frame is obtained by subtracting the offset of its top edge from that of its bottom edge. Horizontal offsets increase “rightwards”, as expected, so a frame’s width is calculated by subtracting the offset of its left edge from that of its right edge. </p> <p>For a frame on a graphical terminal the following function returns the sizes of the areas described above: </p> <dl> <dt id="frame-geometry">Function: <strong>frame-geometry</strong> <em>&optional frame</em>
</dt> <dd>
<p>This function returns geometric attributes of <var>frame</var>. The return value is an association list of the attributes listed below. All coordinate, height and width values are integers counting pixels. Note that if <var>frame</var> has not been mapped yet, (see <a href="visibility-of-frames">Visibility of Frames</a>) some of the return values may only represent approximations of the actual values—those that can be seen after the frame has been mapped. </p> <dl compact> <dt><code>outer-position</code></dt> <dd>
<p>A cons representing the absolute position of the outer <var>frame</var>, relative to the origin at position (0, 0) of <var>frame</var>’s display. </p> </dd> <dt><code>outer-size</code></dt> <dd>
<p>A cons of the outer width and height of <var>frame</var>. </p> </dd> <dt><code>external-border-size</code></dt> <dd>
<p>A cons of the horizontal and vertical width of <var>frame</var>’s external borders as supplied by the window manager. If the window manager doesn’t supply these values, Emacs will try to guess them from the coordinates of the outer and inner frame. </p> </dd> <dt><code>outer-border-width</code></dt> <dd>
<p>The width of the outer border of <var>frame</var>. The value is meaningful for non-GTK+ X builds only. </p> </dd> <dt><code>title-bar-size</code></dt> <dd>
<p>A cons of the width and height of the title bar of <var>frame</var> as supplied by the window manager or operating system. If both of them are zero, the frame has no title bar. If only the width is zero, Emacs was not able to retrieve the width information. </p> </dd> <dt><code>menu-bar-external</code></dt> <dd>
<p>If non-<code>nil</code>, this means the menu bar is external (not part of the native frame of <var>frame</var>). </p> </dd> <dt><code>menu-bar-size</code></dt> <dd>
<p>A cons of the width and height of the menu bar of <var>frame</var>. </p> </dd> <dt><code>tool-bar-external</code></dt> <dd>
<p>If non-<code>nil</code>, this means the tool bar is external (not part of the native frame of <var>frame</var>). </p> </dd> <dt><code>tool-bar-position</code></dt> <dd>
<p>This tells on which side the tool bar on <var>frame</var> is and can be one of <code>left</code>, <code>top</code>, <code>right</code> or <code>bottom</code>. The only toolkit that currently supports a value other than <code>top</code> is GTK+. </p> </dd> <dt><code>tool-bar-size</code></dt> <dd>
<p>A cons of the width and height of the tool bar of <var>frame</var>. </p> </dd> <dt><code>internal-border-width</code></dt> <dd><p>The width of the internal border of <var>frame</var>. </p></dd> </dl> </dd>
</dl> <p>The following function can be used to retrieve the edges of the outer, native and inner frame. </p> <dl> <dt id="frame-edges">Function: <strong>frame-edges</strong> <em>&optional frame type</em>
</dt> <dd>
<p>This function returns the absolute edges of the outer, native or inner frame of <var>frame</var>. <var>frame</var> must be a live frame and defaults to the selected one. The returned list has the form <code>(<var>left</var> <var>top</var> <var>right</var> <var>bottom</var>)</code> where all values are in pixels relative to the origin of <var>frame</var>’s display. For terminal frames the values returned for <var>left</var> and <var>top</var> are always zero. </p> <p>Optional argument <var>type</var> specifies the type of the edges to return: <code>outer-edges</code> means to return the outer edges of <var>frame</var>, <code>native-edges</code> (or <code>nil</code>) means to return its native edges and <code>inner-edges</code> means to return its inner edges. </p> <p>By convention, the pixels of the display at the values returned for <var>left</var> and <var>top</var> are considered to be inside (part of) <var>frame</var>. Hence, if <var>left</var> and <var>top</var> are both zero, the pixel at the display’s origin is part of <var>frame</var>. The pixels at <var>bottom</var> and <var>right</var>, on the other hand, are considered to lie immediately outside <var>frame</var>. This means that if you have, for example, two side-by-side frames positioned such that the right outer edge of the frame on the left equals the left outer edge of the frame on the right, the pixels at that edge show a part of the frame on the right. </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/Frame-Layout.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Frame-Layout.html</a>
</p>
</div>
|
