21.3 Window Hierarchy

If a frame contains multiple windows (panes), they are always created by splitting an existing window along the horizontal or vertical axis. Terminology is a bit confusing here: to split a window horizontally means to create two side-by-side windows, i.e. to make a vertical cut in a window. Likewise, to split a window vertically means to create two windows, one above the other, by making a horizontal cut.

If you split a window and then split again along the same axis, you will end up with a number of panes all arranged along the same axis. The precise way in which the splits were made should not be important, and this is reflected internally. Internally, all windows are arranged in a tree, consisting of two types of windows, combination windows (which have children, and are covered completely by those children) and leaf windows, which have no children and are visible. Every combination window has two or more children, all arranged along the same axis. There are (logically) two subtypes of windows, depending on whether their children are horizontally or vertically arrayed. There is always one root window, which is either a leaf window (if the frame contains only one window) or a combination window (if the frame contains more than one window). In the latter case, the root window will have two or more children, either horizontally or vertically arrayed, and each of those children will be either a leaf window or another combination window.

Here are some rules:

1. Horizontal combination windows can never have children that are horizontal combination windows; same for vertical.
2. Only leaf windows can be split (obviously) and this splitting does one of two things: (a) turns the leaf window into a combination window and creates two new leaf children, or (b) turns the leaf window into one of the two new leaves and creates the other leaf. Rule (1) dictates which of these two outcomes happens.
3. Every combination window must have at least two children.
4. Leaf windows can never become combination windows. They can be deleted, however. If this results in a violation of (3), the parent combination window also gets deleted.
5. All functions that accept windows must be prepared to accept combination windows, and do something sane (e.g. signal an error if so). Combination windows do escape to the Lisp level.
6. All windows have three fields governing their contents: these are hchild (a list of horizontally-arrayed children), vchild (a list of vertically-arrayed children), and buffer (the buffer contained in a leaf window). Exactly one of these will be non-nil. Remember that horizontally-arrayed means “side-by-side” and vertically-arrayed means one above the other.
7. Leaf windows also have markers in their start (the first buffer position displayed in the window) and pointm (the window’s stashed value of point—see above) fields, while combination windows have nil in these fields.
8. The list of children for a window is threaded through the next and prev fields of each child window.
9. Deleted windows can be undeleted. This happens as a result of restoring a window configuration, and is unlike frames, displays, and consoles, which, once deleted, can never be restored. Deleting a window does nothing except set a special dead bit to 1 and clear out the next, prev, hchild, and vchild fields, for GC purposes.
10. Most frames actually have two top-level windows—one for the minibuffer and one (the root) for everything else. The modeline (if present) separates these two. The next field of the root points to the minibuffer, and the prev field of the minibuffer points to the root. The other next and prev fields are nil, and the frame points to both of these windows. Minibuffer-less frames have no minibuffer window, and the next and prev of the root window are nil. Minibuffer-only frames have no root window, and the next of the minibuffer window is nil but the prev points to itself. (#### This is an artifact that should be fixed.)