www.delorie.com/gnu/docs/bash/termcap_11.html   search  
Buy the book!

The Termcap Library

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.5.4 Performing Padding with tputs

Use the termcap function tputs to output a string containing an optional padding spec of the form described above (see section 1.5.3 Specifying Padding in a Terminal Description). The function tputs strips off and decodes the padding spec, outputs the rest of the string, and then outputs the appropriate padding. Here is its declaration in ANSI C:

char PC;
short ospeed;

int tputs (char *string, int nlines, int (*outfun) ());

Here string is the string (including padding spec) to be output; nlines is the number of lines affected by the operation, which is used to multiply the amount of padding if the padding spec ends with a `*'. Finally, outfun is a function (such as fputchar) that is called to output each character. When actually called, outfun should expect one argument, a character.

The operation of tputs is controlled by two global variables, ospeed and PC. The value of ospeed is supposed to be the terminal output speed, encoded as in the ioctl system call which gets the speed information. This is needed to compute the number of padding characters. The value of PC is the character used for padding.

You are responsible for storing suitable values into these variables before using tputs. The value stored into the PC variable should be taken from the `pc' capability in the terminal description (see section 3.17 Padding Capabilities). Store zero in PC if there is no `pc' capability.

The argument nlines requires some thought. Normally, it should be the number of lines whose contents will be cleared or moved by the command. For cursor motion commands, or commands that do editing within one line, use the value 1. For most commands that affect multiple lines, such as `al' (insert a line) and `cd' (clear from the cursor to the end of the screen), nlines should be the screen height minus the current vertical position (origin 0). For multiple insert and scroll commands such as `AL' (insert multiple lines), that same value for nlines is correct; the number of lines being inserted is not correct.

If a "scroll window" feature is used to reduce the number of lines affected by a command, the value of nlines should take this into account. This is because the delay time required depends on how much work the terminal has to do, and the scroll window feature reduces the work. See section 3.5 Scrolling.

Commands such as `ic' and `dc' (insert or delete characters) are problematical because the padding needed by these commands is proportional to the number of characters affected, which is the number of columns from the cursor to the end of the line. It would be nice to have a way to specify such a dependence, and there is no need for dependence on vertical position in these commands, so it is an obvious idea to say that for these commands nlines should really be the number of columns affected. However, the definition of termcap clearly says that nlines is always the number of lines affected, even in this case, where it is always 1. It is not easy to change this rule now, because too many programs and terminal descriptions have been written to follow it.

Because nlines is always 1 for the `ic' and `dc' strings, there is no reason for them to use `*', but some of them do. These should be corrected by deleting the `*'. If, some day, such entries have disappeared, it may be possible to change to a more useful convention for the nlines argument for these operations without breaking any programs.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

  webmaster   donations   bookstore     delorie software   privacy  
  Copyright 2003   by The Free Software Foundation     Updated Jun 2003