Allow the review cursor to be bounded to onscreen text

developerGuide.t2t

@@ -403,7 +403,7 @@ For example:
 --- start ---
 	@script(
 		description=_("Speaks the date and time"),
-		category=inputCore.SCRCAT_MISC,
+		category=scriptCategories.SCRCAT_MISC,
 		gestures=["kb:NVDA+shift+t", "kb:NVDA+alt+r"]
 	)
 	def script_sayDateTime(self, gesture):
@@ -421,7 +421,7 @@ The following keyword arguments can be used when applying the script decorator:
 - category: The category of the script in order for it to be grouped with other similar scripts.
   For example, a script in a global plugin which adds browse mode quick navigation keys may be categorized under the "Browse mode" category.
   The category can be set for individual scripts, but you can also set the "scriptCategory" attribute on the plugin class, which will be used for scripts which do not specify a category.
-  There are constants for common categories prefixed with SCRCAT_ in the inputCore and globalCommands modules, which can also be specified.
+  There are constants for common categories prefixed with SCRCAT_ in the scriptCategories module, which can also be specified.
   The script will be listed under the specified category in the Input Gestures dialog.
   If no category is specified, the script will be categorized under "Miscellaneous".
 - gesture: A string containing a single gesture associated with this script, e.g. "kb:NVDA+shift+r".

source/NVDAObjects/UIA/__init__.py

@@ -297,6 +297,14 @@ def __init__(self,obj,position,_rangeObj=None):
 		elif position==textInfos.POSITION_LAST:
 			self._rangeObj=self.obj.UIATextPattern.documentRange
 			self.collapse(True)
+		elif position in (textInfos.POSITION_FIRSTVISIBLE, textInfos.POSITION_LASTVISIBLE):
+			try:
+				visiRanges = self.obj.UIATextPattern.GetVisibleRanges()
+				element = 0 if position == textInfos.POSITION_FIRSTVISIBLE else visiRanges.length - 1
+				self._rangeObj = visiRanges.GetElement(element)
+			except COMError:
+				# Error: FIRST_VISIBLE/LAST_VISIBLE position not supported by the UIA text pattern.
+				raise NotImplementedError
 		elif position==textInfos.POSITION_ALL or position==self.obj:
 			self._rangeObj=self.obj.UIATextPattern.documentRange
 		elif isinstance(position,UIA) or isinstance(position,UIAHandler.IUIAutomationElement):
@@ -702,6 +710,25 @@ def compareEndPoints(self,other,which):
 			target=UIAHandler.TextPatternRangeEndpoint_End
 		return self._rangeObj.CompareEndpoints(src,other._rangeObj,target)
 
+	def _get_isOffscreen(self):
+		try:
+			visiRanges = self.obj.UIATextPattern.GetVisibleRanges()
+		except COMError:
+			raise NotImplementedError
+		visiLength = visiRanges.length
+		if visiLength > 0:
+			firstVisiRange = visiRanges.GetElement(0)
+			lastVisiRange = visiRanges.GetElement(visiLength - 1)
+			return self._rangeObj.CompareEndPoints(
+				UIAHandler.TextPatternRangeEndpoint_Start, firstVisiRange,
+				UIAHandler.TextPatternRangeEndpoint_Start
+			) < 0 or self._rangeObj.CompareEndPoints(
+				UIAHandler.TextPatternRangeEndpoint_Start, lastVisiRange,
+				UIAHandler.TextPatternRangeEndpoint_End) >= 0
+		else:
+			# Review bounds not available.
+			return super(UIATextInfo, self).isOffscreen()
+
 	def setEndPoint(self,other,which):
 		if which.startswith('start'):
 			src=UIAHandler.TextPatternRangeEndpoint_Start

source/NVDAObjects/UIA/winConsoleUIA.py

@@ -43,16 +43,6 @@ def collapse(self,end=False):
 			)
 
 	def move(self, unit, direction, endPoint=None):
-		oldRange = None
-		if self.basePosition != textInfos.POSITION_CARET:
-			# Insure we haven't gone beyond the visible text.
-			# UIA adds thousands of blank lines to the end of the console.
-			visiRanges = self.obj.UIATextPattern.GetVisibleRanges()
-			visiLength = visiRanges.length
-			if visiLength > 0:
-				firstVisiRange = visiRanges.GetElement(0)
-				lastVisiRange = visiRanges.GetElement(visiLength - 1)
-				oldRange = self._rangeObj.clone()
 		if unit == textInfos.UNIT_WORD and direction != 0:
 			# UIA doesn't implement word movement, so we need to do it manually.
 			# Relative to the current line, calculate our offset
@@ -106,18 +96,8 @@ def move(self, unit, direction, endPoint=None):
 						endPoint=endPoint
 					)
 		else:  # moving by a unit other than word
-			res = super(consoleUIATextInfo, self).move(unit, direction,
+			return super(consoleUIATextInfo, self).move(unit, direction,
 														endPoint)
-		if oldRange and (
-			self._rangeObj.CompareEndPoints(
-				UIAHandler.TextPatternRangeEndpoint_Start, firstVisiRange,
-				UIAHandler.TextPatternRangeEndpoint_Start) < 0
-			or self._rangeObj.CompareEndPoints(
-				UIAHandler.TextPatternRangeEndpoint_Start, lastVisiRange,
-				UIAHandler.TextPatternRangeEndpoint_End) >= 0):
-			self._rangeObj = oldRange
-			return 0
-		return res
 
 	def expand(self, unit):
 		if unit == textInfos.UNIT_WORD:
@@ -292,9 +272,12 @@ def script_flush_queuedChars(self, gesture):
 
 	def _getTextLines(self):
 		# Filter out extraneous empty lines from UIA
-		ptr = self.UIATextPattern.GetVisibleRanges()
-		res = [ptr.GetElement(i).GetText(-1) for i in range(ptr.length)]
-		return res
+		return (
+			self.makeTextInfo(textInfos.POSITION_ALL)
+			._rangeObj.getText(-1)
+			.rstrip()
+			.split("\r\n")
+		)
 
 	def _calculateNewText(self, newLines, oldLines):
 		self._hasNewLines = (

source/NVDAObjects/__init__.py

@@ -28,6 +28,7 @@
 import braille
 import globalPluginHandler
 import brailleInput
+import scriptCategories
 
 class NVDAObjectTextInfo(textInfos.offsets.OffsetsTextInfo):
 	"""A default TextInfo which is used to enable text review of information about widgets that don't support text content.

source/displayModel.py

@@ -590,3 +590,8 @@ def _setSelectionOffsets(self,start,end):
 		if start!=end:
 			raise NotImplementedError("Expanded selections not supported")
 		self._setCaretOffset(start)
+
+	def isOffscreen(self):
+		"""DisplayModelTextInfo instances only show screen contents, so
+		unbounding is impossible."""
+		raise NotImplementedError

source/documentBase.py

@@ -11,7 +11,7 @@
 import ui
 import controlTypes
 
-class TextContainerObject(AutoPropertyObject):
+class TextContainerObject(ScriptableObject):
 	"""
 	An object that contains text which can be accessed via a call to a makeTextInfo method.
 	E.g. NVDAObjects, BrowseModeDocument TreeInterceptors.
@@ -21,14 +21,25 @@ def _get_TextInfo(self):
 		raise NotImplementedError
 
 	def makeTextInfo(self,position):
-		return self.TextInfo(self,position)
+		try:
+			return self.TextInfo(self,position)
+		except NotImplementedError as e:
+			if position == textInfos.POSITION_FIRSTVISIBLE:
+				# Fall back to POSITION_FIRST
+				return self.makeTextInfo(textInfos.POSITION_FIRST)
+			elif position == textInfos.POSITION_LASTVISIBLE:
+				# Fall back to POSITION_LAST
+				return self.makeTextInfo(textInfos.POSITION_LAST)
+			else:
+				raise e
 
 	def _get_selection(self):
 		return self.makeTextInfo(textInfos.POSITION_SELECTION)
 
 	def _set_selection(self,info):
 		info.updateSelection()
 
+
 class DocumentWithTableNavigation(TextContainerObject,ScriptableObject):
 	"""
 	A document that supports standard table navigiation comments (E.g. control+alt+arrows to move between table cells).

source/globalCommands.py

@@ -32,7 +32,7 @@
 import treeInterceptorHandler
 import browseMode
 import scriptHandler
-from scriptHandler import script
+from scriptCategories import *
 import ui
 import braille
 import brailleInput
@@ -44,49 +44,6 @@
 import winVersion
 from base64 import b16encode
 
-#: Script category for text review commands.
-# Translators: The name of a category of NVDA commands.
-SCRCAT_TEXTREVIEW = _("Text review")
-#: Script category for Object navigation commands.
-# Translators: The name of a category of NVDA commands.
-SCRCAT_OBJECTNAVIGATION = _("Object navigation")
-#: Script category for system caret commands.
-# Translators: The name of a category of NVDA commands.
-SCRCAT_SYSTEMCARET = _("System caret")
-#: Script category for mouse commands.
-# Translators: The name of a category of NVDA commands.
-SCRCAT_MOUSE = _("Mouse")
-#: Script category for speech commands.
-# Translators: The name of a category of NVDA commands.
-SCRCAT_SPEECH = _("Speech")
-#: Script category for configuration dialogs commands.
-# Translators: The name of a category of NVDA commands.
-SCRCAT_CONFIG = _("Configuration")
-#: Script category for configuration profile activation and management commands.
-# Translators: The name of a category of NVDA commands.
-SCRCAT_CONFIG_PROFILES = _("Configuration profiles")
-#: Script category for Braille commands.
-# Translators: The name of a category of NVDA commands.
-SCRCAT_BRAILLE = _("Braille")
-#: Script category for tools commands.
-# Translators: The name of a category of NVDA commands.
-SCRCAT_TOOLS = pgettext('script category', 'Tools')
-#: Script category for touch commands.
-# Translators: The name of a category of NVDA commands.
-SCRCAT_TOUCH = _("Touch screen")
-#: Script category for focus commands.
-# Translators: The name of a category of NVDA commands.
-SCRCAT_FOCUS = _("System focus")
-#: Script category for system status commands.
-# Translators: The name of a category of NVDA commands.
-SCRCAT_SYSTEM = _("System status")
-#: Script category for input commands.
-# Translators: The name of a category of NVDA commands.
-SCRCAT_INPUT = _("Input")
-#: Script category for document formatting commands.
-# Translators: The name of a category of NVDA commands.
-SCRCAT_DOCUMENTFORMATTING = _("Document formatting")
-
 class GlobalCommands(ScriptableObject):
 	"""Commands that are available at all times, regardless of the current focus.
 	"""
@@ -972,8 +929,35 @@ def script_review_activate(self,gesture):
 	script_review_activate.__doc__=_("Performs the default action on the current navigator object (example: presses it if it is a button).")
 	script_review_activate.category=SCRCAT_OBJECTNAVIGATION
 
+	def _moveWithBoundsChecking(self, info, unit, direction, endPoint=None):
+		"""
+		Nondestructively moves a textInfo and returns a (newInfo, res) tuple.
+		Res is 0 and the original C{textInfo} is returned if the move would be out of bounds.
+		"""
+		try:
+			if info.isOffscreen:
+				res = info.move(unit, direction, endPoint=endPoint)
+				return (info, res)
+		except NotImplementedError:
+			pass
+		newInfo = info.copy()
+		res = newInfo.move(unit, direction, endPoint=endPoint)
+		try:
+			if globalVars.reviewBounded and newInfo.isOffscreen:
+				return (info, 0)
+		except NotImplementedError:
+			pass
+		return (newInfo, res)
+
 	def script_review_top(self,gesture):
-		info=api.getReviewPosition().obj.makeTextInfo(textInfos.POSITION_FIRST)
+		rp = api.getReviewPosition()
+		pos = textInfos.POSITION_FIRST
+		try:
+			if globalVars.reviewBounded and not rp.isOffscreen:
+				pos = textInfos.POSITION_FIRSTVISIBLE
+		except NotImplementedError:
+			pass
+		info = rp.obj.makeTextInfo(pos)
 		api.setReviewPosition(info)
 		info.expand(textInfos.UNIT_LINE)
 		ui.reviewMessage(_("Top"))
@@ -987,7 +971,7 @@ def script_review_previousLine(self,gesture):
 		if info._expandCollapseBeforeReview:
 			info.expand(textInfos.UNIT_LINE)
 			info.collapse()
-		res=info.move(textInfos.UNIT_LINE,-1)
+		info, res = self._moveWithBoundsChecking(info, textInfos.UNIT_LINE,-1)
 		if res==0:
 			# Translators: a message reported when review cursor is at the top line of the current navigator object.
 			ui.reviewMessage(_("Top"))
@@ -1019,7 +1003,7 @@ def script_review_nextLine(self,gesture):
 		if info._expandCollapseBeforeReview:
 			info.expand(textInfos.UNIT_LINE)
 			info.collapse()
-		res=info.move(textInfos.UNIT_LINE,1)
+		info, res = self._moveWithBoundsChecking(info, textInfos.UNIT_LINE,1)
 		if res==0:
 			# Translators: a message reported when review cursor is at the bottom line of the current navigator object.
 			ui.reviewMessage(_("Bottom"))
@@ -1033,7 +1017,14 @@ def script_review_nextLine(self,gesture):
 	script_review_nextLine.category=SCRCAT_TEXTREVIEW
 
 	def script_review_bottom(self,gesture):
-		info=api.getReviewPosition().obj.makeTextInfo(textInfos.POSITION_LAST)
+		rp = api.getReviewPosition()
+		pos = textInfos.POSITION_LAST
+		try:
+			if globalVars.reviewBounded and not rp.isOffscreen:
+				pos = textInfos.POSITION_LASTVISIBLE
+		except NotImplementedError:
+			pass
+		info = rp.obj.makeTextInfo(pos)
 		api.setReviewPosition(info)
 		info.expand(textInfos.UNIT_LINE)
 		ui.reviewMessage(_("Bottom"))
@@ -1047,7 +1038,7 @@ def script_review_previousWord(self,gesture):
 		if info._expandCollapseBeforeReview:
 			info.expand(textInfos.UNIT_WORD)
 			info.collapse()
-		res=info.move(textInfos.UNIT_WORD,-1)
+		info, res = self._moveWithBoundsChecking(info, textInfos.UNIT_WORD,-1)
 		if res==0:
 			# Translators: a message reported when review cursor is at the top line of the current navigator object.
 			ui.reviewMessage(_("Top"))
@@ -1078,7 +1069,7 @@ def script_review_nextWord(self,gesture):
 		if info._expandCollapseBeforeReview:
 			info.expand(textInfos.UNIT_WORD)
 			info.collapse()
-		res=info.move(textInfos.UNIT_WORD,1)
+		info, res = self._moveWithBoundsChecking(info, textInfos.UNIT_WORD,1)
 		if res==0:
 			# Translators: a message reported when review cursor is at the bottom line of the current navigator object.
 			ui.reviewMessage(_("Bottom"))
@@ -1206,7 +1197,7 @@ def _getCurrentLanguageForTextInfo(self, info):
 			curLanguage = speech.getCurrentLanguage()
 		return curLanguage
 
-	@script(
+	@scriptHandler.script(
 		# Translators: Input help mode message for Review Current Symbol command.
 		description=_("Reports the symbol where the review cursor is positioned. Pressed twice, shows the symbol and the text used to speak it in browse mode"),
 		category=SCRCAT_TEXTREVIEW,
@@ -2286,6 +2277,37 @@ def script_recognizeWithUwpOcr(self, gesture):
 	# Translators: Describes a command.
 	script_recognizeWithUwpOcr.__doc__ = _("Recognizes the content of the current navigator object with Windows 10 OCR")
 
+	def script_toggleReviewBounds(self, gesture):
+		rp = api.getReviewPosition()
+		outOfBounds = None
+		try:
+			outOfBounds = rp.isOffscreen
+		except NotImplementedError:
+			ui.message(
+				# Translators: Reported when review bound configuration isn't supported for this object.
+				_(u"Not supported here"))
+		else:
+			globalVars.reviewBounded = not globalVars.reviewBounded
+			if globalVars.reviewBounded:
+				ui.message(
+					# Translators: Reported when review is constrained to this
+					# object's visible text.
+					_(u"Bounded review")
+				)
+				if outOfBounds:
+					api.setReviewPosition(
+						api.getReviewPosition().obj.makeTextInfo(textInfos.POSITION_CARET))
+			else:
+				ui.message(
+					# Translators: Reported when review is unconstrained, so all
+					# of this object's text can be read.
+					_(u"Unbounded review")
+				)
+
+	# Translators: A gesture description.
+	script_toggleReviewBounds.__doc__ = _(u"Toggles whether review is constrained to the currently visible text")
+	script_toggleReviewBounds.category=SCRCAT_TEXTREVIEW
+
 	__gestures = {
 		# Basic
 		"kb:NVDA+n": "showGui",
@@ -2397,6 +2419,7 @@ def script_recognizeWithUwpOcr(self, gesture):
 		"kb:NVDA+numpad1": "reviewMode_previous",
 		"kb(laptop):NVDA+pageDown": "reviewMode_previous",
 		"ts(object):2finger_flickDown": "reviewMode_previous",
+		"kb:NVDA+o": "toggleReviewBounds",
 
 		# Mouse
 		"kb:numpadDivide": "leftMouseClick",

source/globalVars.py

@@ -18,6 +18,7 @@
 @type navigatorObject: L{NVDAObjects.NVDAObject}
 @var navigatorTracksFocus: if true, the navigator object will follow the focus as it changes
 @type navigatorTracksFocus: boolean
+@var reviewBounded: Whether the review cursor is bounded to the currently visible text.
 """
 
 startTime=0
@@ -32,6 +33,7 @@
 navigatorObject=None
 reviewPosition=None
 reviewPositionObj=None
+reviewBounded = True
 lastProgressValue=0
 appArgs=None
 appArgsExtra=None