Using Xmodmap (the old way)

The first step is to install the xmodmap and xev programs. The N800 versions of the programs may be found here.


xev is a command-line program which pops up a simple window that traps and prints out all the events (cursor movement, keyboard taps, etc.). For example, if you fire it up, type "N", and then close the window, you'll get back something that says "KeyRelease event .... keycode 57 (keysym 0x63, n) ....". This indicates that the key you pressed is keycode 57 (in decimal), and that it's associated with the "key symbol" (keysym) "n". The crucial thing to use xev for is to identify the keycodes of the control, command, option/alt, fn, eject, and various function keys. Unfortunately, you'll need them in hexadecimal for the next step, rather than decimal. To avoid having to convert, here are the important ones pre-converted for you:

left alt0x40 (likely mapped to "Alt_L" keysym)
left command0x73 (likely mapped to "Super_L" keysym)
right command0x74 (likely mapped to "Super_R" keysym)
right alt0x71 (likely mapped to "Alt_R" keysym)

You can refer to other keys by their "keysym" key symbols: a, b, c, 4, etc. Some special keysym names: minus, equal, comma, period, slash, backslash, bracketleft, bracketright, apostrophe, semicolon, space, grave (for the ` key), Return, Tab, BackSpace, Caps_Lock, Up, Down, Left, Right (note the capitalization and spelling).

Notice the key that's missing: the fn key. This key does not generate X events, and so is, as far as we're concerned, totally dead. You can't use it.


Now we move on to xmodmap, an old X11 program which remaps keys to various functions. xmodmap responds to commands which you can issue either one-by-one on the command line (xmodmap -e "put command here") or by sticking them, one to a line, in a file and calling xmodmap filename). Traditionally the filename you use is called .xmodmap, stored in your home directory, since in a more typical X windows scenario it'd get called automatically: but as maemo doesn't do that, you can call it whatever you like since you'll have to manually call the xmodmap program anyway. The important commands are:

  1. keysym key symbol = keymapping
    Indicates that the key presently associated with key symbol should be used with the given keymapping. A keymapping is up to four key symbols representing the (1) standard keypress, (2) shifted keypress, (3) "mode switched" keypress (a second shift key, what Mac users would call "option" and european PC users would call "AltGr") and (4) shifted+mode switched keypress. You don't have to provide all four: for example, you can provide just the first two if you like.

    keysym equal = equal plus notequal plusminus
    keysym z = z Z Greek_omega Greek_OMEGA
    keysym a = a A agrave Agrave
    keysym j = j J

  2. keycode key code = keymapping
    Same as the keysym command, only using the key associated with a given key code. This is useful for keys which don't presently have associated key symbols. Keep in mind that the key code has to be in hexadecimal.

    keycode 0xfd = Page_Down
    keycode 0x5f = End twosuperior threeighths onehalf

  3. clear modifier
    Eliminates all keys from being associated with a given modifier key type. There are eight modifier key types: Shift, Lock, Control, Mod1, Mod2, Mod3, Mod4, Mod5. You can set Mod1...Mod5 to whatever modifier functions you want: for example, associate mod5 with mode-switch ("option" or "AltGr"), and I associate Mod1 with Alt. The idea here is that multiple keys can be associated with the same modifier function (for example, your two shift keys).

    clear Mod1

  4. add modifier = key symbol
    Adds the key associated with key symbol to be a modifier of the given type.

    add Control = Super_L
    add Mod1 = Alt_R

  5. remove modifier = key symbol
    Removes the key associated with key symbol to be a modifier of the given type.

    remove Control = Control_R

  6. ! comment
    A comment. Blank lines are also acceptable.

    ! This is a comment line
    !!!! This is a more emphasized comment line :-)

Here's an excellent tutorial on xmodmap.

You can find all the key symbol names in X11's keysymdef.h file. Strip off the "XK_" to get the key symbol name. Here's a page with unicode symbol equivalents for all of the printable key symbols. Sadly, Nokia's fonts have a dearth of available symbols, though it does appear that they contain at least the union of Microsoft's Windows-1252 (so-called "ANSI"), Microsoft's Windows Glyph List 4, and Apple's MacRoman character sets (except U+F8FF, the Apple Logo).

My Personal .xmodmap File

I already have a working .xmodmap file. Its goals were:

  1. Because Nokia's virtual keyboard refuses to come up even when you try to force it (see below), we should include all the bindings from Nokia's standard "symbols" in their virtual keyboard. (I've got all but one, the "per mille" sign: ‰ ).
  2. Include Italian accents (I'm studying Italian).
  3. Organize bindings largely in the same way the Macintosh does it, with a shift and an option key, and bindings in more or less the same place. To some degree I'm restricted by Nokia's poor fonts and not able to provide all the bindings I'd like.
  4. Include page up, page down, home, and end, but not in the standard Mac cursor location -- put them somewhere more useful (I use F10, F11, F12, and Eject).
  5. Include bullets and arrows.

Here's the file. Also, here is a highly useful PDF diagram of my mappings (check it out!), and the OmniGraffle file in case you want to modify it.

Some notes:

  1. Left Alt/Option operates like a Mac Option key (that is, X11's "mode switch").
  2. Because so many Nokia applications have ctl-x for cut, etc., I've mapped Left Command (the key right next to the space bar) to also be a control key along with ctrl. This helps Mac people used to typing Command-x etc.
  3. Right Command has been mapped to the "Compose" key, which ordinarily would allow you to create all sorts of characters (see here). Sadly, Nokia appears to not support this, so it's presently a dead key until I decide what to do with it.
  4. Right Alt has been mapped to an actual "Alt" key in the traditional sense.
  5. Fn is, as discussed, dead.
  6. Shift-Return is keypad-enter (just like on the Mac).
  7. Shift-Delete is keypad-delete.
  8. Shift-Tab is reverse-tab.
  9. See above about page-up/page-down/home/end

Using Your .xmodmap File

Traditionally, your xmodmap commands are stored in a file called .xmodmap in your home directory. On the maemo wiki there are instructions to modify your real-af-startup file to call xmodmap. It doesn't work, so don't bother. Instead, you can install the Osso Statusbar CPU applet. This applet allows you to, among other things, set up shell commands to issue from the applet's menu. I have one called "Bluetooth Bindings" which issues the command xmodmap .xmodmap That does the job nicely.

More Fun Stuff

The maemo wiki also describes how you can use the kbdconfig file to tell the window server to fire up various applications etc., including popping up the virtual keyboard when it's convenient. Though the procedure works for other functions, it does not work for popping up the virtual keyboard: OS2007 has broken that functionality.

The general idea is to create a file called /home/user/.matchbox/kbdconfig which maps certain keystrokes to various actions, one to a line. Mine simply says this:

This maps Control-Escape to closing windows, and Control-Tab to paging through windows, similar to Command-Tab on the Mac.