[orca-list] Browsing Orca

[Jason White <jason jasonjgw net>]

I set aside some time last night to start browsing the Orca sources. For other
Orca users who are doing this (or planning to do it), I thought I would offer
a few, perhaps obvious, points of interest.

The best place to start is the main() function in orca.py, which processes the
command line arguments, initializes the user settings (including starting up
speech, braille, etc.), selects the focus tracking presentation manager and
finally invokes registry.start(), which calls the presentation manager
whenever an event occurs. After the registry.start() method terminates, we're
finished.

Note that registry.start() is part of pyatspi. Once this is invoked, Orca
(specifically, the presentation manager - see below) will be called whenever
AT-SPI detects an event. When an event takes place, an Orca
function registered with AT-SPI is invoked, and passed an event object as its
argument. In the case of events generated by AT-SPI, this object includes a
field that indicates the type of event, specified as a string. It is this
event type which determines, for the most part, where the event is handled.

The real work of handling events is delegated to a script. There are various
types of events: changes to the objects displayed on screen by an application,
the creation of windows, mouse clicks, key presses and releases, the
activation of controls on a braille display, and so on. The presentation
manager (mentioned above) is responsible for loading scripts, registering
events with AT-SPI in which the scripts have declared an interest, selecting
the active script and, importantly, the initial handling of events before they
are forwarded to the active script. Some events are handled internally by the
presentation manager. For example, in _processObjectEvent(), when a
window:activate event occurs, the active script is changed, if there is one
available for the application that has opened the window. If you want to see
what happens when the presentation manager is started, read the
focusTrackingPresenter.activate() method.

For efficiency, events are placed in a queue, and a separate thread invoked by
GTK calls focusTrackingPresenter._dequeueEvent() to process them. Somewhere, I
presume, GTK is started up, but I haven't tracked down exactly how this is
ensured.

Anyway, the majority of the work of handling events takes place in a script.
If Orca doesn't find a specific script for the application, it selects the
default script, which you can read in default.py. Note that the Script class
is, in fact, a subclass of script.Script, which, as the module name reveals,
is in the script.py file. I would suggest reading the base class (in
script.py) first, to gain an overview of what functionality the scripts
provide. It is also worth noting that specialized scripts, an example of which
is in Gecko.py, can be subclasses of default.Script. Indeed, writing a
subclass of default.Script may be the best way to proceed if you're an
aspiring Orca script writer, as you wouldn't want to rewrite all the
functionality provided by the default script, would you, especially when class
inheritance will give it to you for free? Incidentally, Gecko.py is the
Firefox 3 support.

The calling of functions in the script that handle events of different types
is controlled by methods in script.py, which in turn are called by
corresponding methods in focusTrackingPresenter as each event is removed from
the queue. (Since the event-handling methods in script.py are not overridden
in default.py, the versions in script.py are called). See
processKeyboardEvent(), processBrailleEvent() and processObjectEvent() in
script.py for details of how keyboard, braille and object events,
respectively, are processed. In these methods, the handler functions that
actually do most of the work in response to events are looked up and called.

To avoid potential misconceptions, it should also be observed that not all
events are processed by a script, or by the presentation manager itself. The
orca module (in orca.py), for example, registers an interest in keyboard
events; this is how key echo (the speaking of keys as they are pressed) is
implemented. See the init() function for details. Similarly, 
_onChildrenChanged (again in orca.py) is called by "object:children-changed"
events: it checks whether the desktop is empty (the user has logged out, as
explained in the comment), and if so, shuts down Orca.

I know this hardly digs below the surface, but I hope I haven't committed too
many serious inaccuracies, and that this kind of discussion is helpful to
others who may be tempted to start familiarizing themselves with the Python
source files.

In general, everything is written in a clear style, with good comments in the
code and Python documentation strings to explain the purposes of the various
classes, functions and methods. Meticulous attention is paid to the handling
of exceptions and to ensuring that Orca doesn't hang. Debugging functions are
called frequently to provide a detailed report of what is going on. If you
have ever wondered why the debugging output from Orca is so voluminous, it is
entirely due to the careful inclusion of code that generates debugging
messages in so many relevant places. Of course, the messages are only produced
if debugging has been turned on in your ~/.orca/user-settings.py file.

In short, this is excellent work by serious experts.