@cindex selected window
At any time, one Emacs window is the @dfn{selected window}; the
-buffer this window is displaying is the current buffer. The terminal's
-cursor shows the location of point in this window. Each other window
-has a location of point as well. On text-only terminals, there is no
-way to show where those locations are, since the terminal has only one
-cursor. On a graphical display, the location of point in a
-non-selected window is indicated by a hollow box; the cursor in the
-selected window is blinking or solid.
-
- Commands to move point affect the value of point for the selected Emacs
-window only. They do not change the value of point in other Emacs
-windows, even those showing the same buffer. The same is true for commands
-such as @kbd{C-x b} to switch buffers in the selected window;
-they do not affect other windows at all. However, there are other commands
-such as @kbd{C-x 4 b} that select a different window and switch buffers in
-it. Also, all commands that display information in a window, including
+buffer this window is displaying is the current buffer. Each window
+has its own value of point. On graphical displays, the point is
+indicated by a solid blinking cursor in the selected window, and by a
+hollow box in non-selected windows. On text-only terminals, the
+cursor is drawn only in the selected window. @xref{Cursor Display}.
+
+ Commands to move point affect the value of point for the selected
+Emacs window only. They do not change the value of point in other
+Emacs windows, even those showing the same buffer. The same is true
+for buffer-switching commands such as @kbd{C-x b}; they do not affect
+other windows at all. However, there are other commands such as
+@kbd{C-x 4 b} that select a different window and switch buffers in it.
+Also, all commands that display information in a window, including
(for example) @kbd{C-h f} (@code{describe-function}) and @kbd{C-x C-b}
-(@code{list-buffers}), work by switching buffers in a nonselected window
-without affecting the selected window.
+(@code{list-buffers}), work by switching buffers in a nonselected
+window without affecting the selected window.
When multiple windows show the same buffer, they can have different
regions, because they can have different values of point. However,
Each window has its own mode line, which displays the buffer name,
modification status and major and minor modes of the buffer that is
displayed in the window. The selected window's mode line appears in a
-different color. @xref{Mode Line}, for full details on the mode line.
+different color. @xref{Mode Line}, for details.
@node Split Window
@section Splitting Windows
@table @kbd
@item C-x 2
Split the selected window into two windows, one above the other
-(@code{split-window-vertically}).
+(@code{split-window-below}).
@item C-x 3
-Split the selected window into two windows positioned side by side
-(@code{split-window-horizontally}).
+Split the selected window into two windows, positioned side by side
+(@code{split-window-right}).
@item C-Mouse-2
In the mode line or scroll bar of a window, split that window.
@end table
@kindex C-x 2
-@findex split-window-vertically
- The command @kbd{C-x 2} (@code{split-window-vertically}) breaks the
-selected window into two windows, one above the other. Both windows start
-out displaying the same buffer, with the same value of point. By default
-the two windows each get half the height of the window that was split; a
-numeric argument specifies how many lines to give to the top window.
+@findex split-window-below
+ @kbd{C-x 2} (@code{split-window-below}) splits the selected window
+into two windows, one above the other. After splitting, the selected
+window is the upper one, and the newly split-off window is below.
+Both windows have the same value of point as before, and display the
+same portion of the buffer (or as close to it as possible). If
+necessary, the windows are scrolled to keep point on-screen. By
+default, the two windows each get half the height of the original
+window. A positive numeric argument specifies how many lines to give
+to the top window; a negative numeric argument specifies how many
+lines to give to the bottom window.
-@kindex C-x 3
-@findex split-window-horizontally
- @kbd{C-x 3} (@code{split-window-horizontally}) breaks the selected
-window into two side-by-side windows. A numeric argument specifies how
-many columns to give the one on the left. If you are not using
-scrollbars, a vertical line separates the two windows.
-You can customize its color with the face @code{vertical-border}.
-Windows that are not the full width of the screen have mode lines, but
-they are truncated. On terminals where Emacs does not support
-highlighting, truncated mode lines sometimes do not appear in inverse
-video.
+@vindex split-window-keep-point
+ If you change the variable @code{split-window-keep-point} to
+@code{nil}, @kbd{C-x 2} instead adjusts the portion of the buffer
+displayed by the two windows, as well as the value of point in each
+window, in order to keep the text on the screen as close as possible
+to what it was before; furthermore, if point was in the lower half of
+the original window, the bottom window is selected instead of the
+upper one.
-@kindex C-Mouse-2 @r{(scroll bar)}
- You can split a window horizontally or vertically by clicking
-@kbd{C-Mouse-2} in the mode line or the scroll bar. The line of
-splitting goes through the place where you click: if you click on the
-mode line, the new scroll bar goes above the spot; if you click in the
-scroll bar, the mode line of the split window is side by side with
-your click.
+@kindex C-x 3
+@findex split-window-right
+ @kbd{C-x 3} (@code{split-window-right}) splits the selected window
+into two side-by-side windows. The left window is the selected one;
+the right window displays the same portion of the same buffer, and has
+the same value of point. A positive numeric argument specifies how
+many columns to give the left window; a negative numeric argument
+specifies how many columns to give the right window.
@vindex truncate-partial-width-windows
- When a window occupies less than the full width of the frame, it may
-become too narrow for most of the text lines in its buffer. If most of
-its lines are continued (@pxref{Continuation Lines}), the buffer may
-become difficult to read. Therefore, Emacs automatically truncates
-lines if the window width becomes narrower than 50 columns. This
-truncation occurs regardless of the value of the variable
-@code{truncate-lines} (@pxref{Line Truncation}); it is instead
-controlled by the variable @code{truncate-partial-width-windows}. If
-the value of @code{truncate-partial-width-windows} is a positive integer
-(the default is 50), that specifies the minimum width for a
-partial-width window before automatic line truncation occurs; if the
-value is @code{nil}, automatic line truncation is disabled; and for any
-other non-@code{nil} value, Emacs truncates lines in every partial-width
-window regardless of its width.
-
- Horizontal scrolling is often used in side-by-side windows.
-@xref{Horizontal Scrolling}.
+ When you split a window with @kbd{C-x 3}, each resulting window
+occupies less than the full width of the frame. If it becomes too
+narrow, the buffer may be difficult to read if continuation lines are
+in use (@pxref{Continuation Lines}). Therefore, Emacs automatically
+switches to line truncation if the window width becomes narrower than
+50 columns. This truncation occurs regardless of the value of the
+variable @code{truncate-lines} (@pxref{Line Truncation}); it is
+instead controlled by the variable
+@code{truncate-partial-width-windows}. If the value of this variable
+is a positive integer (the default is 50), that specifies the minimum
+width for a partial-width window before automatic line truncation
+occurs; if the value is @code{nil}, automatic line truncation is
+disabled; and for any other non-@code{nil} value, Emacs truncates
+lines in every partial-width window regardless of its width.
+
+ On text terminals, side-by-side windows are separated by a vertical
+divider which is drawn using the @code{vertical-border} face.
-@vindex split-window-keep-point
- If @code{split-window-keep-point} is non-@code{nil}, the default,
-both of the windows resulting from @kbd{C-x 2} inherit the value of
-point from the window that was split. This means that scrolling is
-inevitable. If this variable is @code{nil}, then @kbd{C-x 2} tries to
-avoid scrolling the text currently visible on the screen, by putting
-point in each window at a position already visible in the window. It
-also selects whichever window contains the screen line that the cursor
-was previously on. Some users prefer that mode on slow terminals.
+@kindex C-Mouse-2 @r{(scroll bar)}
+ You can also split a window horizontally or vertically by clicking
+@kbd{C-Mouse-2} in the mode line or the scroll bar. If you click on
+the mode line, that puts the vertical divider where you click; if you
+click in the scroll bar, that puts the new mode-line where you click.
@node Other Window
@section Using Other Windows
@table @kbd
@item C-x o
-Select another window (@code{other-window}). That is @kbd{o}, not zero.
+Select another window (@code{other-window}).
@item C-M-v
Scroll the next window (@code{scroll-other-window}).
-@item M-x compare-windows
-Find next place where the text in the selected window does not match
-the text in the next window.
@item Mouse-1
-@kbd{Mouse-1}, in a window's mode line, selects that window
-but does not move point in it (@code{mouse-select-window}).
+@kbd{Mouse-1}, in the text area of a window, selects the window and
+moves point to the position clicked. Clicking in the mode line
+selects the window without moving point in it.
@end table
@kindex C-x o
@findex other-window
- To select a different window, click with @kbd{Mouse-1} on its mode
-line. With the keyboard, you can switch windows by typing @kbd{C-x o}
+With the keyboard, you can switch windows by typing @kbd{C-x o}
(@code{other-window}). That is an @kbd{o}, for ``other,'' not a zero.
When there are more than two windows, this command moves through all the
windows in a cyclic order, generally top to bottom and left to right.
window only, but there is one command to scroll the next window.
@kbd{C-M-v} (@code{scroll-other-window}) scrolls the window that
@kbd{C-x o} would select. It takes arguments, positive and negative,
-like @kbd{C-v}. (In the minibuffer, @kbd{C-M-v} scrolls the window
-that contains the minibuffer help display, if any, rather than the
-next window in the standard cyclic order.)
-
- The command @kbd{M-x compare-windows} lets you compare two files or
-buffers visible in two windows, by moving through them to the next
-mismatch. @xref{Comparing Files}, for details.
+like @kbd{C-v}. (In the minibuffer, @kbd{C-M-v} scrolls the help
+window associated with the minibuffer, if any, rather than the next
+window in the standard cyclic order; @pxref{Minibuffer Edit}.)
@vindex mouse-autoselect-window
If you set @code{mouse-autoselect-window} to a non-@code{nil} value,
-moving the mouse into a different window selects that window. This
+moving the mouse over a different window selects that window. This
feature is off by default.
@node Pop Up Window
@table @kbd
@item C-x 0
-Delete the selected window (@code{delete-window}). The last character
-in this key sequence is a zero.
+Delete the selected window (@code{delete-window}).
@item C-x 1
Delete all windows in the selected frame except the selected window
(@code{delete-other-windows}).
@kindex C-x 0
@findex delete-window
- To delete a window, type @kbd{C-x 0} (@code{delete-window}). (That is
-a zero.) The space occupied by the deleted window is given to an
-adjacent window (but not the minibuffer window, even if that is active
-at the time). Once a window is deleted, its attributes are forgotten;
-only restoring a window configuration can bring it back. Deleting the
+ To delete the selected window, type @kbd{C-x 0}
+(@code{delete-window}). (That is a zero.) Once a window is deleted,
+the space that it occupied is given to an adjacent window (but not the
+minibuffer window, even if that is active at the time). Deleting the
window has no effect on the buffer it used to display; the buffer
-continues to exist, and you can select it in any window with @kbd{C-x
-b}.
+continues to exist, and you can still switch to with @kbd{C-x b}.
@findex kill-buffer-and-window
@kindex C-x 4 0
@kindex C-x 1
@findex delete-other-windows
- @kbd{C-x 1} (@code{delete-other-windows}) is more powerful in a
-different way; it deletes all the windows except the selected one (and
-the minibuffer); the selected window expands to use the whole frame
-except for the echo area.
+ @kbd{C-x 1} (@code{delete-other-windows}) deletes all the windows,
+@emph{except} the selected one; the selected window expands to use the
+whole frame. (This command cannot be used while the minibuffer window
+is active; attempting to do so signals an error.)
@kindex C-x ^
@findex enlarge-window
@kindex C-x @}
-@findex enlarge-window-horizontally
@vindex window-min-height
+ The command @kbd{C-x ^} (@code{enlarge-window}) makes the selected
+window one line taller, taking space from a vertically adjacent window
+without changing the height of the frame. With a positive numeric
+argument, this command increases the window height by that many lines;
+with a negative argument, it reduces the height by that many lines.
+If there are no vertically adjacent windows (i.e. the window is at the
+full frame height), that signals an error. The command also signals
+an error if you attempt to reduce the height of any window below a
+certain minimum number of lines, specified by the variable
+@code{window-min-height} (the default is 4).
+
+@findex enlarge-window-horizontally
+@findex shrink-window-horizontally
@vindex window-min-width
- To readjust the division of space among vertically adjacent windows,
-use @kbd{C-x ^} (@code{enlarge-window}). It makes the currently
-selected window one line bigger, or as many lines as is specified
-with a numeric argument. With a negative argument, it makes the
-selected window smaller. @kbd{C-x @}}
-(@code{enlarge-window-horizontally}) makes the selected window wider by
-the specified number of columns. @kbd{C-x @{}
-(@code{shrink-window-horizontally}) makes the selected window narrower
-by the specified number of columns.
-
- When you make a window bigger, the space comes from its peers. If
-this makes any window too small, it is deleted and its space is given
-to an adjacent window. The minimum size is specified by the variables
-@code{window-min-height} and @code{window-min-width}.
+ Similarly, @kbd{C-x @}} (@code{enlarge-window-horizontally}) makes
+the selected window wider, and @kbd{C-x @{}
+(@code{shrink-window-horizontally}) makes it narrower. These commands
+signal an error if you attempt to reduce the width of any window below
+a certain minimum number of columns, specified by the variable
+@code{window-min-width} (the default is 10).
@kindex C-x -
@findex shrink-window-if-larger-than-buffer
@section Displaying a Buffer in a Window
It is a common Emacs operation to display or ``pop up'' some buffer
-in response to a user command. There are several different ways by
+in response to a user command. There are several different ways in
which commands do this.
Many commands, like @kbd{C-x C-f} (@code{find-file}), display the
@findex display-buffer
Some commands try to display ``intelligently'', trying not to take
-over the selected window, e.g. by splitting the selected window and
-displaying the desired buffer in the child window. Such commands,
-which include the various help commands (@pxref{Help}), work by
-calling @code{display-buffer} internally. @xref{Window Choice}, for
-details.
+over the selected window, e.g. by splitting off a new window and
+displaying the desired buffer there. Such commands, which include the
+various help commands (@pxref{Help}), work by calling
+@code{display-buffer} internally. @xref{Window Choice}, for details.
Other commands do the same as @code{display-buffer}, and
additionally select the displaying window so that you can begin
editing its buffer. The command @kbd{C-x `} (@code{next-error}) is
one example (@pxref{Compilation Mode}). Such commands work by calling
-@code{pop-to-buffer} internally. @xref{Switching Buffers,,Switching
-to a Buffer in a Window, elisp, The Emacs Lisp Reference Manual}.
+the function @code{pop-to-buffer} internally. @xref{Switching
+Buffers,,Switching to a Buffer in a Window, elisp, The Emacs Lisp
+Reference Manual}.
Commands with names ending in @code{-other-window} behave like
@code{display-buffer}, except that they never display in the selected
@findex display-buffer
The @code{display-buffer} command (as well as commands that call it
-internally) chooses a window to display using the following steps:
+internally) chooses a window to display by following the steps given
+below. @xref{Choosing Window,,Choosing a Window for Display, elisp,
+The Emacs Lisp Reference Manual}, for details about how to alter this
+sequence of steps.
@itemize
@vindex same-window-buffer-names
@cindex mode, Winner
@cindex undoing window configuration changes
@cindex window configuration changes, undoing
- @kbd{M-x winner-mode} is a global minor mode that records the
-changes in the window configuration (i.e. how the frames are
-partitioned into windows), so that you can ``undo'' them. To undo,
-use @kbd{C-c left} (@code{winner-undo}). If you change your mind
-while undoing, you can redo the changes you had undone using @kbd{C-c
-right} (@code{M-x winner-redo}). Another way to enable Winner mode is
-by customizing the variable @code{winner-mode}.
+ Winner mode is a global minor mode that records the changes in the
+window configuration (i.e. how the frames are partitioned into
+windows), so that you can ``undo'' them. You can toggle Winner mode
+with @kbd{M-x winner-mode}, or by customizing the variable
+@code{winner-mode}. When the mode is enabled, @kbd{C-c left}
+(@code{winner-undo}) undoes the last window configuration change. If
+you change your mind while undoing, you can redo the changes you had
+undone using @kbd{C-c right} (@code{M-x winner-redo}).
+
+ Follow mode (@kbd{M-x follow-mode}) synchronizes several windows on
+the same buffer so that they always display adjacent sections of that
+buffer. @xref{Follow Mode}.
@cindex Windmove package
@cindex directional window selection
@findex windmove-right
@findex windmove-default-keybindings
- The Windmove commands move directionally between neighboring windows in
-a frame. @kbd{M-x windmove-right} selects the window immediately to the
-right of the currently selected one, and similarly for the ``left,'' ``up,''
-and ``down'' counterparts. @kbd{M-x windmove-default-keybindings} binds
-these commands to @kbd{S-right} etc. (Not all terminals support shifted
-arrow keys, however.)
+ The Windmove package defines commands for moving directionally
+between neighboring windows in a frame. @kbd{M-x windmove-right}
+selects the window immediately to the right of the currently selected
+one, and similarly for the ``left,'' ``up,'' and ``down''
+counterparts. @kbd{M-x windmove-default-keybindings} binds these
+commands to @kbd{S-right} etc.; doing so disables shift selection for
+those keys (@pxref{Shift Selection}).
- Follow minor mode (@kbd{M-x follow-mode}) synchronizes several
-windows on the same buffer so that they always display adjacent
-sections of that buffer. @xref{Follow Mode}.
+ The command @kbd{M-x compare-windows} lets you compare the text
+shown in different windows. @xref{Comparing Files}.
@vindex scroll-all-mode
@cindex scrolling windows together
@cindex Scroll-all mode
@cindex mode, Scroll-all
- @kbd{M-x scroll-all-mode} provides commands to scroll all visible
-windows together. You can also turn it on by customizing the variable
-@code{scroll-all-mode}. The commands provided are @kbd{M-x
-scroll-all-scroll-down-all}, @kbd{M-x scroll-all-page-down-all} and
-their corresponding ``up'' equivalents. To make this mode useful,
-you should bind these commands to appropriate keys.
+ Scroll All mode (@kbd{M-x scroll-all-mode}) is a global minor mode
+that causes scrolling commands and point motion commands to apply to
+every single window.
@section Basic Concepts of Emacs Windows
@cindex window
-A @dfn{window} in Emacs is the physical area of the screen in which a
-buffer is displayed, see @ref{Buffers}. The term is also used to refer
-to a Lisp object that represents that screen area in Emacs Lisp. It
-should be clear from the context which is meant.
+A @dfn{window} is a area of the screen which is used to display a
+buffer (@pxref{Buffers}). In Emacs Lisp, windows are represented by a
+special Lisp object type.
@cindex multiple windows
- Emacs groups windows into frames; see @ref{Frames}. Each frame always
-contains at least one window, but you can subdivide it into multiple,
-non-overlapping Emacs windows. Users create multiple windows so they
-can look at several buffers at once. Lisp libraries use multiple
-windows for a variety of reasons, but most often to display related
-information. In Rmail, for example, you can move through a summary
-buffer in one window while the other window shows messages one at a time
-as they are reached.
+ Windows are grouped into frames (@pxref{Frames}). Each frame
+contains at least one window; the user can subdivide it 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.
@cindex terminal screen
@cindex screen of terminal
- The meaning of ``window'' in Emacs is similar to what it means in the
-context of general-purpose window systems such as X, but not identical.
-The X Window System places X windows on the screen; Emacs uses one or
-more X windows as frames, and subdivides them into Emacs windows. When
-you use Emacs on a character-only terminal, Emacs treats the whole
-terminal screen as one frame.
+ Emacs uses the word ``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 of its graphical X
+windows is an Emacs frame (containing one or more Emacs windows).
+When Emacs is run on a text-only terminal, the frame fills the entire
+terminal screen.
@cindex tiled windows
- Most window systems support arbitrarily located overlapping windows.
-In contrast, Emacs windows are @dfn{tiled}; they never overlap, and
-together they fill the whole screen or frame. Because of the way in
-which Emacs creates new windows (@pxref{Splitting Windows}) and resizes
-them (@pxref{Resizing Windows}), not all conceivable tilings of windows
-on an Emacs frame are actually possible.
-
- For practical purposes, a window exists only while it is displayed in
-a frame. Once removed from the frame, the window is effectively deleted
-and should not be used, even though the Lisp object representing it
-might be still referenced from other Lisp objects; see @ref{Deleting
-Windows}. Restoring a saved window configuration is the only way for a
-window no longer on the screen to come back to life; see @ref{Window
-Configurations}.
-
-@defun windowp object
-This function returns @code{t} if @var{object} is a window, @code{nil}
-otherwise. It can return @code{t} if @var{object} denotes a window that
-has been deleted.
-@end defun
+ Unlike X windows, Emacs windows are @dfn{tiled}; they never overlap
+within the area of the frame. When a window is created, resized, or
+deleted, the change in window space is taken from or given to the
+adjacent windows, so that the total area of the frame is unchanged.
@cindex live windows
@cindex internal windows
- For historical reasons a window is considered @dfn{live} if and only
-if it currently displays a buffer; see @ref{Buffers and Windows}. In
-order to show multiple windows within one and the same frame, Emacs
-organizes them in form of a tree called window tree; see @ref{Windows
-and Frames}. The internal nodes of a window tree are called internal
-windows and are not considered live. The leaf nodes of a window tree
-constitute the windows displaying buffers and only they will be called
-live here.
+ A @dfn{live window} is one that is actually displaying a buffer in a
+frame. Such a window can be @dfn{deleted}, i.e. removed from the
+frame (@pxref{Deleting Windows}); then it is no longer live, but the
+Lisp object representing it might be still referenced from other Lisp
+objects. A deleted window may be brought back to life by restoring a
+saved window configuration (@pxref{Window Configurations}).
+
+@defun windowp object
+This function returns @code{t} if @var{object} is a window (whether or
+not it is live). Otherwise, it returns @code{nil}.
+@end defun
@defun window-live-p object
This function returns @code{t} if @var{object} is a live window and
-@code{nil} otherwise. A live window is a window that displays a buffer.
+@code{nil} otherwise. A live window is one that displays a buffer.
@end defun
-@defun window-any-p object
-This function returns @code{t} if @var{object} denotes a live or an
-internal window and @code{nil} otherwise. In particular, this function
-returns @code{nil} if @var{object} is a window that has been
-deleted.
+ The windows in each frame are organized into a @dfn{window tree}.
+@xref{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.
+You can distinguish internal windows from deleted windows with
+@code{window-valid-p}.
+
+@defun window-valid-p object
+This function returns @code{t} if @var{object} is a live window, or an
+internal window in a window tree. Otherwise, it returns @code{nil},
+including for the case where @var{object} is a deleted window.
@end defun
@cindex selected window
-In each frame, at any time, one and only one window is designated as
-@dfn{selected within the frame}. Also, at any time, one frame is the
-selected frame (@pxref{Input Focus}). The window selected within the
-selected frame is the @dfn{selected window}.
-
- The selected window is always a live window. Its buffer is usually
-the current buffer (except when @code{set-buffer} has been used); see
-@ref{Current Buffer}.
+ In each frame, at any time, exactly one Emacs window is designated
+as @dfn{selected within the frame}. For the selected frame, that
+window is called the @dfn{selected window}---the one in which most
+editing takes place, and in which the cursor for selected windows
+appears (@pxref{Cursor Parameters}). The selected window's buffer is
+usually also the current buffer, except when @code{set-buffer} has
+been used (@pxref{Current Buffer}). As for non-selected frames, the
+window selected within the frame becomes the selected window if the
+frame is ever selected. @xref{Selecting Windows}.
@defun selected-window
-This function returns the selected window. This is the window in which
-the cursor for selected windows (@pxref{Cursor Parameters}) appears and
-to which many commands apply.
-@end defun
-
-The window handling functions can be roughly grouped into functions
-operating on live windows only and functions that accept any window as
-argument. Many of these functions accept as argument the value
-@code{nil} to specify the selected window. The two functions below can
-be used to ``normalize'' arguments specifying windows in a uniform
-manner.
-
-@defun window-normalize-any-window window
-This function returns the normalized value for @var{window} which can be
-any window that has not been deleted. More precisely, if @var{window}
-is @code{nil}, it returns the selected window. If @var{window} denotes
-a live or internal window, it returns that window. Otherwise, this
-function signals an error.
-@end defun
-
-@defun window-normalize-live-window window
-This functions returns the normalized value for a live window
-@var{window}. More precisely, if @var{window} is @code{nil}, it returns
-the selected window. If @var{window} is a live window, it returns that
-window. Otherwise, this function signals an error.
+This function returns the selected window (which is always a live
+window).
@end defun
-
@node Windows and Frames
@section Windows and Frames
-Each window is part of one and only one frame (@pxref{Frames}); you can
-get that frame with the function described next.
+Each window belongs to exactly one frame (@pxref{Frames}).
@defun window-frame window
-This function returns the frame that @var{window} is on. The argument
-@var{window} can be any window and defaults to the selected one.
+This function returns the frame that the window @var{window} belongs
+to. If @var{window} is @code{nil}, it defaults to the selected
+window.
@end defun
-The following function returns a list of all live windows on a specific
-frame.
+@defun window-list &optional frame minibuffer window
+This function returns a list of live windows belonging to the frame
+@var{frame}. If @var{frame} is omitted or @code{nil}, it defaults to
+the selected frame.
-@defun window-list &optional frame minibuf window
-This function returns a list of @var{frame}'s live windows, starting
-with @var{window}. The optional argument @var{frame} has to denote a
-live frame and defaults to the selected frame. The optional argument
-@var{window} has to denote a live window on the frame specified by
-@var{frame} and defaults to the selected one.
+The optional argument @var{minibuffer} specifies whether to include
+the minibuffer window in the returned list. If @var{minibuffer} is
+@code{t}, the minibuffer window is included. If @var{minibuffer} is
+@code{nil} or omitted, the minibuffer window is included only if it is
+active. If @var{minibuffer} is neither @code{nil} nor @code{t}, the
+minibuffer window is never included.
-The argument @var{minibuf} specifies if the minibuffer window shall be
-included in the return value. If @var{minibuf} is @code{t}, the result
-always includes the minibuffer window. If @var{minibuf} is @code{nil}
-or omitted, that includes the minibuffer window only if it is active.
-If @var{minibuf} is neither @code{nil} nor @code{t}, the result never
-includes the minibuffer window.
+The optional argument @var{window}, if non-@code{nil}, should be a
+live window on the specified frame; then @var{window} will be the
+first element in the returned list. If @var{window} is omitted or
+@code{nil}, the window selected within the frame is first element.
@end defun
@cindex window tree
-Windows within one and the same frame are organized in form of a tree
-called @dfn{window tree}. The leaf nodes of a window tree constitute
-the windows visible to the user. These are the windows associated with
-buffers and are usually called live windows. The internal nodes of a
-window tree are needed for finding, traversing and displaying the live
-windows.
-
- A minibuffer window (@pxref{Minibuffer Windows}) is not considered
-part of its frame's window tree unless the frame is a minibuffer-only
-frame. Most functions covered in this section accept, however, the
-minibuffer window as argument. Also, the minibuffer window is listed by
-the function @code{window-tree} described at the end of this section.
-
- A window tree is rooted at the root window of its frame.
+@cindex root window
+ Windows in the same frame are organized into a @dfn{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 @dfn{root window}. It can be either a live window (if the
+frame has just one window), or an internal window.
+
+ A minibuffer window (@pxref{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
+@code{window-tree} described at the end of this section lists the
+minibuffer window alongside the actual window tree.
@defun frame-root-window &optional frame-or-window
-This function returns the root window of @var{frame-or-window}. The
-argument @var{frame-or-window} has to denote either a window or a frame
-and defaults to the selected frame. If @var{frame-or-window} denotes a
-window, the return value is the root window of that window's frame.
-This function always returns a window; a live window if the frame
-specified by @var{frame-or-window} contains no other live windows and an
-internal window otherwise.
+This function returns the root window for @var{frame-or-window}. The
+argument @var{frame-or-window} should be either a window or a frame;
+if omitted or @code{nil}, it defaults to the selected frame. If
+@var{frame-or-window} is a window, the return value is the root window
+of that window's frame.
@end defun
-@cindex subwindow
-All other windows of a frame with the exception of the minibuffer window
-are subwindows of the frame's root window. A window is considered a
-@dfn{subwindow} of another window if it occupies a part of that other
-window's screen area.
-
-The functions described next allow to access the members of a window
-tree and take an arbitrary window as argument.
+@cindex parent window
+@cindex child window
+@cindex sibling window
+ 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 @dfn{child windows} of a single
+internal window. If necessary, Emacs automatically creates this
+internal window, which is also called the @dfn{parent window}, and
+assigns it to the appropriate position in the window tree. A set of
+windows that share the same parent are called @dfn{siblings}.
@cindex parent window
@defun window-parent &optional window
-Return @var{window}'s parent in the window tree. The optional argument
-@var{window} can denote an arbitrary window and defaults to the selected
-one. The return value is @code{nil} if @var{window} is a minibuffer
-window or the root window of its frame and an internal window otherwise.
+This function returns the parent window of @var{window}. If
+@var{window} is omitted or @code{nil}, it defaults to the selected
+window. The return value is @code{nil} if @var{window} has no parent
+(i.e. it is a minibuffer window or the root window of its frame).
@end defun
-@cindex child window
- Parent windows do not appear on the screen. The screen area of a
-parent window is the rectangular part of the window's frame occupied by
-the window's @dfn{child windows}, that is, the set of windows having
-that window as their parent. Each parent window has at least two child
-windows, so there are no ``Matryoshka'' windows. Minibuffer windows do
-not have child windows.
+ 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
+@dfn{screen area}---the union of the areas occupied by the live
+windows that are ultimately descended from it.
@cindex window combination
@cindex vertical combination
@cindex horizontal combination
-The children of any parent window form either a vertical or a horizontal
-combination of windows. A @dfn{vertical combination} is a set of
-windows arranged one above each other. A @dfn{horizontal combination}
-is a set of windows arranged side by side. Consider the frame shown
-below (for simplicity we assume that the frame does not contain a
-minibuffer window):
+ 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 @dfn{vertical combination}; if they are arranged side by side, they
+are said to form a @dfn{horizontal combination}. Consider the
+following example:
@smallexample
@group
______________________________________
| ______ ____________________________ |
|| || __________________________ ||
- || ||| ___________ ___________ |||
- || |||| || ||||
- || |||| || ||||
- || ||||_____W6____||_____W7____||||
+ || ||| |||
+ || ||| |||
+ || ||| |||
|| |||____________W4____________|||
|| || __________________________ ||
|| ||| |||
+ || ||| |||
|| |||____________W5____________|||
||__W2__||_____________W3_____________ |
|__________________W1__________________|
@end group
@end smallexample
-The root window of the frame is @code{W1}---a horizontal combination of
-the live window @code{W2} and the internal window @code{W3}. Hence
-@code{(window-parent W1)} is @code{nil} while @code{(window-parent W2)}
-and @code{(window-parent W3)} are both @code{W1}.
-
- The internal window @code{W3} is a vertical combination of @code{W4}
-and the live window @code{W5}. The internal window @code{W4} is a
-horizontal combination of the live windows @code{W6} and @code{W7}. The
-windows you can actually see on the screen are @code{W2}, @code{W5},
-@code{W6} and @code{W7}.
-
- For any parent window, the first child window can be retrieved by the
-functions given next.
-
-@defun window-top-child &optional window
-This function returns @var{window}'s first vertical child window. The
-optional argument @var{window} can be an arbitrary window and defaults
-to the selected one. The return value is @code{nil} if @var{window} is
-a live window or its children form a horizontal combination. In the
-example above @code{(window-top-child W3)} is @code{W4} while
-@code{(window-top-child W4)} is @code{nil}.
+@noindent
+The root window of this frame is an internal window, @code{W1}. Its
+child windows form a horizontal combination, consisting of the live
+window @code{W2} and the internal window @code{W3}. The child windows
+of @code{W3} form a vertical combination, consisting of the live
+windows @code{W4} and @code{W5}. Hence, the live windows in this
+window tree are @code{W2} @code{W4}, and @code{W5}.
+
+ The following functions can be used to retrieve a child window of an
+internal window, and the siblings of a child window.
+
+@defun window-top-child window
+This function returns the topmost child window of @var{window}, if
+@var{window} is an internal window whose children form a vertical
+combination. For any other type of window, the return value is
+@code{nil}.
@end defun
-@defun window-left-child &optional window
-This function returns @var{window}'s first horizontal child window. The
-optional argument @var{window} can be an arbitrary window and defaults
-to the selected one. The return value is @code{nil} if @var{window} is
-a live window or its children form a vertical combination. In the
-example above @code{(window-left-child W4)} is @code{W6} while
-@code{(window-left-child W3)} is @code{nil}.
+@defun window-left-child window
+This function returns the leftmost child window of @var{window}, if
+@var{window} is an internal window whose children form a horizontal
+combination. For any other type of window, the return value is
+@code{nil}.
@end defun
@defun window-child window
-This function return @var{window}'s first child window. The return
-value is @code{nil} if @var{window} is a live window. In the example
-above @code{(window-child W3)} is @code{W4} while @code{(window-child
-W4)} is @code{W6}.
+This function returns the first child window of the internal window
+@var{window}---the topmost child window for a vertical combination, or
+the leftmost child window for a horizontal combination. If
+@var{window} is a live window, the return value is @code{nil}.
@end defun
-The following function is useful to determine whether a window is part
-of a vertical or horizontal combination.
-
@defun window-combined-p &optional window horizontal
-This function returns non-@code{nil} if and only if @var{window} is
-vertically combined. The argument @var{window} can specify any window
-and defaults to the selected one. The actual return value is the first
-vertical child of window.
+This function returns a non-@code{nil} value if and only if
+@var{window} is part of a vertical combination. If @var{window} is
+omitted or nil, it defaults to the selected one.
-If the optional argument @var{horizontal} is non-@code{nil}, this means
-to return non-@code{nil} if and only if @var{window} is horizontally
-combined. In this case, the return value is the first horizontal child
-of window.
+If the optional argument @var{horizontal} is non-@code{nil}, this
+means to return non-@code{nil} if and only if @var{window} is part of
+a horizontal combination.
@end defun
-@cindex sibling window
-For any window that is part of a combination, the other windows in that
-combination are called the window's @dfn{siblings}. The only windows
-that do not have siblings are root windows of frames and minibuffer
-windows. A window's siblings can be retrieved with the following two
-functions.
-
@defun window-next-sibling &optional window
-This function returns @var{window}'s next sibling. The optional
-argument @var{window} can be an arbitrary window and defaults to the
-selected window. It returns @code{nil} if @var{window} is the last
-child of its parent. In our example @code{(window-next-sibling W2)} is
-@code{W3} while @code{(window-next-sibling W3)} is @code{nil}.
+This function returns the next sibling of the window @var{window}. If
+omitted or @code{nil}, @var{window} defaults to the selected window.
+The return value is @code{nil} if @var{window} is the last child of
+its parent.
@end defun
@defun window-prev-sibling &optional window
-This function returns @var{window}'s previous sibling. The optional
-argument @var{window} can be an arbitrary window and defaults to the
-selected window. It returns @code{nil} if @var{window} is the first
-child of its parent. In our example @code{(window-prev-sibling W3)} is
-@code{W2} and @code{(window-prev-sibling W2)} is @code{nil}.
+This function returns the previous sibling of the window @var{window}.
+If omitted or @code{nil}, @var{window} defaults to the selected
+window. The return value is @code{nil} if @var{window} is the first
+child of its parent.
@end defun
-The functions @code{window-next-sibling} and @code{window-prev-sibling}
-should not be confused with the functions @code{next-window} and
-@code{previous-window} which respectively return the next and previous
-window in the cyclic ordering of windows, see @ref{Cyclic Window
-Ordering}.
+The functions @code{window-next-sibling} and
+@code{window-prev-sibling} should not be confused with the functions
+@code{next-window} and @code{previous-window} which respectively
+return the next and previous window in the cyclic ordering of windows
+(@pxref{Cyclic Window Ordering}).
- In order to find the first live window on a frame, the following
-function can be used.
+ You can use the following functions to find the first live window on
+a frame, and to retrieve the entire window tree of a frame:
@defun frame-first-window &optional frame-or-window
This function returns the live window at the upper left corner of the
@code{(frame-first-window)} returns @code{W2}.
@end defun
-You can get the window tree of a frame with the following function.
-
-@cindex window tree
@defun window-tree &optional frame
-This function returns the window tree for frame @var{frame}. The
-optional argument @var{frame} must be a live frame and defaults to the
-selected one.
+This function returns a list representing the window tree for frame
+@var{frame}. If @var{frame} is omitted or @code{nil}, it defaults to
+the selected frame.
The return value is a list of the form @code{(@var{root} @var{mini})},
-where @var{root} represents the window tree of the frame's
-root window, and @var{mini} is the frame's minibuffer window.
+where @var{root} represents the window tree of the frame's root
+window, and @var{mini} is the frame's minibuffer window.
-If the root window is live, @var{root} specifies the root window and
-nothing else. Otherwise, @var{root} is a list @code{(@var{dir}
-@var{edges} @var{w1} @var{w2} ...)} where @var{dir} is @code{nil} for a
-horizontal combination, and @code{t} for a vertical combination,
-@var{edges} gives the size and position of the combination, and the
-remaining elements are the child windows. Each child window may again
-be a live window or a list representing a window combination, and so on.
-The @var{edges} element is a list @code{(@var{left}@var{ top}@var{
-right}@var{ bottom})} similar to the value returned by
-@code{window-edges}, see @ref{Coordinates and Windows}.
+If the root window is live, @var{root} is that window itself.
+Otherwise, @var{root} is a list @code{(@var{dir} @var{edges} @var{w1}
+@var{w2} ...)} where @var{dir} is @code{nil} for a horizontal
+combination and @code{t} for a vertical combination, @var{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 @var{edges} element is a list @code{(@var{left}
+@var{top} @var{right} @var{bottom})}, similar to the value returned by
+@code{window-edges} (@pxref{Coordinates and Windows}).
@end defun
-
@node Window Sizes
@section Window Sizes
@cindex window size
For interactive use, Emacs provides two commands which always split the
selected window.
-@deffn Command split-window-above-each-other &optional size
+@deffn Command split-window-below &optional size
This function splits the selected window into two windows, one above the
other, leaving the upper of the two windows selected, with @var{size}
lines. (If @var{size} is negative, then the lower of the two windows
@defopt split-window-keep-point
If this variable is non-@code{nil} (the default), then
-@code{split-window-above-each-other} behaves as described above.
+@code{split-window-below} behaves as described above.
- If it is @code{nil}, then @code{split-window-above-each-other}
-adjusts point in each of the two windows to avoid scrolling. (This is
-useful on slow terminals.) It selects whichever window contains the
-screen line that point was previously on. Other functions are not
-affected by this variable.
+ If it is @code{nil}, then @code{split-window-below} adjusts point
+in each of the two windows to avoid scrolling. (This is useful on
+slow terminals.) It selects whichever window contains the screen line
+that point was previously on. Other functions are not affected by
+this variable.
@end defopt
-@deffn Command split-window-side-by-side &optional size
+@deffn Command split-window-right &optional size
This function splits the selected window into two windows
side-by-side, leaving the selected window on the left with @var{size}
columns. If @var{size} is negative, the rightmost window gets
@group
(let ((config (current-window-configuration)))
(unwind-protect
- (progn (split-window-vertically nil)
+ (progn (split-window-below nil)
@dots{})
(set-window-configuration config)))
@end group