Window-related updates to NEWS and Emacs manual.

* etc/NEWS: Reorganize, placing user options in Changes section.

* doc/emacs/buffers.texi (Select Buffer): Clarify description of
buffer-switching commands.  Add xref to Window Display node.
Don't repeat confirm-nonexistent-file-or-buffer description from
Visiting node.  Remove even-window-heights.

* doc/emacs/frames.texi (Special Buffer Frames): Add xref to Window Choice.

* doc/emacs/windows.texi (Pop Up Window): Defer discussion of window
splitting to the Window Choice node.  Add index entries.
(Force Same Window): Node deleted.
(Displaying Buffers, Window Choice): New nodes.
This commit is contained in:
Chong Yidong 2011-09-24 14:19:20 -04:00
parent 25b4bfa0d1
commit 0a2132baa8
6 changed files with 229 additions and 141 deletions

View file

@ -1,3 +1,17 @@
2011-09-24 Chong Yidong <cyd@stupidchicken.com>
* windows.texi (Pop Up Window): Defer discussion of window
splitting to the Window Choice node. Add index entries.
(Force Same Window): Node deleted.
(Displaying Buffers, Window Choice): New nodes.
* buffers.texi (Select Buffer): Clarify description of
buffer-switching commands. Add xref to Window Display node.
Don't repeat confirm-nonexistent-file-or-buffer description from
Visiting node. Remove even-window-heights.
* frames.texi (Special Buffer Frames): Add xref to Window Choice.
2011-09-18 Chong Yidong <cyd@stupidchicken.com>
* cmdargs.texi (Icons X): Fix description of Emacs icon.

View file

@ -91,9 +91,9 @@ selected buffer other than the current buffer.
@var{bufname} @key{RET}}. This runs the command
@code{switch-to-buffer} with argument @var{bufname}. While entering
the buffer name, you can use the usual minibuffer completion and
history commands (@pxref{Minibuffer}). An empty argument to @kbd{C-x
b} specifies the buffer that was current most recently among those not
now displayed in any window.
history commands (@pxref{Minibuffer}). An empty input specifies the
buffer that was current most recently among those not now displayed in
any window.
@cindex minibuffer confirmation
@cindex confirming in the minibuffer
@ -107,16 +107,8 @@ catches a common mistake, in which one types @key{RET} before
realizing that @key{TAB} did not complete far enough to yield the
desired buffer name (@pxref{Completion}). Emacs asks for confirmation
by putting the message @samp{[Confirm]} in the minibuffer; type
@key{RET} again to confirm and visit the buffer.
@vindex confirm-nonexistent-file-or-buffer
The variable @code{confirm-nonexistent-file-or-buffer} controls
whether Emacs asks for confirmation before visiting a buffer that did
not previously exist. The default value, @code{after-completion},
gives the behavior we have just described. If the value is
@code{nil}, Emacs never asks for confirmation; for any other
non-@code{nil} value, Emacs always asks for confirmation. This
variable also affects the @code{find-file} command (@pxref{Visiting}).
@key{RET} again to confirm and visit the buffer. @xref{Visiting}, for
information about modifying this behavior.
One reason to create a new buffer is to use it for making temporary
notes. If you try to save it, Emacs asks for the file name to use.
@ -136,36 +128,26 @@ of most recent selection in the current frame), while @kbd{C-x @key{LEFT}}
@kindex C-x 4 b
@findex switch-to-buffer-other-window
@vindex even-window-heights
To select a buffer in a window other than the current one, type
@kbd{C-x 4 b} (@code{switch-to-buffer-other-window}). This prompts
for a buffer name using the minibuffer, displays that buffer in
another window, and selects that window. By default, if displaying
the buffer causes two vertically adjacent windows to be displayed, the
heights of those windows are evened out; to countermand that and
preserve the window configuration, set the variable
@code{even-window-heights} to @code{nil}.
another window, and selects that window.
@kindex C-x 5 b
@findex switch-to-buffer-other-frame
Similarly, @kbd{C-x 5 b} (@code{switch-to-buffer-other-frame})
prompts for a buffer name, displays that buffer in another frame, and
selects that frame.
selects that frame. If the buffer is already being shown in a window
on another frame, Emacs selects that window and frame instead of
creating a new frame.
@xref{Displaying Buffers}, for how the @kbd{C-x 4 b} and @kbd{C-x 5
b} commands get the window and/or frame to display in.
In addition, @kbd{C-x C-f}, and any other command for visiting a
file, can also be used to switch to an existing file-visiting buffer.
@xref{Visiting}.
@vindex display-buffer-reuse-frames
You can control how certain buffers are handled by these commands by
customizing the variables @code{special-display-buffer-names},
@code{special-display-regexps}, @code{same-window-buffer-names}, and
@code{same-window-regexps}. See @ref{Force Same Window}, and
@ref{Special Buffer Frames}, for more about these variables. In
addition, if the value of @code{display-buffer-reuse-frames} is
non-@code{nil}, and the buffer you want to switch to is already
displayed in some frame, Emacs will just raise that frame.
@findex goto-line
@kbd{C-u M-g M-g}, that is @code{goto-line} with a plain prefix
argument, reads a number @var{n} using the minibuffer, selects the

View file

@ -488,9 +488,8 @@ Multiple Windows
* Split Window:: New windows are made by splitting existing windows.
* Other Window:: Moving to another window or doing something to it.
* Pop Up Window:: Finding a file or buffer in another window.
* Force Same Window:: Forcing certain buffers to appear in the selected
window rather than in another window.
* Change Window:: Deleting windows and changing their sizes.
* Displaying Buffers:: How Emacs picks a window for displaying a buffer.
* Window Convenience:: Convenience functions for window handling.
Frames and Graphical Displays

View file

@ -850,11 +850,12 @@ each others' edits if they are not careful.
@vindex special-display-buffer-names
You can make certain chosen buffers, which Emacs normally displays
in ``another window,'' appear in special frames of their own. To do
this, set the variable @code{special-display-buffer-names} to a list
of buffer names; any buffer whose name is in that list automatically
gets a special frame, when an Emacs command wants to display it ``in
another window.''
in ``some other window'' (@pxref{Displaying Buffers}), appear in
special frames of their own. To do this, set the variable
@code{special-display-buffer-names} to a list of buffer names; any
buffer whose name is in that list automatically gets a special frame.
@xref{Window Choice}, for how this fits in with the other ways for
Emacs to choose a window to display in.
For example, if you set the variable this way,
@ -906,13 +907,6 @@ where @var{function} is a symbol. Then the frame is constructed by
calling @var{function}; its first argument is the buffer, and its
remaining arguments are @var{args}.
An analogous feature lets you specify buffers which should be
displayed in the selected window. @xref{Force Same Window}. The
same-window feature takes precedence over the special-frame feature;
therefore, if you add a buffer name to
@code{special-display-buffer-names} and it has no effect, check to see
whether that feature is also in use for the same buffer name.
@node Frame Parameters
@section Setting Frame Parameters
@cindex Auto-Raise mode

View file

@ -18,9 +18,8 @@ one frame.
* Split Window:: New windows are made by splitting existing windows.
* Other Window:: Moving to another window or doing something to it.
* Pop Up Window:: Finding a file or buffer in another window.
* Force Same Window:: Forcing certain buffers to appear in the selected
window rather than in another window.
* Change Window:: Deleting windows and changing their sizes.
* Displaying Buffers:: How Emacs picks a window for displaying a buffer.
* Window Convenience:: Convenience functions for window handling.
@end menu
@ -191,84 +190,47 @@ feature is off by default.
@cindex selecting buffers in other windows
@kindex C-x 4
@kbd{C-x 4} is a prefix key for commands that select another window
(splitting the window if there is only one) and select a buffer in that
window. Different @kbd{C-x 4} commands have different ways of finding the
buffer to select.
@kbd{C-x 4} is a prefix key for a variety of commands that switch to
a buffer in a different window---either another existing window, or a
new window created by splitting the selected window. @xref{Window
Choice}, for how Emacs picks or creates the window to use.
@table @kbd
@findex switch-to-buffer-other-window
@item C-x 4 b @var{bufname} @key{RET}
Select buffer @var{bufname} in another window. This runs
@code{switch-to-buffer-other-window}.
Select buffer @var{bufname} in another window
(@code{switch-to-buffer-other-window}).
@findex display-buffer
@item C-x 4 C-o @var{bufname} @key{RET}
Display buffer @var{bufname} in another window, but
don't select that buffer or that window. This runs
@code{display-buffer}.
Display buffer @var{bufname} in some window, without trying to select
it (@code{display-buffer}). @xref{Displaying Buffers}, for details
about how the window is chosen.
@findex find-file-other-window
@item C-x 4 f @var{filename} @key{RET}
Visit file @var{filename} and select its buffer in another window. This
runs @code{find-file-other-window}. @xref{Visiting}.
Visit file @var{filename} and select its buffer in another window
(@code{find-file-other-window}). @xref{Visiting}.
@findex dired-other-window
@item C-x 4 d @var{directory} @key{RET}
Select a Dired buffer for directory @var{directory} in another window.
This runs @code{dired-other-window}. @xref{Dired}.
Select a Dired buffer for directory @var{directory} in another window
(@code{dired-other-window}). @xref{Dired}.
@findex mail-other-window
@item C-x 4 m
Start composing a mail message in another window. This runs
@code{mail-other-window}; its same-window analogue is @kbd{C-x m}
(@pxref{Sending Mail}).
Start composing a mail message, similar to @kbd{C-x m} (@pxref{Sending
Mail}), but in another window (@code{mail-other-window}).
@findex find-tag-other-window
@item C-x 4 .
Find a tag in the current tags table, in another window. This runs
@code{find-tag-other-window}, the multiple-window variant of @kbd{M-.}
(@pxref{Tags}).
Find a tag in the current tags table, similar to @kbd{M-.}
(@pxref{Tags}), but in another window (@code{find-tag-other-window}).
@item C-x 4 r @var{filename} @key{RET}
Visit file @var{filename} read-only, and select its buffer in another
window. This runs @code{find-file-read-only-other-window}.
@xref{Visiting}.
window (@code{find-file-read-only-other-window}). @xref{Visiting}.
@end table
@vindex split-height-threshold
@vindex split-width-threshold
By default, these commands split the window vertically when there is
only one. You can customize the variables @code{split-height-threshold}
and @code{split-width-threshold} to split the window horizontally
instead.
@node Force Same Window
@section Forcing Display in the Same Window
Certain Emacs commands switch to a specific buffer with special
contents. For example, @kbd{M-x shell} switches to a buffer named
@samp{*shell*}. By convention, all these commands are written to pop up
the buffer in a separate window. But you can specify that certain of
these buffers should appear in the selected window.
@vindex same-window-buffer-names
If you add a buffer name to the list @code{same-window-buffer-names},
the effect is that such commands display that particular buffer by
switching to it in the selected window. For example, if you add the
element @code{"*grep*"} to the list, the @code{grep} command will
display its output buffer in the selected window.
The default value of @code{same-window-buffer-names} is not
@code{nil}: it specifies buffer names @samp{*info*}, @samp{*mail*} and
@samp{*shell*} (as well as others used by more obscure Emacs packages).
This is why @kbd{M-x shell} normally switches to the @samp{*shell*}
buffer in the selected window. If you delete this element from the
value of @code{same-window-buffer-names}, the behavior of @kbd{M-x
shell} will change---it will pop up the buffer in another window
instead.
@vindex same-window-regexps
You can specify these buffers more generally with the variable
@code{same-window-regexps}. Set it to a list of regular expressions;
then any buffer whose name matches one of those regular expressions is
displayed by switching to it in the selected window. (Once again, this
applies only to buffers that normally get displayed for you in a
separate window.) The default value of this variable specifies Telnet
and rlogin buffers.
An analogous feature lets you specify buffers which should be
displayed in their own individual frames. @xref{Special Buffer Frames}.
@node Change Window
@section Deleting and Rearranging Windows
@ -356,6 +318,113 @@ heights of all the windows in the selected frame.
Mouse clicks on the mode line provide another way to change window
heights and to delete windows. @xref{Mode Line Mouse}.
@node Displaying Buffers
@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
which commands do this.
Many commands, like @kbd{C-x C-f} (@code{find-file}), display the
buffer by ``taking over'' the selected window, expecting that the
user's attention will be diverted to that buffer. These commands
usually work by calling @code{switch-to-buffer} internally
(@pxref{Select Buffer}).
@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.
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{Displaying Buffers,,Displaying
Buffers in Windows, 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
window. Several of these commands are bound in the @kbd{C-x 4} prefix
key (@pxref{Pop Up Window}).
Commands with names ending in @code{-other-frame} behave like
@code{display-buffer}, except that they (i) never display in the
selected window and (ii) prefer to create a new frame to display the
desired buffer instead of splitting a window---as though the variable
@code{pop-up-frames} is set to @code{t} (@pxref{Window Choice}).
Several of these commands are bound in the @kbd{C-x 5} prefix key.
@menu
* Window Choice:: How @code{display-buffer} works.
@end menu
@node Window Choice
@subsection How @code{display-buffer} works
@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:
@itemize
@vindex same-window-buffer-names
@vindex same-window-regexps
@item
First, check if the buffer should be displayed in the selected window
regardless of other considerations. You can tell Emacs to do this by
adding the desired buffer's name to the list
@code{same-window-buffer-names}, or adding a matching regular
expression to the list @code{same-window-regexps}. By default, these
variables are @code{nil}, so this step is skipped.
@vindex display-buffer-reuse-frames
@item
Otherwise, if the buffer is already displayed in an existing window,
``reuse'' that window. Normally, only windows on the selected frame
are considered, but windows on other frames are also reusable if you
change @code{display-buffer-reuse-frames} to @code{t}, or if you
change @code{pop-up-frames} (see below) to @code{t}.
@item
Otherwise, if you specified that the buffer should be displayed in a
special frame by customizing @code{special-display-buffer-names} or
@code{special-display-regexps}, do so. @xref{Special Buffer Frames}.
@vindex pop-up-frames
@item
Otherwise, optionally create a new frame and display the buffer there.
By default, this step is skipped. To enable it, change the variable
@code{pop-up-frames} to a non-@code{nil} value. The special value
@code{graphic-only} means to do this only on graphical displays.
@item
Otherwise, try to create a new window by splitting the selected
window, and display the buffer in that new window.
@vindex split-height-threshold
@vindex split-width-threshold
The split can be either vertical or horizontal, depending on the
variables @code{split-height-threshold} and
@code{split-width-threshold}. These variables should have integer
values. If @code{split-height-threshold} is smaller than the selected
window's height, the split puts the new window below. Otherwise, if
@code{split-width-threshold} is smaller than the window's width, the
split puts the new window on the right. If neither condition holds,
Emacs tries to split so that the new window is below---but only if the
window was not split before (to avoid excessive splitting).
@item
Otherwise, display the buffer in an existing window on the selected
frame.
@item
If all the above methods fail for whatever reason, create a new frame
and display the buffer there.
@end itemize
@node Window Convenience
@section Window Handling Convenience Features and Customization

View file

@ -386,6 +386,45 @@ by default.
*** `menu-bar-select-buffer-function' lets you choose another operation
instead of `switch-to-buffer' when selecting an item in the Buffers menu.
** Window changes
+++
*** Resizing an Emacs frame now preserves proportional window sizes,
modulo restrictions like window minimum sizes and fixed-size windows.
*** The behavior of `display-buffer' is now customizable in detail.
**** New option `display-buffer-base-action' specifies a list of
user-determined display "actions" (functions and optional arguments
for choosing the displaying window).
This takes precedence over the default display action, which is
specified by `display-buffer-fallback-action'.
**** New option `display-buffer-alist' maps buffer name regexps to
display actions, taking precedence over `display-buffer-base-action'.
+++
*** New option `window-nest'.
The new option `window-nest' allows to return the space obtained for
resizing or creating a window more reliably to the window from which
such space was obtained.
+++
*** New option `window-splits'.
The new option `window-splits' allows to split a window that otherwise
cannot be split because it's too small by stealing space from other
windows in the same combination.
+++
*** New commands `maximize-window' and `minimize-window'.
These maximize and minize the size of a window within its frame.
+++
*** New commands `switch-to-prev-buffer' and `switch-to-next-buffer'.
These functions allow to navigate through the live buffers that have
been shown in a specific window.
** The inactive minibuffer has its own major mode `minibuffer-inactive-mode'.
This is handy for minibuffer-only frames, and is also used for the "mouse-1
pops up *Messages*" feature, which can now easily be changed.
@ -1002,18 +1041,6 @@ new window appear on the corresponding side of the window that shall be
split. Any other value of SIDE will cause `split-window' to split the
window into two side-by-side windows as before.
+++
*** New option `window-nest'.
The new option `window-nest' allows to return the space obtained for
resizing or creating a window more reliably to the window from which
such space was obtained.
+++
*** New option `window-splits'.
The new option `window-splits' allows to split a window that otherwise
cannot be split because it's too small by stealing space from other
windows in the same combination.
+++
*** `split-window-above-each-other' and `split-window-side-by-side'.
The commands `split-window-vertically' and `split-window-horizontally'
@ -1027,12 +1054,6 @@ A new standard function for resizing windows called `resize-window' has
been introduced. This and all other functions for resizing windows no
longer delete any windows when they become too small.
+++
*** Frame/window resizing.
Resizing an Emacs frame now preserves the proportional sizes of
subwindows modulo restrictions imposed by window minimum sizes and
fixed-size windows.
+++
*** `adjust-window-trailing-edge' adjustments.
`adjust-window-trailing-edge' can now deal with fixed-size windows and
@ -1041,11 +1062,6 @@ edge cannot be shrunk any more. This makes its behavior more similar to
that of Emacs 21 without compromising, however, its inability to delete
windows which was introduced in Emacs 22.
+++
*** Commands for maximizing and minimizing windows.
New functions to maximize and minimize a window within its frame are
provided, namely `maximize-window' and `minimize-window'.
+++
*** Window-local buffer lists.
Windows now have local buffer lists. This means that removing a buffer
@ -1054,17 +1070,31 @@ shown in that window with its previous window-start and window-point
positions. This also means that the same buffer may be automatically
shown twice even if it already appears in another window.
+++
*** New commands `switch-to-prev-buffer' and `switch-to-next-buffer'.
These functions allow to navigate through the live buffers that have
been shown in a specific window.
*** `switch-to-buffer' has a new optional argument FORCE-SAME-WINDOW,
which if non-nil requires the buffer to be displayed in the currently
selected window, signaling an error otherwise. If nil, another window
can be used, e.g. if the selected one is strongly dedicated.
*** FIXME: buffer-display-alist changes
*** `split-window-vertically' and `split-window-horizontally' renamed
to `split-window-above-each-other' and `split-window-side-by-side'
respectively. The old names are kept as aliases.
*** Display actions
**** The second arg to `display-buffer' and `pop-to-buffer' is now
named ACTION, and takes a display action of the same form as
`display-buffer-base-action' (see Changes, above). A non-nil,
non-list value is treated specially, as the old meaning.
**** New variable `display-buffer-overriding-action'.
**** The procedure of `display-buffer' etc. to choose a window is
determined by combining `display-buffer-overriding-action',
`display-buffer-alist', the ACTION arg, `display-buffer-base-action',
and `display-buffer-fallback-action'. The second and fourth of these
are user-customizable variables.
See the docstring of `display-buffer' for details.
** Completion