elisp: Textual Scrolling
27.21 Textual Scrolling
=======================
“Textual scrolling” means moving the text up or down through a window.
It works by changing the window’s display-start location. It may also
change the value of ‘window-point’ to keep point on the screen (
Window Point).
The basic textual scrolling functions are ‘scroll-up’ (which scrolls
forward) and ‘scroll-down’ (which scrolls backward). In these function
names, “up” and “down” refer to the direction of motion of the buffer
text relative to 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 the middle of a buffer and repeatedly
call ‘scroll-down’, you will eventually see the beginning of the buffer.
Unfortunately, this sometimes causes confusion, because some people
tend to think in terms of the opposite convention: they imagine the
window moving over text that remains in place, so that “down” commands
take you to the end of the buffer. This convention is consistent with
fact that such a command is bound to a key named <PageDown> on modern
keyboards.
Textual scrolling functions (aside from ‘scroll-other-window’) have
unpredictable results if the current buffer is not the one displayed in
the selected window. Current Buffer.
If the window contains a row taller than the height of the window
(for example in the presence of a large image), the scroll functions
will adjust the window’s vertical scroll position to scroll the
partially visible row. Lisp callers can disable this feature by binding
the variable ‘auto-window-vscroll’ to ‘nil’ (Vertical
Scrolling).
-- Command: scroll-up &optional count
This function scrolls forward by COUNT lines in the selected
window.
If COUNT is negative, it scrolls backward instead. If COUNT is
‘nil’ (or omitted), the distance scrolled is
‘next-screen-context-lines’ lines less than the height of the
window’s text area.
If the selected window cannot be scrolled any further, this
function signals an error. Otherwise, it returns ‘nil’.
-- Command: scroll-down &optional count
This function scrolls backward by COUNT lines in the selected
window.
If COUNT is negative, it scrolls forward instead. In other
respects, it behaves the same way as ‘scroll-up’ does.
-- Command: scroll-up-command &optional count
This behaves like ‘scroll-up’, except that if the selected window
cannot be scrolled any further and the value of the variable
‘scroll-error-top-bottom’ is ‘t’, it tries to move to the end of
the buffer instead. If point is already there, it signals an
error.
-- Command: scroll-down-command &optional count
This behaves like ‘scroll-down’, except that if the selected window
cannot be scrolled any further and the value of the variable
‘scroll-error-top-bottom’ is ‘t’, it tries to move to the beginning
of the buffer instead. If point is already there, it signals an
error.
-- Command: scroll-other-window &optional count
This function scrolls the text in another window upward COUNT
lines. Negative values of COUNT, or ‘nil’, are handled as in
‘scroll-up’.
You can specify which buffer to scroll by setting the variable
‘other-window-scroll-buffer’ to a buffer. If that buffer isn’t
already displayed, ‘scroll-other-window’ displays it in some
window.
When the selected window is the minibuffer, the next window is
normally the leftmost one immediately above it. You can specify a
different window to scroll, when the minibuffer is selected, by
setting the variable ‘minibuffer-scroll-window’. This variable has
no effect when any other window is selected. When it is non-‘nil’
and the minibuffer is selected, it takes precedence over
‘other-window-scroll-buffer’. Definition of
minibuffer-scroll-window.
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 ‘End of buffer’.
-- Variable: other-window-scroll-buffer
If this variable is non-‘nil’, it tells ‘scroll-other-window’ which
buffer’s window to scroll.
-- User Option: scroll-margin
This option specifies the size of the scroll margin—a minimum
number of lines between point and the top or bottom of a window.
Whenever point gets within this many lines of the top or bottom of
the window, redisplay scrolls the text automatically (if possible)
to move point out of the margin, closer to the center of the
window.
-- User Option: scroll-conservatively
This variable controls how scrolling is done automatically when
point moves off the screen (or into the scroll margin). If the
value is a positive integer N, then redisplay scrolls the text up
to N lines in either direction, if that will bring point back into
proper view. This behavior is called “conservative scrolling”.
Otherwise, scrolling happens in the usual way, under the control of
other variables such as ‘scroll-up-aggressively’ and
‘scroll-down-aggressively’.
The default value is zero, which means that conservative scrolling
never happens.
-- User Option: scroll-down-aggressively
The value of this variable should be either ‘nil’ or a fraction F
between 0 and 1. If it is a fraction, that specifies where on the
screen to put point when scrolling down. More precisely, when a
window scrolls down because point is above the window start, the
new start position is chosen to put point F part of the window
height from the top. The larger F, the more aggressive the
scrolling.
A value of ‘nil’ is equivalent to .5, since its effect is to center
point. This variable automatically becomes buffer-local when set
in any fashion.
-- User Option: scroll-up-aggressively
Likewise, for scrolling up. The value, F, specifies how far point
should be placed from the bottom of the window; thus, as with
‘scroll-up-aggressively’, a larger value scrolls more aggressively.
-- User Option: scroll-step
This variable is an older variant of ‘scroll-conservatively’. The
difference is that if its value is N, that permits scrolling only
by precisely N lines, not a smaller number. This feature does not
work with ‘scroll-margin’. The default value is zero.
-- User Option: scroll-preserve-screen-position
If this option is ‘t’, whenever a scrolling command moves point
off-window, Emacs tries to adjust point to keep the cursor at its
old vertical position in the window, rather than the window edge.
If the value is non-‘nil’ and not ‘t’, Emacs adjusts point to keep
the cursor at the same vertical position, even if the scrolling
command didn’t move point off-window.
This option affects all scroll commands that have a non-‘nil’
‘scroll-command’ symbol property.
-- 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’.
-- User Option: scroll-error-top-bottom
If this option is ‘nil’ (the default), ‘scroll-up-command’ and
‘scroll-down-command’ simply signal an error when no more scrolling
is possible.
If the value is ‘t’, these commands instead move point to the
beginning or end of the buffer (depending on scrolling direction);
only if point is already on that position do they signal an error.
-- Command: recenter &optional count
This function scrolls the text in the selected window so that point
is displayed at a specified vertical position within the window.
It does not move point with respect to the text.
If COUNT is a non-negative number, that puts the line containing
point COUNT lines down from the top of the window. If COUNT 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 COUNT is ‘nil’ (or a non-‘nil’ list), ‘recenter’ puts the line
containing point in the middle of the window. If COUNT is ‘nil’,
this function may redraw the frame, according to the value of
‘recenter-redisplay’.
When ‘recenter’ is called interactively, COUNT is the raw prefix
argument. Thus, typing ‘C-u’ as the prefix sets the COUNT to a
non-‘nil’ list, while typing ‘C-u 4’ sets COUNT 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. The command ‘recenter-top-bottom’ offers a
more convenient way to achieve this.
-- Function: recenter-window-group &optional count
This function is like ‘recenter’, except that when the selected
window is part of a group of windows (Window Group),
‘recenter-window-group’ scrolls the entire group. This condition
holds when the buffer local variable
‘recenter-window-group-function’ is set to a function. In this
case, ‘recenter-window-group’ calls the function with the argument
COUNT, then returns its result. The argument COUNT has the same
meaning as in ‘recenter’, but with respect to the entire window
group.
-- User Option: recenter-redisplay
If this variable is non-‘nil’, calling ‘recenter’ with a ‘nil’
argument redraws the frame. The default value is ‘tty’, which
means only redraw the frame if it is a tty frame.
-- Command: recenter-top-bottom &optional count
This command, which is the default binding for ‘C-l’, acts like
‘recenter’, except if called with no argument. In that case,
successive calls place point according to the cycling order defined
by the variable ‘recenter-positions’.
-- User Option: recenter-positions
This variable controls how ‘recenter-top-bottom’ behaves when
called with no argument. The default value is ‘(middle top
bottom)’, which means that successive calls of
‘recenter-top-bottom’ with no argument cycle between placing point
at the middle, top, and bottom of the window.
Info Catalog
elisp: Window Start and End
elisp: Windows
elisp: Vertical Scrolling