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