[Kde-accessibility] Re: Documentation about ATK and AT-SPI

[Bill Haneman]

Hi Gunnar:

Thanks very much for this well constructed overview.  It really looks
great - in fact with your permission I may wish to link to it (once
final) from our GNOME site since it is in many ways a more concise
summary than anything we have there.

There are a few minor refinements which I'd suggest.

in "Introduction:"

	- instead of "GNOME Applications and the GNOME Desktop" you might just
say "applications" and "the user's 'desktop'" since we tried to make it
as general as we could from the outset, while still taking advantage of
software reuse.  After all, it works with StarOffice, Java, and Mozilla
now, and only the broadest interpretation of "GNOME Desktop" includes
all of those pieces.

"Overview of the Architecture" : the word "daemon" is misspelled.

"An Overview Of The Interface"

Instead of "... for each widget in the interface", I'd say "for each
user-visible component in the interface".  Because some widgets
don't have AtkObjects, and some, like tables, have multiple
Accessible/AtkObject(s) associated with them.
	
One thing you didn't mention was the interface "AtkObjectIface" which 
is a special interface which allows objects which aren't subtypes of
AtkObject to still act like them.  This is a sort of advanced detail so 
perhaps it's OK just to put this in a footnote.  It might turn out to be
a useful feature for KDE however.

"The Interface Registry Within AT-SPI"

In addition to the 'register/deregisterApplication' methods, the
'notifyEvent' method is of interest to applications since either they or
their "bridges" must call "Registry.notifyEvent" in order to send
event notifications to interested clients.  Similarly the applications
are responsible for sending certain kinds of "key events" to the
registry when the application receives keystrokes - this is a method of
AtkUtil which is of interest to non-gtk+ applications and toolkits.

Note that AtkDocument is currently unused, since there is no standard
way to provide access to an application's content DOM, at least there
are no good ways to expose the DOM interface on an application's
document content.  For that reason the "document" pointer returned by
AtkDocument is currently a void* ; we know that this API is potentially
useful but there are a number of implementation issues and in fact none
of our assistive technologies use it yet.

StreamableContent is also largely unimplemented but at least it's
well-defined and there are no known implementation blockers.  It's just
that, so far, we haven't had an urgent need for it.  What we _don't_
want is for applications to use it as a sort of 'cheat' and just pipe
their content to the AT, offloading the burden of parsing and
presentation entirely to the assistive technology.  In some cases this
is desirable, but it should not be a substitute for implementing the
other interfaces on the application's content pane or display widgets.

EditableText/AtkEditableText is a subinterface of Text/AtkText.  However
Hypertext/AtkHypertext can be implemented, in theory, by objects that
don't implement AtkText.  An example (though I don't know of any such
applications offhand) would be a content pane that showed lots of
images/icons which were links, but which contained no actual text.  So
perhaps some kinds of icon container might implement Hypertext.

It's worth noting that Hyperlink/AtkHyperlink is the only one of the
"Specialized Accessibility Interfaces" which is not obtained by querying
AtkObjects, but instead is returned from calls to the Hypertext
interface.  Therefore objects that implement Hyperlink are not always
Accessible/AtkObject instances.


Thanks again for writing up this excellent summary!

- Bill