[Kde-accessibility] documentation of QAccessible and friends

[Volker Hilsheimer]

> > If you compare the ATK interface to the Qt interfaces you can
probably
> > find some of the differences; for instance ATK has a separate
interface
> > for 'AtkComponent' whereas Qt/MSAA does not; also I believe that
MSAA
> > only supports a "default" action for UI components whereas ATK
supports
> > any number of actions on a single component.  Likewise I don't think
> > MSAA supports as rich a text (AtkEditableText and AtkText) or table
> > (AtkTable) interface as ATK.
>
> I think here we have a substancial diference here since there is not a
single
> Q object that represents one of those objects.
> - From what I think, Qt Accessibility works in a more generic way not
having a
> class for each type of object but being the parameters of the
functions of
> the generic class what let's you deal with diferent types of objects.
> Volker, can you please help me with this ?
> If you need the atk documentation to compera, it is here:
> http://developer.gnome.org/doc/API/2.0/atk/book1.html

QAccessibleInterface is a generic API that abstracts every accessible
"object" using four central concepts:

- an object is part of an object hierarchy. It can have children, and
can have a parent
This implies that the parent can identify any child with an index, so
that you can navigate throught the complete hierarchy once you got hold
of any object in the tree.

- an object has properties
Most properties can be expressed by strings - those properties can
change. Some properties can only have a predefined value, e.g. values
that an accessible client and hence a user relying on such a client can
make use of, and are usually static, or at least not writable from
outside. "role" and "state" are such properties.

- an object has methods
You can push a button. IAccessible - and hence the current
QAccessibleInterface API - only provide one default method, apart from
"secondary" methods like setFocus. A new text property, e.g. "verbs" or
"actions", that returns a comma separated list of strings, and a new
method "doVerb" or "doAction" that takes that string is definitely
something we can add to QAccessibleInterface, or to a new interface that
would be supported using multiple inheritance until we can break binary
compatibility in 4.0.

- an object can change, and send a notification about this change
That's what updateAccessibility is all about.

Microsoft figured out that those four central concepts might be
sufficient to abstract any user interface object, but that it's
impractical to both implement and use only those central concepts to do
something complex like selection handling. So
IAccessible/QAccessibleInterface has some special APIs for selection
handling.

The AtkText API is pretty involved, and for QAccessible we would create
a new interface that would be implemented only for a few widget classes.
But then why not just pass the (rich)text string to the client, and let
the client deal with it? It's definitely more efficient to pass the
string to the client, and the clients figures out which character is at
position X than making a remote procedure call to ask the server for
that rather obvious piece of information. Same for attributes at
position X.
Most of the AtkEditableText class could be put into a single function
"doAction(const QString&)" - start_pos and end_pos would be handled with
the selection API. doAction would by default use QObject introspection
and check if there is a slot with that name, e.g. QTextEdit::paste()
would be called if you call doAction("paste") on an interface that wraps
a QTextEdit.

There would be a few special interfaces that 90% of controls or objects
don't have to take care about, e.g. for tables or - even worse -
canvases.

Volker