Keyboard Input

When running under a terminal-based system, retrieving and using keyboard input is accomplished exactly the same, using the same functions. There are some differences in how the tasks are implemented because of differences in the operating system and its use of the hardware.

Consequences of Handling Multiple Character Sequences

The keycodes returned by any particular physical key have been standardized for all keyboards. The IBM PC keyboard was used as the standard. However, in the IBM PC systems, one keystroke generally translates into one keycode that goes in the keyboard buffer.

Unlike PCDOS and OS/2, under UNIX, VMS, and other terminal-based systems, one keycode can be generated by pressing a series of keys. For instance on a VT100, the user presses Esc then 5 to simulate pressing the function key F5 that is on an IBM PC keyboard. For all systems, KEY_F5 is returned.

ki() accepts the single-character and multiple-character keycodes generated by terminals and translates them into single-character Vermont Views keycodes. The information required to make the translation is contained in the key definition table. The key definition table is built using entries in vvtermcap. See the function reference page for ki() in the Function Reference for details about the algorithm used to translate multiple-character keycodes into a Vermont Views keycode.

There are several side effects associated with the algorithm used by ki() that should be understood.

• nA legal (or an illegal) multiple character sequence can be entered by pressing the individual keys in the proper order.

For example, the three individual keystrokes Esc [ A on the VT100 will be interpreted as the Up arrow key, whose key definition string is "<ESC>[A".

A sequence of keys for which no definition string exists, such as "<ESC>/", will be rejected and the terminal will beep.

• nTo generate a keycode for a key which is the first character in any multiple-character keycode, the key must be pressed twice in a row.

  For example, on the VT100, most multiple key code sequences begin with an Esc. To have Vermont Views generate a key code for the Esc key, it must be pressed twice in a row, Esc Esc.

• nIf a sequence of individual keystrokes is a potential match for a multiple-character definition, ki() and ki_same() will not return until a match is found, a match is conclusively ruled out, or until the number of keystrokes in the longest key definition are received.

  For example, on the VT100, the longest key definition is 3. If ki() is called and the individual keystroke Esc is received from a VT100, ki() will not return until at least a second keystroke is received. It will always return after the third keystroke is received.

• nAll multiple-character key codes must be unique. One keycode sequence may not be a sub-set of another sequence.

  For example, the sequence Esc [ cannot be used as a key code sequence on the VT100 because it would be a subset of the valid code sequences Esc [ A, Esc [ B, etc. If Esc [ were to be added to the keystroke definition table, the previously defined sequence Esc [ A would be erroneously interpreted as two keystrokes; Esc [ and A.

Ensuring Full Functionality of the Keyboard

To ensure full functionality of the keyboard with Vermont Views, each terminal entry in vvtermcap should include character sequences for each Vermont Views keycode that is in use. If these keycodes are not defined in vvtermcap, Vermont Views will run, but the functions corresponding to these keys will not be available to the user.

In the default vvtermcap files, we have mapped all keycodes used by Vermont Views to default character sequences. You can change these sequences or add sequences for other keycodes. See Chapter 58, "Modifying the Terminal Interface," for more information about what keycodes need to be defined in vvtermcap, what the default character sequences for them are under each type of terminal, and how to change the character sequences.