Accessibility API handlers (long-term): provide similar interfaces/modules between different API handlers

[josephsl]

Hi,

This issue is a meta issue that should be done over several issue/PR pairs, perhaps taking several dev cycles to complete:

Background and rationale

NVDA includes support for several accessibility API's and specificiations. These include Microsoft Active Accessibility (MSAA)/IAccessible, IAccessible2, UI Automation (UIA), Java Access Bridge (JAB), and web-related specs. Accessibility API handlers consist of components such as a handler thread and interface, conversion between API-level events to NVDA events, definitions for specific objects and window classes, among other things specific to different API's.

Recently NV Access and contributors began reorganizing accessibility API handlers. Specifically, API handlers formerly housed in one file were converted into a package with additional modules to support specific API scenarios. For example, a pull request converted IAccessibleHandler.py into a package and added event ordering support as a submodule. Another recent pull request reorganized UIA handler, gathering UIA support modules such as constant definitions inside the new package.

Is your feature request related to a problem? Please describe.

During UIA handler reorganization (#10916), the file name conventions used in IAccessible handler package was adopted. For example, UIAUtils.py became UIAHandler/utils.py. In the follow-up pull request, it was pointed out that since main UIA handler module contains both the UIA handler class definition and constants such as event and role definitions, it would be better to work on splitting the main UIA handler module into smaller modules (such a proposal is the subject of a separate issue).

The issue with maintenance is not limited to UIA handler: comments throughout IAccessible handler main module notes that it owuld be best to refactor complex functions into smaller ones. At the same time, there might be a request to split IAccessible handler main module into smaller files to make maintenance tasks easier to perform.

More importantly, to help new contributors understand the architecture of NVDA better, along with opening up way to support new accessibility API's in the future, the API handler interface/modules should become more consistent and predictable, similar to how NVDA objects package is organized. In short, the below proposal seeks to come up with a roadmap for a general accessibility API handler reorganization to make basic interfaces/modules common across API's.

Describe the solution you'd like

Since accessibility API's have similar interfaces (initialize/terminate methods, a handler class for some, definitions of API-specific events/roles/states/other constants and so on), plus similar module names (if UIA handler reorganization is included), it is proposed that NVDA contributors work toward a roadmap for making accessibility API interfaces/modules consistent. Specifically:

Current:

• IAccessibleHandler: main module, event ordering, internal event limiter, utilities
• UIA handler before reorganization: public and private UIA handler modules, various uIA modules, browse mode, utilities
• UIA handler after reorganization: main UIA handler module, various UIA support modules, utilities under one package

After the proposal is adopted:

• Common file names and interfaces acrosss API's
• IAccessible specific package
• UIA specific package
• Each package will have a public interface (main) file, plus modules that define events/roles/states, additional constants, and utilities

For backward compatibility, the common interface/module names should be abstract concepts on paper, with concepts translated into implementations in different handler packages, with API packages living at the top level of the source folder. Anyone wishing to extend API support should:

• Propose editing the abstract spec if it is something to be implemented across API's.
• Edit the relevant handler package contents if it concerns a specific API.

The biggest benefit is helping new contributors understand the basic concepts across API's, and then come up with solutions tailored for different API's; in other words, applying the structure of NVDA objects and app module contributions to accessibility API's themselves. The biggest downside is defining what should be common or not, as well as defining which module will be responsible for which. Although there might be a call for a basic "accessibilityHandler.py" module that spells out abstract concepts in detila (with NotImplementedError throughout the module), that is beyond the scope of this proposal as it changes one of the fundamental parts of NVDA and carries both benefits and risks.

As a practical implementation, UIA handler package is being organized, along with a future issue/PR pair that will define the boundaries of different parts of UIA handler package, namely separating events/roles/states to a separate module. IAccessible handler might be reorganized similarly in the future if the NVDA community agrees with the assessment of this proposal.

Describe alternatives you've considered

Leave accessibility handlers as is.

Additional context

Think about the research value of NVDA source code itself. There has been a growing call to use NVDA source code for research purposes, so having a more organized and structured source code would help researchers understand the culture of this project and implementation reasons.

Thanks.

[Adriani90]

cc: @gerald-hartig this one might be interesting for future work in case NV Access cooperates with universities.

[gerald-hartig]

Converting to a discussion.