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 (see Position Parameters) as well as the functions frame-position and set-frame-position (see 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 (see 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 (see 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 (see Frame Titles) as well as buttons for minimizing, maximizing and deleting the frame. The title bar is usually not displayed on fullboth (see Size Parameters) or tooltip frames. Title bars don’t exist for text terminal frames.

‘Menu Bar’

The menu bar (see 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 (see Windows and Frames).

‘Tool Bar’

Like the menu bar, the tool bar (see 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 (see Mouse Position) and for functions dealing with the position of windows like window-edges, window-at or coordinates-in-window-p (see Coordinates and Windows).

‘Internal Border’

The internal border (see 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 (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 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.