THE

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 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

Escape SequenceCurses KeyTHE 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)


The Hessling Editor is Copyright © Mark Hessling, 1990-2011 <mark@rexx.org>

Return to Table of Contents