procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Manual updates for window changes.

Browse source 
* doc/emacs/windows.texi (Basic Window): Add xref to Cursor Display.
(Split Window): Document negative arg for splitting commands.
(Other Window): Document mouse-1 in text area of window.
(Change Window): Don't mention window attributes, since they
aren't defined.  C-x 1 can't be used with minibuffer windows.
Windows are no longer auto-deleted.
(Window Choice): Add xref to Choosing Window in Lisp manual.
(Window Convenience): Note that windmove disables shift-selection.
Move M-x compare-windows here from Other Window node.

* doc/emacs/custom.texi (Mouse Buttons):
* doc/emacs/search.texi (Isearch Scroll):
* doc/emacs/windows.texi (Split Window): Use new names split-window-below
and split-window-right.

* doc/lispref/windows.texi (Basic Windows): Clarify various definitions.
Treat window-normalize-* as internal; don't document them.
(Windows and Frames): Various clarifications, e.g. non-live
windows also belong to frames.  Fix window-list description.
Simplify window nesting example.
(Splitting Windows, Window Configurations): Use
split-window-below.
This commit is contained in:
Chong Yidong 2011-11-06 14:14:01 +08:00
parent 49745b39a1
commit 291d142b33
7 changed files with 371 additions and 402 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

17
doc/emacs/ChangeLog
View file

@ -1,3 +1,20 @@
2011-11-06 Chong Yidong <cyd@gnu.org>
* windows.texi (Basic Window): Add xref to Cursor Display.
(Split Window): Document negative arg for splitting commands.
(Other Window): Document mouse-1 in text area of window.
(Change Window): Don't mention window attributes, since they
aren't defined. C-x 1 can't be used with minibuffer windows.
Windows are no longer auto-deleted.
(Window Choice): Add xref to Choosing Window in Lisp manual.
(Window Convenience): Note that windmove disables shift-selection.
Move M-x compare-windows here from Other Window node.
* custom.texi (Mouse Buttons):
* search.texi (Isearch Scroll):
* windows.texi (Split Window): Use new names split-window-below
and split-window-right.
2011-10-26 Juanma Barranquero <lekktu@gmail.com>
* emacs.texi (Top): Fix typo.

2
doc/emacs/custom.texi
View file

@ -1774,7 +1774,7 @@ button, @code{mouse-2} for the next, and so on. Here is how you can
redefine the second mouse button to split the current window:
@example
(global-set-key [mouse-2] 'split-window-vertically)
(global-set-key [mouse-2] 'split-window-below)
@end example
The symbols for drag events are similar, but have the prefix

11
doc/emacs/search.texi
View file

@ -328,12 +328,11 @@ prefix arguments to these commands in the usual way. This feature
won't let you scroll the current match out of visibility, however.
The @code{isearch-allow-scroll} feature also affects some other
commands, such as @kbd{C-x 2} (@code{split-window-vertically}) and
@kbd{C-x ^} (@code{enlarge-window}), which don't exactly scroll but do
affect where the text appears on the screen. It applies to any
command whose name has a non-@code{nil} @code{isearch-scroll}
property. So you can control which commands are affected by changing
these properties.
commands, such as @kbd{C-x 2} (@code{split-window-below}) and @kbd{C-x
^} (@code{enlarge-window}), which don't exactly scroll but do affect
where the text appears on the screen. It applies to any command whose
name has a non-@code{nil} @code{isearch-scroll} property. So you can
control which commands are affected by changing these properties.
For example, to make @kbd{C-h l} usable within an incremental search
in all future Emacs sessions, use @kbd{C-h c} to find what command it

292
doc/emacs/windows.texi
View file

@ -34,24 +34,22 @@ has its own value of point.
@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.
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 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
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,
@ -61,7 +59,7 @@ only one mark position.
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
@ -69,91 +67,87 @@ different color. @xref{Mode Line}, for full details on the mode line.
@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.
@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.
@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.
@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}.
@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.
@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.
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-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 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.
@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.
@ -172,17 +166,13 @@ finish supplying the minibuffer argument that is requested.
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
@ -236,8 +226,7 @@ window (@code{find-file-read-only-other-window}). @xref{Visiting}.
@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}).
@ -260,14 +249,12 @@ Make all windows the same height (@code{balance-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
@ -277,31 +264,35 @@ selected window.
@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
@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.
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).
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}.
@findex enlarge-window-horizontally
@findex shrink-window-horizontally
@vindex 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
@ -322,7 +313,7 @@ heights and to delete windows. @xref{Mode Line Mouse}.
@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
@ -333,18 +324,18 @@ usually work by calling @code{switch-to-buffer} internally
@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
@ -367,7 +358,10 @@ Several of these commands are bound in the @kbd{C-x 5} prefix key.
@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
@ -433,36 +427,38 @@ and display the buffer there.
@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.

10
doc/lispref/ChangeLog
View file

@ -1,3 +1,13 @@
2011-11-06 Chong Yidong <cyd@gnu.org>
* windows.texi (Basic Windows): Clarify various definitions.
Treat window-normalize-* as internal; don't document them.
(Windows and Frames): Various clarifications, e.g. non-live
windows also belong to frames. Fix window-list description.
Simplify window nesting example.
(Splitting Windows, Window Configurations): Use
split-window-below.
2011-11-04 Eli Zaretskii <eliz@gnu.org>
* windows.texi (Window Sizes): Mention in the doc string that the

439
doc/lispref/windows.texi
View file

@ -50,216 +50,188 @@ is displayed in windows.
@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.
This function returns the selected window (which is always a live
window).
@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.
@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.
@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 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.
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__________________|
@ -267,91 +239,70 @@ minibuffer window):
@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}.
@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 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}.
The following functions can be used to retrieve a child window of an
internal window, and the siblings of a child window.
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}.
@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
@ -363,31 +314,27 @@ the assumption that the frame from our canonical example is selected
@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
@ -1566,7 +1513,7 @@ configuration.
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
@ -1582,16 +1529,16 @@ is the new, lower window.
@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
@ -3689,7 +3636,7 @@ as @code{save-window-excursion}:
@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

2
etc/NEWS
View file

@ -1038,7 +1038,7 @@ of the line.
Functions are provided to return the parent, siblings or child windows
of any window including internal windows (windows not associated with a
buffer) in the window tree.
+++
**** New function `window-valid-p' gives non-nil for live and internal
windows.
+++