elisp: Frame Layout
28.3.1 Frame Layout
-------------------
The drawing below sketches the layout of a frame on a graphical
terminal:
<------------ Outer Frame Width ----------->
___________________________________________
^(0) ___________ External 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 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:
‘Outer Frame’
The “outer frame” is a rectangle comprising all areas shown in the
drawing. The edges of that rectangle are called the “outer edges”
of the frame. The “outer width” and “outer height” of the frame
specify the size of that rectangle.
The upper left corner of the outer frame (indicated by ‘(0)’ in the
drawing above) is the “outer position” or the frame. It is
specified by and settable via the ‘left’ and ‘top’ frame parameters
(
Position Parameters) as well as the functions
‘frame-position’ and ‘set-frame-position’ (Size and
Position).
‘External Border’
The “external border” is part of the decorations supplied by the
window manager. It’s typically used for resizing the frame with
the mouse. The external border is normally not shown on “fullboth”
and maximized frames (Size Parameters) and doesn’t exist
for text terminal frames.
The external border should not be confused with the “outer border”
specified by the ‘border-width’ frame parameter (Layout
Parameters). Since the outer border is usually ignored on most
platforms it is not covered here.
‘Title Bar’
The “title bar” is also part of the window manager’s decorations
and typically displays the title of the frame (Frame
Titles) as well as buttons for minimizing, maximizing and
deleting the frame. The title bar is usually not displayed on
fullboth (Size Parameters) or tooltip frames. Title bars
don’t exist for text terminal frames.
‘Menu Bar’
The menu bar (Menu Bar) can be either internal (drawn by
Emacs itself) or external (drawn by a toolkit). Most builds (GTK+,
Lucid, Motif and 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 (Windows and Frames).
‘Tool Bar’
Like the menu bar, the tool bar (Tool Bar) 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.
‘Native Frame’
The “native frame” is a rectangle located entirely within the outer
frame. It excludes the areas occupied by the external border, the
title bar and any external menu or external tool bar. The area
enclosed by the native frame is sometimes also referred to as the
“display area” of the frame. The edges of the native frame are
called the “native edges” of the frame. The “native width” and
“native height” of the frame specify the size of the rectangle.
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:
(1) non-toolkit and terminal frames
(2) Lucid, Motif and Windows frames
(3) GTK+ and NS frames
Accordingly, the native height of a frame includes the height of
the tool bar but not that of the menu bar (Lucid, Motif, 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 of
functions that set or return the current position of the mouse
(Mouse Position) and for functions dealing with the
position of windows like ‘window-edges’, ‘window-at’ or
‘coordinates-in-window-p’ (Coordinates and Windows).
‘Internal Border’
The internal border (Layout Parameters) is a border drawn
by Emacs around the inner frame (see below).
‘Inner Frame’
The “inner frame” 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 “inner
edges” of the frame. The “inner width” and “inner height” specify
the size of the rectangle.
As a rule, the inner frame is subdivided into the frame’s root
window (Windows and Frames) and the frame’s minibuffer
window (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 configurations.
‘Text Area’
The “text area” of a frame is a somewhat fictitious area located
entirely within the native frame. It can be obtained by removing
from the native frame any internal borders, one vertical and one
horizontal scroll bar, and one left and one right fringe as
specified for this frame, see Layout Parameters.
The “absolute position” of a frame or its edges is usually given in
terms of pixels counted from an origin at position (0, 0) of the frame’s
display. Note that with multiple monitors the origin does not
necessarily coincide with the top left corner of the entire usable
display area. Hence the absolute outer position of a frame or the
absolute positions of the edges of the outer, native or inner frame can
be negative in such an environment even when that frame is completely
visible.
For a frame on a graphical terminal the following function returns
the sizes of the areas described above:
-- Function: frame-geometry &optional frame
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.
‘outer-position’
A cons of the absolute X- and Y-coordinates of the outer
position of FRAME, relative to the origin at position (0, 0)
of FRAME’s display.
‘outer-size’
A cons of the outer width and height of FRAME.
‘external-border-size’
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.
‘title-bar-size’
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.
‘menu-bar-external’
If non-‘nil’, this means the menu bar is external (not part of
the native frame of FRAME).
‘menu-bar-size’
A cons of the width and height of the menu bar of FRAME.
‘tool-bar-external’
If non-‘nil’, this means the tool bar is external (not part of
the native frame of FRAME).
‘tool-bar-position’
This tells on which side the tool bar on FRAME is and can be
one of ‘left’, ‘top’, ‘right’ or ‘bottom’. The only toolkit
that currently supports a value other than ‘top’ is GTK+.
‘tool-bar-size’
A cons of the width and height of the tool bar of FRAME.
‘internal-border-width’
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.
-- Function: frame-edges &optional frame type
This function returns the edges of the outer, native or inner frame
of FRAME. FRAME must be a live frame and defaults to the selected
one. The list returned has the form (LEFT TOP RIGHT BOTTOM) where
all values are in pixels relative to the position (0, 0) of FRAME’s
display. For terminal frames LEFT and TOP are both zero.
Optional argument TYPE specifies the type of the edges to return:
TYPE ‘outer-edges’ means to return the outer edges of FRAME,
‘native-edges’ (or ‘nil’) means to return its native edges and
‘inner-edges’ means to return its inner edges.
Notice that the pixels at the positions BOTTOM and RIGHT lie
immediately outside the corresponding 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 representing that edge
are part of the frame on the right.
Info Catalog
elisp: Frame Geometry
elisp: Frame Font