Hi Rob,
Sorry for the late reply, I've been rather busy recently.
Unfortunately, there isn't a great deal of documentation for most terminal emulators. One way of figuring out what capabilities a terminal provides is by simply running 'cat' on the command line and pressing keys. When trying to figure out if the terminal sends different key codes with and without pressing shift for example, first press the key without shift, then try again while holding shift down. If you see the same thing twice, the terminal doesn't send a different key code. For example, for the right arrow key in xterm, I get the following:
$ cat
^[[C^[[1;2C^C
To explain what you see in more detail: pressing right arrow results in ^[ (which is displayed for the escape byte 0x1B), and then the characters [ and C. Then I pressed shift + right arrow, which results in ^[, [, 1, ;, 2, and finally C. Then I pressed ctrl+C to end the program, resulting in the ^C.
This doesn't always present the entire story though. Most terminal emulators have an extra mode, called keypad transmit mode, which changes the key codes sent by some or all of the keys. To test this, you can use the tput program. If I do the same as above, but using the tput program to switch to keypad transmit mode, we get the following:
$ tput smkx
$ cat
^[OC^[[1;2C^C
$ tput rmkx
As you can see, the code for the right arrow key changed. The second tput command is to make sure we set the terminal back to its original settings.
With this, you should be able to figure out exactly what key codes are produced.
There is, however, one more thing to be aware of. To determine the terminal type that a program is talking to, the terminal sets the value of the environment variable TERM. There are unfortunately quite a few terminal emulators which set the value xterm or similar, but which aren't fully compatible with xterm. Particularly in the generated key codes there can be significant differences. There are reasons for doing this (which are too long to explain here), but it is not a great practice. Putty in particular used to do this. So check this variable as well.
Cheers,
Gertjan