Advanced BeOS Keyboarding
by Nathan Schrenk, Director, Applications 
	The stalwart old 101-key keyboard has grown a few extra keys in recent years to become 
the 104-key keyboard. But keyboard manufacturers were not content to just add 3 keys. 
Many keyboards now on the market have extra buttons above the top row of keys or 
somewhere else. These buttons are not standard, and have various labels such as "Back," 
"Forward," "Stop," "Mail," "Volume +," "Prev Track," "Next Track," "Sleep," and so on. Many 
of these keyboards that I've seen have been marketed as "Internet ready;" the extra 
buttons are aimed at controlling a web browser, controlling the playback of audio CDs in the 
computer's CD-ROM drive, or adjusting the volume. 
	To support the extended functions of these keyboards, many manufacturers ship software 
for the dominant PC operating system, which causes something to happen when the user 
presses the new buttons. If you have one of these keyboards and it uses the AT interface, 
this article should help you with using those buttons. Please note that the technique 
described in this article doesn't work with an ADB or an USB keyboard or with any version of 
BeOS prior to BeOS 5. This technique is supported in BeIA, which includes an Input Server add
-on that performs some common actions or runs a script when a special buttons is pressed. 
First, a little background information: when a key is pressed, the BeOS driver that 
interfaces with the keyboard controller reports a number to the Input Server's keyboard 
device add-on. This number is called a "scan code" and it identifies which key was pressed. 
The Input Server keyboard device then converts the AT keyboard scan code to a BeOS key 
code, which is independent of the type of keyboard used. BeOS supports AT, ADB, and USB 
keyboards, so it's valuable to have a common mapping of keys to key codes so that the 
rest of the system doesn't have to know which type of keyboard is plugged in to interpret 
keyboard events properly. 
	In BeOS 5, a mechanism allows a user to change the mapping of AT keyboard scan codes to 
BeOS key codes. The Input Server's keyboard device looks for a configuration file named 
"AT_Keyboard_Info" in the user settings directory (which is /boot/home/config/settings by 
default) and uses the mapping of scan codes to key codes contained in that file if it exists. 
A sample AT_Keyboard_Info file is contained in the archive for this article at ftp:// 
ftp.be.com/pub/samples/input_server/KeyboardMapping.zip. The file format is 
documented in the comments at the top of the sample file, so I won't repeat that 
information here. The basic idea is that each line contains a mapping from an AT scan code 
to a BeOS key code. For example, a line reading "0x1e[TAB]0x3c" specifies that the scan 
code for the 'A' key, 0x1e, should generate a BeOS keyboard event with the key code 0x3c. 
All numeric values in the file are specified in hexadecimal. 
	All you need to do to support the extra buttons on your keyboard is to find out which AT 
scan code each button generates, and to add a line to your AT_Keyboard_Info file for each 
key. It's not easy to find out which AT scan code a key generates with a standard 
installation of BeOS 5, so I've included a replacement Input Server keyboard device add-on 
in the archive for this article. You'll need to copy this add-on, which is named "keyboard," 
to the /system/add-ons/input_server/devices/ directory, and then restart the Input 
Server, either by running "/system/servers/input_server -q" in a Terminal window, or by 
bringing up the Team Monitor by pressing Ctrl+Alt+Delete, selecting "input_server", and 
then pressing the "Kill" button. Killing the Input Server might seem to be dangerous, and 
likely to leave you with an unresponsive system, but luckily the Input Server is 
automatically restarted if it is killed. 
	When the Input Server restarts, the mouse cursor will move to the center of the screen and 
you'll be ready to find out which scan code is generated by each special button on your 
keyboard. With this new keyboard add-on installed, an alert box pops up every time you 
press an unmapped key on your keyboard. You can write down the scan codes from these 
alerts, and make your own customized AT_Keyboard_Info file that includes mappings for 
your extra buttons. The buttons on various keyboards are different. We haven't developed 
any type of standard for which BeOS keycode should be used for a certain type of button, 
but the convention we've been following is to map the special buttons to BeOS key codes 
starting with "0x100000." When you have your own customized mapping file, you can copy 
it into place and restart the Input Server again. 
	Now that you've mapped the extra buttons on your keyboard to BeOS key codes, how do 
you use them? I recommend Jeremy Friesner's nifty SpicyKeys program, which can be found 
on the web at  http://www.lcscanada.com/jaf. SpicyKeys can be used to launch applications 
or run scripts when a key or combination of keys is pressed. Make sure to download version 
1.24 or later, because support for unmapped keys was added in version 1.24. If you're a 
BeOS developer and you want to support the extra keys in your own application, you can 
add code to handle the B_UNMAPPED_KEY_DOWN and B_UNMAPPED_KEY_UP events that 
will be generated when one of the extra buttons are pressed. Look for the keycode field in 
the message to determine which unmapped key was pressed. 
	A special note for those of you who like the keyboard layout of Sun SPARCstation 
keyboards: if you'd like to bind the Caps Lock key to Left+Ctrl, you can replace the 
default mapping for scancode 0x3a, and map that key to 0x5c. Enjoy!