001: @c This is part of the Emacs manual.
002: @c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2018 Free Software
003: @c Foundation, Inc.
004: @c See file emacs.texi for copying conditions.
005: @node Windows
006: @chapter Multiple Windows
007: @cindex windows in Emacs
008: @cindex multiple windows in Emacs
009: 
010:   Emacs can split a frame into two or many windows.  Multiple windows
011: can display parts of different buffers, or different parts of one
012: buffer.  Multiple frames always imply multiple windows, because each
013: frame has its own set of windows.  Each window belongs to one and only
014: one frame.
015: 
016: @menu
017: * Basic Window::        Introduction to Emacs windows.
018: * Split Window::        New windows are made by splitting existing windows.
019: * Other Window::        Moving to another window or doing something to it.
020: * Pop Up Window::       Finding a file or buffer in another window.
021: * Change Window::       Deleting windows and changing their sizes.
022: * Displaying Buffers::  How Emacs picks a window for displaying a buffer.
023: * Window Convenience::  Convenience functions for window handling.
024: @end menu
025: 
026: @node Basic Window
027: @section Concepts of Emacs Windows
028: 
029:   Each Emacs window displays one Emacs buffer at any time.  A single
030: buffer may appear in more than one window; if it does, any changes in
031: its text are displayed in all the windows where it appears.  But these
032: windows can show different parts of the buffer, because each window
033: has its own value of point.
034: 
035: @cindex selected window
036:   At any time, one Emacs window is the @dfn{selected window}; the
037: buffer this window is displaying is the current buffer.  On graphical
038: displays, the point is indicated by a solid blinking cursor in the
039: selected window, and by a hollow box in non-selected windows.  On text
040: terminals, the cursor is drawn only in the selected window.
041: @xref{Cursor Display}.
042: 
043:   Commands to move point affect the value of point for the selected
044: Emacs window only.  They do not change the value of point in other
045: Emacs windows, even those showing the same buffer.  The same is true
046: for buffer-switching commands such as @kbd{C-x b}; they do not affect
047: other windows at all.  However, there are other commands such as
048: @kbd{C-x 4 b} that select a different window and switch buffers in it.
049: Also, all commands that display information in a window, including
050: (for example) @kbd{C-h f} (@code{describe-function}) and @kbd{C-x C-b}
051: (@code{list-buffers}), usually work by displaying buffers in a
052: nonselected window without affecting the selected window.
053: 
054:   When multiple windows show the same buffer, they can have different
055: regions, because they can have different values of point.  However,
056: they all have the same value for the mark, because each buffer has
057: only one mark position.
058: 
059:   Each window has its own mode line, which displays the buffer name,
060: modification status and major and minor modes of the buffer that is
061: displayed in the window.  The selected window's mode line appears in a
062: different color.  @xref{Mode Line}, for details.
063: 
064: @node Split Window
065: @section Splitting Windows
066: 
067: @table @kbd
068: @item C-x 2
069: Split the selected window into two windows, one above the other
070: (@code{split-window-below}).
071: @item C-x 3
072: Split the selected window into two windows, positioned side by side
073: (@code{split-window-right}).
074: @item C-mouse-2
075: In the mode line of a window, split that window.
076: @end table
077: 
078: @kindex C-x 2
079: @findex split-window-below
080:   @kbd{C-x 2} (@code{split-window-below}) splits the selected window
081: into two windows, one above the other.  After splitting, the selected
082: window is the upper one, and the newly split-off window is below.
083: Both windows have the same value of point as before, and display the
084: same portion of the buffer (or as close to it as possible).  If
085: necessary, the windows are scrolled to keep point on-screen.  By
086: default, the two windows each get half the height of the original
087: window.  A positive numeric argument specifies how many lines to give
088: to the top window; a negative numeric argument specifies how many
089: lines to give to the bottom window.
090: 
091: @vindex split-window-keep-point
092:   If you change the variable @code{split-window-keep-point} to
093: @code{nil}, @kbd{C-x 2} instead adjusts the portion of the buffer
094: displayed by the two windows, as well as the value of point in each
095: window, in order to keep the text on the screen as close as possible
096: to what it was before; furthermore, if point was in the lower half of
097: the original window, the bottom window is selected instead of the
098: upper one.
099: 
100: @kindex C-x 3
101: @findex split-window-right
102:   @kbd{C-x 3} (@code{split-window-right}) splits the selected window
103: into two side-by-side windows.  The left window is the selected one;
104: the right window displays the same portion of the same buffer, and has
105: the same value of point.  A positive numeric argument specifies how
106: many columns to give the left window; a negative numeric argument
107: specifies how many columns to give the right window.
108: 
109: @vindex truncate-partial-width-windows
110:   When you split a window with @kbd{C-x 3}, each resulting window
111: occupies less than the full width of the frame.  If it becomes too
112: narrow, the buffer may be difficult to read if continuation lines are
113: in use (@pxref{Continuation Lines}).  Therefore, Emacs automatically
114: switches to line truncation if the window width becomes narrower than
115: 50 columns.  This truncation occurs regardless of the value of the
116: variable @code{truncate-lines} (@pxref{Line Truncation}); it is
117: instead controlled by the variable
118: @code{truncate-partial-width-windows}.  If the value of this variable
119: is a positive integer (the default is 50), that specifies the minimum
120: total width for a partial-width window before automatic line
121: truncation occurs; if the value is @code{nil}, automatic line
122: truncation is disabled; and for any other non-@code{nil} value, Emacs
123: truncates lines in every partial-width window regardless of its width.
124: The total width of a window is in column units as reported by
125: @code{window-total-width} (@pxref{Window Sizes,,, elisp, The Emacs
126: Lisp Reference Manual}), it includes the fringes, the continuation and
127: truncation glyphs, the margins, and the scroll bar.
128: 
129:   On text terminals, side-by-side windows are separated by a vertical
130: divider which is drawn using the @code{vertical-border} face.
131: 
132: @kindex C-mouse-2 @r{(mode line)}
133: @kindex C-mouse-2 @r{(scroll bar)}
134:   If you click @kbd{C-mouse-2} in the mode line of a window, that
135: splits the window, putting a vertical divider where you click.
136: Depending on how Emacs is compiled, you can also split a window by
137: clicking @kbd{C-mouse-2} in the scroll bar, which puts a horizontal
138: divider where you click (this feature does not work when Emacs uses
139: GTK+ scroll bars).
140: 
141: @vindex window-resize-pixelwise
142:   By default, when you split a window, Emacs gives each of the
143: resulting windows dimensions that are an integral multiple of the
144: default font size of the frame.  That might subdivide the screen
145: estate unevenly between the resulting windows.  If you set the
146: variable @code{window-resize-pixelwise} to a non-@code{nil} value,
147: Emacs will give each window the same number of pixels (give or take
148: one pixel if the initial dimension was an odd number of pixels).  Note
149: that when a frame's pixel size is not a multiple of the frame's
150: character size, at least one window may get resized pixelwise even if
151: this option is @code{nil}.
152: 
153: @node Other Window
154: @section Using Other Windows
155: 
156: @table @kbd
157: @item C-x o
158: Select another window (@code{other-window}).
159: @item C-M-v
160: Scroll the next window (@code{scroll-other-window}).
161: @item mouse-1
162: @kbd{mouse-1}, in the text area of a window, selects the window and
163: moves point to the position clicked.  Clicking in the mode line
164: selects the window without moving point in it.
165: @end table
166: 
167: @kindex C-x o
168: @findex other-window
169: With the keyboard, you can switch windows by typing @kbd{C-x o}
170: (@code{other-window}).  That is an @kbd{o}, for ``other'', not a zero.
171: When there are more than two windows, this command moves through all the
172: windows in a cyclic order, generally top to bottom and left to right.
173: After the rightmost and bottommost window, it goes back to the one at
174: the upper left corner.  A numeric argument means to move several steps
175: in the cyclic order of windows.  A negative argument moves around the
176: cycle in the opposite order.  When the minibuffer is active, the
177: minibuffer window is the last window in the cycle; you can switch from
178: the minibuffer window to one of the other windows, and later switch
179: back and finish supplying the minibuffer argument that is requested.
180: @xref{Minibuffer Edit}.
181: 
182: @kindex C-M-v
183: @findex scroll-other-window
184:   The usual scrolling commands (@pxref{Display}) apply to the selected
185: window only, but there is one command to scroll the next window.
186: @kbd{C-M-v} (@code{scroll-other-window}) scrolls the window that
187: @kbd{C-x o} would select.  It takes arguments, positive and negative,
188: like @kbd{C-v}.  (In the minibuffer, @kbd{C-M-v} scrolls the help
189: window associated with the minibuffer, if any, rather than the next
190: window in the standard cyclic order; @pxref{Minibuffer Edit}.)
191: 
192: @vindex mouse-autoselect-window
193:   If you set @code{mouse-autoselect-window} to a non-@code{nil} value,
194: moving the mouse over a different window selects that window.  This
195: feature is off by default.
196: 
197: @node Pop Up Window
198: @section Displaying in Another Window
199: 
200: @cindex selecting buffers in other windows
201: @kindex C-x 4
202:   @kbd{C-x 4} is a prefix key for a variety of commands that switch to
203: a buffer in a different window---either another existing window, or a
204: new window created by splitting the selected window.  @xref{Window
205: Choice}, for how Emacs picks or creates the window to use.
206: 
207: @table @kbd
208: @item C-x 4 b @var{bufname} @key{RET}
209: Select buffer @var{bufname} in another window
210: (@code{switch-to-buffer-other-window}).  @xref{Select Buffer}.
211: 
212: @findex display-buffer @r{(command)}
213: @item C-x 4 C-o @var{bufname} @key{RET}
214: @kindex C-x 4 C-o
215: Display buffer @var{bufname} in some window, without trying to select
216: it (@code{display-buffer}).  @xref{Displaying Buffers}, for details
217: about how the window is chosen.
218: 
219: @item C-x 4 f @var{filename} @key{RET}
220: Visit file @var{filename} and select its buffer in another window
221: (@code{find-file-other-window}).  @xref{Visiting}.
222: 
223: @item C-x 4 d @var{directory} @key{RET}
224: Select a Dired buffer for directory @var{directory} in another window
225: (@code{dired-other-window}).  @xref{Dired}.
226: 
227: @c Don't index @kbd{C-x 4 m} and @code{compose-mail-other-window}
228: @c here, they are indexed in sending.texi, in the "Sending Mail" node.
229: @item C-x 4 m
230: Start composing a mail message, similar to @kbd{C-x m} (@pxref{Sending
231: Mail}), but in another window (@code{compose-mail-other-window}).
232: 
233: @findex find-tag-other-window
234: @item C-x 4 .
235: Find the definition of an identifier, similar to @kbd{M-.}
236: (@pxref{Xref}), but in another window
237: (@code{xref-find-definitions-other-window}).
238: @item C-x 4 r @var{filename} @key{RET}
239: Visit file @var{filename} read-only, and select its buffer in another
240: window (@code{find-file-read-only-other-window}).  @xref{Visiting}.
241: @end table
242: 
243: @node Change Window
244: @section Deleting and Resizing Windows
245: 
246: @cindex delete window
247: @cindex deleting windows
248: @table @kbd
249: @item C-x 0
250: Delete the selected window (@code{delete-window}).
251: @item C-x 1
252: Delete all windows in the selected frame except the selected window
253: (@code{delete-other-windows}).
254: @item C-x 4 0
255: Delete the selected window and kill the buffer that was showing in it
256: (@code{kill-buffer-and-window}).  The last character in this key
257: sequence is a zero.
258: @item C-x ^
259: Make selected window taller (@code{enlarge-window}).
260: @item C-x @}
261: Make selected window wider (@code{enlarge-window-horizontally}).
262: @item C-x @{
263: Make selected window narrower (@code{shrink-window-horizontally}).
264: @item C-x -
265: Shrink this window if its buffer doesn't need so many lines
266: (@code{shrink-window-if-larger-than-buffer}).
267: @item C-x +
268: Make all windows the same height (@code{balance-windows}).
269: @end table
270: 
271: @kindex C-x 0
272: @findex delete-window
273:   To delete the selected window, type @kbd{C-x 0}
274: (@code{delete-window}).  (That is a zero.)  Once a window is deleted,
275: the space that it occupied is given to an adjacent window (but not the
276: minibuffer window, even if that is active at the time).  Deleting the
277: window has no effect on the buffer it used to display; the buffer
278: continues to exist, and you can still switch to it with @kbd{C-x b}.
279: 
280: @findex kill-buffer-and-window
281: @kindex C-x 4 0
282:   @kbd{C-x 4 0} (@code{kill-buffer-and-window}) is a stronger command
283: than @kbd{C-x 0}; it kills the current buffer and then deletes the
284: selected window.
285: 
286: @kindex C-x 1
287: @findex delete-other-windows
288:   @kbd{C-x 1} (@code{delete-other-windows}) deletes all the windows,
289: @emph{except} the selected one; the selected window expands to use the
290: whole frame.  (This command cannot be used while the minibuffer window
291: is active; attempting to do so signals an error.)
292: 
293: @cindex resize window
294: @cindex resizing windows
295: @kindex C-x ^
296: @findex enlarge-window
297: @kindex C-x @}
298: @vindex window-min-height
299:   The command @kbd{C-x ^} (@code{enlarge-window}) makes the selected
300: window one line taller, taking space from a vertically adjacent window
301: without changing the height of the frame.  With a positive numeric
302: argument, this command increases the window height by that many lines;
303: with a negative argument, it reduces the height by that many lines.
304: If there are no vertically adjacent windows (i.e., the window is at the
305: full frame height), that signals an error.  The command also signals
306: an error if you attempt to reduce the height of any window below a
307: certain minimum number of lines, specified by the variable
308: @code{window-min-height} (the default is 4).
309: 
310: @findex enlarge-window-horizontally
311: @findex shrink-window-horizontally
312: @vindex window-min-width
313:   Similarly, @kbd{C-x @}} (@code{enlarge-window-horizontally}) makes
314: the selected window wider, and @kbd{C-x @{}
315: (@code{shrink-window-horizontally}) makes it narrower.  These commands
316: signal an error if you attempt to reduce the width of any window below
317: a certain minimum number of columns, specified by the variable
318: @code{window-min-width} (the default is 10).
319: 
320:   Mouse clicks on the mode line (@pxref{Mode Line Mouse}) or on window
321: dividers (@pxref{Window Dividers}) provide another way to change window
322: heights and to split or delete windows.
323: 
324: @kindex C-x -
325: @findex shrink-window-if-larger-than-buffer
326:   @kbd{C-x -} (@code{shrink-window-if-larger-than-buffer}) reduces the
327: height of the selected window, if it is taller than necessary to show
328: the whole text of the buffer it is displaying.  It gives the extra
329: lines to other windows in the frame.
330: 
331: @kindex C-x +
332: @findex balance-windows
333:   You can also use @kbd{C-x +} (@code{balance-windows}) to even out the
334: heights of all the windows in the selected frame.
335: 
336: @node Displaying Buffers
337: @section Displaying a Buffer in a Window
338: 
339:   It is a common Emacs operation to display or pop up some buffer
340: in response to a user command.  There are several different ways in
341: which commands do this.
342: 
343:   Many commands, like @kbd{C-x C-f} (@code{find-file}), by default
344: display the buffer by ``taking over'' the selected window, expecting
345: that the user's attention will be diverted to that buffer.
346: 
347:   Some commands try to display intelligently, trying not to take
348: over the selected window, e.g., by splitting off a new window and
349: displaying the desired buffer there.  Such commands, which include the
350: various help commands (@pxref{Help}), work by calling
351: @code{display-buffer} internally.  @xref{Window Choice}, for details.
352: 
353:   Other commands do the same as @code{display-buffer}, and
354: additionally select the displaying window so that you can begin
355: editing its buffer.  The command @kbd{C-x `} (@code{next-error}) is
356: one example (@pxref{Compilation Mode}).  Such commands work by calling
357: the function @code{pop-to-buffer} internally.  @xref{Switching
358: Buffers,,Switching to a Buffer in a Window, elisp, The Emacs Lisp
359: Reference Manual}.
360: 
361:   Commands with names ending in @code{-other-window} behave like
362: @code{display-buffer}, except that they never display in the selected
363: window.  Several of these commands are bound in the @kbd{C-x 4} prefix
364: key (@pxref{Pop Up Window}).
365: 
366:   Commands with names ending in @code{-other-frame} behave like
367: @code{display-buffer}, except that they (i) never display in the
368: selected window and (ii) prefer to either create a new frame or use a
369: window on some other frame to display the desired buffer.  Several of
370: these commands are bound in the @kbd{C-x 5} prefix key.
371: 
372: @menu
373: * Window Choice::   How @code{display-buffer} works.
374: * Temporary Displays::   Displaying non-editable buffers.
375: @end menu
376: 
377: @node Window Choice
378: @subsection How @code{display-buffer} works
379: @findex display-buffer@r{, detailed description}
380: 
381: The @code{display-buffer} command (as well as commands that call it
382: internally) chooses a window to display by following the steps given
383: below.  @xref{Choosing Window,,Choosing a Window for Displaying a
384: Buffer, elisp, The Emacs Lisp Reference Manual}, for details about how
385: to alter this sequence of steps.
386: 
387: @itemize
388: @item
389: If the buffer should be displayed in the selected window regardless of
390: other considerations, reuse the selected window.  By default, this
391: step is skipped, but you can tell Emacs not to skip it by adding a
392: regular expression matching the buffer's name together with a
393: reference to the @code{display-buffer-same-window} action function
394: (@pxref{Buffer Display Action Functions,,Action Functions for Buffer
395: Display, elisp, The Emacs Lisp Reference Manual}) to the option
396: @code{display-buffer-alist} (@pxref{Choosing Window,,Choosing a Window
397: for Displaying a Buffer, elisp, The Emacs Lisp Reference Manual}).
398: For example, to display the buffer @file{*scratch*} preferably in the
399: selected window write:
400: 
401: @example
402: @group
403: (customize-set-variable
404:  'display-buffer-alist
405:  '("\\*scratch\\*" (display-buffer-same-window)))
406: @end group
407: @end example
408: 
409: By default, @code{display-buffer-alist} is @code{nil}.
410: 
411: @item
412: Otherwise, if the buffer is already displayed in an existing window,
413: reuse that window.  Normally, only windows on the selected frame are
414: considered, but windows on other frames are also reusable if you use
415: the corresponding @code{reusable-frames} action alist entry
416: (@pxref{Buffer Display Action Alists,,Action Alists for Buffer
417: Display, elisp, The Emacs Lisp Reference Manual}).  See the
418: next step for an example of how to do that.
419: 
420: @item
421: Otherwise, optionally create a new frame and display the buffer there.
422: By default, this step is skipped.  To enable it, change the value of
423: the option @code{display-buffer-base-action} (@pxref{Choosing
424: Window,,Choosing a Window for Displaying a Buffer, elisp, The Emacs
425: Lisp Reference Manual}) as follows:
426: 
427: @example
428: @group
429: (customize-set-variable
430:  'display-buffer-base-action
431:  '((display-buffer-reuse-window display-buffer-pop-up-frame)
432:    (reusable-frames . 0)))
433: @end group
434: @end example
435: 
436: This customization will also try to make the preceding step search for
437: a reusable window on all visible or iconified frames.
438: 
439: @item
440: Otherwise, try to create a new window by splitting a window on the
441: selected frame, and display the buffer in that new window.
442: 
443: @vindex split-height-threshold
444: @vindex split-width-threshold
445: The split can be either vertical or horizontal, depending on the
446: variables @code{split-height-threshold} and
447: @code{split-width-threshold}.  These variables should have integer
448: values.  If @code{split-height-threshold} is smaller than the chosen
449: window's height, the split puts the new window below.  Otherwise, if
450: @code{split-width-threshold} is smaller than the window's width, the
451: split puts the new window on the right.  If neither condition holds,
452: Emacs tries to split so that the new window is below---but only if the
453: window was not split before (to avoid excessive splitting).
454: 
455: @item
456: Otherwise, display the buffer in a window previously showing it.
457: Normally, only windows on the selected frame are considered, but with
458: a suitable @code{reusable-frames} action alist entry (see above) the
459: window may be also on another frame.
460: 
461: @item
462: Otherwise, display the buffer in an existing window on the selected
463: frame.
464: 
465: @item
466: If all the above methods fail for whatever reason, create a new frame
467: and display the buffer there.
468: @end itemize
469: 
470: 
471: @node Temporary Displays
472: @subsection Displaying non-editable buffers.
473: @cindex temporary windows
474: 
475: Some buffers are shown in windows for perusal rather than for editing.
476: Help commands (@pxref{Help}) typically use a buffer called @file{*Help*}
477: for that purpose, minibuffer completion (@pxref{Completion}) uses a
478: buffer called @file{*Completions*}, etc.  Such buffers are usually
479: displayed only for a short period of time.
480: 
481:   Normally, Emacs chooses the window for such temporary displays via
482: @code{display-buffer}, as described in the previous subsection.  The
483: @file{*Completions*} buffer, on the other hand, is normally displayed
484: in a window at the bottom of the selected frame, regardless of the
485: number of windows already shown on that frame.
486: 
487:   If you prefer Emacs to display a temporary buffer in a different
488: fashion, customize the variable @code{display-buffer-alist}
489: (@pxref{Choosing Window,,Choosing a Window for Displaying a Buffer,
490: elisp, The Emacs Lisp Reference Manual}) appropriately.  For example,
491: to display @file{*Completions*} always below the selected window, use
492: the following form in your initialization file (@pxref{Init File}):
493: 
494: @example
495: @group
496: (customize-set-variable
497:  'display-buffer-alist
498:  '(("\\*Completions\\*" display-buffer-below-selected)))
499: @end group
500: @end example
501: 
502: @findex temp-buffer-resize-mode
503:   The @file{*Completions*} buffer is also special in the sense that
504: Emacs usually tries to make its window just as large as necessary to
505: display all of its contents.  To resize windows showing other
506: temporary displays, like, for example, the @file{*Help*} buffer, turn
507: on the minor mode (@pxref{Minor Modes}) @code{temp-buffer-resize-mode}
508: (@pxref{Temporary Displays,,Temporary Displays, elisp, The Emacs Lisp
509: Reference Manual}).
510: 
511: @vindex temp-buffer-max-height
512: @vindex temp-buffer-max-width
513:   The maximum size of windows resized by @code{temp-buffer-resize-mode}
514: can be controlled by customizing the options
515: @code{temp-buffer-max-height} and @code{temp-buffer-max-width}
516: (@pxref{Temporary Displays,,Temporary Displays, elisp, The Emacs Lisp
517: Reference Manual}), and cannot exceed the size of the containing frame.
518: 
519: 
520: @node Window Convenience
521: @section Convenience Features for Window Handling
522: 
523: @findex winner-mode
524: @cindex Winner mode
525: @cindex mode, Winner
526: @cindex undoing window configuration changes
527: @cindex window configuration changes, undoing
528:   Winner mode is a global minor mode that records the changes in the
529: window configuration (i.e., how the frames are partitioned into
530: windows), so that you can undo them.  You can toggle Winner mode
531: with @kbd{M-x winner-mode}, or by customizing the variable
532: @code{winner-mode}.  When the mode is enabled, @kbd{C-c left}
533: (@code{winner-undo}) undoes the last window configuration change.  If
534: you change your mind while undoing, you can redo the changes you had
535: undone using @kbd{C-c right} (@code{M-x winner-redo}).
536: 
537:   Follow mode (@kbd{M-x follow-mode}) synchronizes several windows on
538: the same buffer so that they always display adjacent sections of that
539: buffer.  @xref{Follow Mode}.
540: 
541: @cindex Windmove package
542: @cindex directional window selection
543: @findex windmove-right
544: @findex windmove-default-keybindings
545:   The Windmove package defines commands for moving directionally
546: between neighboring windows in a frame.  @kbd{M-x windmove-right}
547: selects the window immediately to the right of the currently selected
548: one, and similarly for the left, up, and down
549: counterparts.  @kbd{M-x windmove-default-keybindings} binds these
550: commands to @kbd{S-right} etc.; doing so disables shift selection for
551: those keys (@pxref{Shift Selection}).
552: 
553:   The command @kbd{M-x compare-windows} lets you compare the text
554: shown in different windows.  @xref{Comparing Files}.
555: 
556: @vindex scroll-all-mode
557: @cindex scrolling windows together
558: @cindex Scroll-all mode
559: @cindex mode, Scroll-all
560:   Scroll All mode (@kbd{M-x scroll-all-mode}) is a global minor mode
561: that causes scrolling commands and point motion commands to apply to
562: every single window.
563: