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:
<------------ Outer Frame Width -----------> ____________________________________________ ^(0) ________ External/Outer Border _______ | | | |_____________ Title Bar ______________| | | | (1)_____________ Menu Bar ______________| | ^ | | (2)_____________ Tool Bar ______________| | ^ | | (3) _________ 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 -------->
In practice not all of the areas shown in the drawing will or may be present. The meaning of these areas is described below.
Knowing the outer size of a frame is useful for fitting a frame into the working area of its display (see Multiple Terminals) 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 Visibility of Frames) 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.
The position of the upper left corner of the outer frame (indicated by ‘(0)’ in the drawing above) is the outer position 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.
The outer position is specified by and can be set via the
top frame parameters (see Position Parameters). 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 Child Frames) 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.
External borders don't exist on text terminal frames. For graphical
frames, their display can be suppressed by setting the
undecorated frame parameter
(see Management Parameters).
border-widthframe parameter (see Layout Parameters). 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 Tooltips), child frames (see Child Frames) and
override-redirectframes (see Management Parameters).
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
border-color frame parameter (see Layout Parameters).
undecoratedframe parameters (see Management Parameters).
menu-bar-linesparameter (see Layout Parameters) to zero.
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
tool-bar-linesparameter (see Layout Parameters) to zero.
If the variable
auto-resize-tool-bars is non-
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.
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.
The position of the top left corner of the native frame specifies the native position of the frame. (1)–(3) in the drawing above indicate that position for the various builds:
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).
The native position of a frame is the reference position for functions
that set or return the current position of the mouse (see Mouse Position) and for functions dealing with the position of windows like
(see Coordinates and Windows). It also specifies the (0, 0) origin
for locating and positioning child frames within this frame
(see Child Frames).
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
parameter (see Management Parameters).
internal-border-widthframe parameter (see Layout Parameters). Its color is specified by the background of the
As a rule, the inner frame is subdivided into the frame's root window
(see Windows and Frames) and the frame's minibuffer window
(see Minibuffer Windows). There are two notable exceptions to this
rule: A minibuffer-less frame contains a root window only and does
not contain a minibuffer window. A minibuffer-only frame contains
only a minibuffer window which also serves as that frame's root window.
See Initial Parameters for how to create such frame
The absolute position 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 absolute edges of a frame are given as pixel offsets from that origin.
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.
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.
For a frame on a graphical terminal the following function returns the sizes of the areas described above:
This function returns geometric attributes of frame. 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 frame has not been mapped yet, (see Visibility of Frames) some of the return values may only represent approximations of the actual values—those that can be seen after the frame has been mapped.
- A cons representing the absolute position of the outer frame, relative to the origin at position (0, 0) of frame's display.
- A cons of the outer width and height of frame.
- A cons of the horizontal and vertical width of frame'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.
- The width of the outer border of frame. The value is meaningful for non-GTK+ X builds only.
- A cons of the width and height of the title bar of frame 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.
- If non-
nil, this means the menu bar is external (not part of the native frame of frame).
- A cons of the width and height of the menu bar of frame.
- If non-
nil, this means the tool bar is external (not part of the native frame of frame).
- This tells on which side the tool bar on frame is and can be one of
bottom. The only toolkit that currently supports a value other than
- A cons of the width and height of the tool bar of frame.
- The width of the internal border of frame.
The following function can be used to retrieve the edges of the outer, native and inner frame.
This function returns the absolute edges of the outer, native or inner frame of frame. frame must be a live frame and defaults to the selected one. The returned list has the form
)where all values are in pixels relative to the origin of frame's display. For terminal frames the values returned for left and top are always zero.
Optional argument type specifies the type of the edges to return:
outer-edgesmeans to return the outer edges of frame,
nil) means to return its native edges and
inner-edgesmeans to return its inner edges.
By convention, the pixels of the display at the values returned for left and top are considered to be inside (part of) frame. Hence, if left and top are both zero, the pixel at the display's origin is part of frame. The pixels at bottom and right, on the other hand, are considered to lie immediately outside frame. 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.