Allow the review cursor to be bounded to onscreen text

source/NVDAObjects/UIA/__init__.py

@@ -297,6 +297,20 @@ def __init__(self,obj,position,_rangeObj=None):
 		elif position==textInfos.POSITION_LAST:
 			self._rangeObj=self.obj.UIATextPattern.documentRange
 			self.collapse(True)
+		elif position==textInfos.POSITION_FIRSTVISIBLE:
+			try:
+				visiRanges = self.obj.UIATextPattern.GetVisibleRanges()
+				self._rangeObj = visiRanges.GetElement(0)
+			except COMError:
+				# Error: FIRST_VISIBLE position not supported by the UIA text pattern.
+				raise RuntimeError
+		elif position==textInfos.POSITION_LASTVISIBLE:
+			try:
+				visiRanges = self.obj.UIATextPattern.GetVisibleRanges()
+				self._rangeObj = visiRanges.GetElement(visiRanges.length - 1)
+			except COMError:
+				# Error: LAST_VISIBLE position not supported by the UIA text pattern.
+				raise RuntimeError
 		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 +716,22 @@ def compareEndPoints(self,other,which):
 			target=UIAHandler.TextPatternRangeEndpoint_End
 		return self._rangeObj.CompareEndpoints(src,other._rangeObj,target)
 
+	def isOutOfBounds(self):
+		visiRanges = self.obj.UIATextPattern.GetVisibleRanges()
+		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 False
+
 	def setEndPoint(self,other,which):
 		if which.startswith('start'):
 			src=UIAHandler.TextPatternRangeEndpoint_Start

source/NVDAObjects/UIA/winConsoleUIA.py

@@ -35,16 +35,6 @@ def __init__(self, obj, position, _rangeObj=None):
 			)
 
 	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
@@ -98,22 +88,7 @@ def move(self, unit, direction, endPoint=None):
 						endPoint=endPoint
 					)
 		else:  # moving by a unit other than word
-			res = 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
+			return super(consoleUIATextInfo, self).move(unit, direction, endPoint)
 
 	def expand(self, unit):
 		if unit == textInfos.UNIT_WORD:
@@ -200,6 +175,9 @@ def _get_focusRedirect(self):
 
 class winConsoleUIA(Terminal):
 	STABILIZE_DELAY = 0.03
+	#: Bound review in consoles by default to maintain feature parity
+	#: with legacy
+	reviewBounded = True
 	_TextInfo = consoleUIATextInfo
 	_isTyping = False
 	_lastCharTime = 0

source/NVDAObjects/__init__.py

@@ -12,6 +12,7 @@
 import re
 import weakref
 from logHandler import log
+from scriptHandler import script
 import review
 import eventHandler
 from displayModel import DisplayModelTextInfo
@@ -1267,3 +1268,35 @@ def getSelectedItemsCount(self,maxCount=2):
 		For performance, this method will only count up to the given maxCount number, and if there is one more above that, then sys.maxint is returned stating that many items are selected.
 		"""
 		return 0
+
+	reviewBounded = False
+
+	@script(gesture="kb:NVDA+o",
+		# Hardcoded to avoid circular import
+		category=_(u"Text review"),
+		# Translators: A gesture description.
+		description=_(u"Toggles whether review is constrained to the currently visible text"))
+	def script_toggleReviewBounds(self, gesture):
+		try:
+			rp = api.getReviewPosition()
+			outOfBounds = rp.isOutOfBounds()
+			self.reviewBounded = not self.reviewBounded
+			if self.reviewBounded:
+				ui.message(
+					# Translators: Reported when review is constrained to this
+					# object's visible text.
+					_(u"Bounded review")
+				)
+				if outOfBounds:
+					api.setReviewPosition(
+						self.makeTextInfo(textInfos.POSITION_CARET), isCaret=True)
+			else:
+				ui.message(
+					# Translators: Reported when review is unconstrained, so all
+					# of this object's text can be read.
+					_(u"Unbounded review")
+				)
+		except NotImplementedError:
+			ui.message(
+				# Translators: Reported when review bound configuration isn't supported for this object.
+				_(u"Not supported here"))

source/globalCommands.py

@@ -972,8 +972,21 @@ 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 if the move would be out of bounds.
+		"""
+		newInfo = info.copy()
+		res = newInfo.move(unit, direction, endPoint=endPoint)
+		if newInfo.obj.reviewBounded and newInfo.isOutOfBounds():
+			return (info, 0)
+		return (newInfo, res)
+
 	def script_review_top(self,gesture):
-		info=api.getReviewPosition().obj.makeTextInfo(textInfos.POSITION_FIRST)
+		obj = api.getReviewPosition().obj
+		pos = textInfos.POSITION_FIRSTVISIBLE if obj.reviewBounded else textInfos.POSITION_FIRST
+		info = obj.makeTextInfo(pos)
 		api.setReviewPosition(info)
 		info.expand(textInfos.UNIT_LINE)
 		ui.reviewMessage(_("Top"))
@@ -987,7 +1000,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 +1032,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 +1046,9 @@ 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)
+		obj = api.getReviewPosition().obj
+		pos = textInfos.POSITION_LASTVISIBLE if obj.reviewBounded else textInfos.POSITION_LAST
+		info = obj.makeTextInfo(pos)
 		api.setReviewPosition(info)
 		info.expand(textInfos.UNIT_LINE)
 		ui.reviewMessage(_("Bottom"))
@@ -1047,7 +1062,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 +1093,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"))

source/textInfos/__init__.py

@@ -2,7 +2,7 @@
 #A part of NonVisual Desktop Access (NVDA)
 #This file is covered by the GNU General Public License.
 #See the file COPYING for more details.
-#Copyright (C) 2006-2018 NV Access Limited, Babbage B.V.
+#Copyright (C) 2006-2019 NV Access Limited, Babbage B.V., Bill Dengler
 
 """Framework for accessing text content in widgets.
 The core component of this framework is the L{TextInfo} class.
@@ -155,6 +155,8 @@ def __repr__(self):
 #Position constants
 POSITION_FIRST="first"
 POSITION_LAST="last"
+POSITION_FIRSTVISIBLE="firstVisible"
+POSITION_LASTVISIBLE="lastVisible"
 POSITION_CARET="caret"
 POSITION_SELECTION="selection"
 POSITION_ALL="all"
@@ -259,7 +261,7 @@ class TextInfo(baseObject.AutoPropertyObject):
 	L{Points} must be supported as a position.
 	To support routing to a screen point from a given position, L{pointAtStart} or L{boundingRects} must be implemented.
 	In order to support text formatting or control information, L{getTextWithFields} should be overridden.
-
+	To support review bounds configuration, implement the L{isOutOfBounds} method and L{POSITION_FIRSTVISIBLE} and L{POSITION_LASTVISIBLE} positions.
 	@ivar bookmark: A unique identifier that can be used to make another textInfo object at this position.
 	@type bookmark: L{Bookmark}
 	"""
@@ -551,6 +553,15 @@ def getMathMl(self, field):
 		"""
 		raise NotImplementedError
 
+	def isOutOfBounds(self):
+		"""
+		Returns True if this textInfo is positioned outside its object's
+		visible text.
+		@rtype: bool
+		"""
+		raise NotImplementedError
+
+
 RE_EOL = re.compile("\r\n|[\n\r]")
 def convertToCrlf(text):
 	"""Convert a string so that it contains only CRLF line endings.

source/textInfos/offsets.py

@@ -401,6 +401,10 @@ def __init__(self,obj,position):
 			self._startOffset=self._endOffset=0
 		elif position==textInfos.POSITION_LAST:
 			self._startOffset=self._endOffset=max(self._getStoryLength()-1,0)
+		elif position==textInfos.POSITION_FIRSTVISIBLE:
+			self._startOffset=self._endOffset=self._getFirstVisibleOffset()
+		elif position==textInfos.POSITION_LASTVISIBLE:
+			self._startOffset=self._endOffset=self._getLastVisibleOffset()
 		elif position==textInfos.POSITION_CARET:
 			self._startOffset=self._endOffset=self._getCaretOffset()
 		elif position==textInfos.POSITION_SELECTION:
@@ -457,6 +461,14 @@ def collapse(self,end=False):
 	def expand(self,unit):
 		self._startOffset,self._endOffset=self._getUnitOffsets(unit,self._startOffset)
 
+	def isOutOfBounds(self):
+		try:
+			return self._startOffset < self._getFirstVisibleOffset(
+			) or self._endOffset > self._getLastVisibleOffset()
+		except AttributeError, LookupError: 
+			# Some implementations have incomplete support.
+			raise NotImplementedError
+
 	def copy(self):
 		return self.__class__(self.obj,self)
 

user_docs/en/userGuide.t2t

@@ -402,6 +402,7 @@ The following commands are available for reviewing text:
 | Select then Copy to review cursor | NVDA+f10 | NVDA+f10 | none | On the first press, text is selected from the position previously set start marker up to and including the review cursor's current position. After pressing this key a second time, the text will be copied to the Windows clipboard |
 | Report text formatting | NVDA+f | NVDA+f | none | Reports the formatting of the text where the review cursor is currently situated. Pressing twice shows the information in browse mode |
 | Report current symbol replacement | None | None | none | Speaks the symbol where the review cursor is positioned. Pressed twice, shows the symbol and the text used to speak it in browse mode. |
+| Toggle review bounds | NVDA+o | NVDA+o | none | Toggles whether the review cursor is constrained to the currently visible text. This is particularly useful in the Windows Console for reviewing text that has scrolled off the screen. |
 %kc:endInclude
 
 Note: numpad keys require numlock key to be turned off to work properly.