Add new scripts to move review cursor by page

[codeofdusk]

Link to issue number:

Closes #13157 (given microsoft/terminal#13756). Alternative solution to #13671.

Summary of the issue:

There is no way to move the review cursor by page. This is especially useful in terminals as a "page" can be defined as a screenful of text, solving #13157 without violating any other assumptions in NVDA and still permitting easy jump to the absolute top/bottom of the terminal buffer using the currently existing scripts.

Description of how this pull request fixes the issue:

Added new scripts (bound to NVDA+pageUp/NVDA+pageDown on desktop and NVDA+Shift+pageUp/NVDA+Shift+pageDown on laptop) to move to previous/next page respectively.

Testing strategy:

• Tested in UIA word where the page unit is sanely defined. Scripts work as expected.
• Tested in non-UIA word where the page unit is undefined. NVDA reports that movement by page is not supported.
• Tested in Notepad where the page unit is undefined but defers to document. NVDA reports "top"/"bottom" and reads the entire document as expected.

Known issues with pull request:

As different textInfos define UNIT_PAGE differently, behaviour will vary across applications.

Change log entries:

Feel free to clarify/reword where you see fit.

=== New Features ===

• Introduced new commands to move the review cursor by page where supported by the application. These are especially useful for moving across screens of text, such as paginated output, in Windows Terminal.
  • Move to previous page: NVDA+pageUp (desktop), NVDA+Shift+pageUp (laptop)
  • Move to next page: NVDA+pageDown (desktop), NVDA+Shift+pageDown (laptop)

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

[codeofdusk]

CC @seanbudd, @LeonarddeR, @michaelDCurran.

[seanbudd]

I think this approach is a safe and generally useful feature.
The way it handles the different cases seems appropriate.

[seanbudd]

Great work @codeofdusk!

[Qchristensen]

User Guide reads well, great work.

[burmancomp]

I tried these commands in Thunderbird 102.1.2 message list. NVDA + Shift + PageUp gave result "movement by page not supported" which is expected behavior I suppose. But command NVDA + Shift + PageDown resulted the following in log:

IO - inputCore.InputManager.executeGesture (10:28:16.276) - winInputHook (7160):
Input: kb(laptop):shift+NVDA+pageDown
ERROR - scriptHandler.executeScript (10:28:16.329) - MainThread (14408):
error executing script: <bound method GlobalCommands.script_review_nextPage of <globalCommands.GlobalCommands object at 0x0BF290F0>> with gesture 'vaihto+NVDA+sivu alas'
Traceback (most recent call last):
File "scriptHandler.py", line 216, in executeScript
script(gesture)
File "globalCommands.py", line 1479, in script_review_nextPage
newPage.expand(textInfos.UNIT_PAGE)
File "textInfos\offsets.py", line 527, in expand
self._startOffset,self._endOffset=self._getUnitOffsets(unit,self._startOffset)
File "textInfos\offsets.py", line 505, in _getUnitOffsets
raise ValueError("unknown unit: %s"%unit)
ValueError: unknown unit: page

[LeonarddeR]

I can not reproduce this in the thunderbird messages list. I'm currently investigating what's necessary for broader rollout of page movement.

[codeofdusk]

@burmancomp Now that #14029 has been merged, could you please test the latest master snapshot and verify that NVDA now reports "movement by page not supported" for both previous and next?