38.11 Vertical Scrolling

Vertical scrolling means moving the text up or down in a window. It works by changing the value of the window’s display-start location. It may also change the value of window-point to keep it on the screen.

In the commands scroll-up and scroll-down, the directions “up” and “down” refer to the motion of the text in the buffer at which you are looking through the window. Imagine that the text is written on a long roll of paper and that the scrolling commands move the paper up and down. Thus, if you are looking at text in the middle of a buffer and repeatedly call scroll-down, you will eventually see the beginning of the buffer.

Some people have urged that the opposite convention be used: they imagine that the window moves over text that remains in place. Then “down” commands would take you to the end of the buffer. This view is more consistent with the actual relationship between windows and the text in the buffer, but it is less like what the user sees. The position of a window on the terminal does not move, and short scrolling commands clearly move the text up or down on the screen. We have chosen names that fit the user’s point of view.

The scrolling functions (aside from scroll-other-window) have unpredictable results if the current buffer is different from the buffer that is displayed in the selected window. See Current Buffer.

Command: scroll-up &optional lines

This function scrolls the text in the selected window upward lines lines. If lines is negative, scrolling is actually downward.

If lines is nil (or omitted), then the length of scroll is next-screen-context-lines lines less than the usable height of the window (not counting its modeline).

scroll-up returns nil.

Command: scroll-down &optional lines

This function scrolls the text in the selected window downward lines lines. If lines is negative, scrolling is actually upward.

If lines is omitted or nil, then the length of the scroll is next-screen-context-lines lines less than the usable height of the window (not counting its mode line).

scroll-down returns nil.

Command: scroll-other-window &optional lines

This function scrolls the text in another window upward lines lines. Negative values of lines, or nil, are handled as in scroll-up.

You can specify a buffer to scroll with the variable other-window-scroll-buffer. When the selected window is the minibuffer, the next window is normally the one at the top left corner. You can specify a different window to scroll with the variable minibuffer-scroll-window. This variable has no effect when any other window is selected. See Minibuffer Misc.

When the minibuffer is active, it is the next window if the selected window is the one at the bottom right corner. In this case, scroll-other-window attempts to scroll the minibuffer. If the minibuffer contains just one line, it has nowhere to scroll to, so the line reappears after the echo area momentarily displays the message “Beginning of buffer”.

Variable: other-window-scroll-buffer

If this variable is non-nil, it tells scroll-other-window which buffer to scroll.

User Option: scroll-step

This variable controls how scrolling is done automatically when point moves off the screen. If the value is zero, then redisplay scrolls the text to center point vertically in the window. If the value is a positive integer n, then redisplay brings point back on screen by scrolling n lines in either direction, if possible; otherwise, it centers point. The default value is zero.

User Option: scroll-conservatively

This variable controls how many lines SXEmacs tries to scroll before recentering. If you set it to a small number, then when you move point a short distance off the screen, SXEmacs will scroll the screen just far enough to bring point back on screen, provided that does not exceed scroll-conservatively lines. This variable overrides the redisplay preemption.

User Option: next-screen-context-lines

The value of this variable is the number of lines of continuity to retain when scrolling by full screens. For example, scroll-up with an argument of nil scrolls so that this many lines at the bottom of the window appear instead at the top. The default value is 2.

Command: recenter &optional location window

This function scrolls window (which defaults to the selected window) to put the text where point is located at a specified vertical position within the window.

If location is a nonnegative number, it puts the line containing point location lines down from the top of the window. If location is a negative number, then it counts upward from the bottom of the window, so that -1 stands for the last usable line in the window. If location is a non-nil list, then it stands for the line in the middle of the window.

If location is nil, recenter puts the line containing point in the middle of the window, then clears and redisplays the entire selected frame.

When recenter is called interactively, location is the raw prefix argument. Thus, typing C-u as the prefix sets the location to a non-nil list, while typing C-u 4 sets location to 4, which positions the current line four lines from the top.

With an argument of zero, recenter positions the current line at the top of the window. This action is so handy that some people make a separate key binding to do this. For example,

(defun line-to-top-of-window ()
  "Scroll current line to top of window.
Replaces three keystroke sequence C-u 0 C-l."
  (interactive)
  (recenter 0))

(global-set-key [kp-multiply] 'line-to-top-of-window)