Class Documentation
Keyboard |
2.1 |
ID_KEYBOARD |
Stable |
I/O |
August 2004 |
Rocklyte Systems |
Rocklyte Systems (c) 1996-2004. All rights reserved. |
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. |
DataChannel |
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.
ERR_Okay | The input was successfully processed. |
ERR_Args | Invalid arguments were specified. |
ERR_AccessMemory | Access to the internal channel list was denied. |
|
|
TranslateChars() [V2] |
Translates printable characters into their equivalent key codes. |
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.
ERR_Okay | The characters were successfully translated. |
ERR_Args | Invalid arguments were detected. |
|
|
TranslateKeys() [V2] |
Translates key codes into printable character values |
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.
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.
|
|