The Input Server: Input Functions

The Input Server Table of Contents | The Input Server Index

# Input Functions

Declared in: be/interface/InterfaceDefs.h

Library: libbe.so

This section describes the global mouse and keyboard functions.

## Mouse Functions

### get_click_speed() see set_click_speed()

### get_mouse_map() see set_mouse_map()

### get_mouse_speed() see set_mouse_map()

### get_mouse_acceleration() see set_mouse_acceleration()

### get_mouse_type() see set_mouse_map()

### set_click_speed() , get_click_speed()

Declared in: be/interface/InterfaceDefs.h

status_t `set_click_speed(`bigtime_t interval`) `
status_t `get_click_speed(`bigtime_t *interval`) `

These functions set and report the timing for multiple-clicks. For successive mouse-down events to count as a multiple-click, they must occur within the interval set by `set_click_speed()` and provided by `get_click_speed()`. The interval is measured in microseconds; it's usually set by the user in the Mouse preferences application. The smallest possible interval is 100,000 microseconds (0.1 second).

If successful, these functions return `B_OK`; if unsuccessful, they return an error code, which may be just `B_ERROR`.

### set_mouse_map() , get_mouse_map() , set_mouse_type() , get_mouse_type() , set_mouse_speed() , get_mouse_speed()

Declared in: be/interface/InterfaceDefs.h

status_t `set_mouse_map(`mouse_map *map`) `
status_t `get_mouse_map(`mouse_map *map`) `
status_t `set_mouse_type(`int32 numButtons`) `
status_t `get_mouse_type(`int32 *numButtons`) `
status_t `set_mouse_speed(`int32 speed`) `
status_t `get_mouse_speed(`int32 *speed`) `
status_t `set_mouse_acceleration(`int32 acceleration`) `
status_t `get_mouse_acceleration(`int32 *acceleration`) `

These functions configure the mouse and supply information about the current configuration. The configuration should usually be left to the user and the Mouse preferences application.

`set_mouse_map()` maps the buttons of the mouse to their roles in the user interface, and `get_mouse_map()` writes the current map into the variable referred to by map. The `mouse_map` structure has a field for each button on a three-button mouse:

uint32 `left
` The button on the left of the mouse

uint32 `right
` The button on the right of the mouse

uint32 `middle
` The button in the middle, between the other two buttons

Each field is set to one of the following constants:

`B_PRIMARY_MOUSE_BUTTON`
`B_SECONDARY_MOUSE_BUTTON`
`B_TERTIARY_MOUSE_BUTTON`

The same role can be assigned to more than one physical button. If all three buttons are set to `B_PRIMARY_MOUSE_BUTTON`, they all function as the primary button; if two of them are set to `B_SECONDARY_MOUSE_BUTTON`, they both function as the secondary button; and so on.

`set_mouse_type()` informs the system of how many buttons the mouse actually has. If it has two buttons, only the `left` and `right` fields of the `mouse_map` are operative. If it has just one button, only the `left` field is operative. `set_mouse_type()` writes the current number of buttons into the variable referred to by numButtons.

`set_mouse_speed()` sets the speed of the mouse—the rate at which the cursor image moves on-screen relative to the actual speed at which the user moves the mouse on its pad. A speed value of 0 is the slowest movement rate. The maximum rate is 20, though even 10 is too fast for most users. `get_mouse_speed()` writes the current speed into the variable referred to by speed.

`set_mouse_acceleration()` sets the mouse's acceleration—the rate at which the cursor image gains and loses speed as the user begins and ceases moving the mouse. An acceleration value of 0 is the slowest movement rate. The maximum rate is 20, though even 10 is too fast for most users. `get_mouse_acceleration()` writes the current acceleration into the variable referred to by acceleration.

All six functions return `B_OK` if successful, and an error code, typically `B_ERROR`, if not.

## Keyboard Functions

### get_key_info()

Declared in: be/interface/InterfaceDefs.h

status_t `get_key_info(`key_info *keyInfo`) `

Writes information about the state of the keyboard into the `key_info` structure referred to by keyInfo. This function lets you get information about the keyboard in the absence of `B_KEY_DOWN` messages. The `key_info` structure has just two fields:

uint32 `modifiers
` A mask indicating which modifier keys are down and which keyboard locks are on.

uint8 `key_states` [16]
A bit array that records the state of all the keys on the keyboard, and all the keyboard locks. This array works identically to the "states" array passed in a key-down message. See "Key States" in the Keyboard Information appendix for information on how to read information from the array.

`get_key_info()` returns `B_OK` if it was able to get the requested information, and `B_ERROR` if the return results are unreliable.

See also: `BView::KeyDown()`, the Keyboard Information appendix, `modifiers()`

### get_key_map()

Declared in: be/interface/InterfaceDefs.h

void `get_key_map(`key_map **keys, char **chars`) `

Provides a pointer to a copy of the system key map—the structure that describes the role of each key on the keyboard. The pointers returned by the function are yours; you must `free()` them when you're finished with them.

| In versions of the BeOS before Release 4, the pointers used to belong to the operating system. Now they're yours to do with as you please. Please update your applications as necessary to avoid leaking memory.

Through the Keymap preferences application, users can configure the keyboard to their liking. The user's preferences are stored in a file (Key_map within the `B_USER_SETTINGS_DIRECTORY`, returned by the `find_directory()` function). When the machine reboots, the key map is read from this file. If the file doesn't exist, the original map encoded in the Application Server is used.

The `key_map` structure contains a large number of fields, but it can be broken down into these six parts:

- A version number.

- A series of fields that determine which keys will function as modifier keys—such as Shift, Control, or Num Lock.

- A field that sets the initial state of the keyboard locks in the default key map.

- A series of ordered tables that assign character values to keys. Except for a handful of modifier keys, all keys are mapped to characters, though they may not be mapped for all modifier combinations.

- A series of tables that locate the dead keys for diacritical marks and determine how a combination of a dead key plus another key is mapped to a particular character.

- A set of masks that determine which modifier keys are required for a key to be considered dead.

The following sections describe the parts of the `key_map` structure.

##### Version

The first field of the key map is a version number:

uint32 `version
` An internal identifier for the key map.

The version number doesn't change when the user configures the keyboard, and shouldn't be changed programmatically either. You can ignore it.

##### Modifiers

Modifier keys set states that affect other user actions on the keyboard and mouse. Eight modifier states are defined—Shift, Control, Option, Command, Menu, Caps Lock, Num Lock, and Scroll Lock. These states are discussed under "Modifier Keys" in the Keyboard Information appendix. They fairly closely match the key caps found on a Macintosh keyboard, but only partially match those on a standard PC keyboard—which generally has a set of Alt(ernate) keys, rarely Option keys, and only sometimes Command and Menu keys. Because of these differences, the mapping of keys to modifiers is the area of the key map most open to the user's personal judgement and taste, and consequently to changes in the default configuration.

Since two keys, one on the left and one on the right, can be mapped to the Shift, Control, Option, and Command modifiers, the keyboard can have as many as twelve modifier keys. The `key_map` structure has one field for each key:

uint32 `caps_key
` The key that functions as the Caps Lock key; by default, this is the key labeled "Caps Lock," key 0x3b.

uint32 `scroll_key
` The key that functions as the Scroll Lock key; by default, this is the key labeled "Scroll Lock," key 0x0f.

uint32 `num_key
` The key that functions as the Num Lock key; by default, this is the key labeled "Num Lock," key 0x22.

uint32 `left_shift_key
` A key that functions as a Shift key; by default, this is the key on the left labeled "Shift," key 0x4b.

uint32 `right_shift_key
` Another key that functions as a Shift key; by default, this is the key on the right labeled "Shift," key 0x56.

uint32 `left_command_key
` A key that functions as a Command key; by default, this is key 0x5d, sometimes labeled "Alt."

uint32 `right_command_key
` Another key that functions as a Command key; by default, this is key 0x5f, sometimes labeled "Alt."

uint32 `left_control_key
` A key that functions as a Control key; by default, this is the key labeled "Control" on the left, key 0x5c.

uint32 `right_control_key
` Another key that functions as a Control key; by default on keyboards that have Option keys, this key is the key labeled "Control" on the right, key 0x60. For keyboards that don't have Option keys, this field is unmapped (its value is 0); key 0x60 is used as an Option key.

uint32 `left_option_key
` A key that functions as an Option key; by default, this is key 0x66, which has different labels on different keyboards—"Option," "Command," or a Windows symbol. This key doesn't exist on, and therefore isn't mapped for, a standard 101-key keyboard.

uint32 `right_option_key
` A key that functions as an Option key; by default, this is key 0x67, which has different labels on different keyboards—"Option," "Command," or a Windows symbol. For keyboards without this key, the field is mapped to the key labeled "Control" on the right, key 0x60.

uint32 `menu_key
` A key that initiates keyboard navigation of the menu hierarchy; by default, this is the key labeled with a menu symbol, key 0x68. This key doesn't exist on, and therefore isn't mapped for, a standard 101-key keyboard.

Each field names the key that functions as that modifier. For example, when the user holds down the key whose code is set in the `right_option_key` field, the `B_OPTION_KEY` and `B_RIGHT_OPTION_KEY` bits are turned on in the modifiers mask that the `modifiers()` function returns. When the user then strikes a character key, the `B_OPTION_KEY` state influences the character that's generated.

If a modifier field is set to a value that doesn't correspond to an actual key on the keyboard (including 0), that field is not mapped. No key fills that particular modifier role.

##### Keyboard locks

One field of the key map sets initial modifier states:

uint32 `lock_settings
` A mask that determines which keyboard locks are turned on when the machine reboots or when the default key map is restored.

The mask can be 0 or may contain any combination of these three constants:

`B_CAPS_LOCK`
`B_SCROLL_LOCK`
`B_NUM_LOCK`

It's 0 by default; there are no initial locks.

Altering the `lock_settings` field has no effect unless the altered key map is made the default.

##### Character maps

The principal job of the key map is to assign character values to keys. This is done in a series of nine tables:

int32 `control_map` [128]
The characters that are produced when a Control key is down but both Command keys are up.

int32 `option_caps_shift_map` [128]
The characters that are produced when Caps Lock is on and both a Shift key and an Option key are down.

int32 `option_caps_map` [128]
The characters that are produced when Caps Lock is on and an Option key is down.

int32 `option_shift_map` [128]
The characters that are produced when both a Shift key and an Option key are down.

int32 `option_map` [128]
The characters that are produced when an Option key is down.

int32 `caps_shift_map` [128]
The characters that are produced when Caps Lock is on and a Shift key is down.

int32 `caps_map` [128]
The characters that are produced when Caps Lock is on.

int32 `shift_map` [128]
The characters that are produced when a Shift key is down.

int32 `normal_map` [128]
The characters that are produced when none of the other tables apply.

Each of these tables is an array of 128 offsets into another array, the chars array of Unicode UTF-8 character encodings. `get_key_map()` provides a pointer to the chars array as its second argument.

Key codes are used as indices into the character tables. The offset stored at any particular index maps a character to that key. For example, the code assigned to the M key is 0x52; at index 0x52 in the `option_caps_map` is an offset; at that offset in the chars array, you'll find the character that's mapped to the M key when an Option key is held down and Caps Lock is on.

This indirection—an index to an offset to a character—is required because characters are encoded as Unicode UTF-8 strings. Character values of 127 or less (7-bit ASCII) are just a single byte, but UTF-8 takes two, three, or (rarely) four bytes to encode values over 127.

The chars array represents each character as a Pascal string—the first byte in the string tells how many other bytes the string contains. For example, the string for the trademark symbol ((TM) ) looks like this:

       x03xE2x84xA2

The first byte (x03) indicates that Unicode UTF-8 takes 3 bytes to represent the trademark symbol, and those bytes follow (xE2x84xA2). Pascal strings are not null-terminated.

Here's an example showing you how to decode the character tables. This sample prints out a simple chart of the `normal_map`, `shift_map`, `option_map`, and `option_shift_map` characters:

       #include <interface/InterfaceDefs.h>
       #include <stdio.h>
       #include <string.h>
       #include <stdlib.h>

       static void print_key( char *chars, int32 offset )
       {
          int size = chars[offset++];

          switch( size ) {
          case 0:
             // Not mapped
             printf( "N/A" );
             break;

          case 1:
             // 1-byte UTF-8/ASCII character
             printf( "%c", chars[offset] );
             break;

          default:
             // 2-, 3-, or 4-byte UTF-8 character
             {
                char *str = new char[size + 1];
                strncpy( str, &(chars[offset]), size );
                printf( "%s", str );
                delete [] str;
             }
             break;
          }

          printf( "t" );
       }

       int main( void )
       {
          // Get the current key map.
          key_map *keys;
          char *chars;
          get_key_map( &keys, &chars );

          // Print a chart of the normal, shift, option, and option+shift
          // keys.
          printf( "Key #tNormaltShifttOptiontOption+Shiftn" );
          for( int idx = 0; idx < 128; idx++ ) {
             printf( " %3dt", idx );
             print_key( chars, keys->normal_map[idx] );
             print_key( chars, keys->shift_map[idx] );
             print_key( chars, keys->option_map[idx] );
             print_key( chars, keys->option_shift_map[idx] );
             printf( "n" );
          }

          // Free our copy of the key map.
          free( chars );
          free( keys );

          return EXIT_SUCCESS;
       }

The character map tables are ordered. Values from the first applicable table are used, even if another table might also seem to apply. For example, if Caps Lock is on and a Control key is down (and both Command keys are up), the `control_map` array is used, not `caps_map`. If a Shift key is down and Caps Lock is on, the `caps_shift_map` is used, not `shift_map` or `caps_map`.

Notice that the last eight tables (all except `control_map`) are paired, with a table that names the Shift key (...`_shift_map`) preceding an equivalent table without Shift:

- `option_caps_shift_map` is paired with `option_caps_map`,

- `option_shift_map` with `option_map`,

- `caps_shift_map` with `caps_map`, and

- `shift_map` with `normal_map`.

These pairings are important for a special rule that applies to keys on the numerical keypad when Num Lock is on:

- If the Shift key is down, the non-Shift table is used.

- However, if the Shift key is not down, the Shift table is used.

In other words, Num Lock inverts the Shift and non-Shift tables for keys on the numerical keypad.

Not every key needs to be mapped to a character. If the chars array has a 0-length string for a key, the key is not mapped to a character (given the particular modifier states the table represents). Generally, modifier keys are not mapped to characters, but all other keys are, at least for some tables. Key-down events are not generated for unmapped keys.

##### Dead keys

Next are the tables that map combinations of keys to single characters. The first key in the combination is "dead"—it doesn't produce a key-down event until the user strikes another character key. When the user hits the second key, one of two things will happen: If the second key is one that can be used in combination with the dead key, a single key-down event reports the combination character. If the second key doesn't combine with the dead key, two key-down events occur, one reporting the dead-key character and one reporting the second character.

There are five dead-key tables:

int32 `acute_dead_key` [32]
The table for combining an acute accent (xab ) with other characters.

int32 `grave_dead_key` [32]
The table for combining a grave accent (Q) with other characters.

int32 `circumflex_dead_key` [32]
The table for combining a circumflex (xf6 ) with other characters.

int32 `dieresis_dead_key` [32]
The table for combining a dieresis (xac ) with other characters.

int32 `tilde_dead_key` [32]
The table for combining a tilde (xf7 ) with other characters

The tables are named after diacritical marks that can be placed on more than one character. However, the name is just a mnemonic; it means nothing. The contents of the table determine what the dead key is and how it combines with other characters. It would be possible, for example, to remap the `tilde_dead_key` table so that it had nothing to do with a tilde.

Each table consists of a series of up to 16 offset pairs—where, as in the case of the character maps, each offset picks a character from the chars character array. The first character in the pair is the one that must be typed immediately after the dead key. The second character is the resulting character, the character that's produced by the combination of the dead key plus the first character in the pair. For example, if the first character is 'o', the second might be 'ô'—meaning that the combination of a dead key plus the character 'o' produces a circumflexed 'ô'.

The character pairs for the default `grave_dead_key` array look something like this:

       > >, >'>,
       >A>, >À>,
       >E>, >È>,
       >I>, >Ì>,
       >O>, >Ò>,
       >U>, >Ù>,
       >a>, >à>,
       >e>, >è>,
       >i>, >ì>,
       >o>, >ò>,
       >u>, >ù>,
       . . .

By convention, the first offset in each array is to the `B_SPACE` character and the second is to the dead-key character itself. This pair does double duty: It states that the dead key plus a space yields the dead-key character, and it also names the dead key. The system understands what the dead key is from the second offset in the array.

##### Character tables for dead keys

As mentioned above, for a key to be dead, it must be mapped to the character picked by the second offset in a dead-key array. However, it's not typical for every key that's mapped to the character to be dead. Usually, there's a requirement that the user must hold down certain modifier keys (often the Option key). In other words, a key is dead only if selected character-map tables map it to the requisite character.

Five additional fields of the `key_map` structure specify what those character-map tables are—which modifiers are required for each of the dead keys:

uint32 `acute_tables
` The character tables that cause a key to be dead when they map it to the second character in the `acute_dead_key` array.

uint32 `grave_tables
` The character tables that cause a key to be dead when they map it to the second character in the `grave_dead_key` array.

uint32 `circumflex_tables
` The character tables that cause a key to be dead when they map it to the second character in the `circumflex_dead_key` array.

uint32 `dieresis_tables
` The character tables that cause a key to be dead when they map it to the second character in the `dieresis_dead_key` array.

uint32 `tilde_tables
` The character tables that cause a key to be dead when they map it to the second character in the `tilde_dead_key` array.

Each of these fields contains a mask formed from the following constants:

`B_CONTROL_TABLE` | `B_CAPS_SHIFT_TABLE`
`B_OPTION_CAPS_SHIFT_TABLE` | `B_CAPS_TABLE`
`B_OPTION_CAPS_TABLE` | `B_SHIFT_TABLE`
`B_OPTION_SHIFT_TABLE` | `B_NORMAL_TABLE`
`B_OPTION_TABLE` |

The mask designates the character-map tables that permit a key to be dead. For example, if the mask for the `grave_tables` field is,

       B_OPTION_TABLE | B_OPTION_CAPS_SHIFT_TABLE

a key would be dead whenever either of those tables mapped the key to the character of the second offset in the `grave_dead_key` array ('Q' in the example above). A key mapped to the same character by another table would not be dead.

See also: `get_key_info()`, `modifiers()`, the Keyboard Information appendix, `set_modifier_key()`

### get_key_repeat_delay() see set_key_repeat_rate()

### get_key_repeat_rate() see set_key_repeat_rate()

### get_keyboard_id()

Declared in: be/interface/InterfaceDefs.h

status_t `get_keyboard_id(`uint16 *id`)`

Obtains the keyboard identifier from the Application Server and device driver and writes it into the variable referred to by id. This number reveals what kind of keyboard is currently attached to the computer.

The identifier for the standard 101-key PC keyboard—and for keyboards with a similar set of keys—is 0x83ab.

If unsuccessful for any reason, `get_keyboard_id()` returns `B_ERROR`. If successful, it returns `B_OK`.

### modifiers()

Declared in: be/interface/InterfaceDefs.h

uint32 `modifiers(`void`) `

Returns a mask that has a bit set for each modifier key the user is holding down and for each keyboard lock that's set. The mask can be tested against these constants:

`B_SHIFT_KEY` | `B_COMMAND_KEY` | `B_CAPS_LOCK`
`B_CONTROL_KEY` | `B_MENU_KEY` | `B_SCROLL_LOCK`
`B_OPTION_KEY` |  | `B_NUM_LOCK`

No bits are set (the mask is 0) if no locks are on and none of the modifiers keys are down.

If it's important to know which physical key the user is holding down, the one on the right or the one on the left, the mask can be further tested against these constants:

`B_LEFT_SHIFT_KEY` | `B_RIGHT_SHIFT_KEY`
`B_LEFT_CONTROL_KEY` | `B_RIGHT_CONTROL_KEY`
`B_LEFT_OPTION_KEY` | `B_RIGHT_OPTION_KEY`
`B_LEFT_COMMAND_KEY` | `B_RIGHT_COMMAND_KEY`

By default, the keys closest to the space bar function as Command keys, no matter what their labels on particular keyboards. If a keyboard doesn't have Option keys (for example, a standard 101-key keyboard), the key on the right labeled "Control" functions as the right Option key, and only the left "Control" key is available to function as a Control modifier. However, users can change this configuration with the /bin/keymap application.

### set_key_repeat_rate() , get_key_repeat_rate() , set_key_repeat_delay() , get_key_repeat_delay()

Declared in: be/interface/InterfaceDefs.h

status_t `set_key_repeat_rate(`int32 rate`) `
status_t `get_key_repeat_rate(`int32 *rate`) `
status_t `set_key_repeat_delay(`bigtime_t delay`) `
status_t `get_key_repeat_delay(`bigtime_t *delay`) `

These functions set and report the timing of repeating keys. When the user presses a character key on the keyboard, it produces an immediate `B_KEY_DOWN` message. If the user continues to hold the key down, it will, after an initial delay, continue to produce messages at regularly spaced intervals—until the user releases the key or presses another key. The delay and the spacing between messages are both preferences the user can set with the Keyboard application.

`set_key_repeat_rate()` sets the number of messages repeating keys produce per second. For a standard PC keyboard, the rate can be as low as 2 and as high as 30; `get_key_repeat_rate()` writes the current setting into the integer that rate refers to.

`set_key_repeat_delay()` sets the length of the initial delay before the key begins repeating. Acceptable values are 250,000, 500,000, 750,000 and 1,000,000 microseconds (.25, .5, .75, and 1.0 second); `get_key_repeat_delay()` writes the current setting into the variable that delay points to.

All four functions return `B_OK` if they successfully communicate with the Application Server, and `B_ERROR` if not. It's possible for the `set`...`()` functions to communicate with the server but not succeed in setting the rate or delay (for example, if the delay isn't one of the listed four values).

### set_keyboard_locks()

Declared in: be/interface/InterfaceDefs.h

void `set_keyboard_locks(`uint32 modifiers`) `

Turns the keyboard locks—Caps Lock, Num Lock, and Scroll Lock—on and off. The keyboard locks that are listed in the modifiers mask passed as an argument are turned on; those not listed are turned off. The mask can be 0 (to turn off all locks) or it can contain any combination of the following constants:

`B_CAPS_LOCK`
`B_NUM_LOCK`
`B_SCROLL_LOCK`

See also: `get_key_map()`, `modifiers()`

### set_modifier_key()

Declared in: be/interface/InterfaceDefs.h

void `set_modifier_key(`uint32 modifier, uint32 key`) `

Maps a modifier role to a particular key on the keyboard, where key is a key identifier and modifier is one of the these constants:

`B_CAPS_LOCK` | `B_LEFT_SHIFT_KEY` | `B_RIGHT_SHIFT_KEY`
`B_NUM_LOCK` | `B_LEFT_CONTROL_KEY` | `B_RIGHT_CONTROL_KEY`
`B_SCROLL_LOCK` | `B_LEFT_OPTION_KEY` | `B_RIGHT_OPTION_KEY`
`B_MENU_KEY` | `B_LEFT_COMMAND_KEY` | `B_RIGHT_COMMAND_KEY`

The key in question serves as the named modifier key, unmapping any key that previously played that role. The change remains in effect until the default key map is restored. In general, the user's preferences for modifier keys—expressed in the Keymap application—should be respected.

Modifier keys can also be mapped by calling `get_key_map()` and altering the `key_map` structure directly. This function is merely a convenient alternative for accomplishing the same thing. (It's currently not possible to alter the key map; `get_key_map()` looks at a copy.)

The Input Server Table of Contents | The Input Server Index

The Be Book,
...in lovely HTML...
for BeOS Release 5.

Copyright © 2000 Be, Inc. All rights reserved..