The Interface Kit: Global Functions

The Interface Kit Table of Contents | The Interface Kit Index

# Global Functions

Library: libbe.so

This section describes the global C functions defined in the Interface Kit. All these functions deal with aspects of the systemwide environment for the user interface—the screen, workspaces, installed fonts, the list of possible colors, and various user preferences. For mouse and keyboard functions, see "Input Server Environment Functions".

In almost all cases, you need a valid (but not necessarily running) `be_app` object in order to call these functions.

### activate_workspace() , current_workspace()

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. The workspace is identified by an index, 0-based.

See also: `BWindow::WorkspaceActivated()`

### bitmaps_support_space()

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.

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

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.

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

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

### get_key_repeat_delay() see set_key_repeat_rate()

### get_key_repeat_rate() see set_key_repeat_rate()

### get_key_info() see get_key_info()

### get_key_map() see get_key_map()

### get_menu_info() see set_menu_info()

### get_pixel_size_for()

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

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

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()set_scroll_bar_info()` tells you when the user last directed an action at any application, not just yours.

### keyboard_navigation_color()

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

### modifiers() see modifiers()

### run_add_printer_panel() , run_select_printer_panel()

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

### set_click_speed() see set_click_speed()

### set_key_repeat_rate() see set_key_repeat_rate()

### set_keyboard_locks() see set_keyboard_locks()

### set_menu_info() , get_menu_info()

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

### set_modifier_key() see set_modifier_key()

### set_mouse_map() see set_mouse_map()

### set_screen_space()

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

### set_scroll_bar_info() , get_scroll_bar_info()

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

### set_workspace_count() , count_workspaces()

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

### system_colors()

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

### update_font_families()

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 Interface Kit Table of Contents | The Interface Kit Index

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

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