1/*man-start********************************************************************* 2 3 4======================================================================== 5APPENDIX 2 - KEYBOARD HANDLING IN THE 6======================================================================== 7 8This appendix contains information on how THE handles keystrokes in the 9U*ix environment. One thing that is consistant with PCs is keyboard 10handling. Therefore this explanation is not applicable to the PC 11arena. 12 13Keystroke handling is a very complicated business! There are so many 14layers between the physical keyboard and the application; in this case 15THE. These layers can be best described with the following diagrams: 16 17 +------------------------------------------+ 18 | Text-mode Version of THE using terminal | 19 +------------------------------------------+ 20 | | 21 | Physical Keyboard | 22 | | | 23 | | | 24 | [terminal emulator] | 25 | | | 26 | | | 27 | Termcap/Terminfo | 28 | | | 29 | | | 30 | Curses | 31 | | | 32 | | | 33 | THE | 34 | | 35 +------------------------------------------+ 36 37 +------------------------------------------+ 38 | Text-mode Version of THE using xterm | 39 +------------------------------------------+ 40 | | 41 | Physical Keyboard | 42 | | | 43 | | | 44 | X11 server | 45 | [xmodmap] | 46 | | | 47 | | | 48 | xterm | 49 | [translations] | 50 | | | 51 | | | 52 | Termcap/Terminfo | 53 | | | 54 | | | 55 | Curses | 56 | | | 57 | | | 58 | THE | 59 | | 60 +------------------------------------------+ 61 62 63 +-----------------------+ 64 | X11 Version of THE | 65 +-----------------------+ 66 | | 67 | Physical Keyboard | 68 | | | 69 | | | 70 | X11 server | 71 | [xmodmap] | 72 | | | 73 | | | 74 | PDCurses | 75 | [translations] | 76 | | | 77 | | | 78 | THE | 79 | | 80 +-----------------------+ 81 82Each layer is described below 83 84----------------- 85Physical keyboard 86----------------- 87 88Each keyboard is potentially different from every other. The similarity 89that they do possess is that when a key is pressed, a unique code is 90generated. The state of the Shift, Control, Num Lock, Alt modifiers 91either alter the unique code generated or a separate code is generated 92to identify to the next layer that the key pressed should be modified. 93 94----------------- 95terminal emulator 96----------------- 97 98This is a required layer if the user is connected to the host via some 99emulation software. eg a PC connected to a U*ix host requires a terminal 100emulator of one sort or another. 101 102The terminal emulator translates the unique codes generated by the 103keyboard usually into physical escape sequences that are passed to 104the U*ix shell. These escape sequences can be seen by running the 105U*ix command 'cat -v'. When you press a key on the keyboard while 106in 'cat -v', the escape sequences that the terminal emulator has 107generated are displayed. Some systems require the Enter key to be 108pressed before the escape sequence is displayed. The term "escape 109sequence" is used because in most cases, the first character 110generated is an Escape character (hex 1B). Following the escape 111is any number of other characters, which together form a unique 112sequence of characters. 113 114When using a terminal directly, firmware on the terminal does the 115generation of the escape sequences. Some terminals allow the user 116to specify what escape sequence will be generated when particular 117keys are pressed. 118 119---------------- 120Termcap/Terminfo 121---------------- 122 123Each terminal that connects to a U*ix host is identified by the value 124of the TERM environment variable. The value of TERM is used to setup 125various settings for the terminal. These settings are stored in a 126database; either in a flat file 'termcap' or in a compiled format 127'terminfo'. Which one a particular system uses is dependant on the 128version of the U*ix Operating System being run. 129 130One of the capabilities of the termcap/terminfo databases is to 131translate an escape sequence into a keyboard mnemonic that is used 132by the Curses library functions. This translation can also be 133changed by the user. 134 135An example of this is: 136 137 +------------------------------ 138 Termcap: ku=\E[A 139 Terminfo: kcuu1=\E[A 140 +------------------------------ 141 142This translates the escape sequence ESC [ A into the mnemonic ku or 143kccu1. 144 145------ 146Curses 147------ 148 149The Curses library contains definitions of many keys. These can be 150seen by looking in the Curses header file; usually /usr/include/curses.h 151Here you will see definitions like: 152 153 +------------------------------ 154 #define KEY_UP 0403 /* up arrow key */ 155 +------------------------------ 156 157--- 158THE 159--- 160 161As THE is a Curses-based application, it recognises the Curses key 162definitions defined in curses.h. As not all escape sequences are 163usually defined in the Termcap/Terminfo databases, or are defined in 164curses.h, THE also has special code to decipher other escape sequences. 165 166When a key is pressed, and is interpreted by THE, the first action is 167to check if the value passed to THE is a 'known' curses key. If it is 168THE carries out any command associated with the key. If the value 169is not a 'known' curses key, THE assumes that an escape sequence is 170forthcoming. The module getch.c has code for deciphering many escape 171sequences that are not normally defined in the Termcap/Terminfo 172database. Later in this document is a table of escape sequences and 173its associated curses key. 174 175---------- 176X11 Server 177---------- 178 179When THE is run in a X environment, the X server acts in a similar way 180to terminal emulation software. The principal difference is that there 181are more layers within the X server. The translation of physical 182keyboard codes to an X mnemonic is the first layer. The code generated 183is called a keycode. This keycode is then translated into another 184higher level mnemonic; a keysym. The keysym is usually a name that 185resembles the label on the physical keyboard. 186 187The X environment provides a mechanism to assign keycodes to keysyms. 188This is done with the xmodmap command, and any assignment of keycode 189to keysym is done for all applications within the current X environment. 190 191----- 192xterm 193----- 194 195The xterm program is a terminal emulation program, and as such has many 196of the properties of the terminal emulator described above. 197The xterm program takes keysyms from the X11 server and generates 198escape sequences, which are defined in the xterm entry in the Termcap/ 199Terminfo database. 200 201One of the features of xterm is the ability to alter the standard keysym to 202escape sequence translation. Surprisingly this is via a feature called 203'translations'. Not only do these translations enable the user to 204specify a different escape sequences to be generated, but internal 205xterm commands can also be assigned. These are beyond the scope of 206this description. An example of an xterm translation follows: 207 208 +------------------------------ 209 *VT100.Translations: #override\n\ 210 <Key>F1: string(0x1b) string("[192z")\n\ 211 <Key>F2: string(0x1b) string("[193z")\n 212 +------------------------------ 213 214This specification is typically part of your own $HOME/.Xdefaults file. 215This file is usually read dynamically by the xterm program on startup. 216On some systems, the .Xdefaults file is ignored. To ensure the entries 217are incorporated into the X server resource database, run the command: 218 219 +------------------------------ 220 xrdb -merge .Xdefaults 221 +------------------------------ 222 223The above example will generate the escape sequence ESC [ 1 9 2 z when 224the F1 key is pressed. The trailing "\" is a continuation character. 225 226So, if you had the above translation in effect, and were running THE in 227an xterm, and ran the SHOWKEY command, pressing the F1 key would result 228in THE responding with F11. 229 230-------- 231PDCurses 232-------- 233 234The actions performed by PDCurses in the X environment combine the 235xterm, Termcap/Terminfo and curses actions. This results in fewer 236layers to be traversed. 237 238PDCurses takes a keysym from the X server and converts it into a 239Curses key code. PDCurses also has the same translation capabilities 240as does xterm. The xterm example above would look like: 241 242 +------------------------------ 243 *the.Translations: #override\n\ 244 <Key>F1: string(0x1b) string("[192z")\n\ 245 <Key>F2: string(0x1b) string("[193z")\n 246 +------------------------------ 247 248All the details described in xterm as far as translations are concerned 249hold for translations in PDCurses. 250 251Another capability that translations offer is the ability to assign 252international characters to alphabetic characters, while still having 253the alphabetic characters available. For example, the translations 254below assigns the action of the Shifted Meta key and A, giving a 255capital A with a grave accent, and the unshifted Meta key and A giving 256a small A with a grave accent. 257 258 +------------------------------ 259 *the.Translations: #override\n\ 260 !Shift Meta <Key>a: string(0xc0) \n\ 261 !Meta <Key>a: string(0xe0) \n 262 +------------------------------ 263 264The examples above assume you are using a font with a character set that 265is compatible with ISO 8859-1. 266 267--------------------------------------- 268THE Escape Sequence to Key Name Mapping 269--------------------------------------- 270 271 +------------------+----------------+----------------+ 272 | Escape Sequence | Curses Key | THE Key Name | 273 +------------------+----------------+----------------+ 274 | (pre) 1 ~ | KEY_Find | FIND | 275 | (pre) 2 ~ | KEY_InsertHere | INS | 276 | (pre) 3 ~ | KEY_Remove | DEL | 277 | (pre) 4 ~ | KEY_Select | SELECT | 278 | (pre) 5 ~ | KEY_PrevScreen | PGUP | 279 | (pre) 6 ~ | KEY_NextScreen | PGDN | 280 | (pre) 1 1 ~ | KEY_F(1) | F1 | 281 | (pre) 1 2 ~ | KEY_F(2) | F2 | 282 | (pre) 1 3 ~ | KEY_F(3) | F3 | 283 | (pre) 1 4 ~ | KEY_F(4) | F4 | 284 | (pre) 1 5 ~ | KEY_F(5) | F5 | 285 | (pre) 1 7 ~ | KEY_F(6) | F6 | 286 | (pre) 1 8 ~ | KEY_F(7) | F7 | 287 | (pre) 1 9 ~ | KEY_F(8) | F8 | 288 | (pre) 2 0 ~ | KEY_F(9) | F9 | 289 | (pre) 2 1 ~ | KEY_F(10) | F10 | 290 | (pre) 2 3 ~ | KEY_F(11) | F11 | 291 | (pre) 2 4 ~ | KEY_F(12) | F12 | 292 | (pre) 2 5 ~ | KEY_F(49) | F13 | 293 | (pre) 2 6 ~ | KEY_F(50) | F14 | 294 | (pre) 2 8 ~ | KEY_F(51) | F15 | 295 | (pre) 2 9 ~ | KEY_F(52) | F16 | 296 | (pre) 3 1 ~ | KEY_F(53) | F17 | 297 | (pre) 3 2 ~ | KEY_F(54) | F18 | 298 | (pre) 3 3 ~ | KEY_F(55) | F19 | 299 | (pre) 3 4 ~ | KEY_F(56) | F20 | 300 | (pre) 3 7 ~ | KEY_F(13) | S-F1 | 301 | (pre) 3 8 ~ | KEY_F(14) | S-F2 | 302 | (pre) 3 9 ~ | KEY_F(15) | S-F3 | 303 | (pre) 4 0 ~ | KEY_F(16) | S-F4 | 304 | (pre) 4 1 ~ | KEY_F(17) | S-F5 | 305 | (pre) 4 2 ~ | KEY_F(18) | S-F6 | 306 | (pre) 4 3 ~ | KEY_F(19) | S-F7 | 307 | (pre) 4 4 ~ | KEY_F(20) | S-F8 | 308 | (pre) 4 5 ~ | KEY_F(21) | S-F9 | 309 | (pre) 4 6 ~ | KEY_F(22) | S-F10 | 310 | (pre) 4 7 ~ | KEY_F(23) | S-F11 | 311 | (pre) 4 8 ~ | KEY_F(24) | S-F12 | 312 | (pre) 4 9 ~ | KEY_F(25) | C-F1 | 313 | (pre) 5 0 ~ | KEY_F(26) | C-F2 | 314 | (pre) 5 1 ~ | KEY_F(27) | C-F3 | 315 | (pre) 5 2 ~ | KEY_F(28) | C-F4 | 316 | (pre) 5 3 ~ | KEY_F(29) | C-F5 | 317 | (pre) 5 4 ~ | KEY_F(30) | C-F6 | 318 | (pre) 5 5 ~ | KEY_F(31) | C-F7 | 319 | (pre) 5 6 ~ | KEY_F(32) | C-F8 | 320 | (pre) 5 7 ~ | KEY_F(33) | C-F9 | 321 | (pre) 5 8 ~ | KEY_F(34) | C-F10 | 322 | (pre) 5 9 ~ | KEY_F(35) | C-F11 | 323 | (pre) 6 0 ~ | KEY_F(36) | C-F12 | 324 | (pre) A | KEY_UP | CURU | 325 | (pre) B | KEY_DOWN | CURD | 326 | (pre) C | KEY_RIGHT | CURR | 327 | (pre) D | KEY_LEFT | CURL | 328 | (pre) F | KEY_END | END | 329 | (pre) G | KEY_NextScreen | PGDN | 330 | (pre) H | KEY_HOME | HOME | 331 | (pre) I | KEY_PrevScreen | PGUP | 332 | (pre) L | KEY_InsertHere | INS | 333 | (pre) M | KEY_NUMENTER | NUMENTER | 334 | (pre) N | KEY_F(2) | F2 | 335 | (pre) O | KEY_F(3) | F3 | 336 | (pre) P | KEY_PF1 | PF1 | 337 | (pre) Q | KEY_PF2 | PF2 | 338 | (pre) R | KEY_PF3 | PF3 | 339 | (pre) S | KEY_PF4 | PF4 | 340 | (pre) T | KEY_F(8) | F8 | 341 | (pre) U | KEY_F(9) | F9 | 342 | (pre) V | KEY_F(10) | F10 | 343 | (pre) W | KEY_F(11) | F11 | 344 | (pre) X | KEY_F(12) | F12 | 345 | (pre) Z | KEY_BACKTAB | S-TAB | 346 | (pre) l | KEY_PadComma | COMMA | 347 | (pre) m | KEY_PadMinus | MINUS | 348 | (pre) n | KEY_PadPeriod | NUMSTOP | 349 | (pre) o | KEY_Pad0 | NUM0 | 350 | (pre) p | KEY_Pad1 | NUM1 | 351 | (pre) q | KEY_Pad2 | NUM2 | 352 | (pre) r | KEY_Pad3 | NUM3 | 353 | (pre) s | KEY_Pad4 | NUM4 | 354 | (pre) t | KEY_Pad5 | CENTER | 355 | (pre) u | KEY_Pad6 | NUM6 | 356 | (pre) v | KEY_Pad7 | NUM7 | 357 | (pre) w | KEY_Pad8 | NUM8 | 358 | (pre) x | KEY_Pad9 | NUM9 | 359 | (pre) y | KEY_NUMENTER | NUMENTER | 360 | (pre) 1 z | KEY_BTAB | S-TAB | 361 | (pre) 2 z | KEY_InsertHere | INS | 362 | (pre) 3 z | KEY_HOME | HOME | 363 | (pre) 4 z | KEY_END | END | 364 | (pre) 5 z | KEY_PrevScreen | PGUP | 365 | (pre) 6 z | KEY_NextScreen | PGDN | 366 | (pre) 1 9 5 z | KEY_UNDO | UNDO | 367 | (pre) 2 1 4 z | KEY_HOME | HOME | 368 | (pre) 2 1 5 z | KEY_UP | CURU | 369 | (pre) 2 1 6 z | KEY_PrevScreen | PGUP | 370 | (pre) 2 1 7 z | KEY_LEFT | CURL | 371 | (pre) 2 1 9 z | KEY_RIGHT | CURR | 372 | (pre) 2 2 0 z | KEY_END | END | 373 | (pre) 2 2 1 z | KEY_DOWN | CURD | 374 | (pre) 2 2 2 z | KEY_NextScreen | PGDN | 375 | (pre) 2 2 4 z | KEY_F(1) | F1 | 376 | (pre) 2 2 5 z | KEY_F(2) | F2 | 377 | (pre) 2 2 6 z | KEY_F(3) | F3 | 378 | (pre) 2 2 7 z | KEY_F(4) | F4 | 379 | (pre) 2 2 8 z | KEY_F(5) | F5 | 380 | (pre) 2 2 9 z | KEY_F(6) | F6 | 381 | (pre) 2 3 0 z | KEY_F(7) | F7 | 382 | (pre) 2 3 1 z | KEY_F(8) | F8 | 383 | (pre) 2 3 2 z | KEY_F(9) | F9 | 384 | (pre) 2 3 3 z | KEY_F(10) | F10 | 385 | (pre) 2 3 4 z | KEY_F(11) | F11 | 386 | (pre) 2 3 5 z | KEY_F(12) | F12 | 387 | (pre) 3 2 4 z | KEY_F(13) | S-F1 | 388 | (pre) 3 2 5 z | KEY_F(14) | S-F2 | 389 | (pre) 3 2 6 z | KEY_F(15) | S-F3 | 390 | (pre) 3 2 7 z | KEY_F(16) | S-F4 | 391 | (pre) 3 2 8 z | KEY_F(17) | S-F5 | 392 | (pre) 3 2 9 z | KEY_F(18) | S-F6 | 393 | (pre) 3 3 0 z | KEY_F(19) | S-F7 | 394 | (pre) 3 3 1 z | KEY_F(20) | S-F8 | 395 | (pre) 3 3 2 z | KEY_F(21) | S-F9 | 396 | (pre) 3 3 3 z | KEY_F(22) | S-F10 | 397 | (pre) 3 3 4 z | KEY_F(23) | S-F11 | 398 | (pre) 3 3 5 z | KEY_F(24) | S-F12 | 399 | (pre) 4 1 4 z | KEY_C_HOME | C-HOME | 400 | (pre) 4 1 5 z | KEY_C_CURU | C-CURU | 401 | (pre) 4 1 6 z | KEY_C_PGUP | C-PGUP | 402 | (pre) 4 1 7 z | KEY_C_CURL | C-CURL | 403 | (pre) 4 1 9 z | KEY_C_CURR | C-CURR | 404 | (pre) 4 2 0 z | KEY_C_END | C-END | 405 | (pre) 4 2 1 z | KEY_C_CURD | C-CURD | 406 | (pre) 4 2 2 z | KEY_C_PGDN | C-PGDN | 407 | (pre) 4 2 3 z | KEY_PadComma | COMMA | 408 | (pre) 4 2 4 z | KEY_F(25) | C-F1 | 409 | (pre) 4 2 5 z | KEY_F(26) | C-F2 | 410 | (pre) 4 2 6 z | KEY_F(27) | C-F3 | 411 | (pre) 4 2 7 z | KEY_F(28) | C-F4 | 412 | (pre) 4 2 8 z | KEY_F(29) | C-F5 | 413 | (pre) 4 2 9 z | KEY_F(30) | C-F6 | 414 | (pre) 4 3 0 z | KEY_F(31) | C-F7 | 415 | (pre) 4 3 1 z | KEY_F(32) | C-F8 | 416 | (pre) 4 3 2 z | KEY_F(33) | C-F9 | 417 | (pre) 4 3 3 z | KEY_F(34) | C-F10 | 418 | (pre) 4 3 4 z | KEY_F(35) | C-F11 | 419 | (pre) 4 3 5 z | KEY_F(36) | C-F12 | 420 | (pre) 1 9 2 z | KEY_F(49) | F13 | 421 | (pre) 1 9 3 z | KEY_F(50) | F14 | 422 | (pre) 2 9 2 z | KEY_F(57) | S-F13 | 423 | (pre) 2 9 3 z | KEY_F(58) | S-F14 | 424 | (pre) [ A | KEY_F(1) | F1 | 425 | (pre) [ B | KEY_F(2) | F2 | 426 | (pre) [ C | KEY_F(3) | F3 | 427 | (pre) [ D | KEY_F(4) | F4 | 428 | (pre) [ E | KEY_F(5) | F5 | 429 | (pre) 0 q | KEY_PadComma | COMMA | 430 | (pre) 1 q | KEY_F(1) | F1 | 431 | (pre) 2 q | KEY_F(2) | F2 | 432 | (pre) 3 q | KEY_F(3) | F3 | 433 | (pre) 4 q | KEY_F(4) | F4 | 434 | (pre) 5 q | KEY_F(5) | F5 | 435 | (pre) 6 q | KEY_F(6) | F6 | 436 | (pre) 7 q | KEY_F(7) | F7 | 437 | (pre) 8 q | KEY_F(8) | F8 | 438 | (pre) 9 q | KEY_F(9) | F9 | 439 | (pre) 1 0 q | KEY_F(10) | F10 | 440 | (pre) 1 1 q | KEY_F(11) | F11 | 441 | (pre) 1 2 q | KEY_F(12) | F12 | 442 | (pre) 1 3 q | KEY_F(13) | S-F1 | 443 | (pre) 1 4 q | KEY_F(14) | S-F2 | 444 | (pre) 1 5 q | KEY_F(15) | S-F3 | 445 | (pre) 1 6 q | KEY_F(16) | S-F4 | 446 | (pre) 1 7 q | KEY_F(17) | S-F5 | 447 | (pre) 1 8 q | KEY_F(18) | S-F6 | 448 | (pre) 1 9 q | KEY_F(19) | S-F7 | 449 | (pre) 2 0 q | KEY_F(20) | S-F8 | 450 | (pre) 2 1 q | KEY_F(21) | S-F9 | 451 | (pre) 2 2 q | KEY_F(22) | S-F10 | 452 | (pre) 2 3 q | KEY_F(23) | S-F11 | 453 | (pre) 2 4 q | KEY_F(24) | S-F12 | 454 | (pre) 2 5 q | KEY_F(25) | C-F1 | 455 | (pre) 2 6 q | KEY_F(26) | C-F2 | 456 | (pre) 2 7 q | KEY_F(27) | C-F3 | 457 | (pre) 2 8 q | KEY_F(28) | C-F4 | 458 | (pre) 2 9 q | KEY_F(29) | C-F5 | 459 | (pre) 3 0 q | KEY_F(30) | C-F6 | 460 | (pre) 3 1 q | KEY_F(31) | C-F7 | 461 | (pre) 3 2 q | KEY_F(32) | C-F8 | 462 | (pre) 3 3 q | KEY_F(33) | C-F9 | 463 | (pre) 3 4 q | KEY_F(34) | C-F10 | 464 | (pre) 3 5 q | KEY_F(35) | C-F11 | 465 | (pre) 3 6 q | KEY_F(36) | C-F12 | 466 | (pre) 1 3 9 q | KEY_InsertHere | INS | 467 | (pre) 1 5 0 q | KEY_PrevScreen | PGUP | 468 | (pre) 1 4 6 q | KEY_END | END | 469 | (pre) 1 5 4 q | KEY_NextScreen | PGUP | 470 | ESC P | KEY_PF1 | PF1 | 471 | ESC Q | KEY_PF2 | PF2 | 472 | ESC R | KEY_PF3 | PF3 | 473 | ESC S | KEY_PF4 | PF4 | 474 +------------------+----------------+----------------+ 475 476 Where (pre) is either: 477 478 +------------------------------ 479 ESC [ - (0x1B 0x5B) or 480 ESC O - (0x1B 0x4F) or 481 ESC ? - (0x1B 0x3F) or 482 CSI - (0x9B) 483 +------------------------------ 484 485**man-end**********************************************************************/ 486