From ed5640d8b587fbcfed7dd7967f3de04b37a76f26 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 11:06:44 +0200 Subject: Adding upstream version 4:7.4.7. Signed-off-by: Daniel Baumann --- winaccessibility/README.md | 62 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 winaccessibility/README.md (limited to 'winaccessibility/README.md') diff --git a/winaccessibility/README.md b/winaccessibility/README.md new file mode 100644 index 000000000..6abf34a37 --- /dev/null +++ b/winaccessibility/README.md @@ -0,0 +1,62 @@ +# 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: + + + +But often it's more useful to look at NVDA's text output window. -- cgit v1.2.3