The Interface Kit: Global Functions

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

The Application Server maintains this environment (with just a few exceptions). 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_app()

Declared in: <interface/InterfaceDefs.h>

      void activate_app(team_id app)

Activates the app application < by bringing one of its windows to the front and making it the active window >. This function works only if the target application has a window on- screen. The newly activated application is notified with a B_APP_ACTIVATED message.

< This function is an alternative to sending the application a B_ACTIVATE message. It accomplishes the same thing, except that it communicates directly with the Application Server to do its work. >

See also: BApplication::Activate() in the Application Kit


activate_workspace(), current_workspace()

Declared in: <interface/InterfaceDefs.h>

      void activate_workspace(long workspace)
      long current_workspace(void)

These functions set and return the active workspace, the one that's currently displayed on- screen. Each workspace is represented by a bit in a long integer.

See also: BWindow::WorkspaceActivated()


adjust_crt() see get_screen_info()


count_fonts() see get_font_name()


count_screens() see get_screen_info()


count_symbol_sets() see get_symbol_set_name()


count_workspaces() see set_workspace_count()


current_workspace() see activate_workspace()


desktop_color() see set_desktop_color()


get_click_speed() see set_click_speed()


get_dock_width()

Declared in: <interface/InterfaceDefs.h>

      long get_dock_width(float *width)

Writes the current width of the dock into the variable referred to by width. Since the dock floats on top of other windows, this function can help determine how much usable screen space is actually available. It returns B_NO_ERROR if successful and B_ERROR if not.

See also: get_screen_info()


get_font_name(), count_fonts()

Declared in: <interface/InterfaceDefs.h>

      void get_font_name(long index, font_name *name)
      long count_fonts(void)

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

   long numFonts = count_fonts();
   font_name buf;
   
   for ( long i = 0; i < numFonts; i++ ) {
       get_font_name(i, &buf);
       . . .
   }

The names of all installed fonts are kept in an alphabetically ordered list. get_font_name() reads one of the names from the list, the name at index, and copies it into the name buffer. Font names can be up to 64 characters long, plus a null terminator. Indices begin at 0.

count_fonts() returns the number of fonts currently installed, the number of names in the list.

See also: BView::GetFontInfo(), BView::SetFontName()


get_key_repeat_delay() see set_key_repeat_rate()


get_key_repeat_rate() see set_key_repeat_rate()


get_keyboard_id()

Declared in: <interface/InterfaceDefs.h>

      long get_keyboard_id(ushort *theId)

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

The identifier for the standard 101-key keyboard--and for keyboards with a similar set of keys--is 0x83ab. < Currently, this is the only value this function can provide. > See Key Codes for illustrations showing the keys found on a standard keyboard.

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


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


get_screen_info(), count_screens()

Declared in: <interface/InterfaceDefs.h>

      void get_screen_info(screen_info *theInfo)
      void get_screen_info(long index, screen_info *theInfo)

      long count_screens(void)
      long set_screen_space(long index, ulong space, bool makeDefault = TRUE)
      long set_screen_refresh_rate(long index, float rate, bool makeDefault = TRUE)
      long adjust_crt(long index, uchar hPosition, uchar vPosition, 
         uchar hSize, uchar vSize, bool makeDefault = TRUE)

These functions provide information about the screens (monitors) that are currently hooked up to the BeBox, and alter screen parameters.

Each screen that's attached to the machine is identified by an index into a system-wide screen list. The screen at index 0 is the one that has the origin of the screen coordinate system at its left top corner. Other screens in the list are unordered; they're located elsewhere in the coordinate system that the first screen defines. < Currently, multiple screens are not supported, so the screen at index 0 is the only one in the list. Therefore, the index passed to these functions should always be 0. >

count_screens() returns the number of screens (monitors) that are attached to the computer. < Since no more than one screen can be attached, this function currently always returns 1. >

get_screen_info() writes information about the screen at index into the screen_info structure referred to by theInfo. If no index is mentioned, it assumes the screen at index 0. The screen_info structure contains the following fields:

color_space mode The depth and color interpretation of pixel data in the screen's frame buffer; currently, the mode will be either B_COLOR_8_BIT or B_RGB_32_BIT. (See Colors of the chapter introduction for an explanation of the various color_space modes.)
BRect frame The frame rectangle of the screen--the rectangle that defines the size and location of the screen in the screen coordinate system.
ulong spaces A mask that enumerates all the possible configurations of the screen space. The consonant values that can contribute to the mask are listed below.
float min_refresh_rate The maximum possible refresh rate in cycles per second.
float max_refresh_rate The minimum possible refresh rate (which may be the same as the maximum).
float refresh_rate The current refresh rate.
uchar h_position The current horizontal position of the CRT display on the monitor, a value between 0 (as far to the left as possible) and 100 (as far to the right as possible) with 50 as the default.
uchar v_position The current vertical position of the CRT display on the monitor, a value between 0 (as close to the top as possible) and 100 (as close to the bottom as possible) with 50 as the default.
uchar h_size The current horizontal size of the CRT display on the monitor, a value between 0 (as narrow as possible) and 100 (as wide as possible) with 50 as the default.
uchar v_size The current vertical size of the CRT display on the monitor, a value between 0 (as short as possible) and 100 (as tall as possible) with 50 as the default.

If the color space mode is B_COLOR_8_BIT, each pixel value in the frame buffer for the screen is an 8-bit color index. In B_RGB_32_BIT mode, each value is a set of four 8-bit color components (red, green, blue, and alpha). The components will be arranged in the most natural order for the display device--typically blue, green, red, and alpha. You can access the frame buffer only through the BWindowScreen class in the Game Kit.

The spaces field is a mask that enumerates all the possible configurations of the screen space (its depth and dimensions). It's formed from the following constants:

B_8_BIT_640x400
B_8_BIT_640x480 B_16_BIT_640x480 B_32_BIT_640x480
B_8_BIT_800x600 B_16_BIT_800x600 B_32_BIT_800x600
B_8_BIT_1024x768 B_16_BIT_1024x768 B_32_BIT_1024x768
B_8_BIT_1152x900 B_16_BIT_1152x900 B_32_BIT_1152x900
B_8_BIT_1280x1024 B_16_BIT_1280x1024 B_32_BIT_1280x1024
B_8_BIT_1600x1200 B_16_BIT_1600x1200 B_32_BIT_1600x1200

For example, if the mask includes B_32_BIT_1280x1024, the frame buffer can be 32 bits deep (the B_RGB_32_BIT color space) while the screen grid is 1,280 pixels wide and 1,024 pixels high. Not all configurations are possible for all graphics cards. < The operating system currently doesn't support depths of 16 bits. >

The current screen configuration can be read from the mode and frame fields. To change the configuration, you can pass one of the spaces constants to set_screen_space(). When the configuration of the screen changes, every affected BWindow object is notified with a ScreenChanged() function call. < Since there's currently only one screen, all windows are affected and all, whether on-screen or hidden, receive ScreenChanged() notifications. >

The refresh rate for the screen can be changed by passing a new rate to set_screen_refresh_rate(). The rate should lie between the minimum and maximum reported by get_screen_info(). The requested change is made to the best of the ability of the graphics card driver; exact compliance is not promised.

The h_position, v_position, h_size, and v_size fields of the screen_info structure record the placement of the CRT display on the physical monitor, as set by software controls --not the hardware controls on the monitor itself. If the monitor and the driver for the graphics card permit CRT adjustments through software, adjust_crt() can be called to change any setting. Its hPosition, vPosition, hSize, and vSize arguments have the same meaning as the corresponding fields of screen_info.

The three functions that alter screen parameters--adjust_crt() , set_screen_space(), and set_screen_refresh_rate() --all make changes that take effect immediately. If the makeDefault flag is TRUE, the new setting also becomes the default and will be used the next time the machine is turned on. If makeDefault is FALSE , the setting is in effect for the current session only. Each function returns B_NO_ERROR if successful, and B_ERROR if not.

These three functions are designed for preferences applications--like the Screen application--that permit users to make system-wide choices. Other applications should respect those choices and refrain from modifying them.

get_screen_info() reports on the screen as it is known to the Application Server. If you bypass the Server with the Game Kit, it may not provide accurate information.

See also: BWindow::ScreenChanged(), The Game Kit chapter


get_scroll_bar_info() see set_scroll_bar_info()


get_symbol_set_name(), count_symbol_sets()

Declared in: <interface/InterfaceDefs.h>

      void get_symbol_set_name(long index, symbol_set_name *name)
      long count_symbol_sets(void)

These functions are used to get the names of all available symbol sets. They work much like the parallel font functions get_font_name() and count_fonts().

A symbol set associates character symbols (glyphs) with character codes (ASCII values). They differ mainly in how they extend the standard ASCII set--how they assign characters to codes above 0x7f.

get_symbol_set_name() gets one name from the list of symbol sets, the name at index, and copies it into the name buffer. count_symbol_sets() returns the total number of symbol sets (the number of names in the list).

Unlike font names, the names of symbol sets are not arranged alphabetically.

Every font implements every symbol set. However, some fonts implement particular sets more fully than others--that is, some characters in a symbol set may not be available in some fonts. But the position of each character in the set (its character code) remains the same across all fonts.

See also: BView::SetSymbolSet(), get_font_name()


idle_time()

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


index_for_color()

Declared in: <interface/InterfaceDefs.h>

      uchar index_for_color(rgb_color aColor)
      uchar index_for_color(uchar red, uchar green, uchar blue, uchar alpha = 0)

Returns an index into the list of 256 colors that comprise the B_COLOR_8_BIT color space. The value returned picks out the listed color that most closely matches a full 32-bit color--specified either as an rgb_color value, aColor, or by its red, green , and blue components. < (The alpha component is currently ignored.) >

The returned index identifies a color in the B_COLOR_8_BIT color space. It can, for example, be passed to BBitmap's SetBits() function.

To find the fully specified color that an index picks out, you have to get the color list from the system color map. For example, if you first obtain the index for the "best fit" color that most closely matches an arbitrary color,

   uchar index