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.

Table 4-6. BX_KEY constants

BX_KEY constant Keyboard Symbol
BX_KEY_CTRL_L left Ctrl
BX_KEY_SHIFT_L left Shift
BX_KEY_F1 F1
BX_KEY_F2 F2
BX_KEY_F3 F3
BX_KEY_F4 F4
BX_KEY_F5 F5
BX_KEY_F6 F6
BX_KEY_F7 F7
BX_KEY_F8 F8
BX_KEY_F9 F9
BX_KEY_F10 F10
BX_KEY_F11 F11
BX_KEY_F12 F12
BX_KEY_CTRL_R right Ctrl
BX_KEY_SHIFT_R right Shift
BX_KEY_CAPS_LOCK CapsLock
BX_KEY_NUM_LOCK NumLock
BX_KEY_ALT_L left Alt
BX_KEY_ALT_R right Alt
BX_KEY_A A
BX_KEY_B B
BX_KEY_C C
BX_KEY_D D
BX_KEY_E E
BX_KEY_F F
BX_KEY_G G
BX_KEY_H H
BX_KEY_I I
BX_KEY_J J
BX_KEY_K K
BX_KEY_L L
BX_KEY_M M
BX_KEY_N N
BX_KEY_O O
BX_KEY_P P
BX_KEY_Q Q
BX_KEY_R R
BX_KEY_S S
BX_KEY_T T
BX_KEY_U U
BX_KEY_V V
BX_KEY_W W
BX_KEY_X X
BX_KEY_Y Y
BX_KEY_Z Z
BX_KEY_0 0
BX_KEY_1 1
BX_KEY_2 2
BX_KEY_3 3
BX_KEY_4 4
BX_KEY_5 5
BX_KEY_6 6
BX_KEY_7 7
BX_KEY_8 8
BX_KEY_9 9
BX_KEY_ESC Esc
BX_KEY_SPACE SpaceBar
BX_KEY_SINGLE_QUOTE '
BX_KEY_COMMA ,
BX_KEY_PERIOD .
BX_KEY_SLASH /
BX_KEY_SEMICOLON ;
BX_KEY_EQUALS =
BX_KEY_LEFT_BRACKET [
BX_KEY_BACKSLASH \
BX_KEY_RIGHT_BRACKET ]
BX_KEY_MINUS -
BX_KEY_GRAVE `
BX_KEY_BACKSPACE BackSpace
BX_KEY_ENTER Enter
BX_KEY_TAB Tab
BX_KEY_LEFT_BACKSLASH left \
BX_KEY_PRINT PrintScreen
BX_KEY_SCRL_LOCK ScrollLock
BX_KEY_PAUSE Pause
BX_KEY_INSERT Ins
BX_KEY_DELETE Del
BX_KEY_HOME Home
BX_KEY_END End
BX_KEY_PAGE_UP PageUo
BX_KEY_PAGE_DOWN PageDown
BX_KEY_KP_ADD Numeric Keypad +
BX_KEY_KP_SUBTRACT Numeric Keypad -
BX_KEY_KP_END Numeric Keypad 1
BX_KEY_KP_DOWN Numeric Keypad 2
BX_KEY_KP_PAGE_DOWN Numeric Keypad 3
BX_KEY_KP_LEFT Numeric Keypad 4
BX_KEY_KP_5 Numeric Keypad 5
BX_KEY_KP_RIGHT Numeric Keypad 6
BX_KEY_KP_HOME Numeric Keypad 7
BX_KEY_KP_UP Numeric Keypad 8
BX_KEY_KP_PAGE_UP Numeric Keypad 9
BX_KEY_KP_INSERT Numeric Keypad 0
BX_KEY_KP_DELETE Numeric Keypad .
BX_KEY_KP_ENTER Numeric Keypad Enter
BX_KEY_KP_MULTIPLY Numeric Keypad *
BX_KEY_KP_DIVIDE Numeric Keypad /
BX_KEY_UP UpArrow
BX_KEY_DOWN DownArrow
BX_KEY_LEFT LeftArrow
BX_KEY_RIGHT RightArrow
BX_KEY_WIN_L Left Windows
BX_KEY_WIN_R Right Windows
BX_KEY_MENU Menu
BX_KEY_ALT_SYSREQ Alt-Sysreq
BX_KEY_CTRL_BREAK Ctrl-Break
BX_KEY_INT_BACK Internet - back
BX_KEY_INT_FORWARD Internet - forward
BX_KEY_INT_STOP Internet - stop
BX_KEY_INT_MAIL Internet - mail
BX_KEY_INT_SEARCH Internet - search
BX_KEY_INT_FAVInternet - favorites
BX_KEY_INT_HOME Internet - home
BX_KEY_POWER_MYCOMP Powerkeys - my computer
BX_KEY_POWER_CALC Powerkeys - calculator
BX_KEY_POWER_SLEEP Powerkeys - sleep
BX_KEY_POWER_POWER Powerkeys - power
BX_KEY_POWER_WAKE Powerkeys - wake