Enable Your Multimedia Keyboard

Enable Your Multimedia Keyboard

Make the most of the additional keys on your multimedia keyboard.

When you press a key on your keyboard, it detects the key press and sends a corresponding "keycode," which is then matched using a lookup table that converts the keycode to a character. However, many modern keyboards have a variety of additional keys that typically return keycodes that aren't included in the standard lookup table, so Linux doesn't know what to do with them.

In Ubuntu, you can use these extra keys as shortcuts for such tasks as opening email, launching a browser, or changing audio volume. With the help of GNOME Preferences, you can configure some special actions, but for maximum flexibility, Hotkeys lets you completely customize shortcut-key behavior.

Assign GNOME Keyboard Shortcuts

If you want to create shortcuts only for basic tasks, start by opening SystemKeyboard Shortcuts to see a list of predefined actions, as shown in Figure.

Use System Preferences Keyboard Shortcuts to assign common actions to keys

Click on the shortcut entry for an action and then press the key combination you want to associate with it. For example, if you want F7 to launch your web browser, click the shortcut entry next to "Launch web browser" and then press F7. Changes are applied immediately, so there is no need to save the new settings.

The built-in GNOME keyboard-shortcut settings include only predefined actions, so if you want to launch a custom script or an arbitrary program, you'll need something more flexible, such as Hotkeys.

Hotkeys

Hotkeys is a program that intercepts keycodes from multimedia keys and maps them to specific events. The events are totally user-definable, so you can configure keys to run programs or even custom scripts. For example, in addition to basic actions such as controlling volume, opening email, or launching a browser, you can set keys to do things such as initiate an SSH connection to a remote machine, change your desktop background, launch OpenOffice.org, start a backup, or pretty much anything else you can think of.

Hotkeys is in the universe group of extra software that's not officially supported by Ubuntu, so if your computer is not set to use software from universe, you may need to "Modify the List of Package Repositories" [Hack #60] before you can install it:

$ sudo apt-get install hotkeys
            

Understand Hotkeys configuration parsing

Because Hotkeys uses a two-stage configuration system, it may not be immediately obvious what you need to change to customize commands, and sometimes the changes you make don't seem to be applied. However, it all makes perfect sense once you understand how Hotkeys parses its configuration files.

The first stage is the keyboard definition file, which does two kinds of mapping: indirect conversion of keycodes to predefined events, and direct conversion of keycodes to user-defined commands. The second stage is the Hotkeys configuration file, which does a second mapping for predefined events, associating them with explicit commands.

This approach allows Hotkeys to map the keycode generated by the Favorites button on your keyboard with a predefined Favorites event using the keyboard definition, and then map the Favorites event to a specific command such as gnome-moz-remote --remote=openBookmarks in the Hotkeys configuration. That way, the majority of standard actions can be defined in the Hotkeys configuration, and making them work with a different keyboard is just a matter of switching the keyboard definition file.

However, you can also define custom events right in the keyboard definition. This approach maps a keycode straight to a command directly without referring to the Hotkeys configuration file at all. This is how you will probably define more unusual actions, such as launching a terminal and automatically opening an SSH session to a predefined host.

Set keyboard type

The first step to configuring Hotkeys is to define your keyboard type so the correct keycodes can be recognized. Hotkeys comes with sample configurations for a variety of standard keyboard types, so if you're lucky, you may be able to just select your keyboard from the samples and everything will just work. To see a list of supported keyboard types, run:

$ hotkeys -l
               

Then you can specify one of those keyboard types when you launch Hotkeys using the -t flag.

But what if your keyboard isn't in the list of supported models?

No problem. You can define a custom keyboard type by copying the /usr/share/doc/hotkeys/sample.xml sample file into a .hotkeys directory inside your home directory, and you can then customize the entries in it to match the keycodes returned by your keyboard:

$ mkdir ~/.hotkeys
$ cp /usr/share/doc/hotkeys/sample.xml ~/.hotkeys/mykeyboard.def
               

Be sure to check over the XML in this file. At the time of this writing, the <description> tag at the end of the file was improperly closed (it should be </description>).

If you then run hotkeys -l again, you'll see there is now a keyboard type of mykeyboard at the top of the list in addition to all the default keyboards. You can later refer to your custom keyboard layout by name when launching Hotkeys.

The sample file is commented, but it may make more sense if you have a look at one of the keyboard definition files provided in /usr/share/hotkeys/ to see how they are structured. You may even prefer to start by copying one of the supplied definitions instead if you find one that is close to what you want.

To set up the file, you will need to know the exact keycodes for the various multimedia keys you wish to use. You can detect keycodes using a utility called xev ("X events"), which does nothing but watch input devices including the mouse and keyboard and display the codes of any events sent to X. By running xev and then pressing each of your multimedia keys in turn, you can see exactly what is being returned and then add those codes to your .hotkeys/mykeyboard.def file. First, install xev:

$ sudo apt-get install xev
               

Then launch xev from a terminal to open a small test window. Set the mouse's focus on the test window and then press one of the multimedia keys. In the terminal that you used to launch xev, you will see several lines of event information reported for each key press. What you need to look for is an entry that says keycode with a number after it. That number is the keycode that is associated with that particular key by X. Write down a list of the multimedia keys and their matching keycodes.

Once you have finished with xev, you can close it using Ctrl-C in the original terminal or by clicking the close box in the window manager.

Next, you need to open your .hotkeys/mykeyboard.def config file in a text editor and match events to keycodes according to the list you just made. For example, to match keycode 178 to the Favorites event, you would make an entry like:

<Favorites keycode="178"/>

The sample file contains a number of predefined events that you can uncomment and configure to suit your keycodes.

Customize predefined actions

Now that Hotkeys has a mapping between keycodes and predefined actions, you can customize the command associated with each action. The global config file is located in /etc/hotkeys.conf, but if you want to customize the action list, you can make a local copy that will automatically override the global config:

$ cp /etc/hotkeys.conf ~/.hotkeys/hotkeys.conf
               

Following the example above, you could tell Hotkeys to open your Favorites list in Mozilla with an entry like:

Favorites=gnome-moz-remote --remote=openBookmarks 

Create custom actions

The previous step allows you to customize the predefined actions, but that's not much use if you want an action like "Launch xterm with reversed video and open an SSH session to www.example.com"! No problem: you can use the keyboard definition file to associate keycodes with any arbitrary command you like. For example, if you wanted to use the F2 key for a purpose such as opening an SSH session to a remote machine, you could use xev to find the keycode for F2 and edit ~/.hotkeys/mykeyboard.def and put in:

<userdef keycode="68" command="xterm -fg black -bg white -e ssh www.example.com">SSH www.example.com</userdef> 

In this case, 68 is the keycode for F2, and SSH www.example.com is the event label that will be displayed onscreen by Hotkeys when it executes the command.

Test Hotkeys

Nearly there! By now, you have a keyboard definition file that maps keycodes to actions, plus a Hotkeys configuration file that maps actions to commands. Now it's time to launch Hotkeys and try it out.

Specify the keyboard type and launch hotkeys itself:

$ hotkeys -t mykeyboard -b
               

The -b flag tells Hotkeys not to launch itself into the background; that makes it easier to make quick changes if things don't go quite as planned, because you can just Ctrl-C to kill the program and launch it again. Later, when you're happy with the configuration, you can leave off the -b, and Hotkeys will automatically background itself on startup.

Alternatively, if Hotkeys is backgrounded and you want to make changes, you can simply use:

$ killall hotkeys
               

and then launch it again.

As soon as you launch it, Hotkeys will start watching for key-press events, so try pressing one of the keys you mapped and see what happens.

To save yourself the hassle of passing the keyboard-type argument to Hotkeys every time, you can put an entry in .hotkeys/hotkeys.conf like this:

Kbd=mykeyboard

which will then be applied automatically.

Onscreen display settings

Hotkeys displays each action onscreen while it's executing it to give you feedback that something is happening. By default, the OSD is large, bright green, and hangs around on your display for a couple of seconds, so you may want to change the settings to make it less obtrusive.

Look at the bottom of your hotkeys.conf file for settings starting with osd_. The sample configuration is well commented, so make changes as you see fit, and then kill and relaunch Hotkeys for your changes to take effect.

Start Hotkeys Automatically

Because Hotkeys needs to be running to do its job, you will need to launch it every time you log in to X. That can be a pain, so to have it start automatically, just add it to the Startup Programs in SystemSessions. Click Add and type in the command you used to launch Hotkeys from the command line, then save it (see Figure).

Add Hotkeys to Startup Programs in your session

The next time you log in to GNOME, Hotkeys will be started for you automatically and your multimedia keys will be functional right away.