History

Michael Weghorn 6c5257b680 wina11y: Slightly clean up WinResIDGenerator Changes: * drop the optional `maxNum` param for the constructor, it's never set to anything different than the default value * store negative number in member (renamed from `max` to `m_nMin`) instead of storing positive number and inverting that when returning it in `ResIDGenerator::GenerateNewResID` * Use -1 as the first resource ID instead of -2. Also, add a comment that negative child IDs are used because it's common to use such ones to indicate unique resource IDs in IAccessible2. Quoting James Teh's comment on an NVDA pull request of mine [1]: > The use of negative child ids doesn't fit well into the IAccessible > spec, but it has been done by IAccessible2 for a very long time and > should be considered standard for all intents and purposes. A negative > child id should be treated as a unique id, while a positive child id > should be treated as a child index. > > That said, as noted in #13277 (comment), IAccessible2 elements are > always full IAccessible objects, not "simple elements". Thus, anything > that returns an accessible (including accSelection) really should return > an object pointer. In the case of accSelection, this means VT_DISPATCH > for a single selection or VT_UNKNOWN and iEnumVARIANT (with VT_DISPATCH > elements) for multiple selection. > > In short, NVDA supporting negative child ids returned from accSelection > isn't necessarily "wrong", but ideally, LibreOffice would be fixed to > return full objects. The latter (returning full objects) has already been addressed in commit `00c0ee8cf0` Author: Michael Weghorn <m.weghorn@posteo.de> Date: Mon Jan 31 07:41:14 2022 +0000 tdf#147083 wina11y: Return a11y object instead of child ID but a unique ID is still relevant, s. e.g. the documentation of `IAccessible2::uniqueID` [2], which also mentions potential ways to implement unique IDs: > One means of implementing this would be to create a factory with a 32 > bit number generator and a reuse pool. The number generator would emit > numbers starting at 1. Each time an object's life cycle ended, its > number would be saved into a reuse pool. The number generator would be > used whenever the reuse pool was empty. > > Another way to create a unique ID is to generate it from a pointer > value, e.g. an object's address. That would be unique because no two > active objects can use the same allocated memory space. The first approach is what the LO implementation currently does, except that negative numbers are used. [1] https://github.com/nvaccess/nvda/pull/13277#issuecomment-1024622871 [2] https://accessibility.linuxfoundation.org/a11yspecs/ia2/docs/html/interface_i_accessible2.html#aac1342376cf195a6a6e9ee3b7e30ae3b Change-Id: I6c0a6c4a4e3a69396205fe2d69cd66af6525a273 Reviewed-on: https://gerrit.libreoffice.org/c/core/+/131927 Tested-by: Jenkins Reviewed-by: Michael Weghorn <m.weghorn@posteo.de>		2022-03-22 13:26:54 +01:00
..
inc	wina11y: Slightly clean up WinResIDGenerator	2022-03-22 13:26:54 +01:00
source	wina11y: Slightly clean up WinResIDGenerator	2022-03-22 13:26:54 +01:00
CustomTarget_ia2_idl.mk
Library_uacccom.mk
Library_winaccessibility.mk
Makefile
Module_winaccessibility.mk
README.md
WinResTarget_uacccom.mk

README.md

Windows Accessibility Bridge

This code provides a bridge between our internal Accessibility interfaces (implemented on all visible 'things' in the suite: eg. windows, buttons, entry boxes etc.) - and the Windows MSAA / IAccessible2 COM interfaces that are familiar to windows users and Accessible Technologies (ATs) such as the NVDA screen reader.

The code breaks into three bits:

source/service/
- the UNO service providing the accessibility bridge. It essentially listens to events from the LibreOffice core and creates and synchronises COM peers for our internal accessibility objects when events arrive.
source/UAccCom/
- COM implementations of the MSAA / IAccessible2 interfaces to provide native peers for the accessibility code.
source/UAccCOMIDL/
- COM Interface Definition Language (IDL) for UAccCom.

Here is one way of visualising the code / control flow

VCL <-> UNO toolkit <-> UNO a11y <-> win a11y <-> COM / IAccessible2

vcl/ <-> toolkit/ <-> accessibility/ <-> winaccessibility/ <-> UAccCom/

Threading

It's possible that the UNO components are called from threads other than the main thread, so they have to be synchronized. It would be nice to put the component into a UNO apartment (and the COM components into STA) but UNO would spawn a new thread for it so it's not possible. The COM components also call into the same global AccObjectWinManager as the UNO components do so both have to be synchronized in the same way.

So we use the SolarMutex for all synchronization since anything else would be rather difficult to make work. Unfortunately there is a pre-existing problem in vcl with Win32 Window creation and destruction on non-main threads where a synchronous SendMessage is used while the SolarMutex is locked that can cause deadlocks if the main thread is waiting on the SolarMutex itself at that time and thus not handing the Win32 message; this is easy to trigger with JunitTests but hopefully not by actual end users.

Debugging / Playing with winaccessibility

If NVDA is running when soffice starts, IA2 should be automatically enabled and work as expected. In order to use 'accprobe' to debug it is necessary to override the check for whether an AT (like NVDA) is running; to do that use:

SAL_FORCE_IACCESSIBLE2=1 soffice.exe -writer

Then you can use accprobe to introspect the accessibility hierarchy remotely, checkout:

http://accessibility.linuxfoundation.org/a11yweb/util/accprobe/

But often it's more useful to look at NVDA's text output window.