# The Interface Kit: Global Functions

Library: libbe.so

This section describes the global (nonmember) functions defined in the Interface Kit. All these functions deal with aspects of the systemwide environment for the user interface--the keyboard and mouse, the screen, workspaces, installed fonts, the list of possible colors, and various user preferences.

With just a few exceptions, the Application Server maintains this environment. Therefore, for a global Interface Kit function to work, your application must be connected to the server. The connection these functions depend on is the one that's established when the BApplication object is constructed. Consequently, none of them should be called before a BApplication object is present in your application.

### activate_workspace(), current_workspace()

          void activate_workspace(int32 workspace)

          int32 current_workspace(void)

These functions set and return the active workspace, the one that's currently displayed on-screen. For both functions, the workspace is identified by an index. The indices follow the function keys, at least for the first nine workspaces: CommandF1 switches to the workspace at index 0, Command-F2 to the workspace at index 1, and so on.

See also: `BWindow::WorkspaceActivated()`

### count_font_families() see get_font_family()

### count_font_styles() see get_font_style()

### count_workspaces() see set_workspace_count()

### current_workspace() see activate_workspace()

### get_click_speed() see set_click_speed()

### get_font_family(), count_font_families(), get_font_style(), count_font_styles()

          status_t get_font_family(int32 index, font_family *family,
             uint32 *flags = NULL)

          int32 count_font_families(void)

          status_t get_font_style(font_family family, int32 index, font_style *style,
             uint32 *flags = NULL)

          int32 count_font_styles(font_family family)

These functions are used in combination to get the names of the families and styles of all installed fonts. For example:

       int32 numFamilies = count_font_families();
       for ( int32 i = 0; i < numFamilies; i++ ) {
           font_family family;
           uint32 flags;
           if ( get_font_family(i, &family, &flags) == B_OK ) {
               . . .
               int32 numStyles = count_font_styles(family);
               for ( int32 j = 0; j < numStyles; j++ ) {
                   font_style style;
                   if ( get_font_style(family, j, &style, &flags)
                                                     == B_OK ) {
                       . . .
                   }
               }
           }
       }

`get_font_family()` reads one family name from the list of installed fonts, the name at index, and copies it into the family buffer; `count_font_families()` returns the number of font families currently installed. Similarly, `get_font_style()` reads the name of the style at index and copies into the style buffer. Since each family can have a different set of styles, a family name must be passed to `get_font_style()`; `count_font_styles()` returns the number of styles for the particular family. Family and style names can be up to 64 bytes long including a null terminator. Indices begin at 0.

The names of installed font families and styles are not indexed in any particular order. You might want to alphabetize them before displaying them to the user in a menu or list.

If you pass a flags argument to `get_font_family()` and `get_font_style()`, they will place a mask with useful information about the particular family or style in the variable that the argument refers to. Currently there are just two flags:

`B_IS_FIXED` | Indicates that the font is a nonproportional, or fixed-width, font--one for which all characters have the same width.
`B_HAS_TUNED_FONT` | Indicates that the family or style has versions of the font especially adapted or "tuned" for on-screen display.

If neither flag applies, the variable that flags points to will be set to 0.

If you find a family and style that has a tuned font, you can set a BFont object to that family and style, then call the object's `GetTunedInfo()` function to get details about exactly which combination of font properties (for example, which font sizes) have tuned counterparts. If you set a BFont so that it has those properties and make it a BView's current font, the tuned version will be used when the BView draws to the screen.

It's possible for the user to install or remove fonts while the application is running. However, unless `update_font_families()` has been called to get the updated list, `get_font_family()` will provide information on the same set of fonts each time it's called. The list isn't automatically updated.

See also: `update_font_families()`, `BView::SetFont()`, `BFont::SetFamilyAndStyle()`

### get_key_info()

          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 permits you to 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()

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

Provides a pointer to the system key map--the structure that describes the role of each key on the keyboard. The key map is shared by all applications; you can read from this structure, but should not alter it.

Through the Keymap preferences application, users can configure the keyboard to their liking. The user's preferences are stored in a file (/system/settings/Key_map). 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 keys 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 (by writing it to a file that replaces /system/settings/Key_map).

##### 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 encodes values over 127.

The chars array represents each character as apascal 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:

       \\x03\\xE2\\x84\\xA2

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

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()

          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`.

### get_menu_info() see set_menu_info()

### get_mouse_map() see set_mouse_map()

### get_mouse_speed() see set_mouse_map()

### get_mouse_type() see set_mouse_map()

### set_scroll_bar_info()

### idle_time()

          bigtime_t idle_time(void) const

Returns the number of microseconds since the user last manipulated the mouse or keyboard. This information isn't specific to a particular application; `idle_time()` tells you when the user last directed an action at any application, not just yours.

### keyboard_navigation_color()

          rgb_color keyboard_navigation_color(void)

Returns the color that should be used to mark the BView that's currently in focus, when the user can change the focus from the keyboard. The keyboard navigation color is typically used to underline the labels of control devices and to outline text fields where the user can type.

See also: the BView class

### modifiers()

          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 closes 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 Keymap application.

See also: "Modifier Keys" in the Keyboard Information appendix, `get_key_map()`, `get_key_info()`

### run_add_printer_panel(), run_select_printer_panel()

          void run_add_printer_panel(void)

          void run_select_printer_panel(void)

These two functions have the Print Server place panels on-screen where the user can set up a printer and choose which printer to use. `run_add_printer_panel()` displays a panel that informs the server about a new printer. `run_select_printer_panel()` displays a panel that lists all known printers and lets the user select one.

See also: the BPrintJob class

### set_click_speed(), get_click_speed()

          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`.

See also: `set_mouse_map()`

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

          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()

          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_menu_info(), get_menu_info()

          status_t set_menu_info(menu_info *info)

          status_t get_menu_info(menu_info *info)

These functions set and get the user's preferences for how menus should look and work. User's express their preferences with the Menu application, which calls `set_menu_info()`. `get_menu_info()` writes the current preferences into the `menu_info` structure that into refers to. This structure contains the following fields:

float `font_size
` The size of the font that will be used to display menu items.

font_name `font
` The name of the font that's used to display menu items.

rgb_color `background_color
` The background color of the menu.

int32 `separator
` The style of horizontal line that separates groups of items in a menu. The value is an index ranging from 0 through 2; there are three possible separators.

bool `click_to_open
` Whether it's possible to open a menu by clicking in the item that controls it. The default value is `true`.

bool `triggers_always_shown
` Whether trigger characters are always marked in menus and menu bars, regardless of whether the menu hierarchy is the target for keyboard actions. The default value is `false`.

(At present, both functions always return `B_OK`.)

See also: the BMenu class

### set_modifier_key()

          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.)

See also: `get_key_map()`

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

          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 acceleration)

          status_t get_mouse_speed(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 acceleration of the cursor image on-screen relative to the actual speed at which the user moves the mouse on its pad. An acceleration value of 0 means no acceleration. The maximum acceleration is 20, though even 10 is too fast for most users. `set_mouse_speed()` 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.

### set_screen_space()

          status_t set_screen_space(int32 index, uint32 space, bool makeDefault = true)

Changes the configuration of the screen--its depth and dimensions--to match the values specified in the space constant, which can be any of the following:

`B_8_BIT_640x400` |  |  |
`B_8_BIT_640x480` | `B_15_BIT_640x480` | `B_16_BIT_640x480` | `B_32_BIT_640x480`
`B_8_BIT_800x600` | `B_15_BIT_800x600` | `B_16_BIT_800x600` | `B_32_BIT_800x600`
`B_8_BIT_1024x768` | `B_15_BIT_1024x768` | `B_16_BIT_1024x768` | `B_32_BIT_1024x768`
`B_8_BIT_1152x900` | `B_15_BIT_1152x900` | `B_16_BIT_1152x900` | `B_32_BIT_1152x900`
`B_8_BIT_1280x1024` | `B_15_BIT_1280x1024` | `B_16_BIT_1280x1024` | `B_32_BIT_1280x1024`
`B_8_BIT_1600x1200` | `B_15_BIT_1600x1200` | `B_16_BIT_1600x1200` | `B_32_BIT_1600x1200`

The first part of the constant designates the screen depth and color space. `B_8_BIT`... refers to the `B_CMAP8` color space. The other values correspond to the `B_RGB15`, `B_RGB16`, and `B_RGB32` color spaces, as appropriate. Although constants are defined for 15-bit screen depths, the operating system currently doesn't support them. The second part of the constant designates the pixel resolution of the screen. For example, `B_32_BIT_1280x1024` means that the frame buffer is 32 bits deep (`B_RGB32`) while the screen grid is 1,280 pixels wide and 1,024 pixels high.

This function affects the screen at index. Since the BeOS currently doesn't support more than one screen, the only index that makes sense is 0.

The change to the screen takes effect immediately. If the makeDefault flag is `true`, the new configuration also becomes the default and will be used the next time the machine is turned on. If makeDefault is `false`, the configuration is in effect for the current session only.

Since not all configurations are possible for all graphics cards, `set_screen_space()` can fail. It returns `B_OK` if successful, and `B_ERROR` if not.

This function is designed for preferences applications--like the Screen application--that permit users to make system-wide choices about the screen. Other applications should respect those choices and refrain from modifying them.

The current screen configuration can be obtained from the BScreen object.

See also: the BScreen class, `BWindow::ScreenChanged()`, The Game Kit chapter

### set_scroll_bar_info(), get_scroll_bar_info()

          status_t set_scroll_bar_info(scroll_bar_info *info)

          status_t get_scroll_bar_info(scroll_bar_info *info)

These functions set and report preferences that the BScrollBar class uses when it creates a new scroll bar. `set_scroll_bar_info()` reads the values contained in the `scroll_bar_info` structure that info refers to and sets the system-wide preferences accordingly; `get_scroll_bar_info()` writes the current preferences into the structure provided.

The `scroll_bar_info` structure contains the following fields:

bool `proportional
true` if scroll bars should have a knob that grows and shrinks to show what proportion of the document is currently visible on-screen, and `false` if not. Scroll knobs are proportional by default.

bool `double_arrows
true` if a set of double arrows (for scrolling in both directions) should appear at each end of the scroll bar, or `false` if only single arrows (for scrolling in one direction only) should be used. Double arrows are the default.

int32 `knob
` An index that picks the pattern for the knob. Only values of 0, 1, and 2 are currently valid. The patterns can be seen in the ScrollBar preferences application. The pattern at index 1 is the default.

int32 `min_knob_size
` The length of the scroll knob, in pixels. This is the minimum size for a proportional knob and the fixed size for one that's not proportional. The default is 15.

The user can set these preferences with the ScrollBar application. Applications can call `get_scroll_bar_info()` to find out what choices the user made, but should refrain from calling `set_scroll_bar_info()`. That function is desigined for utilities, like the ScrollBar application, that enable users to set preferences that are respected system-wide.

If successful, these functions return `B_OK`; if not, they return `B_ERROR`.

See also: the BScrollBar class

### set_workspace_count(), count_workspaces()

          void set_workspace_count(int32 numWorkspaces)

          int32 count_workspaces(void)

These functions set and return the number of workspaces the user has available. There can be as many as 32 workspaces and as few as 1. The choice of how many there should be is usually left to the user and the Workspaces application.

See also: `activate_workspace()`

### system_colors()

          const color_map *system_colors(void)

Returns a pointer to the system color map. This function duplicates the BScreen `ColorMap()` function, but it permits software that isn't concerned about the on-screen display to get the color map without referring to a particular screen. (Actually it returns the color map for the main screen.)

The `color_map` structure returned by this function belongs to the operating system.

See also: `BScreen::ColorMap()`

### update_font_families()

          bool update_font_families(bool checkOnly)

Updates the list of installed fonts, so that it reflects any that have been added or removed since the last time the list was updated. Until the list is updated, `get_font_family()` operates assuming the set of fonts that were installed when the application started up. If the list is unchanged since the last update (or since startup), this function returns `false`; if a font has been installed or an installed font has been removed, it returns `true`.

If the checkOnly flag is `true`, `get_font_family()` only reports whether the list has changed; it doesn't modify the current list. If the flag is `false`, it contacts the Application Server to get the updated list, a much more expensive operation.

See also: `get_font_family()`

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

Copyright © 1998 Be, Inc. All rights reserved.

Last modified March 26, 1998.