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.
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.
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:
Top level application window
Displays a label on the screen
A single line text entry box
A multiple line text entry box
A push button
A toggle button
A list of items
A container holding other objects
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:
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:
The object type
A label for the object
Some textual information about the object
The X,Y position in pixels of the object relative to the applications top level window
The width and height of the object in pixels
Object is mapped onto the display
This is a major display object (not a frame etc.) normally a bottom of tree object
The contents can be changed by the user, ie not a fixed display
When the application changes the object to which keyboard entry is directed, this event is generated.
When a text cursor is moved, or redrawn this event is generated
When a window is displayed onto the screen, this event is generated
When a window is withdrawn from the screen, this event is generated.
When the text displayed is changed, this event is generated.
When an objects children list has changed, this event is generated.