29.1 Basic Concepts of Emacs Windows

A window is an area of the screen that can be used to display a buffer (see Buffers). Windows are grouped into frames (see Frames). Each frame contains at least one window; the user can subdivide a frame into multiple, non-overlapping windows to view several buffers at once. Lisp programs can use multiple windows for a variety of purposes. In Rmail, for example, you can view a summary of message titles in one window, and the contents of the selected message in another window.

Emacs uses the term “window” with a different meaning than in graphical desktop environments and window systems, such as the X Window System. When Emacs is run on X, each graphical X window owned by the Emacs process corresponds to one Emacs frame. When Emacs is run on a text terminal, each Emacs frame fills the entire terminal screen. In either case, the frame may contain one or more Emacs windows. For disambiguation, we use the term window-system window when we mean the window-system window corresponding to an Emacs frame.

Unlike X windows, Emacs windows are tiled; they never overlap within the area of their frame. When a window is created, resized, or deleted, the change in window space is taken from or given to other windows on the same frame, so that the total area of the frame is unchanged.

In Emacs Lisp, windows are represented by a special Lisp object type (see Window Type).

Function: windowp object ¶

This function returns t if object is a window (whether or not it displays a buffer). Otherwise, it returns nil.

A live window is one that is actually displaying a buffer in a frame.

Function: window-live-p object ¶

This function returns t if object is a live window and nil otherwise. A live window is one that displays a buffer.

The windows in each frame are organized into a window tree. See Windows and Frames. The leaf nodes of each window tree are live windows—the ones actually displaying buffers. The internal nodes of the window tree are internal windows, which are not live.

A valid window is one that is either live or internal. A valid window can be deleted, i.e., removed from its frame (see Deleting Windows); then it is no longer valid, but the Lisp object representing it might be still referenced from other Lisp objects. A deleted window may be made valid again by restoring a saved window configuration (see Window Configurations).

You can distinguish valid windows from deleted windows with window-valid-p.

Function: window-valid-p object ¶

This function returns t if object is a live window, or an internal window in a window tree. Otherwise, it returns nil, including for the case where object is a deleted window.

The following schematic shows the structure of a live window:

        ____________________________________________
       |________________ Tab Line _______________|RD| ^
       |______________ Header Line ______________|  | |
     ^ |LS|LM|LF|                       |RF|RM|RS|  | |
     | |  |  |  |                       |  |  |  |  | |
Window |  |  |  |                       |  |  |  |  | Window
Body | |  |  |  |      Window Body      |  |  |  |  | Total
Height |  |  |  |                       |  |  |  |  | Height
     | |  |  |  |<- Window Body Width ->|  |  |  |  | |
     v |__|__|__|_______________________|__|__|__|  | |
       |_________ Horizontal Scroll Bar _________|  | |
       |_______________ Mode Line _______________|__| |
       |_____________ Bottom Divider _______________| v
        <---------- Window Total Width ------------>

At the center of that window is the body, where the buffer text is displayed. The body can be surrounded by a series of optional areas which we will call window decorations. On the left and right, from innermost to outermost, these are the left and right fringes, denoted by LF and RF (see Fringes); the left and right margins, denoted by LM and RM in the schematic (see Displaying in the Margins); the left or right vertical scroll bar, only one of which is present at any time, denoted by LS and RS (see Scroll Bars); and the right divider, denoted by RD (see Window Dividers). Together these are the window’s left and right decorations.

At the top of the window are the tab line and the header line (see Window Header Lines). The text area of the window includes the header line and the tab line, if they are present in the window. At the bottom of the window are the horizontal scroll bar (see Scroll Bars); the mode line (see Mode Line Format); and the bottom divider (see Window Dividers). Together these form the window’s top and bottom decorations.

There are two special areas omitted in the schematic:

• When any of the fringes is missing, the display engine may use one character cell in its place for showing a continuation or truncation glyph provided a text line doesn’t fit in a window.
• When both, the vertical scroll bar and the right divider are missing, the display engine usurps one pixel for drawing a vertical divider line between this window and the window on its right, provided such a window exists. On a text terminal, this divider always occupies an entire character cell.

In either case, the resulting artifact is considered part of the window’s body although its screen space cannot be used for displaying buffer text.

Note also, that line numbers (and their surrounding whitespace) as displayed by display-line-numbers-mode (see Display Custom in The GNU Emacs Manual) do not count as decorations either; they are part of the window’s body too.

Internal windows neither show any text nor do they have decorations. Hence, the concept of “body” does not make sense for them. In fact, most functions operating on the body of a window will yield an error when applied to an internal window.

By default, an Emacs frame exhibits one special live window that is used for displaying messages and accepting user input—the minibuffer window (see Minibuffer Windows). Since the minibuffer window is used for displaying text, it has a body but it does not have a tab or header line or any margins. Finally, a tooltip window which is used for displaying a tooltip in a tooltip frame (see Tooltips) has a body too but no decorations at all.