## APPENDIX 2 - KEYBOARD HANDLING IN THE

This appendix contains information on how THE handles keystrokes in the U*ix environment. One thing that is consistant with PCs is keyboard handling. Therefore this explanation is not applicable to the PC arena.

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:

Text-mode Version of THE using terminal
Physical Keyboard | | [terminal emulator] | | Termcap/Terminfo | | Curses | | THE

Text-mode Version of THE using xterm
Physical Keyboard | | X11 server [xmodmap] | | xterm [translations] | | Termcap/Terminfo | | Curses | | THE

X11 Version of THE
Physical Keyboard | | X11 server [xmodmap] | | PDCurses [translations] | | THE

Each layer is described below

Physical keyboard

Each keyboard is potentially different from every other. The similarity that they do possess 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 separate 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 capabilities 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 definitions 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 environment, 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 environment.

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

Escape Sequence | Curses Key | THE Key Name
--- | --- | ---
(pre) 1 ~ (pre) 2 ~ (pre) 3 ~ (pre) 4 ~ (pre) 5 ~ (pre) 6 ~ (pre) 1 1 ~ (pre) 1 2 ~ (pre) 1 3 ~ (pre) 1 4 ~ (pre) 1 5 ~ (pre) 1 7 ~ (pre) 1 8 ~ (pre) 1 9 ~ (pre) 2 0 ~ (pre) 2 1 ~ (pre) 2 3 ~ (pre) 2 4 ~ (pre) 2 5 ~ (pre) 2 6 ~ (pre) 2 8 ~ (pre) 2 9 ~ (pre) 3 1 ~ (pre) 3 2 ~ (pre) 3 3 ~ (pre) 3 4 ~ (pre) 3 7 ~ (pre) 3 8 ~ (pre) 3 9 ~ (pre) 4 0 ~ (pre) 4 1 ~ (pre) 4 2 ~ (pre) 4 3 ~ (pre) 4 4 ~ (pre) 4 5 ~ (pre) 4 6 ~ (pre) 4 7 ~ (pre) 4 8 ~ (pre) 4 9 ~ (pre) 5 0 ~ (pre) 5 1 ~ (pre) 5 2 ~ (pre) 5 3 ~ (pre) 5 4 ~ (pre) 5 5 ~ (pre) 5 6 ~ (pre) 5 7 ~ (pre) 5 8 ~ (pre) 5 9 ~ (pre) 6 0 ~ (pre) A (pre) B (pre) C (pre) D (pre) F (pre) G (pre) H (pre) I (pre) L (pre) M (pre) N (pre) O (pre) P (pre) Q (pre) R (pre) S (pre) T (pre) U (pre) V (pre) W (pre) X (pre) Z (pre) l (pre) m (pre) n (pre) o (pre) p (pre) q (pre) r (pre) s (pre) t (pre) u (pre) v (pre) w (pre) x (pre) y (pre) 1 z (pre) 2 z (pre) 3 z (pre) 4 z (pre) 5 z (pre) 6 z (pre) 1 9 5 z (pre) 2 1 4 z (pre) 2 1 5 z (pre) 2 1 6 z (pre) 2 1 7 z (pre) 2 1 9 z (pre) 2 2 0 z (pre) 2 2 1 z (pre) 2 2 2 z (pre) 2 2 4 z (pre) 2 2 5 z (pre) 2 2 6 z (pre) 2 2 7 z (pre) 2 2 8 z (pre) 2 2 9 z (pre) 2 3 0 z (pre) 2 3 1 z (pre) 2 3 2 z (pre) 2 3 3 z (pre) 2 3 4 z (pre) 2 3 5 z (pre) 3 2 4 z (pre) 3 2 5 z (pre) 3 2 6 z (pre) 3 2 7 z (pre) 3 2 8 z (pre) 3 2 9 z (pre) 3 3 0 z (pre) 3 3 1 z (pre) 3 3 2 z (pre) 3 3 3 z (pre) 3 3 4 z (pre) 3 3 5 z (pre) 4 1 4 z (pre) 4 1 5 z (pre) 4 1 6 z (pre) 4 1 7 z (pre) 4 1 9 z (pre) 4 2 0 z (pre) 4 2 1 z (pre) 4 2 2 z (pre) 4 2 3 z (pre) 4 2 4 z (pre) 4 2 5 z (pre) 4 2 6 z (pre) 4 2 7 z (pre) 4 2 8 z (pre) 4 2 9 z (pre) 4 3 0 z (pre) 4 3 1 z (pre) 4 3 2 z (pre) 4 3 3 z (pre) 4 3 4 z (pre) 4 3 5 z (pre) 1 9 2 z (pre) 1 9 3 z (pre) 2 9 2 z (pre) 2 9 3 z (pre) [ A (pre) [ B (pre) [ C (pre) [ D (pre) [ E (pre) 0 q (pre) 1 q (pre) 2 q (pre) 3 q (pre) 4 q (pre) 5 q (pre) 6 q (pre) 7 q (pre) 8 q (pre) 9 q (pre) 1 0 q (pre) 1 1 q (pre) 1 2 q (pre) 1 3 q (pre) 1 4 q (pre) 1 5 q (pre) 1 6 q (pre) 1 7 q (pre) 1 8 q (pre) 1 9 q (pre) 2 0 q (pre) 2 1 q (pre) 2 2 q (pre) 2 3 q (pre) 2 4 q (pre) 2 5 q (pre) 2 6 q (pre) 2 7 q (pre) 2 8 q (pre) 2 9 q (pre) 3 0 q (pre) 3 1 q (pre) 3 2 q (pre) 3 3 q (pre) 3 4 q (pre) 3 5 q (pre) 3 6 q (pre) 1 3 9 q (pre) 1 5 0 q (pre) 1 4 6 q (pre) 1 5 4 q ESC P ESC Q ESC R ESC S | KEY_Find KEY_InsertHere KEY_Remove KEY_Select KEY_PrevScreen KEY_NextScreen KEY_F(1) KEY_F(2) KEY_F(3) KEY_F(4) KEY_F(5) KEY_F(6) KEY_F(7) KEY_F(8) KEY_F(9) KEY_F(10) KEY_F(11) KEY_F(12) KEY_F(49) KEY_F(50) KEY_F(51) KEY_F(52) KEY_F(53) KEY_F(54) KEY_F(55) KEY_F(56) KEY_F(13) KEY_F(14) KEY_F(15) KEY_F(16) KEY_F(17) KEY_F(18) KEY_F(19) KEY_F(20) KEY_F(21) KEY_F(22) KEY_F(23) KEY_F(24) KEY_F(25) KEY_F(26) KEY_F(27) KEY_F(28) KEY_F(29) KEY_F(30) KEY_F(31) KEY_F(32) KEY_F(33) KEY_F(34) KEY_F(35) KEY_F(36) KEY_UP KEY_DOWN KEY_RIGHT KEY_LEFT KEY_END KEY_NextScreen KEY_HOME KEY_PrevScreen KEY_InsertHere KEY_NUMENTER KEY_F(2) KEY_F(3) KEY_PF1 KEY_PF2 KEY_PF3 KEY_PF4 KEY_F(8) KEY_F(9) KEY_F(10) KEY_F(11) KEY_F(12) KEY_BACKTAB KEY_PadComma KEY_PadMinus KEY_PadPeriod KEY_Pad0 KEY_Pad1 KEY_Pad2 KEY_Pad3 KEY_Pad4 KEY_Pad5 KEY_Pad6 KEY_Pad7 KEY_Pad8 KEY_Pad9 KEY_NUMENTER KEY_BTAB KEY_InsertHere KEY_HOME KEY_END KEY_PrevScreen KEY_NextScreen KEY_UNDO KEY_HOME KEY_UP KEY_PrevScreen KEY_LEFT KEY_RIGHT KEY_END KEY_DOWN KEY_NextScreen KEY_F(1) KEY_F(2) KEY_F(3) KEY_F(4) KEY_F(5) KEY_F(6) KEY_F(7) KEY_F(8) KEY_F(9) KEY_F(10) KEY_F(11) KEY_F(12) KEY_F(13) KEY_F(14) KEY_F(15) KEY_F(16) KEY_F(17) KEY_F(18) KEY_F(19) KEY_F(20) KEY_F(21) KEY_F(22) KEY_F(23) KEY_F(24) KEY_C_HOME KEY_C_CURU KEY_C_PGUP KEY_C_CURL KEY_C_CURR KEY_C_END KEY_C_CURD KEY_C_PGDN KEY_PadComma KEY_F(25) KEY_F(26) KEY_F(27) KEY_F(28) KEY_F(29) KEY_F(30) KEY_F(31) KEY_F(32) KEY_F(33) KEY_F(34) KEY_F(35) KEY_F(36) KEY_F(49) KEY_F(50) KEY_F(57) KEY_F(58) KEY_F(1) KEY_F(2) KEY_F(3) KEY_F(4) KEY_F(5) KEY_PadComma KEY_F(1) KEY_F(2) KEY_F(3) KEY_F(4) KEY_F(5) KEY_F(6) KEY_F(7) KEY_F(8) KEY_F(9) KEY_F(10) KEY_F(11) KEY_F(12) KEY_F(13) KEY_F(14) KEY_F(15) KEY_F(16) KEY_F(17) KEY_F(18) KEY_F(19) KEY_F(20) KEY_F(21) KEY_F(22) KEY_F(23) KEY_F(24) KEY_F(25) KEY_F(26) KEY_F(27) KEY_F(28) KEY_F(29) KEY_F(30) KEY_F(31) KEY_F(32) KEY_F(33) KEY_F(34) KEY_F(35) KEY_F(36) KEY_InsertHere KEY_PrevScreen KEY_END KEY_NextScreen KEY_PF1 KEY_PF2 KEY_PF3 KEY_PF4 | FIND INS DEL SELECT PGUP PGDN F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12 F13 F14 F15 F16 F17 F18 F19 F20 S-F1 S-F2 S-F3 S-F4 S-F5 S-F6 S-F7 S-F8 S-F9 S-F10 S-F11 S-F12 C-F1 C-F2 C-F3 C-F4 C-F5 C-F6 C-F7 C-F8 C-F9 C-F10 C-F11 C-F12 CURU CURD CURR CURL END PGDN HOME PGUP INS NUMENTER F2 F3 PF1 PF2 PF3 PF4 F8 F9 F10 F11 F12 S-TAB COMMA MINUS NUMSTOP NUM0 NUM1 NUM2 NUM3 NUM4 CENTER NUM6 NUM7 NUM8 NUM9 NUMENTER S-TAB INS HOME END PGUP PGDN UNDO HOME CURU PGUP CURL CURR END CURD PGDN F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12 S-F1 S-F2 S-F3 S-F4 S-F5 S-F6 S-F7 S-F8 S-F9 S-F10 S-F11 S-F12 C-HOME C-CURU C-PGUP C-CURL C-CURR C-END C-CURD C-PGDN COMMA C-F1 C-F2 C-F3 C-F4 C-F5 C-F6 C-F7 C-F8 C-F9 C-F10 C-F11 C-F12 F13 F14 S-F13 S-F14 F1 F2 F3 F4 F5 COMMA F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12 S-F1 S-F2 S-F3 S-F4 S-F5 S-F6 S-F7 S-F8 S-F9 S-F10 S-F11 S-F12 C-F1 C-F2 C-F3 C-F4 C-F5 C-F6 C-F7 C-F8 C-F9 C-F10 C-F11 C-F12 INS PGUP END PGUP PF1 PF2 PF3 PF4

Where (pre) is either:

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

Return to Table of Contents