Re: [orca-list] Browsing Orca

[Jon <j orcauser googlemail com>]

Hi Jason,

Your description sounds plausible, and if it was confirmed by one of the 
developers that would be really great.

Maybe we should start a section on the wiki for those who are intrested 
in learning about the Orca source, an introduction to developers 
section, where anything that might be useful to a new developer is put. 
That way they wouldnt have to search through the mail archives for 
golden nuggets.


hope this suggestion is reasonable.

Thanks

-Jon
On Sun 23/03/2008 at 18:38:32, Jason White wrote:
> 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-list gnome org
> http://mail.gnome.org/mailman/listinfo/orca-list
> Visit http://live.gnome.org/Orca for more information on Orca