elisp: Windows and Frames
27.2 Windows and Frames
=======================
Each window belongs to exactly one frame (
Frames).
-- Function: window-frame &optional window
This function returns the frame that the window WINDOW belongs to.
If WINDOW is ‘nil’, it defaults to the selected window.
-- Function: window-list &optional frame minibuffer window
This function returns a list of live windows belonging to the frame
FRAME. If FRAME is omitted or ‘nil’, it defaults to the selected
frame.
The optional argument MINIBUFFER specifies whether to include the
minibuffer window in the returned list. If MINIBUFFER is ‘t’, the
minibuffer window is included. If MINIBUFFER is ‘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’, should 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 the frame is the first element.
Windows in 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 can be either a live window (if the frame has just
one window), or an internal window.
A minibuffer window (Minibuffer Windows) is not part of its
frame’s window tree unless the frame is a minibuffer-only frame.
Nonetheless, most of the functions in this section accept the minibuffer
window as an argument. Also, the function ‘window-tree’ described at
the end of this section lists the minibuffer window alongside the actual
window tree.
-- Function: frame-root-window &optional frame-or-window
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 window is split, 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. A set of windows that share
the same parent are called “siblings”.
-- Function: window-parent &optional window
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).
Each internal window always has at least two child windows. If this
number falls to one as a result of window deletion, Emacs automatically
deletes the internal window, and its sole remaining child window takes
its place in the window tree.
Each 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.
-- Function: window-top-child &optional window
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’.
-- Function: window-left-child &optional window
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’.
-- Function: window-child window
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’.
-- Function: window-combined-p &optional window horizontal
This function returns a non-‘nil’ value if and only if WINDOW is
part of a vertical combination. If WINDOW is omitted or ‘nil’, it
defaults to the selected one.
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.
-- Function: window-next-sibling &optional window
This function returns the next sibling of the window WINDOW. If
omitted or ‘nil’, WINDOW defaults to the selected window. The
return value is ‘nil’ if WINDOW is the last child of its parent.
-- Function: window-prev-sibling &optional window
This function returns the previous sibling of the window WINDOW.
If omitted or ‘nil’, WINDOW defaults to the selected 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, respectively, in the cyclic
ordering of windows (Cyclic Window Ordering).
You can use the following functions to find the first live window on
a frame and the window nearest to a given window.
-- Function: frame-first-window &optional frame-or-window
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.
-- Function: window-in-direction direction &optional window ignore sign
wrap mini
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’ (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 MINI is ‘nil’, this means to return the
minibuffer window if and only if it is currently active. If MINI
is non-‘nil’, this function may return the minibuffer window even
when it’s not active. However, if WRAP is non-‘nil’, it always
acts as if MINI were ‘nil’.
If it doesn’t find a suitable window, this function returns ‘nil’.
The following function allows the entire window tree of a frame to be
retrieved:
-- Function: window-tree &optional 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’
(Coordinates and Windows).
Info Catalog
elisp: Basic Windows
elisp: Windows
elisp: Window Sizes