47. Scrolling In Place

This library provides improved vertical scrolling commands for GNU Emacs.

47.1 Features

The new vertical scrolling commands offer the following features:

• When a scrolling command is executed, GNU Emacs tries to keep point as close as possible to its original window position (window line and column). This is what "scroll in place" means: point stays "in place" within the window. (There are times when point must be moved from its original window position in order to execute the scroll; see below.)

  The variable scroll-in-place, which is true by default, determines whether or not the standard GNU Emacs scrolling commands (scroll-down, scroll-up, scroll-other-window-down, and scroll-other-window) use the "in place" features listed here. When scroll-in-place is nil the standard GNU Emacs scrolling commands essentially just call the original versions of themselves. (Note that even when scroll-in-place is nil the new versions of scroll-down and scroll-up have slightly different behavior when a minibuffer window is the selected window. See below.)

  It is possible to turn off (or turn on) "in place" scrolling for certain buffers by making buffer-local bindings of the variable scroll-in-place for those buffers. The variable scroll-in-place is not usually buffer-local, but you can make it so if you desire.

• Because the improved scrolling commands keep point at its original window position, these scrolling commands are "reversible." The scroll-up command undoes the effect of the immediately previous scroll-down command (if any) and vice versa. In other words, if you scroll up and then immediately scroll back down, the window configuration is restored to its exact original state. This allows you to browse through a buffer more easily, as you can always get back to the original configuration.

  Note, however, that the improved scrolling commands are guaranteed to be reversible only if there are no intervening non-scrolling commands. Also, if you give a prefix argument to a scrolling command (in order to specify the number of lines to scroll by), previous scrolling commands may no longer be reversible. More specifically, if the new prefix argument has a different magnitude than the previous scrolling distance, then any previous scrolling commands are not reversible. The new prefix argument takes precedence.

  You might find it useful to think of the scrolling commands as forming "chains." A scrolling command either starts or continues a chain. By issuing a non-scrolling command or by changing the number of lines to be scrolled, you break the chain. (Note that simply changing the scrolling direction won’t break the chain; changing the absolute number of lines to be scrolled is what breaks the chain.) Scrolling commands are guaranteed to be reversible only within the current chain. Hopefully that’s clear enough.

• When a scrolling command is given a prefix argument (which specifies the number of lines to scroll by), then that argument becomes the default scrolling distance for all immediately subsequent scrolling commands. This means that you can easily set the scrolling distance for a chain of scrolling commands. Note that a new prefix argument or any non- scrolling command breaks the chain (as described above), and any further scrolling commands will use the usual defaults (or the prefix argument you specify at that time, of course).

  However, there are cases in which one doesn’t want the current scrolling command to use the default scrolling distance that was set by the previous scrolling command. For example, suppose that you had special commands that scrolled one line up and one line down. When you invoke one of these commands, the "in place" scrolling routines set the default scrolling distance to be just one line. Now suppose that you use one of your special commands and then immediately invoke scroll-up (C-v), expecting it to scroll by a near windowful of text. You would be disappointed — because the previous command set the default scrolling distance to be just one line, scroll-up just scrolls by one line.

  To solve this problem, "scroll-in-place" allows you to divide scrolling commands into separate "groups." Commands in a group can only form chains with (and therefore, inherit defaults from) commands in the same group. (Note that no command can be in more than one group.) If you invoke a scrolling command that is not in the same group as that of the immediately previous scrolling command, then the previous chain is broken and you start a new chain — with a new set of defaults.

  So to solve the problem described above, you could put your one-line scrolling commands in their own group. Once that is done, the standard scrolling commands will not form chains with your one-line scrolling commands, and therefore will not use the default scrolling distance set by those commands. Problem solved!

  By default, all "in place" scrolling commands are in a single group. If you want to partition some commands into separate groups, you must do that yourself before any "in place" commands are invoked. For more information about grouping commands, see the documentation for the variables scroll-command-groups and scroll-default-command-group.

• The improved scrolling commands will avoid displaying empty lines past the end of the buffer when possible. In other words, just as you can’t see "dead space" before the beginning of the buffer text, the new scrolling commands try to avoid displaying "dead space" past the end of the buffer text. This behavior is somewhat configurable; see the documentation for the variable scroll-allow-blank-lines-past-eob.

  Dead space will be displayed if it is necessary in order to make a previous scrolling action reversible, however.

• If the scrolling commands cannot keep point at its initial window position (because a buffer boundary is on screen and the window can’t be scrolled as far as necessary to keep point at the right place), point is allowed to temporarily stray from its initial window position. That is, point moves the correct number of window lines, even if it means that it has to stray from its desired window position. This straying is undone when (and if) the scrolling action is reversed.
• If a scrolling command tries to move point past a buffer boundary, point is instead moved to the boundary (the beginning or the end of the buffer as appropriate) and an appropriate message is displayed. This motion is reversible, of course.

  However, if point was already at the buffer boundary when the scrolling command was invoked, the command signals an appropriate error instead.

• When a minibuffer window is the selected window, the new versions of scroll-up and scroll-down either scroll the window in the variable minibuffer-scroll-window (which is usually the window of completions) or the next-window if there is no minibuffer-scroll-window. This is usually much more useful than scrolling the minibuffer itself. (Note that this feature is available even when the variable scroll-in-place is nil.)
• When a scrolling command is scrolling a window other than the selected window, it will signal an appropriate buffer boundary error if the window cannot be scrolled (because the appropriate buffer boundary is already visible). This means that an error is signalled even in cases that would be allowed (by "straying" point or by moving it to the buffer boundary) if the window were selected.

  (If an error were not signalled in these cases, then there would be many cases in which the last scroll in a particular direction would appear to do nothing because only the point position would change — the displayed text would stay the same! To avoid these cases the scrolling commands signal boundary errors "prematurely" when the window to be scrolled is not selected.)

47.2 Command and Functions

This library provides the following "in place" versions of GNU Emacs’ standard vertical scrolling commands:

• scroll-down-in-place
• scroll-up-in-place
• scroll-other-window-down-in-place
• scroll-other-window-in-place

The variable scroll-in-place, which is true by default, determines whether or not the new versions of the standard GNU Emacs scrolling commands (scroll-down, scroll-up, scroll-other-window-down, and scroll-other-window) use the "in place" features listed above. When scroll-in-place is nil the standard GNU Emacs scrolling commands essentially just call the original versions of themselves. (Note that even when scroll-in-place is nil the new versions of scroll-down and scroll-up have slightly different behavior when a minibuffer window is the selected window. See the feature list above.)

NOTE that this package redefines the standard GNU Emacs commands scroll-down, scroll-up, scroll-other-window-down, and scroll-other-window (in order to check the variable scroll-in-place, as described above). The command scroll-other-window-down first appeared as a standard command in the FSF’s GNU Emacs 19.26.

This package also provides the following functions and variables which are of use to programmers:

• scroll-window
• scroll-window-in-place
• scroll-window-in-place-continue-sequence
• scroll-default-lines (variable)
• scroll-command-groups (variable)

The scroll-window-in-place function is the heart of the "in place" scrolling commands. scroll-window is a function that checks the variable scroll-in-place and calls the appropriate scrolling function (either scroll-window-in-place or one of the original versions of scroll-down and scroll-up). The function scroll-window-in-place-continue-sequence is provided in order to preserve running "chains" of scrolling commands as described above.

The variable scroll-default-lines determines the default scrolling distance when a new chain of "in place" scrolling commands begins. If this variable is not a number, then the default distance is the height of the window to be scrolled minus next-screen-context-lines. The variable scroll-command-groups contains the explicit groups of "in place" scrolling commands; for more information read the variable documentation.

47.3 Installation

To use this package, you simply need to load it from within your initialization file:

  (require 'scroll-in-place)

By default, this package provides for the standard GNU Emacs vertical scrolling commands (scroll-down, scroll-up, scroll-other-window-down, and scroll-other-window) to use the "in place" features. If you would rather not have this, set the variable (setq scroll-in-place nil).

When scroll-in-place is nil you will have to bind keys in order to call the "in place" scrolling commands. For example, you might want to do the following:

  (global-set-key "\M-v" 'scroll-down-in-place)
  (global-set-key "\C-v" 'scroll-up-in-place)

47.4 Advanced Customization

If you want to partition certain "in place" scrolling commands into separate groups, you should do something like the following:

  ;; Make one group containing the commands `scroll-down-one-line' and
  ;; `scroll-up-one-line'.  (These are not standard GNU Emacs commands.)
  (setq scroll-command-groups
        (list '(scroll-down-one-line scroll-up-one-line)))

You could write the ‘scroll-down-one-line’ command like this:

  (defun scroll-down-one-line (arg)
    "Scroll down one line, or number of lines specified by prefix arg."
    (interactive "P")
    (let ((scroll-default-lines 1))
      (scroll-down-in-place arg)))

If you want to disable "in place" scrolling for windows that display a particular buffer (while leaving it available in other windows), you can make scroll-in-place a buffer-local variable for that buffer and then bind that local copy of scroll-in-place to nil. This is the kind of thing that one generally does in a major mode hook. For example, you can disable "in place" scrolling of GNUS article windows with the following code:

  (setq gnus-article-mode-hook
        (function (lambda ()
                    (make-local-variable 'scroll-in-place)
                    (setq scroll-in-place nil))))
  ;; Set the variable `gnus-Article-mode-hook' instead if you are using
  ;; an old version of GNUS, say version 3.13 or 3.14.

The variable scroll-allow-blank-lines-past-eob can also be made local to particular buffers, if you desire. (But why would you want to do that?)

This document was generated by Aidan Kehoe on December 27, 2016 using texi2html 1.82.