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

See also: BWindow::WorkspaceActivated()


adjust_crt() see get_screen_info()


count_font_families() see get_font_family()


count_font_styles() see get_font_style()


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


get_click_speed() see set_click_speed()


get_font_cache_info(), set_font_cache_info()


      status_t get_font_cache_info(uint32 mode, void *info)

      status_t set_font_cache_info(uint32 mode, void *info)

< Documentation on the font cache will be available soon. >


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. 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() (and count_font_styles() ). Family and style names can be up to 64 bytes long including a null terminator. Indices begin at 0.

count_font_families() returns the number of font families currently installed, and count_font_styles() returns the number of styles for a particular family.

The names of installed font families and styles are not indexed in any particular order (for example, they're not alphabetized). You might want to alphabetize them before displaying them in a menu or list.

Both get_font_family() and get_font_style() can provide a set of flags with useful information about the particular family or style. Currently there's just one flag, B_HAS_TUNED_FONT , and each of the functions provides it. The flag indicates that the family or style has versions of the font especially adapted or "tuned" for on-screen display.

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:

The following sections describe each part of the key_map structure in turn.

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.Modifier Keys

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