[Kde-accessibility] documentation of QAccessible and friends

[Volker Hilsheimer]

> Now the files are:
> http://www.futzion.com/~pupeno/files/QtandKDEAccessibility.kwd
> and
> http://www.futzion.com/~pupeno/files/QtandKDEAccessibility.txt
> Thanks.

Here are the answers to the questions in the documentation. I hope I
found all questions, maybe you can highlight them with "???" or
something next time ;-)

1. queryAccessibleInterface:
...
"This function is called to answer an accessibility client's request for
object information. You should never need to call this function
yourself.

How does an accessibility client do that request ?"

QApplication receives a WM_GETOBJECT window message through the event
loop. This message is sent by the Active Accessibility infrastructure
and is answered with the following code:

      QAccessibleInterface *acc = 0;
      QAccessible::queryAccessibleInterface( widget, &acc );
      if ( !acc ) {
   result = FALSE;
   break;
      }

      QCustomEvent e( QEvent::Accessibility, acc );
      QApplication::sendEvent( widget, &e );

      // and get an instance of the IAccessibile implementation
      IAccessible *iface = qt_createWindowsAccessible( acc );
      acc->release();
      LRESULT res = LresultFromObject( IID_IAccessible, wParam, iface );
// ref == 2
      iface->Release(); // the client will release the object again, and
then it will destroy itself

      if ( res > 0 )
   RETURN(res);

qt_createWindowsAccessible creates an IAccessible wrapper around the
QAccessibility interface. IAccessible is a COM interface.
LresultFromObject is a magic Windows API that - probably - assigns a
unique integer to the pointer value or so. See:

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msaa/ms
aaccrf_5rjo.asp
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msaa/ms
aaccrf_4wms.asp


2. updateAccessibility
How does an accessibility tool listen to this event?

The implementation of updateAccessibility uses the Windows API
NotifyWinEvent:

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msaa/ms
aaccrf_76gk.asp


3. QAccessibleInterface
Exposes it to who and how? Where is the IPC? How is a
QAccessibleInterface related to an object?

The QAccessibleInterface implementation knows of course about the object
it provides access to. The IPC is handled by COM, since we create a
IAccessible implementation around it in the WM_GETOBJECT message
handler. IAccessible is a COM interface. Don't ask me how COM does it
though... since it's an integral part of the Windows OS it can basically
do everything.


4. QAccessibleInterface::childCount()
A listview would be an example for a widget without sub-widgets, but
with children. The items are the children. Same for popup menus, and
even sliders, where you have a "button" to the left for "page down", the
handle, and another "button" to the right for "page up". That "page
up/down" don't look like a button on a proper slider doesn't mean
anything.


Volker