[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] /srv/bzr/emacs/trunk r106304: Manual updates for window ch
|
From: |
Chong Yidong |
|
Subject: |
[Emacs-diffs] /srv/bzr/emacs/trunk r106304: Manual updates for window changes. |
|
Date: |
Sun, 06 Nov 2011 14:14:01 +0800 |
|
User-agent: |
Bazaar (2.3.1) |
------------------------------------------------------------
revno: 106304
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Sun 2011-11-06 14:14:01 +0800
message:
Manual updates for window changes.
* 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.
modified:
doc/emacs/ChangeLog
doc/emacs/custom.texi
doc/emacs/search.texi
doc/emacs/windows.texi
doc/lispref/ChangeLog
doc/lispref/windows.texi
etc/NEWS
=== modified file 'doc/emacs/ChangeLog'
--- a/doc/emacs/ChangeLog 2011-10-26 14:07:31 +0000
+++ b/doc/emacs/ChangeLog 2011-11-06 06:14:01 +0000
@@ -1,3 +1,20 @@
+2011-11-06 Chong Yidong <address@hidden>
+
+ * 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 <address@hidden>
* emacs.texi (Top): Fix typo.
=== modified file 'doc/emacs/custom.texi'
--- a/doc/emacs/custom.texi 2011-10-20 00:41:15 +0000
+++ b/doc/emacs/custom.texi 2011-11-06 06:14:01 +0000
@@ -1774,7 +1774,7 @@
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
=== modified file 'doc/emacs/search.texi'
--- a/doc/emacs/search.texi 2011-10-24 02:01:54 +0000
+++ b/doc/emacs/search.texi 2011-11-06 06:14:01 +0000
@@ -328,12 +328,11 @@
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
address@hidden ^} (@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 address@hidden @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 address@hidden @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
=== modified file 'doc/emacs/windows.texi'
--- a/doc/emacs/windows.texi 2011-10-22 10:57:50 +0000
+++ b/doc/emacs/windows.texi 2011-11-06 06:14:01 +0000
@@ -34,24 +34,22 @@
@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
address@hidden 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 @@
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 @@
@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
address@hidden 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.
address@hidden 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.
+
address@hidden split-window-keep-point
+ If you change the variable @code{split-window-keep-point} to
address@hidden, @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
address@hidden 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.
address@hidden 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.
+
address@hidden 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
address@hidden 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 address@hidden 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 split a window horizontally or vertically by clicking
address@hidden 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.
-
address@hidden 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
address@hidden (@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 address@hidden value, Emacs truncates lines in every partial-width
-window regardless of its width.
-
- Horizontal scrolling is often used in side-by-side windows.
address@hidden Scrolling}.
-
address@hidden split-window-keep-point
- If @code{split-window-keep-point} is address@hidden, 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.
+ You can also split a window horizontally or vertically by clicking
address@hidden 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}).
address@hidden 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
address@hidden, in a window's mode line, selects that window
-but does not move point in it (@code{mouse-select-window}).
address@hidden, 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 @@
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 address@hidden 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 @@
@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 @@
@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 @@
@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,
address@hidden 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 @}
address@hidden 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
address@hidden (the default is 4).
+
@findex enlarge-window-horizontally
address@hidden window-min-height
address@hidden 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
address@hidden 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
address@hidden (the default is 10).
@kindex C-x -
@findex shrink-window-if-larger-than-buffer
@@ -322,7 +313,7 @@
@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 @@
@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
address@hidden 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
address@hidden 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 @@
@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 @@
@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
address@hidden 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
address@hidden 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.
=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog 2011-11-04 10:09:41 +0000
+++ b/doc/lispref/ChangeLog 2011-11-06 06:14:01 +0000
@@ -1,3 +1,13 @@
+2011-11-06 Chong Yidong <address@hidden>
+
+ * 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 <address@hidden>
* windows.texi (Window Sizes): Mention in the doc string that the
=== modified file 'doc/lispref/windows.texi'
--- a/doc/lispref/windows.texi 2011-11-04 10:09:41 +0000
+++ b/doc/lispref/windows.texi 2011-11-06 06:14:01 +0000
@@ -50,216 +50,188 @@
@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}.
-
address@hidden 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.
address@hidden 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}).
+
address@hidden windowp object
+This function returns @code{t} if @var{object} is a window (whether or
+not it is live). Otherwise, it returns @code{nil}.
address@hidden defun
@defun window-live-p object
This function returns @code{t} if @var{object} is a live window and
address@hidden otherwise. A live window is a window that displays a buffer.
address@hidden otherwise. A live window is one that displays a buffer.
@end defun
address@hidden 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}.
address@hidden 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
address@hidden
+
address@hidden 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
address@hidden 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
address@hidden 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.
address@hidden 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
address@hidden to specify the selected window. The two functions below can
-be used to ``normalize'' arguments specifying windows in a uniform
-manner.
-
address@hidden 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.
address@hidden defun
-
address@hidden window-normalize-live-window window
-This functions returns the normalized value for a live window
address@hidden 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.
address@hidden defun
-
+This function returns the selected window (which is always a live
+window).
address@hidden 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
address@hidden 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.
-
address@hidden 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
address@hidden has to denote a live window on the frame specified by
address@hidden and defaults to the selected one.
-
-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.
address@hidden window-list &optional frame minibuffer window
+This function returns a list of live windows belonging to the frame
address@hidden If @var{frame} is omitted or @code{nil}, it defaults to
+the selected frame.
+
+The optional argument @var{minibuffer} specifies whether to include
+the minibuffer window in the returned list. If @var{minibuffer} is
address@hidden, the minibuffer window is included. If @var{minibuffer} is
address@hidden 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 optional argument @var{window}, if address@hidden, 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
address@hidden, 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.
address@hidden 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
address@hidden 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
address@hidden is a window, the return value is the root window
+of that window's frame.
@end defun
address@hidden 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
address@hidden 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.
address@hidden parent window
address@hidden child window
address@hidden 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
address@hidden 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
address@hidden 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
address@hidden 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
address@hidden 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 @@
@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
address@hidden(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},
address@hidden and @code{W7}.
-
- For any parent window, the first child window can be retrieved by the
-functions given next.
-
address@hidden 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
address@hidden(window-top-child W4)} is @code{nil}.
address@hidden
+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.
+
address@hidden window-top-child window
+This function returns the topmost child window of @var{window}, if
address@hidden is an internal window whose children form a vertical
+combination. For any other type of window, the return value is
address@hidden
@end defun
address@hidden 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
address@hidden(window-left-child W3)} is @code{nil}.
address@hidden window-left-child window
+This function returns the leftmost child window of @var{window}, if
address@hidden is an internal window whose children form a horizontal
+combination. For any other type of window, the return value is
address@hidden
@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
address@hidden topmost child window for a vertical combination, or
+the leftmost child window for a horizontal combination. If
address@hidden 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 address@hidden 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 address@hidden value if and only if
address@hidden 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 address@hidden, this means
-to return address@hidden 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 address@hidden, this
+means to return address@hidden if and only if @var{window} is part of
+a horizontal combination.
@end defun
address@hidden 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
address@hidden 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
address@hidden 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
address@hidden 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
address@hidden should not be confused with the functions
address@hidden 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 @@
@code{(frame-first-window)} returns @code{W2}.
@end defun
-You can get the window tree of a frame with the following function.
-
address@hidden 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
address@hidden 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}
address@hidden @var{w1} @var{w2} ...)} where @var{dir} is @code{nil} for a
-horizontal combination, and @code{t} for a vertical combination,
address@hidden 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{(@address@hidden address@hidden
address@hidden bottom})} similar to the value returned by
address@hidden, 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}
address@hidden ...)} 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}
address@hidden @var{right} @var{bottom})}, similar to the value returned by
address@hidden (@pxref{Coordinates and Windows}).
@end defun
-
@node Window Sizes
@section Window Sizes
@cindex window size
@@ -1566,7 +1513,7 @@
For interactive use, Emacs provides two commands which always split the
selected window.
address@hidden Command split-window-above-each-other &optional size
address@hidden 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 @@
@defopt split-window-keep-point
If this variable is address@hidden (the default), then
address@hidden behaves as described above.
address@hidden 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
address@hidden Command split-window-side-by-side &optional size
address@hidden 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 @@
@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
=== modified file 'etc/NEWS'
--- a/etc/NEWS 2011-11-05 03:20:45 +0000
+++ b/etc/NEWS 2011-11-06 06:14:01 +0000
@@ -1038,7 +1038,7 @@
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.
+++
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] /srv/bzr/emacs/trunk r106304: Manual updates for window changes.,
Chong Yidong <=