Honor Windows setting to swap primary mouse button

[michaelDCurran]

Link to issue number:

Fixes #12642

Summary of the issue:

NVDA may at times resort to clicking the mouse to perform particular actions on behalf of the user, such as activating a link or bringing up a context menu.
Currently, NVDA clicks the left mouse button to activate / select items, and clicks the right mouse button to display a context menu. This is generally expected behaviour.
However, Windows has a user setting allowing the user to swap the mouse buttons, such that the primary button (activating / selecting) is the right mouse button, and the secondary (context menu) is the left.
If the user has chosen to swap the buttons, NVDA may inadvertantly display a context menu when trying to activate an item, or the other way round.

Description of how this pull request fixes the issue:

This pr adds doPrimaryClick and doSecondaryClick functions to mouseHandler that honor the Windows user preference for which button is the primary mouse button.
All code in NVDA that licks aa mouse button in order to perform activation, selection or show a context menu has been changed to call these new functions in place of calling executeMouseEvent for the left or right mouse button.
However, The mouse click scripts in globalCommands have not been changed, as these are specifically named after which physical mouse button they click, rather than performing a logical primary or secondary action.

Testing strategy:

this certainly requires a lot of testing, especially because we don't know if each of the affected apps actually do honor the Windows user preference themselves. I would think it is very highly likely though as the setting has existed as far back as Windows 95.
App scenarios that need testing:

• Firefox / Chrome / Edge: activating a link or other clickable where that link or clickable contains extra nodes. E.g. data:text/html,<a href="http://www.google.com/"><h1>Test</h1></a>
• iTunes: the iTunes Store web area. Again, links or clickables containing extra nodes.
• LotusNotes: I think we can probably remove support entirely from NVDA -- it has not been verified for about 10 years.
• Excel (with UIA disabled): activating a form field.
• MSCandUI (MSAA IME input pre Windows 10): activating a candidate.
• DisplayModel editable text setting the caret
• Azadi: Pressing enter, and showing a context menu ... I'm really not familiar with this app.
• Kindle for PC: Select some text and show selection objects (context menu, or shift+f10 or control+c).

Known issues with pull request:

There are a great deal of things to test for this pr, much of which is old or esoteric. At a mimimum this should be held back until 2022.1. But we also may consider only taking the specific scendarios we can verify and that were reported in issue #12642

Change log entries:

New features
Changes
Bug fixes

• NVDA will honor the Windows user setting for swapping the primary mouse button when needing to use the mouse to activate a clickable item in Web browsers such as Firefox or Google Chrome.
  Changes for developers
• mouseHandler.doPrimaryClick and mouseHandler.doSecondaryClick functions should be used to click the mouse to perform a logical action such as activating (primary) or secondary (show context menu), rather than using executeMouseEvent and specifying the left or right mouse button specifically. This ensures your code will honor the Windows user setting for swapping the primary mouse button.

Code Review Checklist:

• Pull Request description:
  • description is up to date
  • change log entries
• Testing:
  • Unit tests
  • System (end to end) tests
  • Manual testing
• API is compatible with existing add-ons.
• Documentation:
  • User Documentation
  • Developer / Technical Documentation
  • Context sensitive help for GUI changes
• UX of all users considered:
  • Speech
  • Braille
  • Low Vision
  • Different web browsers
  • Localization in other languages / culture than English

[CyrilleB79]

Would it also be worth adding an item in the change for developers in the change log?
This may be useful for add-on developers who are using statements such as:
mouseHandler.executeMouseEvent(winUser.MOUSEEVENTF_LEFTDOWN, 0, 0)

[michaelDCurran]

This pr has been split such that we can drop off the last 7 comits if we don't want to test all the scenarios other than Firefox / Chrome (which has been verified fixed).

[michaelDCurran]

We are going to merge this now, very early in the 2022.1 dev cycle, to ensure it gets wide user testing in alphas, as we want to identify any app that for some reason does not honor the Windows primary mouse button setting.