How to get special keys to work

Overview

key	standard function	tools supporting key1	configurability	remarks
Fn	-	xmodmap, tpb	full	on release without completed key combination
FnF3	blank screen	ibm-acpi, thinkpad-acpi	full
FnF4	suspend to ram	ibm-acpi, thinkpad-acpi	full
FnF5	switch bluetooth	ibm-acpi, thinkpad-acpi	full	in models starting from 2002
FnF7	switch display	ibm-acpi, thinkpad-acpi, tpb	additional actions
FnF8	toggle display expansion	ibm-acpi, thinkpad-acpi, tpb	additional actions
FnF9	eject from dock	ibm-acpi, thinkpad-acpi	full
FnF12	hibernate	ibm-acpi, thinkpad-acpi	full
FnPos1	brightness up	tpb	additional actions
FnEnd	brightness down	tpb	additional actions
FnPageUp	toggle thinklight	ibm-acpi, tpb	additional actions
FnSpace	toggle zoom	tpb	full
Access IBM or ThinkPad	help application	tpb	full
Home	open web browser	xmodmap, tpb	full	only A30, A30p, A31, A31p and ext. keyboards
Search	open search application	xmodmap, tpb	full	only A30, A30p, A31, A31p and ext. keyboards
Mail	open mail application	xmodmap, tpb	full	only A30, A30p, A31, A31p and ext. keyboards
Favorites	open favorites	xmodmap, tpb	full	only A30, A30p, A31, A31p and ext. keyboards
Reload	reload web page	xmodmap, tpb	full	only A30, A30p, A31, A31p and ext. keyboards
Abort	abort loading page	xmodmap, tpb	full	only A30, A30p, A31, A31p and ext. keyboards
Backward	previous page	xmodmap, tpb	full	ext. keyboards and Thinkpads starting from 2002
Forward	next page	xmodmap, tpb	full	ext. keyboards and Thinkpads starting from 2002
Volume up	volume up	tpb	additional actions
Volume down	volume down	tpb	additional actions
Volume mute	mute volume	tpb	additional actions
Power	shutdown	ibm-acpi	full	triggered on pressing 3secs, but notebook goes off on 5sec press
Display lid	blank screen	ibm-acpi	full
Ultrabay lid	announce ultrabay change	ibm-acpi	full
Dock eject	eject from dock	ibm-acpi	full

Triggering key events

ibm-acpi events

events triggered by ibm-acpi for /etc/acpi/events files

key	event
FnF3	ibm/hotkey HKEY 00000080 00001003
FnF4	ibm/hotkey HKEY 00000080 00001004
FnF5	ibm/hotkey HKEY 00000080 00001005
FnF7	ibm/hotkey HKEY 00000080 00001007
FnF8	ibm/hotkey HKEY 00000080 00001008
FnF9	ibm/hotkey HKEY 00000080 00001009
FnF12	ibm/hotkey HKEY 00000080 0000100c
Power	button/power PWRF 00000080 xxxxxxxx
Display lid	button/lid LID 00000080 xxxxxxxx
Ultrabay eject	ibm/bay MSTR 00000003 00000000
Ultrabay inserted	ibm/bay MSTR 00000001 00000000
Dock eject	ibm/dock GDCK 00000003 00000001

tpb configuration

configuration keywords for tpb (to put in /etc/tpbrc)

key	config keyword
Access IBM or ThinkPad	THINKPAD
Home	HOME
Search	SEARCH
Mail	MAIL
Favorites	FAVORITES
Reload	RELOAD
Abort	ABORT
Backward	BACKWARD
Forward	FORWARD
Fn	FN
FnSpace	CALLBACK (zoom on/off)
FnPageUp	CALLBACK (thinklight on/off)
FnF7	CALLBACK (display lcd/crt/both)
FnF8	CALLBACK (expand on/off)
FnHome	CALLBACK (brightness <percent>)
FnEnd	CALLBACK (brightness <percent>)
Volume up	CALLBACK (volume <percent>)
Volume down	CALLBACK (volume <percent>)
Volume mute	CALLBACK (mute on/off)

To all parameter keywords should be assigned the full path to the executables supposed to be started on key press. The exectable provided for the CALLBACK keyword should take the parameters given in parentheses and act according to them. If you want to use xmodmap for the HOME, SEARCH, MAIL, FAVORITES, RELOAD, ABORT, BACKWARD, FORWARD and FN keys you should provide a XEVENTS=off in your /etc/tpbrc.

For Debian users, tpb is started from /etc/X11/Xsession.d/90tpb.

xmodmap configuration

xmodmap enables you to edit the modifier map and keymap tables that are used to translate keycodes into keysyms. Understood? Well, basically it allows you to give the X server a dictionary for the translation of keycodes like "97" into more human readable synonyms like "Home". This way xmodmap allows you to make the special keys of your keyboard known to X applications.

Usually you should write your keycode-keysym associations into the file ~/.Xmodmap. This file is usually read by the X session startup scripts of your system, so that the mappings automatically get included everytime you run the X server.

The ~/.Xmodmap lines for our purpose are in the form of

keycode <keycode> = <keysym>

The following table shows the keycodes generated by the Thinkpad special keys and sensible keysyms to assign them to.

keycodes and recommended keysyms

key	keycode	keysym
Backward	234	XF86Back or F21
Forward	233	XF86Forward or F22
Home	178	XF86HomePage
Search	229	XF86Search
Mail	236	XF86Mail
Favorites	230	XF86AddFavorite or XF86Favorites
Reload	231	XF86Reload
Abort	232	XF86Stop
Fn	227	F35

(In case you want to use the browser keys in Firefox, you will have to assign the F21 and F22 or similar keysyms to them.)

Note: if you are running tpb you might need to add the line XEVENTS=off into your tpbrc to stop it from grabbing the key events and allow them to get through to X instead.

Example Applications

Web Browsers

Firefox

(First of all thanks go to Ryan Barrett for writing the little howto on his blog.)
To have firefox make use of the browser keys you need to modify one of its files. To do this you will first need to extract it from the browser.jar archive. Do...

# cd <firefox-directory>/chrome

# unzip browser.jar

The file of interest is content/browser/browser.xul. Edit it...

# vi content/browser/browser.xul

Look for the <keyset id="mainKeyset"> section and add the following lines within...

<key id="goBackTP" keycode="VK_F21" command="Browser:Back" />
<key id="goForwardTP" keycode="VK_F22" command="Browser:Forward" />

Now save the file and repackage the browser.jar archive...

# zip -rD0 browser.jar content/browser/

That's it.

Another interesting Page on Firefox is http://dqd.com/~mayoff/notes/thinkpad/dqdnavkeys/ It uses different key mappings (F19 resp. F20) but a ready .xpi is provided which is pretty comfortable.

Firefox and KDE

KDE provides Khotkeys. Get into the KDE system controls (kcontrol) and just assign keyboard inputs "Alt+Left" and "Alt+Right" to the two browser keys. That way, you don't need to mess around with the firefox internals. Maybe, you'll need to set up ~/.Xmodmap as described above in order to assign them the symbols XF86Back and XF86Forward.

Opera

However this isn't a simple configration file, you can set your browser manually.
Go to Tool > Settings > Mouse and keyboard > Keyboard settings > Edit > Browser Window. There add F21 - Back and F22 - Forward. Now you can surf using your TP keys ;-)

Window Managers

fvwm

To get the Backwards and Forwards keys to cycle through pages in the virtual desktop, add this to your ~/.fvwmrc:

Key    XF86Back     A      A   Scroll     -100000   0
Key    XF86Forward  A      A   Scroll     +100000   0

If you use multiple virtual desktops, you could instead use the keys to flip between them by using GotoDesk.

pekwm configuration

You can make the two browser keys switch workspaces in pekwm, by adding the following two lines to the ~/.pekwm/keys file:

KeyPress = "Mod1 XF86Back" { Actions = "GoToWorkspace prev" }
KeyPress = "Mod1 XF86Forward" { Actions = "GoToWorkspace next" }

pwm

Another example how to use these two keys to switch between pwm tabs. These two lines should be added to ~/.pwm/keys-default.conf or /etc/pwm/keys-default.conf:

kbind "Back", "switch_rot", -1
kbind "Forward", "switch_rot", 1

Other Uses

Console tools configuraton

To make the Forward and Backward keys useful in console, add this to your keymap (/etc/console/boottime.kmap.gz in Debian):

keycode 158 = Decr_Console
keycode 159 = Incr_Console

External Sources

• IBMs page on configuring the ThinkPad buttons (ThinkPad, Access IBM, Mail, Search, and Home buttons) under Linux
• Rob Mayoffs page on using IBM Keyboard Navigation Keys in Linux Mozilla and Firefox
• Ryan Barretts blog article about using the browser keys in Firefox

FOOTNOTES [Δ]

1. if there are more than one tool listed, one is sufficient