Each window belongs to exactly one frame (see Frames). For all windows belonging to a specific frame, we sometimes also say that these windows are owned by that frame or simply that they are on that frame.
This function returns the specified window’s frame—the frame
that window belongs to. If window is omitted or nil,
it defaults to the selected window (see Selecting Windows).
This function returns a list of all live windows owned by the specified
frame. If frame is omitted or nil, it defaults to
the selected frame (see Input Focus).
The optional argument minibuffer specifies whether to include the
minibuffer window (see Minibuffer Windows) in that list. If
minibuffer is t, the minibuffer window is included. If
nil or omitted, the minibuffer window is included only if it is
active. If minibuffer is neither nil nor t, the
minibuffer window is never included.
The optional argument window, if non-nil, must be a live
window on the specified frame; then window will be the first
element in the returned list. If window is omitted or nil,
the window selected within frame (see Selecting Windows) is
the first element.
Windows on the same frame are organized into a window tree, whose leaf nodes are the live windows. The internal nodes of a window tree are not live; they exist for the purpose of organizing the relationships between live windows. The root node of a window tree is called the root window. It is either a live window or an internal window. If it is a live window, then the frame has just one window besides the minibuffer window, or the frame is a minibuffer-only frame, see Frame Layout.
A minibuffer window (see Minibuffer Windows) that is not alone on
its frame does not have a parent window, so it strictly speaking is not
part of its frame’s window tree. Nonetheless, it is a sibling window of
the frame’s root window, and thus can be reached from the root window via
window-next-sibling, see below. Also, the function
window-tree described at the end of this section lists the
minibuffer window alongside the actual window tree.
This function returns the root window for frame-or-window. The
argument frame-or-window should be either a window or a frame;
if omitted or nil, it defaults to the selected frame. If
frame-or-window is a window, the return value is the root window
of that window’s frame.
When a live window is split (see Splitting Windows), there are two live windows where previously there was one. One of these is represented by the same Lisp window object as the original window, and the other is represented by a newly-created Lisp window object. Both of these live windows become leaf nodes of the window tree, as child windows of a single internal window. If necessary, Emacs automatically creates this internal window, which is also called the parent window, and assigns it to the appropriate position in the window tree. The set of windows that share the same parent are called siblings.
This function returns the parent window of window. If
window is omitted or nil, it defaults to the selected
window. The return value is nil if window has no parent
(i.e., it is a minibuffer window or the root window of its frame).
A parent window always has at least two child windows. If this number were to fall to one as a result of window deletion (see Deleting Windows), Emacs automatically deletes the parent window too, and its sole remaining child window takes its place in the window tree.
A child window can be either a live window, or an internal window (which in turn would have its own child windows). Therefore, each internal window can be thought of as occupying a certain rectangular screen area—the union of the areas occupied by the live windows that are ultimately descended from it.
For each internal window, the screen areas of the immediate children are arranged either vertically or horizontally (never both). If the child windows are arranged one above the other, they are said to form a vertical combination; if they are arranged side by side, they are said to form a horizontal combination. Consider the following example:
______________________________________
| ______ ____________________________ |
|| || __________________________ ||
|| ||| |||
|| ||| |||
|| ||| |||
|| |||____________W4____________|||
|| || __________________________ ||
|| ||| |||
|| ||| |||
|| |||____________W5____________|||
||__W2__||_____________W3_____________ |
|__________________W1__________________|
The root window of this frame is an internal window, W1. Its child windows form a horizontal combination, consisting of the live window W2 and the internal window W3. The child windows of W3 form a vertical combination, consisting of the live windows W4 and W5. Hence, the live windows in this window tree are W2, W4, and W5.
The following functions can be used to retrieve a child window of an internal window, and the siblings of a child window. Their window argument always defaults to the selected window (see Selecting Windows).
This function returns the topmost child window of window, if
window is an internal window whose children form a vertical
combination. For any other type of window, the return value is
nil.
This function returns the leftmost child window of window, if
window is an internal window whose children form a horizontal
combination. For any other type of window, the return value is
nil.
This function returns the first child window of the internal window
window—the topmost child window for a vertical combination, or
the leftmost child window for a horizontal combination. If
window is a live window, the return value is nil.
This function returns a non-nil value if and only if
window is part of a vertical combination.
If the optional argument horizontal is non-nil, this
means to return non-nil if and only if window is part of
a horizontal combination.
This function returns the next sibling of the specified window. The
return value is nil if window is the last child of its
parent.
This function returns the previous sibling of the specified window.
The return value is nil if window is the first child of its
parent.
The functions window-next-sibling and window-prev-sibling
should not be confused with the functions next-window and
previous-window, which return the next and previous window in the
cyclic ordering of windows (see Cyclic Ordering of Windows).
The following functions can be useful to locate a window within its frame.
This function returns the live window at the upper left corner of the
frame specified by frame-or-window. The argument
frame-or-window must denote a window or a live frame and defaults
to the selected frame. If frame-or-window specifies a window,
this function returns the first window on that window’s frame. Under
the assumption that the frame from our canonical example is selected
(frame-first-window) returns W2.
This function returns t if window is located at
side of its containing frame. The argument window must be
a valid window and defaults to the selected one. The argument
side can be any of the symbols left, top,
right or bottom. The default value nil is
handled like bottom.
Note that this function disregards the minibuffer window
(see Minibuffer Windows). Hence, with side equal to
bottom it may return t also when the minibuffer window
appears right below window.
This function returns the nearest live window in direction
direction as seen from the position of window-point in
window window. The argument direction must be one of
above, below, left or right. The optional
argument window must denote a live window and defaults to the
selected one.
This function does not return a window whose no-other-window
parameter is non-nil (see Window Parameters). If the nearest
window’s no-other-window parameter is non-nil, this
function tries to find another window in the indicated direction whose
no-other-window parameter is nil. If the optional
argument ignore is non-nil, a window may be returned even
if its no-other-window parameter is non-nil.
If the optional argument sign is a negative number, it means to
use the right or bottom edge of window as reference position
instead of window-point. If sign is a positive number, it
means to use the left or top edge of window as reference position.
If the optional argument wrap is non-nil, this means to
wrap direction around frame borders. For example, if window
is at the top of the frame and direction is above, then
this function usually returns the frame’s minibuffer window if it’s
active and a window at the bottom of the frame otherwise.
If the optional argument minibuf is t, this function may
return the minibuffer window even when it’s not active. If the
optional argument minibuf is nil, this means to return
the minibuffer window if and only if it is currently active.
If minibuf is neither nil nor t, this function
never returns the minibuffer window. However, if wrap is
non-nil, it always acts as if minibuf were nil.
If it doesn’t find a suitable window, this function returns
nil.
Don’t use this function to check whether there is no window in
direction. Calling window-at-side-p described above is a
much more efficient way to do that.
The following function retrieves the entire window tree of a frame:
This function returns a list representing the window tree for frame
frame. If frame is omitted or nil, it defaults to
the selected frame.
The return value is a list of the form (root mini),
where root represents the window tree of the frame’s root
window, and mini is the frame’s minibuffer window.
If the root window is live, root is that window itself.
Otherwise, root is a list (dir edges w1
w2 ...) where dir is nil for a horizontal
combination and t for a vertical combination, edges gives
the size and position of the combination, and the remaining elements
are the child windows. Each child window may again be a window object
(for a live window) or a list with the same format as above (for an
internal window). The edges element is a list (left
top right bottom), similar to the value returned by
window-edges (see Coordinates and Windows).