Next: , Up: Frame Geometry

29.3.1 Frame Layout

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.

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. Together, the outer width and outer height of the frame specify the outer size of that rectangle.

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 left and 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 Border
The external border 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 Size Parameters). Its width is determined by the window manager and cannot be changed by Emacs' functions.

External borders don't exist on text terminal frames. For graphical frames, their display can be suppressed by setting the override-redirect or undecorated frame parameter (see Management Parameters).

Outer Border
The outer border is a separate border whose width can be specified with the border-width frame 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 undecorated or override-redirect frames (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).

Title Bar
The title bar, a.k.a. caption 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. It can be also used for dragging the frame with the mouse. The title bar is usually not displayed for fullboth (see Size Parameters), tooltip (see Tooltips) and child frames (see Child Frames) and doesn't exist for terminal frames. Display of the title bar can be suppressed by setting the override-redirect or the undecorated frame parameters (see Management Parameters).
Menu Bar
The menu bar (see Menu Bar) 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 Windows and Frames). As a rule, menu bars are never shown on child frames (see Child Frames). Display of the menu bar can be suppressed by setting the menu-bar-lines parameter (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 change instead.

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. Tool bars are usually not shown for child frames (see Child Frames). Display of the tool bar can be suppressed by setting the tool-bar-lines parameter (see Layout Parameters) to zero.

If the variable auto-resize-tool-bars is non-nil, 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.

Native Frame
The native frame 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 native edges of the frame. Together, the native width and native height of a frame specify the native size of the frame.

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 window-edges, window-at or coordinates-in-window-p (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 override-redirect or undecorated parameter (see Management Parameters).

Internal Border
The internal border is a border drawn by Emacs around the inner frame (see below). Its width is specified by the internal-border-width frame parameter (see Layout Parameters). Its color is specified by the background of the internal-border face.
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 inner size of the rectangle. The inner frame is sometimes also referred to as the display area of the frame.

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 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 Layout Parameters. 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 and one horizontal scroll bar if specified for this 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:

— 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. 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.

outer-position
A cons representing the absolute position of the outer 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.
outer-border-width
The width of the outer border of frame. The value is meaningful for non-GTK+ X builds only.
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 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 (left top right bottom) 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-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.

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.