Browsing Orca

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.

_______________________________________________
Orca-list mailing list
Orca-listgnome.org
http
://mail.gnome.org/mailman/listinfo/orca-list
Visit http://live.gnome.org/Orca
 for more information on Orca

Browsing Orca

Thread: Browsing Orca