Text review

[Emil-18]

Link to issue number:

fixes #18539
Also fixes issues related to users being unable to read the current line/word/character in chrome/firefox/edge, when using focus mode, but I don't know the number of those.

Summary of the issue:

• Unable to read the current line/word/character in chrome/edge/firefox in some cases. In other cases, the visual text can be reviewed with the review cursor commands, instead of the objects name/value/description. The visual text isn't shown in braille in follow cursors mode
• Unable to decide if you want to move the mouse to the center of the navigator object, if the text info it uses implements pointAtStart.
• Unable to decide if you want to performe the default action on the navigator object, if the text info it uses implements activate.
• Unable to decide if you want to review the name/value in editable controls, as supposed to its editable text.
• If the object screen review creates a DisplayModelTextInfo instance from isn't navigable, braille doesn't follow the review cursor as it moves in screen review.

Description of user facing changes:

The user will get access to a new review mode called text review. Text review will be automaticly activated when the navigator object contains text that is navigable and is likely to be of most interest to the user, e.g in edit controls. If the object contains navigable text that could be useful, but the name/value is more useful, e.g on none editable objects in chrome/firefox, object review is used by default, but text review can be switched to manualy. If the object contains no navigable text, text review isn't available. Object review will now always review the name/value/description of the navigator object. When braille is tethered to review, and the review mode is anything other then object review, it will always show the content that the review cursor can read

Description of developer facing changes:

Since a new review mode is added, if the setReviewMode function is used directly with numbers, it could set NVDA to the wrong review mode.

Description of development approach:

the getObjectPosition function has been modified so that if the objects textInfo is a subclass of NVDAObjectTextInfo, it will return that, else it will return the NVDAObjectTextInfo directly.
a new function, called getTextPosition, has been added to get the text review position for the navigator object. If the object has a text info that isn't a subclass of NVDAObjectTextInfo, it will be returned, and text review will be activated automaticly. Else it will look for a new property on the NVDAObject called TextReviewTextInfo. If this is implemented, text review will be available, but it will not be activated automaticly. If it isn't implemented, text review will not be available.
When braille isn't tethered to focus, the NVDAObjectHasUsefulText, will not be used to determine if the content the review cursor can read should be shown on the braille display. Instead, if the review mode isn't object, it will be shown.
The _get_TextInfo method on IAccessible.IAccessible has been removed, so NVDA will use NVDAObjectTextInfo by default in web browsers.

Testing strategy:

Tested in edit fields, and in focus mode in chrome.

Known issues with pull request:

• When in an object that causes NVDA to activate text review automaticly, and when switching to object review, the value isn't shown on the braille display. I know what is causing it, but I don't know how to fix it in a graceful way. I could probably check if braille is tethered to review and if the review mode is object, but I don't think I am supposed to do that in the NVDAObjectRegion.update method.
• When switching between object and text review, braille isn't updating as it should.
• If API.setReviewPosition is called with a textInfo that isn't an instance of NVDAObjectTextInfo, but the review mode is set to object, braille isn't showing the new review position.
• I don't know what ramifications removing the _get_TextInfo method on IAccessible.IAccessible makes. According to @jcsteh, NVDA uses the IA2 text info to get some properties on web objects.
• I don't know if this will be considered API breaking.

Code Review Checklist:

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

@coderabbitai summary