"Fossies" - the Fresh Open Source Software Archive

Member "emacs-26.1/doc/emacs/windows.texi" (23 Apr 2018, 23522 Bytes) of package /linux/misc/emacs-26.1.tar.xz:

Caution: As a special service "Fossies" has tried to format the requested Texinfo source page into HTML format but that may be not always succeeeded perfectly. Alternatively you can here view or download the uninterpreted Texinfo source code. A member file download can also be achieved by clicking within a package contents listing on the according byte size field. See also the latest Fossies "Diffs" side-by-side code changes report for "windows.texi": 25.3_vs_26.1.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1 Multiple Windows

Emacs can split a frame into two or many windows. Multiple windows can display parts of different buffers, or different parts of one buffer. Multiple frames always imply multiple windows, because each frame has its own set of windows. Each window belongs to one and only one frame.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.1 Concepts of Emacs Windows

Each Emacs window displays one Emacs buffer at any time. A single buffer may appear in more than one window; if it does, any changes in its text are displayed in all the windows where it appears. But these windows can show different parts of the buffer, because each window has its own value of point.

At any time, one Emacs window is the selected window; the buffer this window is displaying is the current buffer. On graphical displays, the point is indicated by a solid blinking cursor in the selected window, and by a hollow box in non-selected windows. On text terminals, the cursor is drawn only in the selected window. @xref{Cursor Display}.

Commands to move point affect the value of point for the selected Emacs window only. They do not change the value of point in other Emacs windows, even those showing the same buffer. The same is true for buffer-switching commands such as C-x b; they do not affect other windows at all. However, there are other commands such as C-x 4 b that select a different window and switch buffers in it. Also, all commands that display information in a window, including (for example) C-h f (describe-function) and C-x C-b (list-buffers), work by switching buffers in a nonselected window without affecting the selected window.

When multiple windows show the same buffer, they can have different regions, because they can have different values of point. However, they all have the same value for the mark, because each buffer has only one mark position.

Each window has its own mode line, which displays the buffer name, modification status and major and minor modes of the buffer that is displayed in the window. The selected window’s mode line appears in a different color. @xref{Mode Line}, for details.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2 Splitting Windows

C-x 2

Split the selected window into two windows, one above the other (split-window-below).

C-x 3

Split the selected window into two windows, positioned side by side (split-window-right).


In the mode line of a window, split that window.

C-x 2 (split-window-below) splits the selected window into two windows, one above the other. After splitting, the selected window is the upper one, and the newly split-off window is below. Both windows have the same value of point as before, and display the same portion of the buffer (or as close to it as possible). If necessary, the windows are scrolled to keep point on-screen. By default, the two windows each get half the height of the original window. A positive numeric argument specifies how many lines to give to the top window; a negative numeric argument specifies how many lines to give to the bottom window.

If you change the variable split-window-keep-point to nil, C-x 2 instead adjusts the portion of the buffer displayed by the two windows, as well as the value of point in each window, in order to keep the text on the screen as close as possible to what it was before; furthermore, if point was in the lower half of the original window, the bottom window is selected instead of the upper one.

C-x 3 (split-window-right) splits the selected window into two side-by-side windows. The left window is the selected one; the right window displays the same portion of the same buffer, and has the same value of point. A positive numeric argument specifies how many columns to give the left window; a negative numeric argument specifies how many columns to give the right window.

When you split a window with C-x 3, each resulting window occupies less than the full width of the frame. If it becomes too narrow, the buffer may be difficult to read if continuation lines are in use (@pxref{Continuation Lines}). Therefore, Emacs automatically switches to line truncation if the window width becomes narrower than 50 columns. This truncation occurs regardless of the value of the variable truncate-lines (@pxref{Line Truncation}); it is instead controlled by the variable truncate-partial-width-windows. If the value of this variable is a positive integer (the default is 50), that specifies the minimum total width for a partial-width window before automatic line truncation occurs; if the value is nil, automatic line truncation is disabled; and for any other non-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 window-total-width (see Window Sizes in 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 vertical-border face.

If you click 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 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).

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 window-resize-pixelwise to a non-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 nil.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3 Using Other Windows

C-x o

Select another window (other-window).


Scroll the next window (scroll-other-window).


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.

With the keyboard, you can switch windows by typing C-x o (other-window). That is an o, for “other”, not a zero. When there are more than two windows, this command moves through all the windows in a cyclic order, generally top to bottom and left to right. After the rightmost and bottommost window, it goes back to the one at the upper left corner. A numeric argument means to move several steps in the cyclic order of windows. A negative argument moves around the cycle in the opposite order. When the minibuffer is active, the minibuffer window is the last window in the cycle; you can switch from the minibuffer window to one of the other windows, and later switch back and finish supplying the minibuffer argument that is requested. @xref{Minibuffer Edit}.

The usual scrolling commands (@pxref{Display}) apply to the selected window only, but there is one command to scroll the next window. C-M-v (scroll-other-window) scrolls the window that C-x o would select. It takes arguments, positive and negative, like C-v. (In the minibuffer, C-M-v scrolls the help window associated with the minibuffer, if any, rather than the next window in the standard cyclic order; @pxref{Minibuffer Edit}.)

If you set mouse-autoselect-window to a non-nil value, moving the mouse over a different window selects that window. This feature is off by default.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4 Displaying in Another Window

C-x 4 is a prefix key for a variety of commands that switch to a buffer in a different window—either another existing window, or a new window created by splitting the selected window. See section How display-buffer works, for how Emacs picks or creates the window to use.

C-x 4 b bufname <RET>

Select buffer bufname in another window (switch-to-buffer-other-window). @xref{Select Buffer}.

C-x 4 C-o bufname <RET>

Display buffer bufname in some window, without trying to select it (display-buffer). See section Displaying a Buffer in a Window, for details about how the window is chosen.

C-x 4 f filename <RET>

Visit file filename and select its buffer in another window (find-file-other-window). @xref{Visiting}.

C-x 4 d directory <RET>

Select a Dired buffer for directory directory in another window (dired-other-window). @xref{Dired}.

C-x 4 m

Start composing a mail message, similar to C-x m (@pxref{Sending Mail}), but in another window (compose-mail-other-window).

C-x 4 .

Find the definition of an identifier, similar to M-. (@pxref{Xref}), but in another window (xref-find-definitions-other-window).

C-x 4 r filename <RET>

Visit file filename read-only, and select its buffer in another window (find-file-read-only-other-window). @xref{Visiting}.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.5 Deleting and Resizing Windows

C-x 0

Delete the selected window (delete-window).

C-x 1

Delete all windows in the selected frame except the selected window (delete-other-windows).

C-x 4 0

Delete the selected window and kill the buffer that was showing in it (kill-buffer-and-window). The last character in this key sequence is a zero.

C-x ^

Make selected window taller (enlarge-window).

C-x }

Make selected window wider (enlarge-window-horizontally).

C-x {

Make selected window narrower (shrink-window-horizontally).

C-x -

Shrink this window if its buffer doesn’t need so many lines (shrink-window-if-larger-than-buffer).

C-x +

Make all windows the same height (balance-windows).

To delete the selected window, type C-x 0 (delete-window). (That is a zero.) Once a window is deleted, 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 it with C-x b.

C-x 4 0 (kill-buffer-and-window) is a stronger command than C-x 0; it kills the current buffer and then deletes the selected window.

C-x 1 (delete-other-windows) deletes all the windows, except the selected one; the selected window expands to use the whole frame. (This command cannot be used while the minibuffer window is active; attempting to do so signals an error.)

The command C-x ^ (enlarge-window) makes the selected window one line taller, taking space from a vertically adjacent window 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 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 window-min-height (the default is 4).

Similarly, C-x } (enlarge-window-horizontally) makes the selected window wider, and C-x { (shrink-window-horizontally) makes it narrower. These commands signal an error if you attempt to reduce the width of any window below a certain minimum number of columns, specified by the variable 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.

C-x - (shrink-window-if-larger-than-buffer) reduces the height of the selected window, if it is taller than necessary to show the whole text of the buffer it is displaying. It gives the extra lines to other windows in the frame.

You can also use C-x + (balance-windows) to even out the heights of all the windows in the selected frame.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.6 Displaying a Buffer in a Window

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.

Many commands, like C-x C-f (find-file), display the buffer by “taking over” the selected window, expecting that the user’s attention will be diverted to that buffer. These commands usually work by calling switch-to-buffer internally (@pxref{Select Buffer}).

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 display-buffer internally. See section How display-buffer works, for details.

Other commands do the same as display-buffer, and additionally select the displaying window so that you can begin editing its buffer. The command C-x ` (next-error) is one example (@pxref{Compilation Mode}). Such commands work by calling the function pop-to-buffer internally. See Switching to a Buffer in a Window in The Emacs Lisp Reference Manual.

Commands with names ending in -other-window behave like display-buffer, except that they never display in the selected window. Several of these commands are bound in the C-x 4 prefix key (see section Displaying in Another Window).

Commands with names ending in -other-frame behave like display-buffer, except that they (i) never display in the selected window and (ii) prefer to create a new frame to display the desired buffer instead of splitting a window—as though the variable pop-up-frames is set to t (see section How display-buffer works). Several of these commands are bound in the C-x 5 prefix key.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.6.1 How display-buffer works

The display-buffer command (as well as commands that call it internally) chooses a window to display by following the steps given below. See Choosing a Window for Display in The Emacs Lisp Reference Manual, for details about how to alter this sequence of steps.

A more advanced and flexible way to customize the behavior of display-buffer is by using the option display-buffer-alist mentioned in the next section.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.6.2 Displaying non-editable buffers.

Some buffers are shown in windows for perusal rather than for editing. Help commands (@pxref{Help}) typically use a buffer called ‘*Help*’ for that purpose, minibuffer completion (@pxref{Completion}) uses a buffer called ‘*Completions*’ instead. Such buffers are usually displayed only for a short period of time.

Normally, Emacs chooses the window for such temporary displays via display-buffer as described above. The ‘*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 customizing the variable display-buffer-alist (see Choosing a Window for Display in The Emacs Lisp Reference Manual). For example, to display ‘*Completions*’ by splitting a window as described in the previous section, use the following form in your initialization file (@pxref{Init File}):

 '(("\\*Completions\\*" display-buffer-pop-up-window)))

The ‘*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 ‘*Help*’ buffer accordingly, turn on the minor mode (@pxref{Minor Modes}) temp-buffer-resize-mode (see Temporary Displays in The Emacs Lisp Reference Manual).

The maximum size of windows resized by temp-buffer-resize-mode can be controlled by customizing the options temp-buffer-max-height and temp-buffer-max-width (see Temporary Displays in The Emacs Lisp Reference Manual) and cannot exceed the size of the containing frame.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.7 Convenience Features for Window Handling

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 with M-x winner-mode, or by customizing the variable winner-mode. When the mode is enabled, C-c left (winner-undo) undoes the last window configuration change. If you change your mind while undoing, you can redo the changes you had undone using C-c right (M-x winner-redo).

Follow mode (M-x follow-mode) synchronizes several windows on the same buffer so that they always display adjacent sections of that buffer. @xref{Follow Mode}.

The Windmove package defines commands for moving directionally between neighboring windows in a frame. M-x windmove-right selects the window immediately to the right of the currently selected one, and similarly for the left, up, and down counterparts. M-x windmove-default-keybindings binds these commands to S-right etc.; doing so disables shift selection for those keys (@pxref{Shift Selection}).

The command M-x compare-windows lets you compare the text shown in different windows. @xref{Comparing Files}.

Scroll All mode (M-x scroll-all-mode) is a global minor mode that causes scrolling commands and point motion commands to apply to every single window.

[Top] [Contents] [Index] [ ? ]

About This Document

This document was generated on May 30, 2018 using texi2html.

The buttons in the navigation panels have the following meaning:

Button Name Go to From 1.2.3 go to
[ << ] FastBack Beginning of this chapter or previous chapter 1
[ < ] Back Previous section in reading order 1.2.2
[ Up ] Up Up section 1.2
[ > ] Forward Next section in reading order 1.2.4
[ >> ] FastForward Next chapter 2
[Top] Top Cover (top) of document  
[Contents] Contents Table of contents  
[Index] Index Index  
[ ? ] About About (help)  

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

This document was generated on May 30, 2018 using texi2html.