Logo (klik voor homepage)
 
Using special keyboards
Keyboard - Special keys
Many new keyboards these days have a number of special keys, often referred to as the Internet keys or the Multi-Media keys. In official USB language, these keys are called the Consumer Control keys. By default, these keys cannot be used, as RISC OS only supports the basic keyboard functionality. This is where !HID comes to the rescue. Not only does it recognise each special key, it also allows you to assign a useful function to such a key.
 
Contents

How does it work?
Well, the USBHID module, featured in this package, extracts detailed information from the keyboard and assigns a unique number to each key. This is not restricted to just 256 keys as on a normal keyboard. Each KeyCode produced by the USBHID module is 32-bit wide and will generally be presented in hexadecimal format, e.g. 220c01e5. From this number, the software can not only read the key number, but also the group to which a key belongs and the status of the modifier keys (i.e. Control, Shift, Alt and the GUI keys). Further down this chapter we'll explain how this number is built. The USBHID module then passes the KeyCode together with the DeviceID on to the WimpKey module which in turn allows you to link a useful action to each key. A more technical description can be found in Appendix 2.A.
 
Editing the list of keys
A list of keys and their action can be maintained by !HID. This is called the Keyboard window. The Keyboard window may open automatically when the application is started (if configured to do so). If it doesn't open automatically, select Keyboard from the iconbar menu. Alternatively click Select on the iconbar icon. A window similar to the one below will open showing the current key mappins.
For each key recognised by the system a single line is present in this window. The lines towards the top of the window have the highest priority, but if two actions have been assigned to the same key, only the lower one will be used. Optional colours are used to highlight some special groups of keys, such as vendor-specific keys or GUI key combinations. The information in this window can be shown in two ways: basic level and advanced level (shown here). You may toggle between the two levels via the menu or by clicking the legend at the top of the window.

In advanced mode, each line will show the following information: Line number, Device present, DeviceID, PortID, KeyCode, Last key pressed, State of the modifiers (Control, Shift, Alt and GUI), Name of the key (as per USB convention), Action assigned to the key, Name of a task linked to the key (if any), Parameter (e.g. a path name).
The last special key pressed is always indicated by a small 'hand' icon. This is, of course, only the case if the key is present in the list. If you want to view the meaning of the special keys prior to assigning them, you may want to use the Monitor window. Each time a special key is pressed, it will display the name of the key, the group to which the key belongs and the usage for the key.
 
The Keyboard Menu
   A small menu reveals the various features available to this window. It allows the contents of the Keyboard window to be saved and reloaded. Furthermore, it allows new lines to be added and existing lines to be edited. Several display options are available and the on-line user manual is only a key press away.
 Detailed description of the menu...
 

 
Editing a single key
Lines can be moved around by dragging them to the required position. A line may be selected by clicking it, or by navigating using the cursor keys (ArrowUp, ArrowDown, PageUp, PageDown, etc.). A selected line will have a pale-blue background. The contents of a line can be edited, by double clicking the line, or by pressing Enter. This will bring up a window similar to the one shown here.

Although this may appear as a rather technical window, it allows you to configure each key easily. The window consists of a number of areas. The top part of the window shows advanced information about the KeyCode (i.e. the key number, group, usage and modifier state). The middle part of the window is used to show details about the Vendor and Product ID numbers as presented by the actual USB device. The lower part of the window is used to assign an action to the KeyCode.

Some features of this window are described below. A more detailed description can be found in the section about the Edit key window. 		  
Edit key window

 

 
Adding new key definitions
There are several ways in which a new key can be added to the list. Each of these methods is described here. A key mapping can be added by one of the following methods:
  • Inserting a new line in the Keyboard window.
  • Dragging an application straight into the Keyboard window.
  • Grabbing each new key.
  • Via the pop-up window.

 
Inserting a new line
When editing the Keyboard window, you may insert a new line either at the top of the window, the bottom of the window or above the currently selected line. This can be done via the menu or through the keyboard short-cuts. Once a new line is inserted, the window Edit key definition will automatically open.
 
Dragging an application into the Keyboard window
If you want to launch an application, you may also drop the required application directly inside the Keyboard window. A new line will be inserted at the position of the mouse pointer. The name of the application and its path will be filled in automatically and you may now link a KeyCode to it. The latter can be done by typing a KeyCode (if known) directly in the KeyCode field, or by using the Learn mode.
 
Grabbing a new key
Once a KeyCode is already linked to a certain Action, e.g. launching an application, it is still possible to change the KeyCode. This can be done by changing the KeyCode directly in the multi-coloured field, or by entering Learn mode. This can also be used when added new lines.

As an extra aid, three menus have been added, one for Key, one for Group and one for Usage. These menus are created dynamically, directly from the official USB key definitions as maintained by the Suse Linux group.
 The KeyCode in more detail 		  

 
Using the pop-up window
Whenever you press a special key to which no action has been assigned yet, a pop-up window will appear to ask you if you want to assign a function to it. The pop-up window looks like the one shown here. In this case the My sites key on a Logitech keyboard has been pressed. You have the following choices:

  • Click OK or press Return to add a new key definition.
  • Click Cancel or press Esc to close the window.
  • Click Don't tell me again if you don't want this box to appear again during this session.
  
New key detected

 
Please note that this window will only appear if it is configured to do so from Choices.... If you've clicked the button Don't tell me again, the window is closed and won't appear when another new special key is pressed, until !HID is restarted. If you've pressed the button accidently, you may turn the pop-up window back on from the menu in the Keyboard window, by ticking the option Display -> Pop-up new keys, or from the iconbar menu Keyboard -> Pop-up new keys.
 
Testing a key
You may whish to test a certain key without having the actual device that holds the key present. Hold down Control and Double click the required line to execute the action. Alternatively you may select Preview from the menu or press Ctrl-P.

Alternatively you may want to monitor the KeyCodes assigned to the various key combinations of your keyboard. To do so, open the Monitor window shown here. Pressing a special key will cause this window to be updated. Please note that the window will only respond to keys or key combination generating SpecialKey events.
 More about the Monitor window
 The KeyCode in more detail 		  
Monitor window

 
Keyboard short-cuts in the 'Keyboard' window
Key Name Description
^B Add new line at bottom Add a new (empty) line at the bottom of the list.
^C Copy Copy a line to the clipboard.
^I Insert new line Insert a new (empty) line before the currently selected line
^P Preview line Execute the action for this key without actually pressing the key
^S Sort lines Sort the entries. Vendor-specific first, then alphabetical.
^T Insert new line at top Insert a new (empty line at the top of the list.
^V Paste Paste a line from the clipboard and insert it before the selected line.
^X Cut Remove a line from the list and copy it to the clipboard.
^Z Clear selection Unselect the currently selected line.
F1 Help Open the first page of the on-line manual.
F3 Save Save the current list.
^F1 Keyboard manual Show detailed information about the keyboard window.
^F2 Close window Close the Keyboard window (as per style guide convention)
More information Show advanced information in the Keyboard window (modifiers, keynames, etc.)
- Less information Show only the basic information in the Keyboard window.
Enter Edit current line Use the ArrowUp and ArrowDown keys to select the required line then press Enter.

 
Using different keyboards
Any USB keyboard can be used with this package, ranging form a simple (standard) PS2-like keyboard to the more advanced multi-media and Internet keyboards from manufacturers like Logitech and Microsoft. Many such keyboards have special keys for CD control, web browsing, e-mail, etc. The USB standard imposes certain rules on these keys, so that the e-mail key on a Logitech keyboard will generate the same key code as the e-mail key on a Microsoft keyboard. USB describes the use for each key carefully. Most of the extra keys will be referred to as the Consumer Control Keys. We will call these the Consumer keys. At present we can recognise 3 different groups of Consumer keys:

  • Standard Control
  • Application Launchers (AL)
  • Application Control (AC)
  • Vendor-specific

Unfortunately, not everyone seems to conform to the standard and some manufacturers have added their own vendor-specific keys to the keyboard. E.g. some of the Logitech Internet keyboards have a number of vendor-specific keys, such as the My Sites and Comunity keys. !HID will recognise such keys and identify them as vendor-specific. Additional definition tables may be added to !HID to allow such keys to be given sensible names.
 
Please read this
    When using a wireless RF keyboard (e.g. the Logitech iTouch Cordless Keyboard) you may not be able to hold down a key whilst starting the computer. The reason for this is that, when the computer is started, the RF receiver is powered up but has no means to 'ask' the keyboard which key is currently being pressed. The keyboard only sends a radio signal to the receiver when a key is pressed or released. If you need to press keys during the boot sequence of the computer, you are adviced to use a wired keyboard.

 
Keyboard auto-repeat
Some special keys can be made to auto-repeat whenever they are held down for a certain period, just like for the standard keys on the keyboard. Please note that auto-repeat will only work with the Consumer Control keys. Other special keys, such as the System Sleep key will not auto-repeat, as this would not be convenient. Auto-repeat may be useful e.g. for media control keys, such as Volume up and Volume down. On some keyboards the audio volume can be adjusted with a rotary dial, but other keyboards may have a separate Up and Down key instead.

Auto-repeat can be turned on and off in the section Keyboard settings in Choices. By default, the auto-repeat settings of the operating system will be used. These are the same settings as for the normal keyboard. Alternatively you may specify your own settings for the Consumer Control keys only.
 
The DeviceID number in more detail
Each USB device has some unique identification number on board which allows the computer to recognise it. Whenever a special key is pressed, the USBHID module not only broadcasts the 32-bit KeyCode, but also the 32-bit DeviceID. This anables applications to discriminate one keyboard from another. E.g. the e-mail button on each keyboard could be given a different function. The DeviceID is a 32-bit number, presented in hexadecimal format, and consists of two parts: the VendorID and the ProductID. The VendorID is unique for each manufacturer and the ProductID is unique for each product from that manufacturer. The first 4 digits of the hexadecimal number represent the Vendor ID. The remaining 4 digits are the Product ID. This is clearly demonstrated in the centre part of the Edit key window.
You may want to use the free !USBinfo application to find out the exact details for each device. Please note that some vendors are selling other manufacturers' equipment. So if you buy, say, a Xerox printer, you may find that there's actually a Ricoh printer inside of the box.
 
Using the PortID
When using multiple devices with the same DeviceID (e.g. two identical keyboards) you may want to assign different Actions the the keys of each keyboard. This can be done by using the PortID in the the centre part of the Edit key window. There are two ways to identify the device:

A. By using the Absolute port number
An 8-digit hexadecimal number is assigned by USBHID to each device, representing its physical position in the USB topology. This is called the Hardware port number.
The first two digits represent the USB filing system involved. For the native USB filing system on an IYONIX machine (called usb) this will always be 00. The 3rd digit represents the USB Bus number, which is 1 in the example. The rest of the PortID is built from the physical port numbers of each of the HUBs in the chain. In the example, the keyboard is connected to port 1 of the root HUB. Please note that, when using the absolute port number, the assignments will only work when the keyboard is connected to that particular USB socket.
 The PortID in more detail

B. By using the Relative port number
As an alternative to the above, you may also use the method by which each device is given a relative port number. When using two or more identical devices, the one on the lowest physical port will be given relative port number 0. The next one will be 1 and so on. This number is called the Index.

 
Related subjects

Klik voor homepage © Copyright Paul Reuvers X-Ample Technology bv  usb@xat.nl Last changed: Fri,21 Apr 2006.10:32:47