BEAM SCREEN READER API

Overview of BEAM Screen Reader API

Introduction

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.