| 1 | @c This is part of the Emacs manual. |
| 2 | @c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012 |
| 3 | @c Free Software 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 | @node Other Window |
| 138 | @section Using Other Windows |
| 139 | |
| 140 | @table @kbd |
| 141 | @item C-x o |
| 142 | Select another window (@code{other-window}). |
| 143 | @item C-M-v |
| 144 | Scroll the next window (@code{scroll-other-window}). |
| 145 | @item Mouse-1 |
| 146 | @kbd{Mouse-1}, in the text area of a window, selects the window and |
| 147 | moves point to the position clicked. Clicking in the mode line |
| 148 | selects the window without moving point in it. |
| 149 | @end table |
| 150 | |
| 151 | @kindex C-x o |
| 152 | @findex other-window |
| 153 | With the keyboard, you can switch windows by typing @kbd{C-x o} |
| 154 | (@code{other-window}). That is an @kbd{o}, for ``other'', not a zero. |
| 155 | When there are more than two windows, this command moves through all the |
| 156 | windows in a cyclic order, generally top to bottom and left to right. |
| 157 | After the rightmost and bottommost window, it goes back to the one at |
| 158 | the upper left corner. A numeric argument means to move several steps |
| 159 | in the cyclic order of windows. A negative argument moves around the |
| 160 | cycle in the opposite order. When the minibuffer is active, the |
| 161 | minibuffer is the last window in the cycle; you can switch from the |
| 162 | minibuffer window to one of the other windows, and later switch back and |
| 163 | finish supplying the minibuffer argument that is requested. |
| 164 | @xref{Minibuffer Edit}. |
| 165 | |
| 166 | @kindex C-M-v |
| 167 | @findex scroll-other-window |
| 168 | The usual scrolling commands (@pxref{Display}) apply to the selected |
| 169 | window only, but there is one command to scroll the next window. |
| 170 | @kbd{C-M-v} (@code{scroll-other-window}) scrolls the window that |
| 171 | @kbd{C-x o} would select. It takes arguments, positive and negative, |
| 172 | like @kbd{C-v}. (In the minibuffer, @kbd{C-M-v} scrolls the help |
| 173 | window associated with the minibuffer, if any, rather than the next |
| 174 | window in the standard cyclic order; @pxref{Minibuffer Edit}.) |
| 175 | |
| 176 | @vindex mouse-autoselect-window |
| 177 | If you set @code{mouse-autoselect-window} to a non-@code{nil} value, |
| 178 | moving the mouse over a different window selects that window. This |
| 179 | feature is off by default. |
| 180 | |
| 181 | @node Pop Up Window |
| 182 | @section Displaying in Another Window |
| 183 | |
| 184 | @cindex selecting buffers in other windows |
| 185 | @kindex C-x 4 |
| 186 | @kbd{C-x 4} is a prefix key for a variety of commands that switch to |
| 187 | a buffer in a different window---either another existing window, or a |
| 188 | new window created by splitting the selected window. @xref{Window |
| 189 | Choice}, for how Emacs picks or creates the window to use. |
| 190 | |
| 191 | @table @kbd |
| 192 | @findex switch-to-buffer-other-window |
| 193 | @item C-x 4 b @var{bufname} @key{RET} |
| 194 | Select buffer @var{bufname} in another window |
| 195 | (@code{switch-to-buffer-other-window}). |
| 196 | |
| 197 | @findex display-buffer |
| 198 | @item C-x 4 C-o @var{bufname} @key{RET} |
| 199 | @kindex C-x 4 C-o |
| 200 | Display buffer @var{bufname} in some window, without trying to select |
| 201 | it (@code{display-buffer}). @xref{Displaying Buffers}, for details |
| 202 | about how the window is chosen. |
| 203 | |
| 204 | @findex find-file-other-window |
| 205 | @item C-x 4 f @var{filename} @key{RET} |
| 206 | Visit file @var{filename} and select its buffer in another window |
| 207 | (@code{find-file-other-window}). @xref{Visiting}. |
| 208 | |
| 209 | @findex dired-other-window |
| 210 | @item C-x 4 d @var{directory} @key{RET} |
| 211 | Select a Dired buffer for directory @var{directory} in another window |
| 212 | (@code{dired-other-window}). @xref{Dired}. |
| 213 | |
| 214 | @findex mail-other-window |
| 215 | @item C-x 4 m |
| 216 | Start composing a mail message, similar to @kbd{C-x m} (@pxref{Sending |
| 217 | Mail}), but in another window (@code{mail-other-window}). |
| 218 | |
| 219 | @findex find-tag-other-window |
| 220 | @item C-x 4 . |
| 221 | Find a tag in the current tags table, similar to @kbd{M-.} |
| 222 | (@pxref{Tags}), but in another window (@code{find-tag-other-window}). |
| 223 | @item C-x 4 r @var{filename} @key{RET} |
| 224 | Visit file @var{filename} read-only, and select its buffer in another |
| 225 | window (@code{find-file-read-only-other-window}). @xref{Visiting}. |
| 226 | @end table |
| 227 | |
| 228 | @node Change Window |
| 229 | @section Deleting and Rearranging Windows |
| 230 | |
| 231 | @table @kbd |
| 232 | @item C-x 0 |
| 233 | Delete the selected window (@code{delete-window}). |
| 234 | @item C-x 1 |
| 235 | Delete all windows in the selected frame except the selected window |
| 236 | (@code{delete-other-windows}). |
| 237 | @item C-x 4 0 |
| 238 | Delete the selected window and kill the buffer that was showing in it |
| 239 | (@code{kill-buffer-and-window}). The last character in this key |
| 240 | sequence is a zero. |
| 241 | @item C-x ^ |
| 242 | Make selected window taller (@code{enlarge-window}). |
| 243 | @item C-x @} |
| 244 | Make selected window wider (@code{enlarge-window-horizontally}). |
| 245 | @item C-x @{ |
| 246 | Make selected window narrower (@code{shrink-window-horizontally}). |
| 247 | @item C-x - |
| 248 | Shrink this window if its buffer doesn't need so many lines |
| 249 | (@code{shrink-window-if-larger-than-buffer}). |
| 250 | @item C-x + |
| 251 | Make all windows the same height (@code{balance-windows}). |
| 252 | @end table |
| 253 | |
| 254 | @kindex C-x 0 |
| 255 | @findex delete-window |
| 256 | To delete the selected window, type @kbd{C-x 0} |
| 257 | (@code{delete-window}). (That is a zero.) Once a window is deleted, |
| 258 | the space that it occupied is given to an adjacent window (but not the |
| 259 | minibuffer window, even if that is active at the time). Deleting the |
| 260 | window has no effect on the buffer it used to display; the buffer |
| 261 | continues to exist, and you can still switch to with @kbd{C-x b}. |
| 262 | |
| 263 | @findex kill-buffer-and-window |
| 264 | @kindex C-x 4 0 |
| 265 | @kbd{C-x 4 0} (@code{kill-buffer-and-window}) is a stronger command |
| 266 | than @kbd{C-x 0}; it kills the current buffer and then deletes the |
| 267 | selected window. |
| 268 | |
| 269 | @kindex C-x 1 |
| 270 | @findex delete-other-windows |
| 271 | @kbd{C-x 1} (@code{delete-other-windows}) deletes all the windows, |
| 272 | @emph{except} the selected one; the selected window expands to use the |
| 273 | whole frame. (This command cannot be used while the minibuffer window |
| 274 | is active; attempting to do so signals an error.) |
| 275 | |
| 276 | @kindex C-x ^ |
| 277 | @findex enlarge-window |
| 278 | @kindex C-x @} |
| 279 | @vindex window-min-height |
| 280 | The command @kbd{C-x ^} (@code{enlarge-window}) makes the selected |
| 281 | window one line taller, taking space from a vertically adjacent window |
| 282 | without changing the height of the frame. With a positive numeric |
| 283 | argument, this command increases the window height by that many lines; |
| 284 | with a negative argument, it reduces the height by that many lines. |
| 285 | If there are no vertically adjacent windows (i.e., the window is at the |
| 286 | full frame height), that signals an error. The command also signals |
| 287 | an error if you attempt to reduce the height of any window below a |
| 288 | certain minimum number of lines, specified by the variable |
| 289 | @code{window-min-height} (the default is 4). |
| 290 | |
| 291 | @findex enlarge-window-horizontally |
| 292 | @findex shrink-window-horizontally |
| 293 | @vindex window-min-width |
| 294 | Similarly, @kbd{C-x @}} (@code{enlarge-window-horizontally}) makes |
| 295 | the selected window wider, and @kbd{C-x @{} |
| 296 | (@code{shrink-window-horizontally}) makes it narrower. These commands |
| 297 | signal an error if you attempt to reduce the width of any window below |
| 298 | a certain minimum number of columns, specified by the variable |
| 299 | @code{window-min-width} (the default is 10). |
| 300 | |
| 301 | @kindex C-x - |
| 302 | @findex shrink-window-if-larger-than-buffer |
| 303 | @kbd{C-x -} (@code{shrink-window-if-larger-than-buffer}) reduces the |
| 304 | height of the selected window, if it is taller than necessary to show |
| 305 | the whole text of the buffer it is displaying. It gives the extra |
| 306 | lines to other windows in the frame. |
| 307 | |
| 308 | @kindex C-x + |
| 309 | @findex balance-windows |
| 310 | You can also use @kbd{C-x +} (@code{balance-windows}) to even out the |
| 311 | heights of all the windows in the selected frame. |
| 312 | |
| 313 | Mouse clicks on the mode line provide another way to change window |
| 314 | heights and to delete windows. @xref{Mode Line Mouse}. |
| 315 | |
| 316 | @node Displaying Buffers |
| 317 | @section Displaying a Buffer in a Window |
| 318 | |
| 319 | It is a common Emacs operation to display or ``pop up'' some buffer |
| 320 | in response to a user command. There are several different ways in |
| 321 | which commands do this. |
| 322 | |
| 323 | Many commands, like @kbd{C-x C-f} (@code{find-file}), display the |
| 324 | buffer by ``taking over'' the selected window, expecting that the |
| 325 | user's attention will be diverted to that buffer. These commands |
| 326 | usually work by calling @code{switch-to-buffer} internally |
| 327 | (@pxref{Select Buffer}). |
| 328 | |
| 329 | @findex display-buffer |
| 330 | Some commands try to display ``intelligently'', trying not to take |
| 331 | over the selected window, e.g., by splitting off a new window and |
| 332 | displaying the desired buffer there. Such commands, which include the |
| 333 | various help commands (@pxref{Help}), work by calling |
| 334 | @code{display-buffer} internally. @xref{Window Choice}, for details. |
| 335 | |
| 336 | Other commands do the same as @code{display-buffer}, and |
| 337 | additionally select the displaying window so that you can begin |
| 338 | editing its buffer. The command @kbd{C-x `} (@code{next-error}) is |
| 339 | one example (@pxref{Compilation Mode}). Such commands work by calling |
| 340 | the function @code{pop-to-buffer} internally. @xref{Switching |
| 341 | Buffers,,Switching to a Buffer in a Window, elisp, The Emacs Lisp |
| 342 | Reference Manual}. |
| 343 | |
| 344 | Commands with names ending in @code{-other-window} behave like |
| 345 | @code{display-buffer}, except that they never display in the selected |
| 346 | window. Several of these commands are bound in the @kbd{C-x 4} prefix |
| 347 | key (@pxref{Pop Up Window}). |
| 348 | |
| 349 | Commands with names ending in @code{-other-frame} behave like |
| 350 | @code{display-buffer}, except that they (i) never display in the |
| 351 | selected window and (ii) prefer to create a new frame to display the |
| 352 | desired buffer instead of splitting a window---as though the variable |
| 353 | @code{pop-up-frames} is set to @code{t} (@pxref{Window Choice}). |
| 354 | Several of these commands are bound in the @kbd{C-x 5} prefix key. |
| 355 | |
| 356 | @menu |
| 357 | * Window Choice:: How @code{display-buffer} works. |
| 358 | @end menu |
| 359 | |
| 360 | @node Window Choice |
| 361 | @subsection How @code{display-buffer} works |
| 362 | @findex display-buffer |
| 363 | |
| 364 | The @code{display-buffer} command (as well as commands that call it |
| 365 | internally) chooses a window to display by following the steps given |
| 366 | below. @xref{Choosing Window,,Choosing a Window for Display, elisp, |
| 367 | The Emacs Lisp Reference Manual}, for details about how to alter this |
| 368 | sequence of steps. |
| 369 | |
| 370 | @itemize |
| 371 | @vindex same-window-buffer-names |
| 372 | @vindex same-window-regexps |
| 373 | @item |
| 374 | First, check if the buffer should be displayed in the selected window |
| 375 | regardless of other considerations. You can tell Emacs to do this by |
| 376 | adding the desired buffer's name to the list |
| 377 | @code{same-window-buffer-names}, or adding a matching regular |
| 378 | expression to the list @code{same-window-regexps}. By default, these |
| 379 | variables are @code{nil}, so this step is skipped. |
| 380 | |
| 381 | @item |
| 382 | Otherwise, if the buffer is already displayed in an existing window, |
| 383 | ``reuse'' that window. Normally, only windows on the selected frame |
| 384 | are considered, but windows on other frames are also reusable if you |
| 385 | change @code{pop-up-frames} (see below) to @code{t}. |
| 386 | |
| 387 | @vindex pop-up-frames |
| 388 | @item |
| 389 | Otherwise, optionally create a new frame and display the buffer there. |
| 390 | By default, this step is skipped. To enable it, change the variable |
| 391 | @code{pop-up-frames} to a non-@code{nil} value. The special value |
| 392 | @code{graphic-only} means to do this only on graphical displays. |
| 393 | |
| 394 | @item |
| 395 | Otherwise, try to create a new window by splitting the selected |
| 396 | window, and display the buffer in that new window. |
| 397 | |
| 398 | @vindex split-height-threshold |
| 399 | @vindex split-width-threshold |
| 400 | The split can be either vertical or horizontal, depending on the |
| 401 | variables @code{split-height-threshold} and |
| 402 | @code{split-width-threshold}. These variables should have integer |
| 403 | values. If @code{split-height-threshold} is smaller than the selected |
| 404 | window's height, the split puts the new window below. Otherwise, if |
| 405 | @code{split-width-threshold} is smaller than the window's width, the |
| 406 | split puts the new window on the right. If neither condition holds, |
| 407 | Emacs tries to split so that the new window is below---but only if the |
| 408 | window was not split before (to avoid excessive splitting). |
| 409 | |
| 410 | @item |
| 411 | Otherwise, display the buffer in an existing window on the selected |
| 412 | frame. |
| 413 | |
| 414 | @item |
| 415 | If all the above methods fail for whatever reason, create a new frame |
| 416 | and display the buffer there. |
| 417 | @end itemize |
| 418 | |
| 419 | @node Window Convenience |
| 420 | @section Convenience Features for Window Handling |
| 421 | |
| 422 | @findex winner-mode |
| 423 | @cindex Winner mode |
| 424 | @cindex mode, Winner |
| 425 | @cindex undoing window configuration changes |
| 426 | @cindex window configuration changes, undoing |
| 427 | Winner mode is a global minor mode that records the changes in the |
| 428 | window configuration (i.e., how the frames are partitioned into |
| 429 | windows), so that you can ``undo'' them. You can toggle Winner mode |
| 430 | with @kbd{M-x winner-mode}, or by customizing the variable |
| 431 | @code{winner-mode}. When the mode is enabled, @kbd{C-c left} |
| 432 | (@code{winner-undo}) undoes the last window configuration change. If |
| 433 | you change your mind while undoing, you can redo the changes you had |
| 434 | undone using @kbd{C-c right} (@code{M-x winner-redo}). |
| 435 | |
| 436 | Follow mode (@kbd{M-x follow-mode}) synchronizes several windows on |
| 437 | the same buffer so that they always display adjacent sections of that |
| 438 | buffer. @xref{Follow Mode}. |
| 439 | |
| 440 | @cindex Windmove package |
| 441 | @cindex directional window selection |
| 442 | @findex windmove-right |
| 443 | @findex windmove-default-keybindings |
| 444 | The Windmove package defines commands for moving directionally |
| 445 | between neighboring windows in a frame. @kbd{M-x windmove-right} |
| 446 | selects the window immediately to the right of the currently selected |
| 447 | one, and similarly for the ``left'', ``up'', and ``down'' |
| 448 | counterparts. @kbd{M-x windmove-default-keybindings} binds these |
| 449 | commands to @kbd{S-right} etc.; doing so disables shift selection for |
| 450 | those keys (@pxref{Shift Selection}). |
| 451 | |
| 452 | The command @kbd{M-x compare-windows} lets you compare the text |
| 453 | shown in different windows. @xref{Comparing Files}. |
| 454 | |
| 455 | @vindex scroll-all-mode |
| 456 | @cindex scrolling windows together |
| 457 | @cindex Scroll-all mode |
| 458 | @cindex mode, Scroll-all |
| 459 | Scroll All mode (@kbd{M-x scroll-all-mode}) is a global minor mode |
| 460 | that causes scrolling commands and point motion commands to apply to |
| 461 | every single window. |