]> code.delx.au - gnu-emacs/blob - doc/emacs/windows.texi
Minor copyedits of documentation for temporary displays
[gnu-emacs] / doc / emacs / windows.texi
1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2016 Free Software
3 @c Foundation, Inc.
4 @c See file emacs.texi for copying conditions.
5 @node Windows
6 @chapter Multiple Windows
7 @cindex windows in Emacs
8 @cindex multiple windows in Emacs
9
10 Emacs can split a frame into two or many windows. Multiple windows
11 can display parts of different buffers, or different parts of one
12 buffer. Multiple frames always imply multiple windows, because each
13 frame has its own set of windows. Each window belongs to one and only
14 one frame.
15
16 @menu
17 * Basic Window:: Introduction to Emacs windows.
18 * Split Window:: New windows are made by splitting existing windows.
19 * Other Window:: Moving to another window or doing something to it.
20 * Pop Up Window:: Finding a file or buffer in another window.
21 * Change Window:: Deleting windows and changing their sizes.
22 * Displaying Buffers:: How Emacs picks a window for displaying a buffer.
23 * Window Convenience:: Convenience functions for window handling.
24 @end menu
25
26 @node Basic Window
27 @section Concepts of Emacs Windows
28
29 Each Emacs window displays one Emacs buffer at any time. A single
30 buffer may appear in more than one window; if it does, any changes in
31 its text are displayed in all the windows where it appears. But these
32 windows can show different parts of the buffer, because each window
33 has its own value of point.
34
35 @cindex selected window
36 At any time, one Emacs window is the @dfn{selected window}; the
37 buffer this window is displaying is the current buffer. On graphical
38 displays, the point is indicated by a solid blinking cursor in the
39 selected window, and by a hollow box in non-selected windows. On text
40 terminals, the cursor is drawn only in the selected window.
41 @xref{Cursor Display}.
42
43 Commands to move point affect the value of point for the selected
44 Emacs window only. They do not change the value of point in other
45 Emacs windows, even those showing the same buffer. The same is true
46 for buffer-switching commands such as @kbd{C-x b}; they do not affect
47 other windows at all. However, there are other commands such as
48 @kbd{C-x 4 b} that select a different window and switch buffers in it.
49 Also, all commands that display information in a window, including
50 (for example) @kbd{C-h f} (@code{describe-function}) and @kbd{C-x C-b}
51 (@code{list-buffers}), work by switching buffers in a nonselected
52 window without affecting the selected window.
53
54 When multiple windows show the same buffer, they can have different
55 regions, because they can have different values of point. However,
56 they all have the same value for the mark, because each buffer has
57 only one mark position.
58
59 Each window has its own mode line, which displays the buffer name,
60 modification status and major and minor modes of the buffer that is
61 displayed in the window. The selected window's mode line appears in a
62 different color. @xref{Mode Line}, for details.
63
64 @node Split Window
65 @section Splitting Windows
66
67 @table @kbd
68 @item C-x 2
69 Split the selected window into two windows, one above the other
70 (@code{split-window-below}).
71 @item C-x 3
72 Split the selected window into two windows, positioned side by side
73 (@code{split-window-right}).
74 @item C-Mouse-2
75 In the mode line of a window, split that window.
76 @end table
77
78 @kindex C-x 2
79 @findex split-window-below
80 @kbd{C-x 2} (@code{split-window-below}) splits the selected window
81 into two windows, one above the other. After splitting, the selected
82 window is the upper one, and the newly split-off window is below.
83 Both windows have the same value of point as before, and display the
84 same portion of the buffer (or as close to it as possible). If
85 necessary, the windows are scrolled to keep point on-screen. By
86 default, the two windows each get half the height of the original
87 window. A positive numeric argument specifies how many lines to give
88 to the top window; a negative numeric argument specifies how many
89 lines to give to the bottom window.
90
91 @vindex split-window-keep-point
92 If you change the variable @code{split-window-keep-point} to
93 @code{nil}, @kbd{C-x 2} instead adjusts the portion of the buffer
94 displayed by the two windows, as well as the value of point in each
95 window, in order to keep the text on the screen as close as possible
96 to what it was before; furthermore, if point was in the lower half of
97 the original window, the bottom window is selected instead of the
98 upper one.
99
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 width for a partial-width window before automatic line truncation
121 occurs; if the value is @code{nil}, automatic line truncation is
122 disabled; and for any other non-@code{nil} value, Emacs truncates
123 lines in every partial-width window regardless of its width.
124
125 On text terminals, side-by-side windows are separated by a vertical
126 divider which is drawn using the @code{vertical-border} face.
127
128 @kindex C-Mouse-2 @r{(mode line)}
129 @kindex C-Mouse-2 @r{(scroll bar)}
130 If you click @kbd{C-Mouse-2} in the mode line of a window, that
131 splits the window, putting a vertical divider where you click.
132 Depending on how Emacs is compiled, you can also split a window by
133 clicking @kbd{C-Mouse-2} in the scroll bar, which puts a horizontal
134 divider where you click (this feature does not work when Emacs uses
135 GTK+ scroll bars).
136
137 @vindex window-resize-pixelwise
138 By default, when you split a window, Emacs gives each of the
139 resulting windows dimensions that are an integral multiple of the
140 default font size of the frame. That might subdivide the screen
141 estate unevenly between the resulting windows. If you set the
142 variable @code{window-resize-pixelwise} to a non-@code{nil} value,
143 Emacs will give each window the same number of pixels (give or take
144 one pixel if the initial dimension was an odd number of pixels). Note
145 that when a frame's pixel size is not a multiple of the frame's
146 character size, at least one window may get resized pixelwise even if
147 this option is @code{nil}.
148
149 @node Other Window
150 @section Using Other Windows
151
152 @table @kbd
153 @item C-x o
154 Select another window (@code{other-window}).
155 @item C-M-v
156 Scroll the next window (@code{scroll-other-window}).
157 @item Mouse-1
158 @kbd{Mouse-1}, in the text area of a window, selects the window and
159 moves point to the position clicked. Clicking in the mode line
160 selects the window without moving point in it.
161 @end table
162
163 @kindex C-x o
164 @findex other-window
165 With the keyboard, you can switch windows by typing @kbd{C-x o}
166 (@code{other-window}). That is an @kbd{o}, for ``other'', not a zero.
167 When there are more than two windows, this command moves through all the
168 windows in a cyclic order, generally top to bottom and left to right.
169 After the rightmost and bottommost window, it goes back to the one at
170 the upper left corner. A numeric argument means to move several steps
171 in the cyclic order of windows. A negative argument moves around the
172 cycle in the opposite order. When the minibuffer is active, the
173 minibuffer is the last window in the cycle; you can switch from the
174 minibuffer window to one of the other windows, and later switch back and
175 finish supplying the minibuffer argument that is requested.
176 @xref{Minibuffer Edit}.
177
178 @kindex C-M-v
179 @findex scroll-other-window
180 The usual scrolling commands (@pxref{Display}) apply to the selected
181 window only, but there is one command to scroll the next window.
182 @kbd{C-M-v} (@code{scroll-other-window}) scrolls the window that
183 @kbd{C-x o} would select. It takes arguments, positive and negative,
184 like @kbd{C-v}. (In the minibuffer, @kbd{C-M-v} scrolls the help
185 window associated with the minibuffer, if any, rather than the next
186 window in the standard cyclic order; @pxref{Minibuffer Edit}.)
187
188 @vindex mouse-autoselect-window
189 If you set @code{mouse-autoselect-window} to a non-@code{nil} value,
190 moving the mouse over a different window selects that window. This
191 feature is off by default.
192
193 @node Pop Up Window
194 @section Displaying in Another Window
195
196 @cindex selecting buffers in other windows
197 @kindex C-x 4
198 @kbd{C-x 4} is a prefix key for a variety of commands that switch to
199 a buffer in a different window---either another existing window, or a
200 new window created by splitting the selected window. @xref{Window
201 Choice}, for how Emacs picks or creates the window to use.
202
203 @table @kbd
204 @findex switch-to-buffer-other-window
205 @item C-x 4 b @var{bufname} @key{RET}
206 Select buffer @var{bufname} in another window
207 (@code{switch-to-buffer-other-window}).
208
209 @findex display-buffer @r{(command)}
210 @item C-x 4 C-o @var{bufname} @key{RET}
211 @kindex C-x 4 C-o
212 Display buffer @var{bufname} in some window, without trying to select
213 it (@code{display-buffer}). @xref{Displaying Buffers}, for details
214 about how the window is chosen.
215
216 @findex find-file-other-window
217 @item C-x 4 f @var{filename} @key{RET}
218 Visit file @var{filename} and select its buffer in another window
219 (@code{find-file-other-window}). @xref{Visiting}.
220
221 @findex dired-other-window
222 @item C-x 4 d @var{directory} @key{RET}
223 Select a Dired buffer for directory @var{directory} in another window
224 (@code{dired-other-window}). @xref{Dired}.
225
226 @c Don't index @kbd{C-x 4 m} and @code{compose-mail-other-window}
227 @c here, they are indexed in sending.texi, in the "Sending Mail" node.
228 @item C-x 4 m
229 Start composing a mail message, similar to @kbd{C-x m} (@pxref{Sending
230 Mail}), but in another window (@code{compose-mail-other-window}).
231
232 @findex find-tag-other-window
233 @item C-x 4 .
234 Find the definition of an identifier, similar to @kbd{M-.}
235 (@pxref{Xref}), but in another window
236 (@code{xref-find-definitions-other-window}).
237 @item C-x 4 r @var{filename} @key{RET}
238 Visit file @var{filename} read-only, and select its buffer in another
239 window (@code{find-file-read-only-other-window}). @xref{Visiting}.
240 @end table
241
242 @node Change Window
243 @section Deleting and Resizing Windows
244
245 @cindex delete window
246 @cindex deleting windows
247 @table @kbd
248 @item C-x 0
249 Delete the selected window (@code{delete-window}).
250 @item C-x 1
251 Delete all windows in the selected frame except the selected window
252 (@code{delete-other-windows}).
253 @item C-x 4 0
254 Delete the selected window and kill the buffer that was showing in it
255 (@code{kill-buffer-and-window}). The last character in this key
256 sequence is a zero.
257 @item C-x ^
258 Make selected window taller (@code{enlarge-window}).
259 @item C-x @}
260 Make selected window wider (@code{enlarge-window-horizontally}).
261 @item C-x @{
262 Make selected window narrower (@code{shrink-window-horizontally}).
263 @item C-x -
264 Shrink this window if its buffer doesn't need so many lines
265 (@code{shrink-window-if-larger-than-buffer}).
266 @item C-x +
267 Make all windows the same height (@code{balance-windows}).
268 @end table
269
270 @kindex C-x 0
271 @findex delete-window
272 To delete the selected window, type @kbd{C-x 0}
273 (@code{delete-window}). (That is a zero.) Once a window is deleted,
274 the space that it occupied is given to an adjacent window (but not the
275 minibuffer window, even if that is active at the time). Deleting the
276 window has no effect on the buffer it used to display; the buffer
277 continues to exist, and you can still switch to it with @kbd{C-x b}.
278
279 @findex kill-buffer-and-window
280 @kindex C-x 4 0
281 @kbd{C-x 4 0} (@code{kill-buffer-and-window}) is a stronger command
282 than @kbd{C-x 0}; it kills the current buffer and then deletes the
283 selected window.
284
285 @kindex C-x 1
286 @findex delete-other-windows
287 @kbd{C-x 1} (@code{delete-other-windows}) deletes all the windows,
288 @emph{except} the selected one; the selected window expands to use the
289 whole frame. (This command cannot be used while the minibuffer window
290 is active; attempting to do so signals an error.)
291
292 @cindex resize window
293 @cindex resizing windows
294 @kindex C-x ^
295 @findex enlarge-window
296 @kindex C-x @}
297 @vindex window-min-height
298 The command @kbd{C-x ^} (@code{enlarge-window}) makes the selected
299 window one line taller, taking space from a vertically adjacent window
300 without changing the height of the frame. With a positive numeric
301 argument, this command increases the window height by that many lines;
302 with a negative argument, it reduces the height by that many lines.
303 If there are no vertically adjacent windows (i.e., the window is at the
304 full frame height), that signals an error. The command also signals
305 an error if you attempt to reduce the height of any window below a
306 certain minimum number of lines, specified by the variable
307 @code{window-min-height} (the default is 4).
308
309 @findex enlarge-window-horizontally
310 @findex shrink-window-horizontally
311 @vindex window-min-width
312 Similarly, @kbd{C-x @}} (@code{enlarge-window-horizontally}) makes
313 the selected window wider, and @kbd{C-x @{}
314 (@code{shrink-window-horizontally}) makes it narrower. These commands
315 signal an error if you attempt to reduce the width of any window below
316 a certain minimum number of columns, specified by the variable
317 @code{window-min-width} (the default is 10).
318
319 Mouse clicks on the mode line (@pxref{Mode Line Mouse}) or on window
320 dividers (@pxref{Window Dividers}) provide another way to change window
321 heights and to split or delete windows.
322
323 @kindex C-x -
324 @findex shrink-window-if-larger-than-buffer
325 @kbd{C-x -} (@code{shrink-window-if-larger-than-buffer}) reduces the
326 height of the selected window, if it is taller than necessary to show
327 the whole text of the buffer it is displaying. It gives the extra
328 lines to other windows in the frame.
329
330 @kindex C-x +
331 @findex balance-windows
332 You can also use @kbd{C-x +} (@code{balance-windows}) to even out the
333 heights of all the windows in the selected frame.
334
335 @node Displaying Buffers
336 @section Displaying a Buffer in a Window
337
338 It is a common Emacs operation to display or pop up some buffer
339 in response to a user command. There are several different ways in
340 which commands do this.
341
342 Many commands, like @kbd{C-x C-f} (@code{find-file}), display the
343 buffer by ``taking over'' the selected window, expecting that the
344 user's attention will be diverted to that buffer. These commands
345 usually work by calling @code{switch-to-buffer} internally
346 (@pxref{Select Buffer}).
347
348 Some commands try to display intelligently, trying not to take
349 over the selected window, e.g., by splitting off a new window and
350 displaying the desired buffer there. Such commands, which include the
351 various help commands (@pxref{Help}), work by calling
352 @code{display-buffer} internally. @xref{Window Choice}, for details.
353
354 Other commands do the same as @code{display-buffer}, and
355 additionally select the displaying window so that you can begin
356 editing its buffer. The command @kbd{C-x `} (@code{next-error}) is
357 one example (@pxref{Compilation Mode}). Such commands work by calling
358 the function @code{pop-to-buffer} internally. @xref{Switching
359 Buffers,,Switching to a Buffer in a Window, elisp, The Emacs Lisp
360 Reference Manual}.
361
362 Commands with names ending in @code{-other-window} behave like
363 @code{display-buffer}, except that they never display in the selected
364 window. Several of these commands are bound in the @kbd{C-x 4} prefix
365 key (@pxref{Pop Up Window}).
366
367 Commands with names ending in @code{-other-frame} behave like
368 @code{display-buffer}, except that they (i) never display in the
369 selected window and (ii) prefer to create a new frame to display the
370 desired buffer instead of splitting a window---as though the variable
371 @code{pop-up-frames} is set to @code{t} (@pxref{Window Choice}).
372 Several of these commands are bound in the @kbd{C-x 5} prefix key.
373
374 @menu
375 * Window Choice:: How @code{display-buffer} works.
376 * Temporary Displays:: Displaying non-editable buffers.
377 @end menu
378
379 @node Window Choice
380 @subsection How @code{display-buffer} works
381 @findex display-buffer, detailed description
382
383 The @code{display-buffer} command (as well as commands that call it
384 internally) chooses a window to display by following the steps given
385 below. @xref{Choosing Window,,Choosing a Window for Display, elisp,
386 The Emacs Lisp Reference Manual}, for details about how to alter this
387 sequence of steps.
388
389 @itemize
390 @vindex same-window-buffer-names
391 @vindex same-window-regexps
392 @item
393 First, check if the buffer should be displayed in the selected window
394 regardless of other considerations. You can tell Emacs to do this by
395 adding the desired buffer's name to the list
396 @code{same-window-buffer-names}, or adding a matching regular
397 expression to the list @code{same-window-regexps}. By default, these
398 variables are @code{nil}, so this step is skipped.
399
400 @item
401 Otherwise, if the buffer is already displayed in an existing window,
402 reuse that window. Normally, only windows on the selected frame
403 are considered, but windows on other frames are also reusable if you
404 change @code{pop-up-frames} (see below) to @code{t}.
405
406 @vindex pop-up-frames
407 @item
408 Otherwise, optionally create a new frame and display the buffer there.
409 By default, this step is skipped. To enable it, change the variable
410 @code{pop-up-frames} to a non-@code{nil} value. The special value
411 @code{graphic-only} means to do this only on graphical displays.
412
413 @item
414 Otherwise, try to create a new window by splitting a window on the
415 selected frame, and display the buffer in that new window.
416
417 @vindex split-height-threshold
418 @vindex split-width-threshold
419 The split can be either vertical or horizontal, depending on the
420 variables @code{split-height-threshold} and
421 @code{split-width-threshold}. These variables should have integer
422 values. If @code{split-height-threshold} is smaller than the chosen
423 window's height, the split puts the new window below. Otherwise, if
424 @code{split-width-threshold} is smaller than the window's width, the
425 split puts the new window on the right. If neither condition holds,
426 Emacs tries to split so that the new window is below---but only if the
427 window was not split before (to avoid excessive splitting).
428
429 @item
430 Otherwise, display the buffer in a window previously showing it.
431 Normally, only windows on the selected frame are considered, but if
432 @code{pop-up-frames} is non-@code{nil} the window may be also on another
433 frame.
434
435 @item
436 Otherwise, display the buffer in an existing window on the selected
437 frame.
438
439 @item
440 If all the above methods fail for whatever reason, create a new frame
441 and display the buffer there.
442 @end itemize
443
444 A more advanced and flexible way to customize the behavior of
445 @code{display-buffer} is by using the option @code{display-buffer-alist}
446 mentioned in the next section.
447
448
449 @node Temporary Displays
450 @subsection Displaying non-editable buffers.
451 @cindex pop-up windows
452 @cindex temporary windows
453
454 Some buffers are shown in windows for perusal rather than for editing.
455 Help commands (@pxref{Help}) typically use a buffer called @file{*Help*}
456 for that purpose, minibuffer completion (@pxref{Completion}) uses a
457 buffer called @file{*Completions*} instead. Such buffers are usually
458 displayed only for a short period of time.
459
460 Normally, Emacs chooses the window for such temporary displays via
461 @code{display-buffer} as described above. The @file{*Completions*}
462 buffer, on the other hand, is normally displayed in a window at the
463 bottom of the selected frame, regardless of the number of windows
464 already shown on that frame.
465
466 If you prefer Emacs to display a temporary buffer in a different
467 fashion, we recommend to customize the variable
468 @code{display-buffer-alist} (@pxref{Choosing Window,,Choosing a Window
469 for Display, elisp, The Emacs Lisp Reference Manual}). For example,
470 to display @file{*Completions*} by splitting a window as described in
471 the previous section, use the following form in your initialization
472 file (@pxref{Init File}):
473
474 @example
475 @group
476 (customize-set-variable
477 'display-buffer-alist
478 '(("\\*Completions\\*" display-buffer-pop-up-window)))
479 @end group
480 @end example
481
482 @findex temp-buffer-resize-mode
483 The @file{*Completions*} buffer is also special in the sense that
484 Emacs usually tries to make its window just as large as necessary to
485 display all of its contents. To resize windows showing other
486 temporary displays like, for example, the @file{*Help*} buffer
487 accordingly, turn on the minor mode (@pxref{Minor Modes})
488 @code{temp-buffer-resize-mode} (@pxref{Temporary Displays,,Temporary
489 Displays, elisp, The Emacs Lisp Reference Manual}).
490
491 @vindex temp-buffer-max-height
492 @vindex temp-buffer-max-width
493 The maximum size of windows resized by @code{temp-buffer-resize-mode}
494 can be controlled by customizing the options
495 @code{temp-buffer-max-height} and @code{temp-buffer-max-width}
496 (@pxref{Temporary Displays,,Temporary Displays, elisp, The Emacs Lisp
497 Reference Manual}) and cannot exceed the size of the containing frame.
498
499
500 @node Window Convenience
501 @section Convenience Features for Window Handling
502
503 @findex winner-mode
504 @cindex Winner mode
505 @cindex mode, Winner
506 @cindex undoing window configuration changes
507 @cindex window configuration changes, undoing
508 Winner mode is a global minor mode that records the changes in the
509 window configuration (i.e., how the frames are partitioned into
510 windows), so that you can undo them. You can toggle Winner mode
511 with @kbd{M-x winner-mode}, or by customizing the variable
512 @code{winner-mode}. When the mode is enabled, @kbd{C-c left}
513 (@code{winner-undo}) undoes the last window configuration change. If
514 you change your mind while undoing, you can redo the changes you had
515 undone using @kbd{C-c right} (@code{M-x winner-redo}).
516
517 Follow mode (@kbd{M-x follow-mode}) synchronizes several windows on
518 the same buffer so that they always display adjacent sections of that
519 buffer. @xref{Follow Mode}.
520
521 @cindex Windmove package
522 @cindex directional window selection
523 @findex windmove-right
524 @findex windmove-default-keybindings
525 The Windmove package defines commands for moving directionally
526 between neighboring windows in a frame. @kbd{M-x windmove-right}
527 selects the window immediately to the right of the currently selected
528 one, and similarly for the left, up, and down
529 counterparts. @kbd{M-x windmove-default-keybindings} binds these
530 commands to @kbd{S-right} etc.; doing so disables shift selection for
531 those keys (@pxref{Shift Selection}).
532
533 The command @kbd{M-x compare-windows} lets you compare the text
534 shown in different windows. @xref{Comparing Files}.
535
536 @vindex scroll-all-mode
537 @cindex scrolling windows together
538 @cindex Scroll-all mode
539 @cindex mode, Scroll-all
540 Scroll All mode (@kbd{M-x scroll-all-mode}) is a global minor mode
541 that causes scrolling commands and point motion commands to apply to
542 every single window.