5.2.17 Handling unmapped keys

For most every modern-day terminal, you’ll find that if you get the TERM environment variable set correctly, then each of the function keys on the keyboard will be interpreted as a key code.

But in rare circumstances, you may find that a function key on your keyboard is not being mapped to a keycode. As an example, on some keyboards there is a special “menu” key in between Ctrl and Alt. On my keyboard, pressing “menu” returns “ESC [ 2 9 ~”, which getch returns as a that 5 separate characters, instead of a single keycode like KEY_MENU.

When this happens, the problem is most often that you’ve set your TERM incorrectly. Next most likely is that your terminfo or termcap database is out of date. That is where you should first seek your solution.

But, if that fails, and you need a quick-and-dirty workaround, define-key can help. It lets you map an escape sequence to a key code.

Continuing my example, if I choose to map this menu key to a keycode, I can choose the keycode of a key that that doesn’t appear on my keyboard, like KEY_FIND, and associate with that string, using define-key.

Procedure: define-key defn keycode

This procedure defines a new, custom keycode. When the string in defn is input, routines like getch will return the keycode instead, if the keypad is on. If defn is an empty string, the keycode will be cleared.

If keycode is an existing keycode, its defn replaces its previous definition.

The return value is #t on success.

For the example, I can use the command

 (define-key (string #\esc #\[ #\2 #\9 #\~) KEY_FIND)

From that point on, when the Menu key is pressed, getch will return the integer KEY_FIND.

Procedure: key-defined defn

If the string defn is a character sequence that is bound to a keycode, that keycode is returned. Otherwise #f is returned.