@c This is part of the Emacs manual.
-@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2016 Free Software
+@c Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Windows
@chapter Multiple Windows
@item C-x 3
Split the selected window into two windows, positioned side by side
(@code{split-window-right}).
-@item C-Mouse-2
+@item C-mouse-2
In the mode line of a window, split that window.
@end table
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.
+total 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.
+The total width of a window is in column units as reported by
+@code{window-total-width} (@pxref{Window Sizes,,, elisp, The Emacs
+Lisp Reference Manual}), it includes the fringes, the continuation and
+truncation glyphs, the margins, and the scroll bar.
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{(mode line)}
-@kindex C-Mouse-2 @r{(scroll bar)}
- If you click @kbd{C-Mouse-2} in the mode line of a window, that
+@kindex C-mouse-2 @r{(mode line)}
+@kindex C-mouse-2 @r{(scroll bar)}
+ If you click @kbd{C-mouse-2} in the mode line of a window, that
splits the window, putting a vertical divider where you click.
Depending on how Emacs is compiled, you can also split a window by
-clicking @kbd{C-Mouse-2} in the scroll bar, which puts a horizontal
+clicking @kbd{C-mouse-2} in the scroll bar, which puts a horizontal
divider where you click (this feature does not work when Emacs uses
GTK+ scroll bars).
+@vindex window-resize-pixelwise
+ By default, when you split a window, Emacs gives each of the
+resulting windows dimensions that are an integral multiple of the
+default font size of the frame. That might subdivide the screen
+estate unevenly between the resulting windows. If you set the
+variable @code{window-resize-pixelwise} to a non-@code{nil} value,
+Emacs will give each window the same number of pixels (give or take
+one pixel if the initial dimension was an odd number of pixels). Note
+that when a frame's pixel size is not a multiple of the frame's
+character size, at least one window may get resized pixelwise even if
+this option is @code{nil}.
+
@node Other Window
@section Using Other Windows
Select another window (@code{other-window}).
@item C-M-v
Scroll the next window (@code{scroll-other-window}).
-@item Mouse-1
-@kbd{Mouse-1}, in the text area of a window, selects the window and
+@item mouse-1
+@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
Select buffer @var{bufname} in another window
(@code{switch-to-buffer-other-window}).
-@findex display-buffer
+@findex display-buffer @r{(command)}
@item C-x 4 C-o @var{bufname} @key{RET}
@kindex C-x 4 C-o
Display buffer @var{bufname} in some window, without trying to select
Select a Dired buffer for directory @var{directory} in another window
(@code{dired-other-window}). @xref{Dired}.
-@findex mail-other-window
+@c Don't index @kbd{C-x 4 m} and @code{compose-mail-other-window}
+@c here, they are indexed in sending.texi, in the "Sending Mail" node.
@item C-x 4 m
Start composing a mail message, similar to @kbd{C-x m} (@pxref{Sending
-Mail}), but in another window (@code{mail-other-window}).
+Mail}), but in another window (@code{compose-mail-other-window}).
@findex find-tag-other-window
@item C-x 4 .
-Find a tag in the current tags table, similar to @kbd{M-.}
-(@pxref{Tags}), but in another window (@code{find-tag-other-window}).
+Find the definition of an identifier, similar to @kbd{M-.}
+(@pxref{Xref}), but in another window
+(@code{xref-find-definitions-other-window}).
@item C-x 4 r @var{filename} @key{RET}
Visit file @var{filename} read-only, and select its buffer in another
window (@code{find-file-read-only-other-window}). @xref{Visiting}.
@end table
@node Change Window
-@section Deleting and Rearranging Windows
+@section Deleting and Resizing Windows
+@cindex delete window
+@cindex deleting windows
@table @kbd
@item C-x 0
Delete the selected window (@code{delete-window}).
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 still switch to with @kbd{C-x b}.
+continues to exist, and you can still switch to it with @kbd{C-x b}.
@findex kill-buffer-and-window
@kindex C-x 4 0
whole frame. (This command cannot be used while the minibuffer window
is active; attempting to do so signals an error.)
+@cindex resize window
+@cindex resizing windows
@kindex C-x ^
@findex enlarge-window
@kindex C-x @}
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
+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
a certain minimum number of columns, specified by the variable
@code{window-min-width} (the default is 10).
+ Mouse clicks on the mode line (@pxref{Mode Line Mouse}) or on window
+dividers (@pxref{Window Dividers}) provide another way to change window
+heights and to split or delete windows.
+
@kindex C-x -
@findex shrink-window-if-larger-than-buffer
@kbd{C-x -} (@code{shrink-window-if-larger-than-buffer}) reduces the
You can also use @kbd{C-x +} (@code{balance-windows}) to even out the
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
+ It is a common Emacs operation to display or pop up some buffer
in response to a user command. There are several different ways in
which commands do this.
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 off a new window and
+ Some commands try to display intelligently, trying not to take
+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.
@menu
* Window Choice:: How @code{display-buffer} works.
+* Temporary Displays:: Displaying non-editable buffers.
@end menu
@node Window Choice
@subsection How @code{display-buffer} works
-@findex display-buffer
+@findex display-buffer, detailed description
The @code{display-buffer} command (as well as commands that call it
internally) chooses a window to display by following the steps given
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
+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{Choosing Window
-Options,,, elisp, The Emacs Lisp Reference Manual}.
-
@vindex pop-up-frames
@item
Otherwise, optionally create a new frame and display the buffer there.
@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.
+Otherwise, try to create a new window by splitting a window on the
+selected frame, 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
+values. If @code{split-height-threshold} is smaller than the chosen
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 a window previously showing it.
+Normally, only windows on the selected frame are considered, but if
+@code{pop-up-frames} is non-@code{nil} the window may be also on another
+frame.
+
@item
Otherwise, display the buffer in an existing window on the selected
frame.
and display the buffer there.
@end itemize
+A more advanced and flexible way to customize the behavior of
+@code{display-buffer} is by using the option @code{display-buffer-alist}
+mentioned in the next section.
+
+
+@node Temporary Displays
+@subsection Displaying non-editable buffers.
+@cindex pop-up windows
+@cindex temporary windows
+
+Some buffers are shown in windows for perusal rather than for editing.
+Help commands (@pxref{Help}) typically use a buffer called @file{*Help*}
+for that purpose, minibuffer completion (@pxref{Completion}) uses a
+buffer called @file{*Completions*} instead. Such buffers are usually
+displayed only for a short period of time.
+
+ Normally, Emacs chooses the window for such temporary displays via
+@code{display-buffer} as described above. The @file{*Completions*}
+buffer, on the other hand, is normally displayed in a window at the
+bottom of the selected frame, regardless of the number of windows
+already shown on that frame.
+
+ If you prefer Emacs to display a temporary buffer in a different
+fashion, we recommend to customize the variable
+@code{display-buffer-alist} (@pxref{Choosing Window,,Choosing a Window
+for Display, elisp, The Emacs Lisp Reference Manual}). For example,
+to display @file{*Completions*} by splitting a window as described in
+the previous section, use the following form in your initialization
+file (@pxref{Init File}):
+
+@example
+@group
+(customize-set-variable
+ 'display-buffer-alist
+ '(("\\*Completions\\*" display-buffer-pop-up-window)))
+@end group
+@end example
+
+@findex temp-buffer-resize-mode
+ The @file{*Completions*} buffer is also special in the sense that
+Emacs usually tries to make its window just as large as necessary to
+display all of its contents. To resize windows showing other
+temporary displays like, for example, the @file{*Help*} buffer
+accordingly, turn on the minor mode (@pxref{Minor Modes})
+@code{temp-buffer-resize-mode} (@pxref{Temporary Displays,,Temporary
+Displays, elisp, The Emacs Lisp Reference Manual}).
+
+@vindex temp-buffer-max-height
+@vindex temp-buffer-max-width
+ The maximum size of windows resized by @code{temp-buffer-resize-mode}
+can be controlled by customizing the options
+@code{temp-buffer-max-height} and @code{temp-buffer-max-width}
+(@pxref{Temporary Displays,,Temporary Displays, elisp, The Emacs Lisp
+Reference Manual}) and cannot exceed the size of the containing frame.
+
+
@node Window Convenience
@section Convenience Features for Window Handling
@cindex undoing window configuration changes
@cindex window configuration changes, undoing
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
+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
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''
+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}).