
Advanced BeOS Keyboarding
by Nathan Schrenk -- <nschrenk@be.com>


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 <<< INSERT URL HERE >>>.
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!




