Nivo2vnc Keymap Format
From Ndiyo
This page describes the file format used for nivo2vnc keymap files, hopefully allowing others to specify new keymap files for nivo2vnc when the shipped files are not enough and/or need modifying.
Contents |
[edit] Background
Keyboards generally do not return useful information that users would understand. When a key is pressed a numeric code is sent from the keyboard to the computer (or in our case, to the nivo) that has no relation to what is printed on the key the user just pressed. Thus any software that manages a keyboard at the hardware level, like nivo2vnc, needs to convert these numbers, referred to as key codes here, into something more useful. In the case of nivo2vnc it must convert them in X11 key symbols, which we'll explain later on, but basically these are symbols that the VNC server knows how to turn into useful things for the user.
For example, when on a UK keyboard you press they 't' key, they keyboard generates the key code 44. nivo2vnc has to take this number, look it up in a table, and convert it to a symbol represing t that a VNC server will understand. To make matters worse, different keyboards will use the same key code to mean different things. On a UK keyboard key code 30, in combination with the shift key, will indicate a double quote symbol, but on a US keyboard indicate the at symbol.
The VNC server, as mentioned already, understands X11 key symbols. These are symbols that are converted to different numbers but have a human understandable name. For example, XK_t and XK_T symbols represent lower and upper case t respectively. There are also symbols for non visible characters such as XK_Alt_L for the left hand alt key on the keyboard, and XK_space for the space key.
Because each keyboard may use the same key codes to represent different symbols nivo2vnc needs a different set of key code to VNC key symbols for each one. The rules for doing each conversion are stored in a keymap file. For example, we have uk.kmap and us.kmap that contail the rules for converting the key codes returned by UK and US keyboards repsectively into the correct VNC symbols.
One last complication is that some key codes are flagged as extended by the keyboard. For example, the keys block of keys on a UK keyboard that sit between the main set of keys and the numeric key pad containing insert, home, etc. are all flagged as extended keys.
[edit] How key codes are handled in nivo2vnc
It helps a little to understand how nivo2vnc handles a key code when it receives it. nivo2vnc maintains a series of tables that each contain an entry per key code containing either an invalid symbol or a recognised VNC key symbol. The first table represents the base state of the keyboard with not modifiers pressed. The next represents what happens to the key codes when the shift key is pressed, another with the caps lock key, and so on. nivo2vnc will try these tables in turn depending on the state of any meta keys, and stopping when it either finds a VNC key symbol, or runs out of tables.
For example, if the skift key is held down and the F11 key is pressed, then under the standard UK keymap the following will happen. nivo2vnc will look in the table relating to the skift key being set, where it will find no valid VNC key symbol for that entry (as none was specified in the keymap file), so it will then go on to check the base table, where it will find the VNC key code for F11, which is then passed on to the VNC server.
With this arrangement if there's not entry for a given meta key then the base table will always be used. If this is undesirable then there is a VNC key symbol that can be used to change this behaviour, as discussed later on.
[edit] Finding keyboard key codes
Before you can create or modify a keymap file, you need to know what key code corresponds to a given key on the keyboard. nivo2vnc can be made to print out on the console key codes when invoked with the -reportkeycodes option. When you press a key it will print out the key code related to that key so you can use it when making/editing key map files.
[edit] Finding VNC (X11) key symbols
The VNC server expects to receive notification of key presses in the same format used by the X11 windowing symbol; nivo2vnc has to take the keyboard generated key codes and convert them into this format. The X11 symbols are numeric values, but have a defined human readable string name, and it is this name that nivo2vnc uses in the keymap file. The symbol names all start with the prefix 'XK_' and then a name describing the key. For example, XK_t is a lower case letter t, XK_T is the upper case version, XK_space is the space character and so on.
A full list of X11 symbol definitions can be found in the X11 key symbol file.
[edit] Keymap file format
Keymap files are plain text files. For each key code that is of interest they contain a like that lists the key code, one or more X11 key symbols that it should generate, and some special extra information, such as whether is should respond to caps lock or such. In addition, the file contains some information describing what key codes correspond to state keys such as shift and caps lock.
Here is the first few lines from the UK keymap file that comes with nivo2vnc:
# UK keyboard map
left_shift = 0x12
right_shift = 0x59
caps_lock = 0x58
num_lock = 119
scroll_lock = 126
1 XK_F9
3 XK_F5
4 XK_F3
5 XK_F1
6 XK_F2
7 XK_F12
9 XK_F10
...
You can find the keymap file in full here: Media:uk-sample.kmap Here is a US keymap: Media:us-sample.kmap and a German one: Media:de-sample.kmap. They may not be complete, but will give you a good starting point!
The ordering of the lines is not important to nivo2vnc, blank lines are ignored, and the file can contain comments, which start with a # and run to the end of the line. The rest of the lines consist of either state key assignments or key code map lines, of which there can be at most one per line. Intergers are accepted as eithe decimals or, if prefixed by 0x as hexidecimal.
[edit] State key assignments
State key assignments are used to tell nivo2vnc which key codes map to the state keys on the keyboard that can cause the results of kepresses to change. The format of each state assignment is:
STATE_KEY = keycode
Where STATE_KEY is one of caps_lock, num_lock, left_shift, right_shift, or scroll_lock, and keycode is an integer.
[edit] Key code map lines
Key code lines follow a variety of formats, depending on the complexity of the key they're mapping. The basic form is just a key code followed by a keysymbol:
keycode X11_SYMBOL_NAME
For example, to bind the letter t to key code 79 we would write:
79 XK_t
If the key reacts to a shift character then this is placed after the standard key symbol for the key code. In the form:
keycode X11_SYMBOL_NAME X11_SYMBOL_NAME
Again, for the same example above we might do:
79 XK_t XK_T
This says that when nivo2vnc sees key code 79 it should generate a 't' for the normal case but 'T' if shift is pressed.
If they key in question should react to caps lock as a form of sticky shift then we follow the key with the special word 'caps', in the format:
keycode X11_SYMBOL_NAME X11_SYMBOL_NAME caps
Once again, for our example, we would write:
79 XK_t XK_T caps
Now the key code 79 will generate a 'T' if the caps lock key is on.
Similarly, there is a format to specify what num lock should do. For keys that use num lock they don't generally respond to shift, so the format is to specify just the default behaviour and the num lock behaviour after it like so:
keycode X11_SYMBOL_NAME X11_SYMBOL_NAME num
An example of this might look like:
42 XK_home XK_7 num
In this example the key code 42 will normally generate a home key event, but when num lock is on it will generate the character 7.
The final example is to handle extended keys, as mentioned before. If the keyboard generates an extended key then you need to specify the word 'extended' before the entry, like so:
extended keycode X11_SYMBOL_NAME
For example:
extended 118 XK_end
This is all the current valid set of entries, though this may grow as requirements dictate (in which case this document will be updated).
[edit] Notes
Some times there are times when you don't want to let nivo2vnc fall through it's tables. For example, extended shift is generally not used, but can occurin obscure situations. When it does it should generally be ignored. But unless there is an entry in the extended table to tell nivo2vnc to ignore it then nivo2vnc will find no extended mapping, and this use the base mapping (generate a shift key) and this is wrong.
To handle cases like this an entry should be created to refer to the symbol XK_VoidSymbol, which will not cause an event on the VNC server but cause nivo2vnc to stop looking for something to map to. For example, in the UK keymap file there is the following entry to catch this:
extended 18 XK_VoidSymbol
