@c This is part of the Emacs manual.
-@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2013 Free Software
+@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
@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}).
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 @}
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
+ 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
@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
@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{pop-up-frames} (see below) to @code{t}.
@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 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
+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}).