Link to issue number:

Closes #10732

Summary of the issue:

controlTypes.py is a large file with many constants. To maintain backwards compatibility, the file length would increase to 1000+ LOC. It would be an improvement to split this code up, and group the constants into enums. As 2021.2 is not a compatibility breaking release, all changes must be backwards compatible.

Description of how this pull request fixes the issue:

This is a large refactor. The changes are split into individual commits for reviewers.

The first commit can be reviewed using the following tool

for file in $(ls source/controlTypes/*.py)
do
git diff master:source/controlTypes.py 8642581:$file > $file-controlTypes.diff
done

The second commit is generated using the following sed commands.

sed -i'' -bre "s/ROLE_([A-z0-9_]+) ?= ?/\t\1 = /g" source/controlTypes.py
sed -i'' -bre "s/ROLE_([A-z0-9_]+) ?:([^ ])/Role.\1: \2/g" source/controlTypes.py
sed -i'' -bre "s/ROLE_([A-z0-9_]+)/Role.\1/g" source/controlTypes.py

sed -i'' -bre "s/STATE_([A-z0-9_]+) ?= ?/\t\1 = /g" source/controlTypes.py
sed -i'' -bre "s/STATE_([A-z0-9_]+) ?:([^ ])/State.\1: \2/g" source/controlTypes.py
sed -i'' -bre "s/STATE_([A-z0-9_]+)/State.\1/g" source/controlTypes.py

The mixin strategy follows what is outlined for python 3.7 here. Mixins with Enums are fragile, and this code will have to be changed when updating (or downgrading python) Python.

Testing strategy:

Manual testing.

There is unit testing for the controlTypes module which should help ensure that compatibility doesn't break.

This module is fairly widely utilised, so any breaking changes are likely to be picked up quickly.

Known issues with pull request:

Changes can't be tracked backwards using git blame to controlTypes.py due to how the files are split up. As such, I've linted these files.

I haven't implemented the enums in the wider NVDA codebase. When we break the backwards compatibility, by updating to 2022.1, we will need to update the rest of the NVDA code beforehand (see #12549).

Change log entries:

For developers:

• controlTypes has been split up into various submodules. ROLE_* and STATE_* constants should be replaced to their equivalent Role.* and State.* before 2022.1. (Backwards compatible control types refactor #12510)
• roleLabels, stateLabels and negativeStateLabels have been deprecated, usages such as roleLabels[ROLE_*] should be replace to their equivalent Role.*.displayString or State.*.negativeDisplayString before 2022.1. (Backwards compatible control types refactor #12510)

Code Review Checklist:

• Pull Request description is up to date.
• Unit tests.
• System (end to end) tests.
• Manual testing.
• User Documentation.
• Change log entry.
• Context sensitive help for GUI changes.
• UX of all users considered:
  • Speech
  • Braille
  • Low Vision
  • Different web browsers