18.1 Scrolling

If a buffer contains text that is too large to fit entirely within a window that is displaying the buffer, Emacs shows a contiguous portion of the text. The portion shown always contains point.

Scrolling means moving text up or down in the window so that different parts of the text are visible. Scrolling “forward” or “up” means that text moves up, and new text appears at the bottom. Scrolling “backward” or “down” moves text down, and new text appears at the top.

Scrolling happens automatically if you move point past the bottom or top of the window. You can also scroll explicitly with these commands:

C-l

Scroll the selected window to center point vertically within it and redisplay the screen (recenter-top-bottom).

C-v

<next>

<PageDown>

Scroll forward by nearly a full window (scroll-up).

M-v

<prior>

<PageUp>

Scroll backward (scroll-down).

C-M-l

Scroll heuristically to bring useful information onto the screen (reposition-window).

The most basic scrolling command is C-l (recenter-top-bottom). This recenters the selected window, scrolling it so that the current screen line is exactly in the center of the window, or as close to the center as possible. It also clears the screen and redisplays all windows; this is useful in case the screen becomes garbled for any reason (see Screen Garbled).

Typing C-l twice in a row (C-l C-l) scrolls the window so that point is on the topmost screen line. Typing a third C-l scrolls the window so that point is on the bottom-most screen line. Each successive C-l cycles through these three screen positions. (If you change the variable scroll-margin to a non-zero value n, Emacs leaves n screen lines between point and the top or bottom of the window. See Auto Scrolling.)

You can also supply C-l with a prefix argument. With a plain prefix argument, C-u C-l, Emacs simply recenters point. With a positive argument n, it scrolls to place point n lines down from the top of the window. An argument of zero puts point on the topmost line. A negative argument -n puts point n lines from the bottom of the window. For example, C-u - 1 C-l puts point on the bottom line, and C-u - 5 C-l puts it five lines from the bottom. When given an argument, C-l does not clear the screen or cycle through different screen positions.

To read the buffer a windowful at a time, use C-v (scroll-up). This scrolls forward by nearly the whole window height. The effect is to take the two lines at the bottom of the window and put them at the top, followed by lines that were not previously visible. If point was in the text that scrolled off the top, it ends up at the new top of the window.

M-v (scroll-down) scrolls backward in a similar way.

The variable next-screen-context-lines controls the number of lines of overlap left by C-v or M-v; by default, it is 2. The function keys <next> and <prior>, or <PageDown> and <PageUp>, are equivalent to C-v and M-v respectively.

You can supply C-v or M-v with a numeric prefix argument n. This scrolls the window by n lines, while attempting to leave point unchanged (so that the text and point move up or down together). C-v with a negative argument is like M-v and vice versa.

The names of scroll commands are based on the direction that the text moves in the window. Thus, the command to scroll forward is called scroll-up because it moves the text upward on the screen. The keys <PageUp> and <PageDown> derive their names and customary meanings from a different convention that developed elsewhere; hence the strange result that <PageDown> runs scroll-up.

Some users like the full-screen scroll commands to keep point at the same screen position. To enable this behavior, set the variable scroll-preserve-screen-position to a non-nil value. Then, whenever a command scrolls the text around point offscreen (or within scroll-margin lines of the edge), Emacs moves point to keep it at the same vertical and horizontal position within the window. This mode is convenient for browsing through a file by scrolling by screenfuls; if you come back to the screen where you started, point goes back to the line where it started.

The C-M-l command (reposition-window) scrolls the current window heuristically in a way designed to get useful information onto the screen. For example, in a Lisp file, this command tries to get the entire current defun onto the screen if possible.