www.delorie.com/gnu/docs/termcap/termcap_28.html

search

	Buy the book!

The Termcap Library

3.5 Scrolling

Scrolling means moving the contents of the screen up or down one or more lines. Moving the contents up is forward scrolling; moving them down is reverse scrolling.

Scrolling happens after each line of output during ordinary output on most display terminals. But in an application program that uses termcap for random-access output, scrolling happens only when explicitly requested with the commands in this section.

Some terminals have a scroll region feature. This lets you limit the effect of scrolling to a specified range of lines. Lines outside the range are unaffected when scrolling happens. The scroll region feature is available if either `cs' or `cS' is present.

`sf'

String of commands to scroll the screen one line up, assuming it is output with the cursor at the beginning of the bottom line.

`sr'

String of commands to scroll the screen one line down, assuming it is output with the cursor at the beginning of the top line.

`do'

A few programs will try to use `do' to do the work of `sf'. This is not really correct--it is an attempt to compensate for the absence of a `sf' command in some old terminal descriptions.

Since these terminal descriptions do define `sr', perhaps at one time the definition of `do' was different and it could be used for scrolling as well. But it isn't desirable to combine these two functions in one capability, since scrolling often requires more padding than simply moving the cursor down. Defining `sf' and `do' separately allows you to specify the padding properly. Also, all sources agree that `do' should not be relied on to do scrolling.

So the best approach is to add `sf' capabilities to the descriptions of these terminals, copying the definition of `do' if that does scroll.

`SF'

String of commands to scroll the screen n lines up, assuming it is output with the cursor at the beginning of the bottom line.

`SR'

String of commands to scroll the screen n lines down, assuming it is output with the cursor at the beginning of the top line.

`cs'

String of commands to set the scroll region. This command takes two parameters, start and end, which are the line numbers (origin-zero) of the first line to include in the scroll region and of the last line to include in it. When a scroll region is set, scrolling is limited to the specified range of lines; lines outside the range are not affected by scroll commands.

Do not try to move the cursor outside the scroll region. The region remains set until explicitly removed. To remove the scroll region, use another `cs' command specifying the full height of the screen.

The cursor position is undefined after the `cs' command is set, so position the cursor with `cm' immediately afterward.

`cS'

String of commands to set the scroll region using parameters in different form. The effect is the same as if `cs' were used. Four parameters are required:

1. Total number of lines on the screen.
2. Number of lines above desired scroll region.
3. Number of lines below (outside of) desired scroll region.
4. Total number of lines on the screen, the same as the first parameter.

This capability is a GNU extension that was invented to allow the Ann Arbor Ambassador's scroll-region command to be described; it could also be done by putting non-Unix `%'-sequences into a `cs' string, but that would have confused Unix programs that used the `cs' capability with the Unix termcap. Currently only GNU Emacs uses the `cS' capability.

`ns'

Flag which means that the terminal does not normally scroll for ordinary sequential output. For modern terminals, this means that outputting a newline in ordinary sequential output with the cursor on the bottom line wraps to the top line. For some obsolete terminals, other things may happen.

The terminal may be able to scroll even if it does not normally do so. If the `sf' capability is provided, it can be used for scrolling regardless of `ns'.

`da'

Flag whose presence means that lines scrolled up off the top of the screen may come back if scrolling down is done subsequently.

The `da' and `db' flags do not, strictly speaking, affect how to scroll. But programs that scroll usually need to clear the lines scrolled onto the screen, if these flags are present.

`db'

Flag whose presence means that lines scrolled down off the bottom of the screen may come back if scrolling up is done subsequently.

`lm'

Numeric value, the number of lines of display memory that the terminal has. A value of zero means that the terminal has more display memory than can fit on the screen, but no fixed number of lines. (The number of lines may depend on the amount of text in each line.)

Any terminal description that defines `SF' should also define `sf'; likewise for `SR' and `sr'. However, many terminals can only scroll by one line at a time, so it is common to find `sf' and not `SF', or `sr' without `SR'.

Therefore, all programs that use the scrolling facilities should be prepared to work with `sf' in the case that `SF' is absent, and likewise with `sr'. On the other hand, an application program that uses only `sf' and not `SF' is acceptable, though slow on some terminals.

When outputting a scroll command with tputs, the nlines argument should be the total number of lines in the portion of the screen being scrolled. Very often these commands require padding proportional to this number of lines. See section 1.5 Padding.