Special Keys and XFree86

Overview: Getting X to recognise special keys: Testing and Using the keys: Problems and Other thoughts:

About this page

I'm sure that I'm not the only person to have bought a nice new keyboard. You know - one of those that has lots of extra keys on them that are supposed to control multimedia functions, etc.

Now, whilst a part of me is boggling that we have come to a point where even a keyboard has to come with a driver CD, I can see that those extra keys can be useful. Heck, that's why I bought a keyboard with extra keys on it in the first place.

Shoving that driver CD in the drive isn't going to do me much good, though... What use are Windows drivers to me - I use Linux. So no pre-configured drivers for me, then.

On the other hand, I use Linux - and that makes all the difference in the world to me.

It's not hard to put those useful keys to a good use. The hardest part, as far as I was concerned, was finding out what was required to do it. That's why I wrote this page: to share what I found out and (hopefully) make things easier for anyone else in the same position I was.

I'm not going to go into any technical details - they're not really the point. The point, insofar as there is one, is that if I'd known just how easy this stuff was to set up I'd have done it long before I did.

So don't expect rigorous explanations or anything complex. Anyway, if you're up for the complex version then you probably already know where to look for it.

Back to contents...

How 'special' keys work

There's not a lot to say about this, to be honest. They pretty much work in the same way as the mundane, normal keys we take for granted. That's why we can make use of them so easily.

Some keyboards, of course, just have to be different. I have one, for instance, that has a whole bunch of special keys that work as expected and then another little group that try to be 'clever'. They do things like faking the keypresses needed to open the Windows Start menu and then make a selection from it. This can still be useful, it's just more bother to make it worthwhile.

Anyway, the point is that pressing a (normal) 'special' key does just the same as pressing, say, the space bar. The only difference is that X knows what the spacebar means but doesn't have a clue what the 'special' key means.

So how do 'normal' keys work, then?

When a key is pressed or released, the keyboard sends a keycode to the computer. This keycode is just a number that identifies the key that's been pressed (or released). Each key has a specific keycode. These codes can vary from keyboard model to model, but so long as the system knows what the keyboard means, that's not a problem. This is why you identified a keyboard 'mapping' (or whatever) when installing the system, by the way.

The 'special' keys generate keycodes that the system doesn't recognise, so it just ignores them. All we have to do is get the system to recognise those keycodes and we're sorted. Dead easy.

Back to contents...

Getting XFree86 to recognise the 'special' keys

It's all about the keycodes, baby

The first thing to do is to discover what keycodes the special keys actually send. We'll do this using a little wosname called xev whose main function is to spew out gallons of Really Really Useful Gibberish when things happen to it.

We're interested in the keycodes, so we'll use grep to filter just that information out. This is a bit kludgy, to be honest, but the chances are that it'll work just fine for you.

So, start up an xterm (or Konsole, gnome-terminal, or whatever if you're a KDE/GNOME fan). It's time to enter some shell commands... (Twilight Zone music optional).

Run the following command in your terminal:

    xev | grep keycode | uniq 
A little window will open that has a black square in it. Try not to let its inherent strangeness bother you - it's here to help. Click in it now, just to make sure that it has the 'input focus'. Don't worry, it won't bite.

Now press each 'special' key (just once!) in turn. Try to do them in a logical order, though, and only press the special keys. When you've done that, close the xev window.

As if by magic, some text will appear in the terminal window - one line for each key you pressed (and, just maybe, one initial line that corresponds to the Return key - you should ignore that one).

You might want to cut'n'paste this text into an editor (or whatever) because you're going to want to know what those numbers are. I went a stage further and took a (digital) photo of the keyboard and then 'wrote' on it. Whatever. The key thing (ho ho) is that you want to know which keycode belongs to which key.

If there's too many lines (and you didn't press any other keys) then your keyboard is generating multiple key-presses for some keys (like that one of mine that I mentioned). Either don't use the keys that do this (run xev | grep keycode to figure out which) and/or figure out how to use something like KDE to map them to something meaningful.

Back to contents...

XFree86 and keycodes

So now we know what the keycodes are, how do we explain our position (ie. "These keys are actual keys that you should pay attention to.") to X? For that matter, why do we have to explain it anyway?

Well, taking the second question first (and not just because I'm annoying like that), it's all down to the way that X actually handles the keyboard. Now, I know what you're thinking (and not just because I'm psychic) - "Here comes the horrible part." Well, you're sort of right, but don't worry about it, or about me knowing what you're thinking (I don't. I lied about being psychic).

XFree86 (as used in Linux) is a little bit ornery when it comes to keys. Its policy, basically, is that it'll only recognise keys that it already knows about and it's not interested in what we have to say about the matter. When it was made it was told what keys it would be expected to recognise... and that's that.

Fortunately, we're not quite as screwed as it might seem. Okay, so we have to work within XFree86's fairly rigid idea of a keyboard, but luckily for us that includes such wonders as function keys right up to F35.

So, what we'll do is to make our 'special' keys be those function keys. It doesn't have to be like that but it's probably the most logical and neat option available to us. So that's cool.

If you really (and I mean really) care, take a look at /usr/include/X11/xeysymdef.h to see what keys are actually available). Better yet, don't - just trust me on this one: the function keys are where it's at.

As for the first question... Nuts. I hoped you'd forgotten about that.

Just kidding...

Back to contents...

Actually, it's all about .Xmodmap, baby

We know the keycodes. We know that we want them to be function keys. If you're like me, you've probably only just realised that it'd be a good idea to decide which special keys are going to be which function keys. Go on, do it - it'll make you feel better after that last section.

So you've got a list of keycodes and you know which function keys you want them to be... It's time to tell X about it, which is where a file called .Xmodmap in your home directory comes in. You might, or might not, already have such a file - it doesn't actually matter. What we're going to do is to get X to tell us what the current one looks (or would look) like, then we'll modify it to add our 'special' keys.

In your terminal window, run this command:

    xmodmap -pke >Xmodmap.current 
That will create a file called Xmodmap.current, which it'd be a great idea to open in a text editor, so do just that.

What we want to do now is to assign a name to each of the special keys (without a name, the key is pretty much useless, you see). Fortunately, this is as easy as just tacking the name we want onto the appropriate "keycode NNN =" line in the file. The names we'll use are F13 to F35.

For each of your 'special' keys, find the corresponding  keycode NNN =  line in the file and put the function key name that you've decided on that line.

So if, for example, the 'mute' key generates keycode 160 and you want it to be F20 then you'd find the

    keycode 160 =
line and change it so that it reads
    keycode 160 = F20

Save your ammended Xmodmap.current file. The more cautious amongst you may wish to tack all the keycode info from step 1, and the mapping to F-keys you decided on, onto the top of the file and save it somewhere, just in case. That's cool: just remember to put !s at the start of any lines you add - that way the file will still be functional.

Back to contents...

These things are sent to try us

It's time to test the mappings we've just explained (in intimate detail) to XFree86. Incidentally, I don't recommend crossing your fingers at this point - it can actually make things go icky. If that bothers you, lobby your keyboard manufacturer to support superstitous use in future models.

Let's make XFree86 know what we want. Run the following command in your terminal:

    xmodmap Xmodmap.current
Now, lets' see what's changed. Run this in your terminal:
    xev | grep keycode
Click in the xev window (just like before) and then press the 'special' keys. If all is well, you should get the same sort of keycode lines as before, but this time the cryptic gunk in brackets won't say keysym 0x0, "" but will say something like keysym 0xffd1, F20. Don't worry about the keysym bit - just feel smug that you've persuaded XFree86 that your 'special' keys are, in fact, plain ol' function keys.

Assuming that all went OK, you'll probably want to make these changes 'permanent' (by which I mean that they'll be applied every time you use the machine). We can do that by copying the Xmodmap.current file as .Xmodmap. There's probably a gazillion ways of achieving this, but since we've got a terminal window open anyway and we're feeling all smug and clever, let's do it the old fashioned "we didn't have graphical file managers when I was young..." way. Run the following command in your terminal:

    cp Xmodmap.current ~/.Xmodmap

Step 4: There is no step 4

Sorted. You can now use the keys as if they were normal ones.

And you thought that configuring XFree86 was going to be impenetrably complex and downright evil, didn't you?

Back to contents...

Things to do in XFree86 when you're F26

Of course, configuring XFree86 is only the start... OK, so it was a fairly major hurdle, but what we really want is for F31 to actually do something useful.

There's plenty of ways to make that happen...

Many applications will let you assign keyboard shortcuts to commands, etc. Maybe you'd like XMMS to use the multimedia keys? And so on.

Desktop environments like KDE will let you set keys up to do all sorts of things. Take a look the KDE Control Center's 'Regional & Accessibility' section at the Keyboard Shortcuts stuff. The 'menu editor' (right-click on the K menu icon) will let you assign keys to start applications - like maybe the 'Mail' key on your keyboard should start KMail...

Maybe you want finer control over your 'special' keys. Perhaps they have become precious to you and you don't want to let the nasty little hobbitses get their hairy little hands on them... Well, you could check out things like speckeysd.

Personally, I went down the speckeysd route - but then that's because I want to do things my way, and that includes things like modifying someone else's keyboard daemon program to work the way that I want it to.

Back to contents...

Things that make you go "Aaargh."

I hope it all worked out for you, I really do. Something this simple really shouldn't cause too much bother, but life so seldom seems to play fair.

The number one problem I ran into was that keyboard which tried to be too clever. Now, as it happens, KDE helped me out with that one. Since the 'calculator' key sent shift-alt-C (or something like that), I just set that as the shortcut for kcalc. Easy. Your milage may vary, of course.

Number two on my list of niggles is that I use several keyboards, some of them even on different machines. Now, if you're doing this for more than one machine/keyboard (or you're changing keyboard) then it's probably a good idea to stick to the same mappings. Ie. if 'Mute' is F20 then make it F20 for all the keyboards. The advantages of this should be obvious, I hope.

Not all keyboards are happy about combining 'modifier' (ie. shift, alt, etc) with special keys. One of mine won't recognise Control-Shift-Alt-<key>, for instance. Your milage, again, may vary.

Oh, and what I've blithely been referring to as Linux should more properly be referred to as GNU/Linux. This really does make some people go "Aaargh" and, to be fair, they do have a point.

Back to contents...


Now would be a good time to drink a beverage of your choice and raise a toast to all the fine folks who've made it possible to do what we've just done.


Back to contents...

If you want to contact me about this stuff, drop a mail to musus.speckeys@verelanthe.co.uk. Spiders and other automated systems need not apply - I already have enough inanimate/virtual penfriends and, although I find your interest touching, I just can't fit any more into my life right now. Sorry, but that's how it is.