Add new scripts to move review cursor by page (#14021)

Closes #13157 (given microsoft/terminal#13756). Supercedes #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.

source/globalCommands.py

@@ -1433,6 +1433,61 @@ def script_review_nextLine(self, gesture):
 			api.setReviewPosition(info)
 		speech.speakTextInfo(newLine, unit=textInfos.UNIT_LINE, reason=controlTypes.OutputReason.CARET)
 
+	@script(
+		# Translators: Input help mode message for move review cursor to previous page command.
+		description=_("Moves the review cursor to the previous page of the current navigator object and speaks it"),
+		resumeSayAllMode=sayAll.CURSOR.REVIEW,
+		category=SCRCAT_TEXTREVIEW,
+		gestures=("kb:NVDA+pageUp", "kb(laptop):NVDA+shift+pageUp", "ts(text):flickUp")
+	)
+	def script_review_previousPage(self, gesture: inputCore.InputGesture) -> None:
+		info = api.getReviewPosition().copy()
+		try:
+			info.expand(textInfos.UNIT_PAGE)
+			info.collapse()
+			res = info.move(textInfos.UNIT_PAGE, -1)
+		except (ValueError, NotImplementedError):
+			# Translators: a message reported when movement by page is unsupported
+			ui.reviewMessage(_("Movement by page not supported"))
+			return
+		if res == 0:
+			# Translators: a message reported when review cursor is at the top line of the current navigator object.
+			ui.reviewMessage(_("Top"))
+		else:
+			api.setReviewPosition(info)
+		info.expand(textInfos.UNIT_PAGE)
+		speech.speakTextInfo(info, unit=textInfos.UNIT_PAGE, reason=controlTypes.OutputReason.CARET)
+
+	@script(
+		# Translators: Input help mode message for move review cursor to next page command.
+		description=_("Moves the review cursor to the next page of the current navigator object and speaks it"),
+		resumeSayAllMode=sayAll.CURSOR.REVIEW,
+		category=SCRCAT_TEXTREVIEW,
+		gestures=("kb:NVDA+pageDown", "kb(laptop):NVDA+shift+pageDown", "ts(text):flickUp")
+	)
+	def script_review_nextPage(self, gesture: inputCore.InputGesture) -> None:
+		origInfo = api.getReviewPosition().copy()
+		origInfo.collapse()
+		info = origInfo.copy()
+		try:
+			res = info.move(textInfos.UNIT_PAGE, 1)
+		except (ValueError, NotImplementedError):
+			# Translators: a message reported when movement by page is unsupported
+			ui.reviewMessage(_("Movement by page not supported"))
+			return
+		newPage = info.copy()
+		newPage.expand(textInfos.UNIT_PAGE)
+		# #12808: Some implementations of move forward may succeed one more time than expected,
+		# landing on the exclusive end of the document.
+		# Therefore, verify that expanding after the move does result in being on a new page,
+		# i.e. the new page starts after the original review cursor position.
+		if res == 0 or newPage.start <= origInfo.start:
+			# Translators: a message reported when review cursor is at the bottom line of the current navigator object.
+			ui.reviewMessage(_("Bottom"))
+		else:
+			api.setReviewPosition(info)
+		speech.speakTextInfo(newPage, unit=textInfos.UNIT_PAGE, reason=controlTypes.OutputReason.CARET)
+
 	@script(
 		# Translators: Input help mode message for move review cursor to bottom line command.
 		description=_("Moves the review cursor to the bottom line of the current navigator object and speaks it"),

user_docs/en/changes.t2t

@@ -8,8 +8,18 @@ What's New in NVDA
 == New Features ==
 - Added a "Quick Start Guide" section to the User Guide. (#13934)
 - Introduced a new command to check the keyboard shortcut of the current focus. (#13960)
-  - Desktop: ``shift+numpad2``
-  - Laptop: ``NVDA+ctrl+shift+.``
+  - Desktop: ``shift+numpad2``.
+  - Laptop: ``NVDA+ctrl+shift+.``.
+  -
+- Introduced new commands to move the review cursor by page where supported by the application.
+  - Move to previous page:
+    - Desktop: ``NVDA+pageUp``.
+    - Laptop: ``NVDA+shift+pageUp``.
+    -
+  - Move to next page:
+    - Desktop: ``NVDA+pageDown``.
+    - Laptop: ``NVDA+shift+pageDown``.
+    -
   -
 -
 

user_docs/en/userGuide.t2t

@@ -630,6 +630,8 @@ The following commands are available for reviewing text:
 | Report current character in review | numpad2 | NVDA+. | none | Announces the current character on the line of text where the review cursor is positioned. Pressing twice reports a description or example of that character. Pressing three times reports the numeric value of the character in decimal and hexadecimal. |
 | Move to next character in review | numpad3 | NVDA+rightArrow | flick right (text mode) | Move the review cursor to the next character on the current line of text |
 | Move to end of line in review | shift+numpad3 | NVDA+end | none | Moves the review cursor to the end of the current line of text |
+| Move to previous page in review | ``NVDA+pageUp`` | ``NVDA+shift+pageUp`` | none | Moves the review cursor to the previous page of text if supported by the application |
+| Move to next page in review | ``NVDA+pageDown`` | ``NVDA+shift+pageDown`` | none | Moves the review cursor to the next page of text if supported by the application |
 | Say all with review | numpadPlus | NVDA+shift+a | 3-finger flick down (text mode) | Reads from the current position of the review cursor, moving it as it goes |
 | Select then Copy from review cursor | NVDA+f9 | NVDA+f9 | none | Starts the select then copy process from the current position of the review cursor. The actual action is not performed until you tell NVDA where the end of the text range is |
 | Select then Copy to review cursor | NVDA+f10 | NVDA+f10 | none | On the first press, text is selected from the position previously set as start marker up to and including the review cursor's current position. If the system caret can reach the text, it will be moved to the selected text. After pressing this key stroke a second time, the text will be copied to the Windows clipboard |