Class Documentation

Name:Keyboard
Version:2.1
ID:ID_KEYBOARD
Status:Stable
Category:I/O
Date:August 2004
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 1996-2004. All rights reserved.
Short:  The keyboard class is used to manage keyboard I/O.



Description

The Keyboard class is a dummy class type that is used to create objects that represent key-based hardware devices. This means that Keyboard objects don't actually read hardware, they just receive input from the devices responsible for controlling keyboard I/O. Objects that subscribe to a Keyboard object's data channel can then receive this input in a format that is standardised by the Pandora Engine.

The most common keyboard object is the 'SystemKeyboard', which is created during the boot process. This particular object represents the main PC keyboard. If you are designing a system in which you want multiple keyboards, you can create as many keyboard objects as you have hardware or virtual devices to associate with them. This can be useful for hooking up remote keyboards over a network, or attaching extra devices that have their own keyboard to a PC.

The Keyboard class supports translation methods for converting raw key values into characters and vice versa. Please use them rather than translating the raw key values yourself, or you will lose vital keymap translations that may be required on behalf of the user.

Actions

The Keyboard class supports the following actions:

DataChannel  This action can be used to send fake keyboard input.
Reset  Resets the keyboard settings.
SaveToObject  Saves the current keyboard settings to another object.

Methods

The Keyboard class implements the following methods:

TranslateChars  Translates printable characters into their equivalent key codes.
TranslateKeys  Translates key codes into printable character values

Structure

The Keyboard object consists of the following public fields:

Layout  Determines the keyboard layout (defaults to US101).
RepeatDelay  Defines the delay between the holding of any key and the start of the key repeat rate.
RepeatRate  Defines the keyboard repeat rate for held keypresses.
UnicodeTable  Refers to a global unicode table for converting unicode values to names and vice versa.
XShift  Configures the extended-shift key.
Action:DataChannel
Short:This action can be used to send fake keyboard input.

Keypresses can be sent to a Keyboard object through the DataChannel action by using the DATA_KEYPRESS data type. All characters that are sent to a Keyboard object through the data channel will inevitably be reported to programs that read the Keyboard through the data channel service.

Please note that it is extremely important that the key qualifiers are set correctly and that each key press is matched with a key release. If the data is not defined correctly, the objects receiving the data may not interpret it as intended.

Result
ERR_Okay  The input was successfully processed.
ERR_Args  Invalid arguments were specified.
ERR_AccessMemory  Access to the internal channel list was denied.

Method:TranslateChars() [V2]
Short:Translates printable characters into their equivalent key codes.
Arguments:
STRING String  String of character codes to be translated.
APTR Keys  Output buffer (struct dcKeyEntry).
LONG Size  Size of the output buffer in bytes.

The TranslateChars method is used to convert UTF-8 character strings into their equivalent raw key values. The routine will scan the character buffer in the String argument and write the equivalent key values to the buffer referred to by the Keys argument. The routine will stop when the String buffer is terminated, or the Keys buffer runs out of space.

Result
ERR_Okay  The characters were successfully translated.
ERR_Args  Invalid arguments were detected.

Method:TranslateKeys() [V2]
Short:Translates key codes into printable character values
Arguments:
APTR Keys  List of keys to translate (struct dcKeyEntry), terminated with a NULL entry.
STRING String  String based output buffer.
LONG Size  Size of the output buffer in bytes.

The TranslateKeys method is used to convert raw key values into printable characters. The routine will scan the key array passed in the Keys argument and each key value that is linked to a printable character will be written to the String buffer that you have supplied. The routine will stop when the the Keys array is terminated, or the supplied buffer runs out of space.

Please note that this method will return unicode (UTF-8) characters for keypresses that translate to unicode values. For this reason the minimum recommended buffer size is 7 bytes. It is also worth keeping in mind that even a single keypress can potentially return multiple characters if a string sequence has been assigned to the key.

Result
ERR_Okay  The characters were successfully translated.
ERR_Args  Invalid arguments were detected.
ERR_EmptyString  None of the keys were translated into printable characters.

Field:Layout
Short:Determines the keyboard layout (defaults to US101).
Type:STRING
Status:Get/Set

The layout of a keyboard can be redefined by setting the Layout field. The available keyboard layouts are determined by the available configuration files in the "system:config/keymaps/" directory. For instance, if an "italian" file is available, you can set a layout of "Italian".

If you set a layout string that does not match any existing keymap files, the keyboard object will revert to the default US101 format.


Field:RepeatDelay
Short:Defines the delay between the holding of any key and the start of the key repeat rate.
Type:LONG
Status:Get/Set

Defines the delay, in milliseconds, between the time of pressing a key and the start of the key repeat rate. The recommended default is 250ms.


Field:RepeatRate
Short:Defines the keyboard repeat rate for held keypresses.
Type:LONG
Status:Get/Set

Defines the character repeat rate in characters per second.


Field:UnicodeTable
Short:Refers to a global unicode table for converting unicode values to names and vice versa.
Type:struct UnicodeDescriptor *
Status:Get

This field refers to a unicode table that you can use to translate unicode values into their standard system names. The structure of each entry in the table is defined as follows:

   struct UnicodeDescriptor {
      STRING Name;
      UWORD  Value;
   };

The table is sorted by unicode value (ascending) and is terminated with a NULL entry in both fields. You can view all of the content of the table if you load the "input/unicodetable.h" include file.


Field:XShift
Short:Configures the extended-shift key.
Type:LONG
Status:Read/Write

The extended-shift key is normally mapped against the AltGr key for foreign keyboards; also known as the right-alt key for vanilla keyboards. You can change the extended shift key to the left and right command keys if you pass XSF_COMMAND to the XShift field. Switching to the default AltGr key is possible by passing XSF_ALTGR.

The extended-shift key has the same properties as the keyboard's standard shift key, i.e. the user holds down the key and presses it in conjunction with another key to create a printable character. The resulting character will be taken from the keyboard's mapping for the second shift key. If there is no character set against the extended-shift key, no printable character will result.