APPENDIX 2 - KEYBOARD HANDLING IN THE

Keystroke handling is a very complicated business! There are so many layers between the physical keyboard and the application; in this case THE. These layers can be best described with the following diagrams:

Each layer is described below

Physical keyboard

Each keyboard is potentially different from every other. The similarity that they do posess is that when a key is pressed, a unique code is generated. The state of the Shift, Control, Num Lock, Alt modifiers either alter the unique code generated or a seperate code is generated to identify to the next layer that the key pressed should be modified.

terminal emulator

This is a required layer if the user is connected to the host via some emulation software. eg a PC connected to a U*ix host requires a terminal emulator of one sort or another.

The terminal emulator translates the unique codes generated by the keyboard usually into physical escape sequences that are passed to the U*ix shell. These escape sequences can be seen by running the U*ix command cat -v . When you press a key on the keyboard while in cat -v , the escape sequences that the terminal emulator has generated are displayed. Some systems require the Enter key to be pressed before the escape sequence is displayed. The term "escape sequence" is used because in most cases, the first character generated is an Escape character (hex 1B). Following the escape is any number of other characters, which together form a unique sequence of characters.

When using a terminal directly, firmware on the terminal does the generation of the escape sequences. Some terminals allow the user to specify what escape sequence will be generated when particular keys are pressed.

Termcap/Terminfo

Each terminal that connects to a U*ix host is identified by the value of the TERM environment variable. The value of TERM is used to setup various settings for the terminal. These settings are stored in a database; either in a flat file termcap or in a compiled format terminfo . Which one a particular system uses is dependant on the version of the U*ix Operating System being run.

One of the capabilites of the termcap/terminfo databases is to translate an escape sequence into a keyboard mnemonic that is used by the Curses library functions. This translation can also be changed by the user.

An example of this is:

Termcap: ku=\E[A
Terminfo: kcuu1=\E[A

This translates the escape sequence ESC [ A into the mnemonic ku or kccu1.

Curses

The Curses library contains definitions of many keys. These can be seen by looking in the Curses header file; usually /usr/include/curses.h Here you will see defintions like:

#define KEY_UP 0403 /* up arrow key */

THE

As THE is a Curses-based application, it recognises the Curses key definitions defined in curses.h. As not all escape sequences are usually defined in the Termcap/Terminfo databases, or are defined in curses.h, THE also has special code to decipher other escape sequences.

When a key is pressed, and is interpreted by THE, the first action is to check if the value passed to THE is a known curses key. If it is THE carries out any command associated with the key. If the value is not a known curses key, THE assumes that an escape sequence is forthcoming. The module getch.c has code for deciphering many escape sequences that are not normally defined in the Termcap/Terminfo database. Later in this document is a table of escape sequences and its associated curses key.

X11 Server

When THE is run in a X environemnt, the X server acts in a similar way to terminal emulation software. The principal difference is that there are more layers within the X server. The translation of physical keyboard codes to an X mnemonic is the first layer. The code generated is called a keycode. This keycode is then translated into another higher level mnemonic; a keysym. The keysym is usually a name that resembles the label on the physical keyboard.

The X environment provides a mechanism to assign keycodes to keysyms. This is done with the xmodmap command, and any assignment of keycode to keysym is done for all applications within the current X environemnt.

xterm

The xterm program is a terminal emulation program, and as such has many of the properties of the terminal emulator described above. The xterm program takes keysyms from the X11 server and generates escape sequences, which are defined in the xterm entry in the Termcap/ Terminfo database.

One of the features of xterm is the ability to alter the standard keysym to escape sequence translation. Surprisingly this is via a feature called translations . Not only do these translations enable the user to specify a different escape sequences to be generated, but internal xterm commands can also be assigned. These are beyond the scope of this description. An example of an xterm translation follows:

*VT100.Translations: #override\n\
<Key>F1: string(0x1b) string("[192z")\n\
<Key>F2: string(0x1b) string("[193z")\n

This specification is typically part of your own $HOME/.Xdefaults file. This file is usually read dynamically by the xterm program on startup. On some systems, the .Xdefaults file is ignored. To ensure the entries are incorporated into the X server resource database, run the command:

xrdb -merge .Xdefaults

The above example will generate the escape sequence ESC [ 1 9 2 z when the F1 key is pressed. The trailing "\" is a continuation character.

So, if you had the above translation in effect, and were running THE in an xterm, and ran the SHOWKEY command, pressing the F1 key would result in THE responding with F11.

PDCurses

The actions performed by PDCurses in the X environment combine the xterm, Termcap/Terminfo and curses actions. This results in fewer layers to be traversed.

PDCurses takes a keysym from the X server and converts it into a Curses key code. PDCurses also has the same translation capabilities as does xterm. The xterm example above would look like:

*the.Translations: #override\n\
<Key>F1: string(0x1b) string("[192z")\n\
<Key>F2: string(0x1b) string("[193z")\n

All the details described in xterm as far as translations are concerned hold for translations in PDCurses.

Another capability that translations offer is the ability to assign international characters to alphabetic characters, while still having the alphabetic characters available. For example, the translations below assigns the action of the Shifted Meta key and A, giving a capital A with a grave accent, and the unshifted Meta key and A giving a small A with a grave accent.

*the.Translations: #override\n\
!Shift Meta <Key>a: string(0xc0) \n\
!Meta <Key>a: string(0xe0) \n

The examples above assume you are using a font with a character set that is compatible with ISO 8859-1.

THE Escape Sequence to Key Name Mapping

Where (pre) is either:

ESC [ - (0x1B 0x5B) or
ESC O - (0x1B 0x4F) or
ESC ? - (0x1B 0x3F) or
CSI - (0x9B)