winaccessibility/README.md

   1 # Windows Accessibility Bridge
   2
   3 This code provides a bridge between our internal Accessibility
   4 interfaces (implemented on all visible 'things' in the suite: eg.
   5 windows, buttons, entry boxes etc.) - and the Windows `MSAA` /
   6 `IAccessible2` COM interfaces that are familiar to windows users and
   7 Accessible Technologies (ATs) such as the NVDA screen reader.
   8
   9 The code breaks into three bits:
  10
  11 + `source/service/`
  12         + the UNO service providing the accessibility bridge.
  13           It essentially listens to events from the LibreOffice
  14           core and creates and synchronises COM peers for our
  15           internal accessibility objects when events arrive.
  16
  17 + `source/UAccCom/`
  18         + COM implementations of the `MSAA` / `IAccessible2` interfaces
  19           to provide native peers for the accessibility code.
  20
  21 + `source/UAccCOMIDL/`
  22         + COM Interface Definition Language (IDL) for UAccCom.
  23
  24 Here is one way of visualising the code / control flow
  25
  26     VCL <-> UNO toolkit <-> UNO a11y <-> win a11y <-> COM / IAccessible2
  27
  28     vcl/ <-> toolkit/ <-> accessibility/ <-> winaccessibility/ <-> UAccCom/
  29
  30 ## Threading
  31
  32 It's possible that the UNO components are called from threads other
  33 than the main thread, so they have to be synchronized. It would be nice
  34 to put the component into a UNO apartment (and the COM components into STA)
  35 but UNO would spawn a new thread for it so it's not possible.
  36 The COM components also call into the same global `AccObjectWinManager`
  37 as the UNO components do so both have to be synchronized in the same way.
  38
  39 So we use the `SolarMutex` for all synchronization since anything else
  40 would be rather difficult to make work.  Unfortunately there is a
  41 pre-existing problem in vcl with Win32 Window creation and destruction
  42 on non-main threads where a synchronous `SendMessage` is used while
  43 the `SolarMutex` is locked that can cause deadlocks if the main thread is
  44 waiting on the `SolarMutex` itself at that time and thus not handing the
  45 Win32 message; this is easy to trigger with `JunitTests` but hopefully
  46 not by actual end users.
  47
  48 ## Debugging / Playing with winaccessibility
  49
  50 If NVDA is running when soffice starts, IA2 should be automatically enabled
  51 and work as expected. In order to use 'accprobe' to debug
  52 it is necessary to override the check for whether an AT (like NVDA) is
  53 running; to do that use:
  54
  55     SAL_FORCE_IACCESSIBLE2=1 soffice.exe -writer
  56
  57 Then you can use accprobe to introspect the accessibility hierarchy
  58 remotely, checkout:
  59
  60 <http://accessibility.linuxfoundation.org/a11yweb/util/accprobe/>
  61
  62 But often it's more useful to look at NVDA's text output window.