Home information products services support downloads


    Overview of BEAM Screen Reader API


The purpose of the BEAM Screen Reader API (BSRAPI) is to provide a screen reader with information regarding the graphical user interface (GUI) of running applications.


The main features for the BEAM Screen Reader API (BSRAPI) include:
  • Application GUI independent: The BSRAPI has been made independent on the particular GUI in use. This will allow functionality with the current GUI tool kits such as Motif, Xt, KDE, Gnome and TK with an appropriate GUI tool kit interface module.
  • Can use information from the tool kit in use or directly from the application. This enables easy retrofit to existing applications with simple GUI tool kit library changes. For critical applications, the application can take over or modify the tool kit interface for a more sophisticated interface.
  • Can be used with applications not using a GUI such as ASCII terminal based applications.
  • Independent of the X-Windows system and platform independent.

Technical Overview

The BSRAPI system consists a client application shared library, GUI tool kit interface libraries and a screen reader server module.
When an application is invoked, the GUI tool kit or application initialises the BSRAPI. This attempts to connect to a screen reader on the host which is providing the GUI. Once connected the screen reader can ask the application for information on the GUI using the BSRAPI. It can also ask for events to be sent on certain conditions, such as a change in keyboard focus.

Picture showing code modules in use

Information Requests

The GUI is described as a set of generic objects. These can be accessed either in hierarchical form to match the typical GUI object layout or in viewable 2D forms. The object types provided include:
Object Usage
Window Top level application window
Label Displays a label on the screen
TextLine A single line text entry box
Text A multiple line text entry box
Button A push button
ButtonToggle A toggle button
List A list of items
Selection A selection
Container A container holding other objects
Table A table object

Each object has an application unique id and has a number of attributes. The Object ID 0 is a special case defining the whole application. Within this object will be the applications main top level windows. The following functionality is provided:
Function Usage
List GetObjects(ID id) Gets a list of the objects contained within the given object id.
List GetObjectLine(ID id) Gets a list of the objects on the given line
Text GetTextLine(ID id, int line) Gets a line of text from the objects data
ObjInfo GetInfo(ID id) Gets generic info on the object. Includes: type, label, position, size etc
String GetParam(ID id, String paramName) Gets the value of a named parameter from the object
Event EnableEvents(EventMask mask) Enable the given events to be generated

An objects state, as returned by GetInfo() includes the following attributes:
Object State Usage
Type The object type
Label A label for the object
Information Some textual information about the object
Position The X,Y position in pixels of the object relative to the applications top level window
Size The width and height of the object in pixels
Mapped Object is mapped onto the display
Main This is a major display object (not a frame etc.) normally a bottom of tree object
Editable The contents can be changed by the user, ie not a fixed display


Event Usage
KeyboardFocus When the application changes the object to which keyboard entry is directed, this event is generated.
TextCursor When a text cursor is moved, or redrawn this event is generated
WindowMapped When a window is displayed onto the screen, this event is generated
WindowUnMapped When a window is withdrawn from the screen, this event is generated.
TextChanged When the text displayed is changed, this event is generated.
StructureChange When an objects children list has changed,  this event is generated.