4.4. How to write your own keymap table

Christophe Bothamy wrote the keymapping code for Bochs, and provided this documentation for how to create new keymaps. Keymapping was first implemented for X windows only, so there are many references to X-specific values in this section. In Bochs 2.0 keymapping is also available for SDL (Linux port) and wxWidgets (wxGTK port).

  The standard US Keyboard looks like this:

          -------------------------------------------
  Top row Esc F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12
          -------------------------------------------
  2nd row ` 1 2 3 4 5 6 7 8 9 0 - = \ Back
          -------------------------------------------
  3rd row Tab Q W E R T Y U I O P [ ] Enter
          -------------------------------------------
  4rd row Caps A S D F G H J K L ; '
          -------------------------------------------
  5rd row lShift l\ Z X C V B N M , . / rShift
          -------------------------------------------
  6rd row lCtrl lAlt Space rAlt rCtrl
          -------------------------------------------

Each key of the US keyboard maps to a Bochs constant named BX_KEY_symbol. You can find the current list of BX_KEY_symbol in the BX_KEY table, below. Please note that there is only one BX_KEY_symbol for each physical key.

Now, for each key of the US keyboard, look at which symbols you can type on your real keyboard. Each symbol maps to a X-windows XK_symbol constant. In X11/keysymdef.h, you will find the list of all possible XK_symbol on your system. Alternatively, you can use a small utility called "xev" that prints out the symbol names of a pressed key. Note that the symbol name given by xev does not contain the XK_ prefix. Don't forget to add a line for every symbol you can type on each key. For the key BX_KEY_A, you can type both lowercase 'a' and uppercase 'A', so you would need two different entries.

You can then create your own map file. Keymap files are found in the "gui/keymaps" directory in the source code, or in the "keymaps" directory in binary releases. Look at the existing keymap file as an example, and create a file containing one line for each symbol. The first column tells what key or combination of keys can be used to produce a given symbol. The second column is the ASCII equivalent for that symbol, or a special keyword (none, space, return, tab, backslash, or apostrophe). The third column is the X windows keysym for that symbol.

For example :

BX_KEY_0                                      '0'        XK_0
BX_KEY_1                                      '1'        XK_1
BX_KEY_2                                      '2'        XK_2
BX_KEY_0+BX_KEY_SHIFT_L                       ')'        XK_parenright
BX_KEY_1+BX_KEY_SHIFT_L                       '!'        XK_exclam
BX_KEY_2+BX_KEY_SHIFT_L                       '@'        XK_at
BX_KEY_A                                      'a'        XK_a
BX_KEY_B                                      'b'        XK_b
BX_KEY_A+BX_KEY_SHIFT_L                       'A'        XK_A
BX_KEY_B+BX_KEY_SHIFT_L                       'B'        XK_B
BX_KEY_TAB                                    tab        XK_Tab
BX_KEY_ENTER                                  return     XK_Return
BX_KEY_F1                                     none       XK_F1
BX_KEY_F2                                     none       XK_F2
BX_KEY_F3                                     none       XK_F3

Now that there are several keymap files in the Bochs distribution, it is easiest to copy an existing keymap and follow the examples you see. When it works, be sure to send it to the mailing list or post it on Source Forge so that we can include it in the next release. You may need to look up some of your country specific X11 symbols in X11/keysymdef.h.