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.
Declared in: be/interface/InterfaceDefs.h
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()
Declared in: be/interface/GraphicsDefs.h
bool bitmaps_support_space(color_space space, uint32 *supportFlags)
Returns true if BBitmaps can contain graphics in the specified color space, or false if not.
The uint32 pointed to by supportFlags will be set to a bit field of flags, further describing the support for the specified color space by the BBitmap class. The flags are:
| B_VIEWS_SUPPORT_DRAW_BITMAP | BView::DrawBitmap() supports drawing BBitmaps of the specified color space. |
| B_BITMAPS_SUPPORT_ATTACHED_VIEWS | Indicates that BBitmaps in the specified color space support attached BViews. |
Declared in: be/interface/InterfaceDefs.h
status_t get_deskbar_frame(BRect *frame)
Writes the screen coordinates of the current frame of the Deskbar window into frame. Returns B_OK on success or an appropriate error code on failure.
Declared in: be/interface/Font.h
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()
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 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()
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.
|
This is a change in behavior since BeOS Release 3--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 (/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:
The following sections describe the parts of the key_map structure.
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.
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.
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).
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:
These pairings are important for a special rule that applies to keys on the numerical keypad when Num Lock is on:
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.
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.
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()
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.
Declared in: be/interface/GraphicsDefs.h
status_t get_pixel_size_for(color_space space, size_t *pixelChunk,
size_t *rowAlignment, size_t *pixelsPerChunk)
Given the specified color space, returns information about pixel and row alignment for that color space.
On return, pixelChunk indicates
Declared in: be/interface/InterfaceDefs.h
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.
Declared in: be/interface/InterfaceDefs.h
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
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 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()
Declared in: be/interface/InterfaceDefs.h
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
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.
See also: set_mouse_map()
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).
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()
Declared in: be/interface/Menu.h
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
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.)
See also: get_key_map()
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 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.
Declared in: be/interface/InterfaceDefs.h
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
Declared in: be/interface/InterfaceDefs.h
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
Declared in: be/interface/InterfaceDefs.h
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()
Declared in: be/interface/InterfaceDefs.h
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()
Declared in: be/interface/Font.h
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 4.
Copyright © 1998 Be, Inc. All rights reserved.
Last modified December 23, 1998.